Files
zeekay 03d3c36c05 chore(quality-gate): green the workspace clippy -D warnings + rustfmt gate
Clears accumulated debt across the session's merged code so
`cargo clippy --workspace --tests --examples -- -D warnings` and
`cargo fmt --all --check` pass (both CI-enforced). No behavior change.

- cast_possible_truncation/precision_loss: file-level allow on the new model
  files, matching the 250+ existing model files (llama.rs et al). All sites are
  grid/index/dimension/serialization casts.
- dead_code: scoped allows on deserialized-verbatim config fields, backend-gated
  helpers (vulkan/cuda/rocm), and accessors, matching the model-file convention.
- unused imports removed (pixal3d Module, function-local SpeculativeProposer).
- needless_range_loop/too_many_arguments: scoped allows (rewriting tensor loops
  or arg-lists would risk numerics; matches the 343 existing too_many_args allows).
- ring_exchange cfg-gated to feature=ring (its only callers are ring-gated).
- dropped the inert route_handler utoipa::path annotation (not in the OpenApi
  paths() registry; RouteResponse's Decision can't be ToSchema).
- misc idiom fixes (sort_by_key, checked_div, struct-update literal, doc lists).
- rustfmt the merged files (pixal3d, film, oasis, qwen3_omni, ...).
2026-07-10 17:15:09 -07:00
..

hanzo-film

Long-form film / episode orchestration over the Hanzo Engine /v1 endpoints. A one-paragraph brief becomes a validated Film Bible, thousands of independent per-shot render jobs, dialogue + score, and a final assembled mp4 — with all orchestration state as plain JSON files in a project directory (no database).

The engine is the model backend (LLM, image, TTS, embeddings, and the async /v1/videos job). This crate is a pure client + ffmpeg assembler; it holds no model weights and builds independently of the inference crates.

Pipeline

plan     brief -> bible.json                 (LLM, structured output)
assets   reference image per character/loc   (image endpoint / procedural)
render   bible -> per-shot clips             (parallel, idempotent, continuity)
audio    dialogue TTS + score + per-shot mix (TTS endpoint / placeholder tone)
assemble concat + mux -> film.mp4 + timeline.json (EDL manifest)
verify   identity-coherence scoring hook

Each stage is a resumable CLI subcommand; run chains them. Every stage reads the bible and writes into the project dir, so a re-run picks up where it left off.

Backends (one interface, two impls)

Each modality is an enum: an engine-backed variant (the real target) and a dependency-free variant that proves the whole pipeline end-to-end on a box with no image/video/TTS model loaded. If an engine call fails, the pipeline logs a warning and falls back per item.

modality engine variant fallback variant
image /v1/images/generations procedural color card
video /v1/videos (WAN, async) placeholder: keyframe + Ken-Burns
speech /v1/audio/speech quiet tone sized to the line
music /v1/audio/music* silence
coherence /v1/embeddings (vision) downsampled-luma cosine (proxy)

* WAN video and ACE-Step music endpoints land from sibling work; the interface is wired and used the moment they answer.

The Bible schema (the contract)

bible.json is versioned (BIBLE_VERSION) and validated before any render job runs (Bible::validate): every id unique, every ref (location_ref, character_ref, scene_ref) resolvable, durations positive.

{
  "version": 1,
  "title": "...", "logline": "...",
  "style": { "prompt": "cinematic, warm light",
             "lora": null, "grade": "eq=contrast=1.05" },   // grade = ffmpeg filter
  "characters": [ { "id": "c1", "name": "Lila", "description": "...",
                    "reference_image": "assets/char_c1.png", "voice_id": "v1" } ],
  "locations":  [ { "id": "l1", "description": "...", "reference_image": "assets/loc_l1.png" } ],
  "scenes": [ {
    "id": "sc1", "location_ref": "l1", "characters": ["c1","c2"], "synopsis": "...",
    "shots": [ {
      "id": "sc1_sh1", "scene_ref": "sc1",
      "duration_s": 4.0, "shot_type": "wide",
      "action_prompt": "one vivid visual sentence",
      "dialogue": [ { "character_ref": "c1", "line": "..." } ],
      "continuity": "cut"          // "cut" | "continue"
    } ]
  } ]
}

Characters are global and referenced by every scene/shot, which is what makes a character recur coherently.

Continuity & parallelism

Shots are independent jobs. A continue shot conditions on the prior shot's tail frame (same camera run); a cut starts fresh from its scene/location anchor. The renderer partitions shots into continuity runs (a cut plus the continue shots after it): runs are mutually independent and dispatched concurrently up to --concurrency, while shots inside a run stay sequential.

Idempotent re-runs

Each shot writes a spec-hash sidecar (shots/<id>.json) covering everything that determines its pixels (prompt, geometry, style, conditioning, renderer + version). A re-run skips any shot whose clip exists and whose hash still matches — change a prompt and only that shot (and its dependents) re-render.

Project directory

<proj>/
  project.json      brief + config
  bible.json        the validated contract
  assets/           char_<id>.png, loc_<id>.png
  shots/            <shot>.mp4, <shot>.json (spec-hash), <shot>.tail.png, <shot>.av.mp4
  audio/            line_<shot>_<n>.wav, music_<scene>.wav, mix_<shot>.wav
  timeline.json     EDL manifest (durable assembly artifact)
  coherence.json    identity-consistency scores
  film.mp4          final render

Usage

# 1. serve a planner model (any chat model; structured output via response_format)
hanzo serve -p 1234 text -m Qwen/Qwen3-4B --format gguf -f model.gguf

# 2. orchestrate
hanzo-film new  ./myfilm --brief "A lighthouse keeper finds a message from her future self." \
                --engine http://127.0.0.1:1234 --width 768 --height 432 --fps 24 --concurrency 8
hanzo-film run  ./myfilm --scenes 2 --shots-per-scene 3     # plan..assemble..verify
# or step-by-step, each resumable:
hanzo-film plan ./myfilm && hanzo-film assets ./myfilm && hanzo-film render ./myfilm \
  && hanzo-film audio ./myfilm && hanzo-film assemble ./myfilm && hanzo-film verify ./myfilm

# real WAN video (once the endpoint lands) — same project, just the video backend:
hanzo-film new ./myfilm --brief "..." --video wan

Tests

cargo test -p hanzo-film            # 32 unit (schema, JSON repair, hashing, runs, timeline)
                                    # + 1 offline integration: full pipeline -> mp4, ffprobed

The offline integration test renders a complete mp4 (video + audio) through the procedural/placeholder backends, so cargo test proves the pipeline with no engine and no GPU.