# Godfortune YouTube Production V2

Last updated: 2026-07-14

## Decision

The top-level video unit is a shot, not a generated image and not a viseme clip.

```text
content request
-> production compiler
-> shot timeline
-> asset plan
-> audio plan
-> quality gate
-> shot-based 2D compositor
-> final mix and encode
-> review
-> YouTube publish
```

The `layered_2d_viseme_renderer` remains the character performance component. It
does not own backgrounds, multi-character blocking, camera cuts, props, captions,
sound effects, music sections, or callback timing.

## Server Boundary

The content server owns:

- reconstructed story
- saju claims
- dialogue and lyrics
- image-generation intent
- TTS voice and song-generation intent
- comedy beats and upload metadata

Studio-core owns:

- shot expansion and absolute timing
- catalog asset reuse versus story asset generation
- character identity and rig selection
- background, prop, expression, pose, camera, caption, effect, and transition cues
- audio cue placement, ducking, and final mix
- render artifacts, review, and publishing

## Executable Contract

Input model:

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

Compiler:

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

The V1 contract remains available for the current image plus audio research renderer.
V2 is a separate contract so that existing jobs are not silently reinterpreted.

## Shot Fields

Each shot specifies:

- story phase and reusable template
- background and prop asset ids
- character identity, pose, expression, mouth mode, placement, and action
- camera type, composition, scale, pan, and shake
- caption text and preset
- dialogue, song, BGM, and SFX cues
- effects and transition
- comedy devices and retention role
- quality roles such as hook, saju entry, escalation, payoff, and callback

Shots are sequential in V2. The compiler assigns absolute start and end times. A
future renderer may render or rerender one shot without rebuilding unrelated shots.

## Compiled Outputs

`production_plan.json` is the render source of truth. It contains the absolute shot
timeline and execution stages.

`asset_plan.json` separates:

- `catalog_reuse`: fixed Godfortune and reusable library assets
- `generation_required`: story client, story backgrounds, and story props
- `provided_file`: media already supplied by the content server

It also inspects character rig manifests and reports missing layer files.

`audio_plan.json` resolves every shot-relative audio cue to absolute time. TTS text is
kept on the cue, while voice configuration is kept on the reusable source. Song cues
can address source ranges so a continuous generated song can span multiple shots.

`quality_gate.json` separates editorial quality from production readiness. A plan may
pass all timing rules while remaining blocked on missing character layers.

## Benchmark-Derived Editorial Gate

The active 60-second profile checks:

- total duration: 55 to 65 seconds
- first hook: by 1 second
- saju interpretation entry: by 9 seconds
- cut rate: 38 to 55 cuts per minute
- maximum visual event gap: 1.7 seconds
- escalation: at least 5 category cycles
- punchlines: at least 9
- main payoff: between 50 and 57 seconds
- callback: within the final 3 seconds
- subtitle changes: 32 to 48 per minute

These values reproduce pacing discipline, not the benchmark's characters, dialogue,
lyrics, costumes, drawing style, or exact gag sequence.

## Sample

The sample implements the original Godfortune structure:

```text
story reconstruction
-> saju interpretation
-> exaggerated musical situation
```

Input:

```text
examples/godfortune_production_job_v2.json
```

Compile:

```bash
cd /home/studio/studio-core
.venv/bin/python scripts/compile_godfortune_production_plan.py \
  examples/godfortune_production_job_v2.json \
  --output-dir /data/studio-core/production_plans/godfortune_one_dot_office_v2_001
```

Expected editorial result:

- 60 seconds
- 40 shots
- 39 cuts per minute
- 1.5-second maximum visual gap
- saju entry at 7.5 seconds
- 6 escalation categories
- main payoff at 52.5 seconds
- final callback at 57 seconds

## Current Blocker

The V2 Godfortune rig manifest and selected ComfyUI master exist, but the registered
28-state character pack is not complete. The compiler currently reports 28 missing
state files. This keeps the plan editorially valid while correctly blocking
production render readiness.

The next implementation order is:

1. create the 28 registered character state PNGs
2. implement the shot compositor consuming `production_plan.json`
3. connect audio generation and viseme extraction to `audio_plan.json`
4. render the 60-second sample to review artifacts
5. connect approved V2 plans to the persistent job worker and YouTube publisher