# Godfortune Content Server Media Input Guide

This guide defines what the content server must send to Studio-Core and what
Studio-Core must decide. It applies to `2026-07-14.media-workbench.v2`
`generate_only` jobs.

## Content Lock

The content server owns and locks:

- dialogue, lyrics, speakers, and segment order
- fortune logic and the ending
- `visual_intent`, `on_screen_character_ids`, and duration hints
- character appearance, references, design rules, and change limits
- semantic voice and music requirements
- required and prohibited scene elements

Studio-Core must not rewrite these fields. When timing or production quality
cannot be satisfied, Studio returns the affected segment IDs, timecodes, reason,
and requested timing range.

Before rendering, Studio-Core also returns a visual route decision for every
`visual_intent`: SAFE, CONDITIONAL, or BLOCKED. SAFE may render through an
approved local route. CONDITIONAL requires the named human gate. BLOCKED must be
split, simplified, or moved to a video-generation-native route before
production rendering.

## Music Package

Send the story as setup dialogue, one continuous musical block, and closing
dialogue. The musical block must list its ordered segment IDs and section roles
such as `verse`, `pre_chorus`, `chorus`, `bridge`, and `final_chorus`.

Use `duration_policy=quality_first_flexible` and
`allow_timeline_extension=true`. The current local baseline prefers a 75-to-90
second musical block for lyric packages with similar density. This is an
observed Studio range, not a fixed script requirement.

Do not request one generated song clip per lyric line. Do not require Studio to
time-compress a completed song into a short slot. When a locked package is too
dense, Studio returns a timing revision request without changing the lyrics.

## Required Segment Data

Every segment must include:

- `segment_id`
- `speaker`
- `text` or `lyrics`
- `visual_intent`
- `on_screen_character_ids`
- `duration_hint_seconds`

Every character must include `character_id`, appearance description,
`design_rules`, and `character_change_limits`. Include approved reference,
catalog, and state-pack URIs when they exist.

Send role voice aliases and semantic requirements. Do not send the actual TTS
engine, singing engine, checkpoint, LoRA, prompt recipe, negative prompt,
sampler, seed, or cache key. Studio-Core owns those implementation choices.

## Release Boundary

`upload.mode` remains `generate_only`. The content server must not request
YouTube OAuth, upload, publish, comment, or reply calls. Studio returns the MP4,
review sheet, quality report, and machine-readable blockers.

Machine-readable contract:
`config/content_server_godfortune_media_input_guide_v1.json`.

Current pre-H3 gate implementation:
`src/studio_core/youtube_pipeline/visual_intent_router.py`.

Current blocked-segment revision request artifact:
`/data/studio-core/artifacts/media_workbench_research/godfortune_seedance_benchmark_v1/current_video_reassessment_v1/yaco_visual_intent_route_plan_v1/content_server_visual_revision_request_v1.json`.

Current route-compatible V0 request:
`examples/media_workbench_intake_v2_current_route_v0.json`. It demonstrates how
the content server can keep the same story while splitting multi-character,
prop, and effect beats into single-character performance clips plus editor-owned
cutaways and overlays.