# Word-boundary caption sync + explicit solution gate

Session learning from a TrueTraceShorts Proof Short review where the user found captions irritating because they were not exactly simultaneous with the voiceover, and also noted that the video lacked a real solution/fazit.

## Trigger

Use this pattern when producing final-near Shorts with voiceover + subtitles, especially Proof Shorts / Digital Red Flags / mechanism reveal videos.

User-visible failure signals:

- subtitles lag or lead the voiceover;
- captions are approximated by sentence duration and feel “off” while listening/reading;
- the video explains a mechanism but the viewer does not leave with a concrete action;
- the ending feels like an observation rather than a solution.

## Caption timing rule

Do not rely on evenly distributing words across sentence SRT durations when a better timing source is available. For EdgeTTS, request word-boundary metadata directly:

```python
communicate = edge_tts.Communicate(
    script,
    voice,
    rate='+0%',
    boundary='WordBoundary',
)

async for chunk in communicate.stream():
    if chunk['type'] == 'audio':
        audio_bytes.extend(chunk['data'])
    elif chunk['type'] == 'WordBoundary':
        start = chunk['offset'] / 10_000_000
        duration = chunk['duration'] / 10_000_000
        word = chunk['text']
```

Build `WordCue(start, end, word, sentence)` from those offsets, then feed the existing static active-word caption renderer:

```text
EdgeTTS WordBoundary cues
→ 3–7 word static phrase segments
→ active spoken word highlighted/pulsed
→ phrase changes only at phrase/sentence boundary
```

This gives the Hormozi/TikTok-style feel the user prefers: several words remain stable, while the currently spoken word lights up exactly when spoken.

## Caption QA gates

Before delivery, verify and report:

- `caption_sync_source = edge_tts_word_boundary_offsets` or another forced-alignment source;
- `static_phrase_active_word = true`;
- no default one-word-only captions;
- no sliding word window where all visible words change each word;
- no subtitle box/bar unless explicitly requested;
- mobile-safe bottom placement;
- contact sheet inspected for clipping/legibility.

If WordBoundary / forced alignment is unavailable, label the render as approximation-only and do not present it as final-near.

## Explicit solution/fazit gate

Every Proof Short must answer the viewer’s post-watch question: “What do I do now?” Add a concrete end-state action, not just a clever line.

Good ending shape:

```text
Mechanism revealed → simple safe action → memorable rule
```

Examples:

- Calendar login trap: “Open the service yourself. Trust the app you opened, not the button that rushed you.”
- Invoice route trap: “Do not pay from the email. Verify route changes through a second channel.”

Review-package fields to include:

```json
{
  "usefulness_fix": "Concrete action the viewer should take",
  "takeaway": "Short memorable rule",
  "summary_fazit_present": true,
  "final_solution": "..."
}
```

## Pitfall

A video can be factually correct and still feel unsatisfying if it only diagnoses the trap. The final beat must solve the viewer’s immediate problem in one simple action.