# Media Workbench Character-Seed Pipeline

Last updated: 2026-07-20

## Product Scope

Studio-core receives varied content packages and varied character seeds from an
internal content server. Its job is not to reproduce one fixed Godfortune character
pack. It compiles each request into benchmark-informed shots, creates or reuses only
the character states required by those shots, adds deterministic 2D motion, aligns
voice and music, renders the video, and publishes only after review.

```text
content + character seeds + voice/song inputs
-> intake validation and identity fingerprinting
-> benchmark shot planning
-> required-state compilation and cache lookup
-> missing character/background/prop generation
-> held-state motion and camera composition
-> word/beat alignment, captions, SFX, and mix
-> quality gate, encode, review, upload
```

The benchmark contributes pacing and production grammar. It does not contribute
characters, dialogue, lyrics, costumes, exact jokes, or branded drawing identity.

## Character Seed Meaning

The intake contract separates a character identity seed from a diffusion random
seed. They are not interchangeable.

- identity seed: reference images, a catalog character, an existing state pack, or
  a prompt from which a master must first be approved
- random seed: reproduces one generation run and never counts as identity locking
- identity fingerprint: cache key derived from identity inputs, excluding the random
  seed and per-job cache settings

Supported identity strategies:

| Input | Compiled strategy |
| --- | --- |
| Existing state pack | registered state reuse |
| Catalog character | global or project cache reuse |
| One to three references | reference conditioning plus structure control |
| Four or more curated references | character LoRA candidate plus structure control |
| Prompt only | generate and approve a master, then use it as a reference |

The controlled ComfyUI prompt, seed, LoRA, and reference-conditioning audit is in:

```text
docs/comfyui-character-consistency-deep-research.md
config/comfyui_character_generation_protocol_v1.json
```

## Dynamic State Budget

Twenty-eight assets are a research coverage target for the Godfortune case, not a
mandatory cost for every incoming character. After shot planning, the state compiler
collects per character:

- unique body states: pose, facing, and action
- unique facial expressions
- required mouth or viseme states
- unique final composites used by shots
- every shot that consumes each character

Recurring characters can fill and reuse a larger cached state library. One-off
characters generate only the states required for the current script. All new
characters must first pass a neutral/action/extreme-reaction identity gate.

## Benchmark Motion Grammar

The target is held-state 2D animation, not continuous diffusion video:

- hard cuts and beat cuts
- push-ins, pans, scale punches, and reframing
- short shake, recoil, squash, bounce, and slide presets
- prop entry and effect overlays
- sparse registered mouth changes where useful
- full-state swaps for pose and extreme reaction changes

The compositor should make a new visual event at the benchmark cadence without
redrawing the character every frame.

## Audio Direction

Voice, song, BGM, and SFX may arrive as files or generation intents. Studio-core
owns their final timing and mix:

1. generate or validate each source
2. obtain word timing for dialogue and beat/section timing for music
3. place visual cuts and state changes on meaningful words or beats
4. duck BGM under speech and keep SFX on separate cues
5. render captions from the same timing source

## Implemented Research Contract

The request-versus-quality ownership boundary is defined separately:

```text
docs/media-workbench-request-quality-boundary.md
```

New integrations should use the v2 request contract. It contains content, identity,
source-asset, constraint, and publication intent only. Studio-owned generation and
quality settings are resolved from a versioned internal profile.

Input model:

```text
src/studio_core/youtube_pipeline/intake_contracts.py
```

Intake planner and idempotent store:

```text
src/studio_core/youtube_pipeline/intake_planner.py
src/studio_core/youtube_pipeline/intake_store.py
```

Required-state compiler:

```text
src/studio_core/youtube_pipeline/state_requirements.py
```

API:

```text
POST /v1/media-workbench/intakes
GET  /v1/media-workbench/intakes/{intake_id}
```

The POST currently persists `request.json`, `intake_plan.json`, and `manifest.json`,
then returns `planning_required`. It intentionally does not claim that the video is
ready before benchmark shot expansion and asset quality gates exist.

Example:

```text
examples/media_workbench_intake_v2.json
```

## Next Research Gates

1. Implement content-segment to benchmark-shot expansion.
2. Define and render the deterministic motion preset library.
3. Connect character-state generation recipes and cache lookup.
4. Add word alignment, beat detection, and audio stem mixing.
5. Render one multi-character end-to-end research job.
6. Measure identity drift, cut cadence, visual-event gaps, caption cadence, and
   word/beat synchronization before enabling automatic upload.

## First End-to-End Animatic Result

The `multi_character_comedy_test_001` intake was treated as a received content job
and expanded into a 45-second research animatic.

Compiled result:

- 36 shots and 35 cuts
- 46.667 cuts per minute
- 1.25-second average shot
- 1.334-second maximum shot
- 12 full-state shots and 24 layered-face shots
- immediate hook, musical escalation, reversal, and callback
- Korean Edge TTS dialogue
- deterministic 132 BPM guide music and rhythmic guide vocal
- H.264 1080x1920 at 30 fps with AAC stereo audio at 48 kHz
- measured loudness of approximately -16.5 LUFS
- no detected black frames or complete silence longer than 0.7 seconds

Artifact root:

```text
/data/studio-core/media_workbench_intakes/
media_intake_7c8bf812adc0f0fb290116d0/research_animatic_v3/
```

The shot and motion grammar passes the current benchmark checks. This does not yet
approve ComfyUI character quality or generated singing. The animatic deliberately
uses deterministic original shape characters and a guide track so those risks remain
separate and measurable.