codec-diffusers (Docker)
HuggingFace diffusers reference server with the Codec v0.3 latent transport patch. Doubles as the bench/golden perceptual-conformance reference for every Codec latent client.
Server
'codec-diffusers' is a pre-built Docker image of the HuggingFace diffusers (https://github.com/huggingface/diffusers) reference path with the Codec v0.3 latent transport patch applied. It exposes the same '/v1/images/generations' and '/v1/videos/generations' endpoints as codec-comfyui, and the wire shape is byte-identical, but it sits on top of 'diffusers' instead of ComfyUI's workflow engine.
This image doubles as the bench/golden perceptual-conformance reference. The 'torch' + 'diffusers' + 'transformers' versions pinned in this image define the SSIM / PSNR / LPIPS contract every latent bench cell resolves against. Bumping any of them re-pins the perceptual contract. Operators tracking conformance across runs MUST pin to a specific image digest, not ':latest'.
The patch is built from the 'wdunn001/diffusers' fork (https://github.com/wdunn001/diffusers/tree/feat/codec-latent-transport) at branch 'feat/codec-latent-transport'. 'diffusers' is a library, not a server, so the fork adds an 'examples/codec_server/' FastAPI wrapper that loads any 'StableDiffusionPipeline' / 'StableVideoDiffusionPipeline' / etc. and serves Codec latent streams.
Quick start
code (bash):
docker run -d --gpus all
-p 8080:8080
-v codec-models:/models
--shm-size 8g
-e CODEC_MODEL=stabilityai/stable-diffusion-2-1
wdunn001/codec-diffusers:latest
Same request shape as codec-comfyui:
code (bash):
curl http://localhost:8080/v1/images/generations
-H "Content-Type: application/json"
-H "Accept: application/x-codec-msgpack"
-H "Accept-Encoding: zstd"
-d '{
"model": "sd2.1",
"prompt": "a wide-angle photograph of a snowy mountain at dusk",
"stream_format": "msgpack",
"modality": "image-latents",
"latent_space": "stabilityai/sd-vae-ft-mse",
"pipeline": "int8-adaptive",
"size": "768x768", "steps": 30, "seed": 42
}'
Response carries the same headers as codec-comfyui: 'Codec-Latent-Map', 'Codec-Zstd-Dict', and 'Content-Encoding: zstd' when a per-pipeline dict is loaded.
Why two latent servers
'codec-comfyui' and 'codec-diffusers' are siblings, same wire, same pipelines, same registry. Pick by use case:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โ Need โ Image โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโค
โ Production image-gen with rich workflow primitives โ 'codec-comfyui' โ
โ Reference / bench / "what does the canonical decoder produce" โ 'codec-diffusers' โ
โ Custom pipeline (e.g. ControlNet variants, LoRA stacks) easier to script โ 'codec-diffusers' โ
โ Pre-built node graph + queue + visual editor โ 'codec-comfyui' โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโ
The wire format is identical between the two. A Codec client can switch upstream without code changes.
Measured wire numbers (2026-05-09 lab run)
First end-to-end latent run against 'codec-diffusers:v0.3.4' running SD-1.5 on an RTX 3090. Pipeline math validates byte-for-byte against 'spec/PIPELINES.md' (https://github.com/wdunn001/Codec/blob/main/spec/PIPELINES.md):
โโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโฌโโโโโโโโโโฌโโโโโโโโโฌโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโ
โ Fixture โ raw โ int8 โ int4 โ int8 vs raw โ int4 vs raw โ
โโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโผโโโโโโโโโโผโโโโโโโโโผโโโโโโโโโโโโโโผโโโโโโโโโโโโโโค
โ 256ร256 (4ร32ร32) โ 8.4 KB โ 4.4 KB โ 2.4 KB โ 1.9ร โ 3.5ร โ
โ 512ร512 (4ร64ร64) โ 32.4 KB โ 16.4 KB โ 8.4 KB โ 2.0ร โ 3.9ร โ
โโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโดโโโโโโโโโโดโโโโโโโโโดโโโโโโโโโโโโโโดโโโโโโโโโโโโโโ
The 512 latent at int8 (16.4 KB) is ~5-10ร smaller than JPEG (web quality 85) and ~90ร smaller than raw fp16 pixels (1.5 MB). Per-pipeline zstd dicts aren't loaded yet. That adds another ~25-40% on top once trained; tracked as the next concrete step. See the full results (https://github.com/wdunn001/Codec/tree/main/packages/bench/results/2026-05-09T13-01-55Z/latent) for the methodology.
Bench / golden role
When the Codec bench harness (https://github.com/wdunn001/Codec/tree/main/packages/bench) computes perceptual quality (SSIM / PSNR / LPIPS) for a given '(latent_space_id, pipeline)' cell, the reference pixels come from this image, executed against a pinned image digest (the 'decoder.canonical_image' field in the latent-space-map schema (https://github.com/wdunn001/Codec/blob/main/spec/latent-space-map.schema.json)).
Operators reporting bench results MUST pin to the same digest, 'wdunn001/codec-diffusers@sha256:โฆ', that the published latent map references. ':latest' drift is the difference between "we beat last quarter's SSIM" and "we measured a noisier reference."
The 'golden-builder' Dockerfile in the Codec repo bumps in lockstep with this image; bumping 'torch' or 'diffusers' here without bumping 'packages/bench/golden-builder/Dockerfile' breaks the conformance gate.
Pointing a Codec client at it
Source & links
โข Image: 'wdunn001/codec-diffusers:latest' (https://hub.docker.com/r/wdunn001/codec-diffusers) on Docker Hub.
โข Codec patch source: github.com/wdunn001/diffusers (https://github.com/wdunn001/diffusers/tree/feat/codec-latent-transport).
โข Image build recipe: github.com/wdunn001/codec-supervisor/blob/main/Dockerfile.diffusers (https://github.com/wdunn001/codec-supervisor/blob/main/Dockerfile.diffusers).
โข v0.3 spec section: Codec PROTOCOL.md ยง Latent Modality (https://github.com/wdunn001/Codec/blob/main/spec/PROTOCOL.md#latent-modality-v03).
See also
โข codec-comfyui, workflow-oriented sibling.
โข codec-metamcp, gateway in front of latent + text + tool servers.
โข Protocol overview, the wire format spec.