Add expressive TTS governance

2026-06-29 12:08:37 -07:00
parent 80e51fd618
commit 5e4943a41b
18 changed files with 489 additions and 24 deletions
@@ -49,7 +49,7 @@ Prefer the lowest-variance useful path:

 Before batch-generating assets, produce one sample of each expensive type and show the user:

-1. **TTS sample** (if narration-led): Generate one section. Confirm voice and tone before batching.
+1. **TTS sample** (if narration-led): Generate `script.voice_performance.sample_section_id` when present; otherwise choose the section with the strongest emotional or pacing change. Confirm voice, pace, pauses, emphasis, and tone before batching.
 2. **Visual sample**: Generate one representative scene visual (diagram, illustration, or motion background). Confirm style and quality before batching the rest.

 If rejected, adjust parameters and retry (max 3 iterations). Do not batch until approved.
@@ -100,7 +100,12 @@ Create once:

 ### 3. Narration Is Optional, But The Plan Must Be Explicit

-If the project is narration-led, produce or source narration. If it is text-led or music-led, say so clearly in metadata.
+If the project is narration-led, produce or source narration. Read
+`skills/meta/voice-performance-director.md`, then apply `script.voice_performance`
+and each section's `delivery_cues` when building TTS requests. Use
+`provider_text` when present, map cues to provider controls, and record the
+applied settings on each narration asset. If it is text-led or music-led, say so
+clearly in metadata.

 ### 4. Use Metadata For Feasibility Truth

@@ -109,6 +114,7 @@ Recommended metadata keys:
 - `tool_path_map`
 - `reusable_assets`
 - `narration_assets`
+- `voice_performance`: sample approval path, provider settings, and whether delivery cues were applied
 - `scene_asset_index`
 - `blocked_assets`

@@ -117,7 +123,8 @@ Recommended metadata keys:
 - the asset path is explicit per scene,
 - reusable assets are actually reused,
 - missing capabilities are surfaced honestly,
- every referenced file exists.
+- every referenced file exists,
+- narration-led assets apply the approved voice-performance settings.

 ### Mid-Production Fact Verification

@@ -135,6 +142,8 @@ the AI model's training data — it may be wrong or outdated.
 - Using high-variance generation when a deterministic asset would work better.
 - Rebuilding the same title or label system repeatedly.
 - Hiding failed asset paths instead of reporting them.
+- Treating TTS as raw text-to-audio. Narration-led animation needs pauses,
+  emphasis, and pace cues carried from the script into the generated audio.
 - Treating "consistency" as "same prompt every time." Good animation keeps a recognizable world while still letting each beat feel fresh.


@@ -11,6 +11,7 @@ This stage turns the approved proposal into animation-ready beats. The script mu
 | Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
 | Prior artifact | `proposal_packet` from Proposal Director | Selected concept, animation mode, target duration, reuse strategy |
 | Optional artifact | `research_brief` from Research Director | Data points, audience insights, accuracy constraints |
+| Meta skill | `skills/meta/voice-performance-director.md` | Structured TTS delivery cues for natural, expressive narration |
 | Tools | `transcriber` | Optional source transcript support |

 ## Process
@@ -41,6 +42,11 @@ Each section should express ONE clear visual idea:
 - **Comparison** — show two things side by side (split screen or sequential)
 - **Conclusion** — land the insight (hold + emphasis)

+If the piece is narration-led, also create `voice_performance` and section
+`delivery_cues` using `skills/meta/voice-performance-director.md`. Motion-heavy
+videos need vocal breathing room: mark pauses where the viewer must absorb an
+animation, and mark emphasis where a reveal, transform, or comparison lands.
+
 **Animation mode affects writing style:**

 | Mode | Writing Style |
@@ -82,6 +88,7 @@ Recommended metadata keys per section:
 - `narration_plan`: how narration relates to visual (describes / complements / silent)
 - `visual_priority`: what the viewer should focus on (the animation, the text, the data)
 - `hold_time_seconds`: minimum visual hold time after this section's content
+- `delivery_cues`: pace, energy, emphasis, pause timing, and provider-ready narration text for TTS
 - `data_source`: if this section uses a research data point, reference it

 ### 6. Research Integration
@@ -101,6 +108,7 @@ Before submitting the script, verify:
 - [ ] Every section supports ONE strong visual idea
 - [ ] On-screen text is concise (phrases, not paragraphs)
 - [ ] Timing is animation-friendly (holds budgeted)
+- [ ] Narration-led sections include concrete delivery cues and a voice-performance sample section
 - [ ] Word count is within ±10% of target duration
 - [ ] Animation mode is respected in writing style
 - [ ] Research data points are integrated (if research_brief available)