Narration Voice Director

Narration Voice Director

Every story this engine renders is read aloud by a single narrator. Picking that narrator is a one-shot decision made at render kickoff: the same voice carries every beat, so the choice has to land the tone of the WHOLE story (not any single beat).

This skill makes that pick. It looks at the story's title, opening, and franchise hint, then emits a persona label plus a search query the downstream voice_sample_builder tool will feed to YouTube. Output is one JSON object, fire and forget.

The single most important contract is the search query phrasing. YouTube's top result for "Galadriel ring scene" is a 10-second screaming clip — diarization cannot extract a normal speaking voice from material that has no normal speaking voice in it. The same character searched as "Galadriel prologue narration" returns the LOTR opening monologue, calm and clean. The skill MUST emit narration-style queries.

When to Use

• User starts rendering a story for the first time → fire this skill exactly once.
• User changes the story seed AND wants a re-render with a new voice → fire again.
• Do NOT re-fire per beat. The narrator is story-scoped.

Input Shape

{
  "title": "string (story title)",
  "body":  "string (opening 200-500 words of the story, sets tone)",
  "seed":  "string (optional — story logline, used when body is empty)",
  "franchise": "marvel | lotr | avatar-airbender | null  (slug from story-copyright-detector)"
}

At least one of title / body / seed must be non-empty. franchise is the slug from the copyright detector when available; treat null as "original / unknown franchise".

Output Contract

Return exactly one JSON object, nothing else. First character {, last character }:

{
  "persona_label":   "<short human-readable narrator persona, max 8 words>",
  "search_query":    "<6-12 word YouTube search query, narration-friendly>",
  "fallback_query":  "<alternate 6-12 word query, used if first fetch fails>",
  "reasoning":       "<one sentence explaining the persona + query choice>"
}

Field rules:

• persona_label — what the narrator sounds like, in plain English. Examples: "Galadriel-style elven sage narrator", "Iroh-style warm uncle storyteller", "hardboiled noir detective voiceover", "breathless young female audiobook narrator". Callers typically surface this label in the UI so the user can judge "does the rendered voice match the label?" — make it the most useful one-line description you can fit.
• search_query — a 6-12 word YouTube search string. MUST follow the narration-query rules below. Goes verbatim into voice_sample_builder.query.
• fallback_query — an alternate 6-12 word query the caller will retry with if voice_sample_builder fails or returns a wav the user rejects. MUST be meaningfully different (different keywords, different angle), not a near-paraphrase.
• reasoning — one sentence, ≤ 30 words. Justifies why this persona fits the story tone AND why the query phrasing was chosen.

Search-Query Rules — STRICT

The query phrasing dominates output quality. These rules are non-negotiable.

Required modifiers (pick one or more)

Forbidden modifiers — surface drama, not voice

These words are blacklisted in search_query and fallback_query:

• scene, fight, battle, clash
• action, climax, epic moment
• screaming, crying, shouting
• Any clickbait phrasing: INSANE, MIND-BLOWING, DESTROYS, etc.

Special rule: characters famous for a dramatic moment

If the natural narrator candidate is a character whose iconic appearance is a screaming / fighting / monstrous moment (Galadriel "ring scene", Joker laugh, Vader breath, Hulk smash), DO NOT phrase the query around that moment. Either:

• Target the same character in a calm context: "Galadriel prologue narration" instead of "Galadriel ring scene".
• OR target the actor in any other context: "Cate Blanchett interview" instead of "Galadriel" at all.

Including the actor name

Adding the actor's real name (Cate Blanchett, Mark Hamill, Ian McKellen, Iain Glen) widens the search beyond the dramatic-moment trap and surfaces interview / audiobook material across multiple projects. Prefer "<actor name> <character> <modifier>" when the actor is well-known for narration / audiobook work.