# Chatterbox forced-alignment Shorts render pattern

Session learning from producing consecutive Everyday Red Flags / TrueTraceShorts videos with Chatterbox cloned voiceovers and forced alignment.

Use this when rendering final-near AutoShorts/TrueTraceShorts videos with Chatterbox and the user expects Telegram-playable review packages.

## Current user voice standard

The current accepted ERF/AutoShorts voice standard is **Gianna premium female reference clone v1**:

- `voice_mode=clone`
- `reference_audio_filename=Gianna.wav`
- warm semantic/performance chunks
- approx. 500ms inter-chunk pauses
- `speed_factor=1.0`
- `temperature≈0.80`, `exaggeration≈0.52`, `cfg_weight≈0.50`

Older Taylor/Scientific examples in existing renderers are historical patterns only. Do not silently render a new final-near ERF video with Taylor or EdgeTTS when the package/version says Gianna.

## When to use

- Final social video language is English.
- Voice is Chatterbox `Taylor.wav` with the Scientific Abstract Reading style/preset.
- The user has accepted clean visual style: AI/generated scene images + voiceover + subtitles only.
- Thumbnail should **not** be required, attached, or set unless explicitly requested; user sets thumbnails manually.

## Pipeline

1. Pick the next Everyday Red Flags topic from normal-person scam self-defense, not AI-workflow content by default.
   - When the user simply says “erstelle das nächste Video”, proceed autonomously; do not ask which topic unless the recent sequence or constraints are genuinely ambiguous.
   - Good sequence examples: delivery SMS scam, Hi Mom/new-number scam, bank fraud alert / one-time-code scam, fake parking QR-code sticker scam.
   - Useful next-topic backlog: marketplace buyer courier scam, fake support popup, fake invoice bank-detail change, package customs fee, WhatsApp verification-code request, fake QR menu/payment page.
   - Structure: one visible screen, one red flag, one safer move, memorable rule.

2. Generate/select 6 premium vertical scene keyframes.
   - 9:16 portrait.
   - Realistic everyday phone/screen setting.
   - No arrows, boxes, labels, circles, watermarks, logos, or renderer-like graphics.
   - AI-generated screen text is acceptable only when visually inspected; critical UI/copy should be simple and generic.

3. Render Chatterbox voiceover.
   - Current accepted ERF/AutoShorts voice: `Gianna.wav` reference clone, warm semantic chunks, approx. 500ms inter-chunk pauses, `speed_factor=1.0`, `temperature≈0.80`, `exaggeration≈0.52`, `cfg_weight≈0.50`.
   - Keep `speed_factor=1.0`; pace by punctuation, chunk boundaries, and sentence linking — not time-stretching or speed changes.
   - Prefer connected spoken phrasing with colons, em dashes, and combined short sentences when the user says sentence-end emphasis sounds unnatural.
   - Save WAV plus metadata with params, script hash, duration, and output SHA256.
   - For humaner sentence endings, join related micro-sentences with dashes/colons/semicolons and chunk by meaning. Example: `This app says you earned money — that is the hook.` Avoid a pattern where every sentence ends with the same falling TTS cadence.

4. Extract word timings from the final WAV.
   - Chatterbox does not expose reliable provider WordBoundary events.
   - Use `faster_whisper` with `word_timestamps=True` on the rendered WAV.
   - Store `*.faster_whisper_words.json` with model, language, duration, segments, and per-word start/end/duration.

5. Build subtitle segments from source-script punctuation + phrase breakers.
   - Do not rely only on ASR-token punctuation; it may drift or be stripped.
   - Avoid cross-sentence chunks.
   - Keep short static phrase blocks; for long phrases, split into two balanced rows.
   - Render only the currently spoken word in yellow/active state; all other words remain fixed in place.

6. Render final MP4.
   - Output: `1080x1920`, `setsar=1,setdar=9/16`, `yuv420p`, 30 fps.
   - Motion: subtle image push-in/crossfade is fine.
   - Renderer overlays: subtitles only. No caption boxes, progress bars, labels, cards, arrows, or circles.

7. QA before delivery.
   - ffprobe width/height/SAR/DAR/fps/duration.
   - Extract QA frames around beginning/middle/end.
   - Inspect at least one subtitle frame and the contact sheet.
   - If the first QA frame has no captions yet, inspect a later frame with active subtitles; do not treat a clean no-subtitle hook frame as subtitle QA.
   - Check: no black bars, no clipped subtitles, no unwanted overlays, no obvious logos/watermarks/fake-text disasters.
   - For AI keyframes with intentional QR-code-like patterns, QR blocks are acceptable; block only distracting readable fake text, real logos, watermarks, or severe anatomy/UI artifacts.

8. Build private YouTube upload package.
   - `thumbnail_path=None` by default for this user.
   - `privacyStatus=private` only.
   - Include `containsSyntheticMedia=True` and made-for-kids false with reason.
   - Validate hash-bound approval gate.

9. Stage media for Telegram.
   - Copy MP4 into Hermes media cache / allowed media path.
   - Final review message must include:
     - playable `MEDIA:/...mp4`
     - proposed title
     - engaging description
     - QA metadata
     - exact `APPROVED_FOR_PRIVATE_YOUTUBE_UPLOAD ...` command
     - duration immediately after the approval code block.

## Pitfalls

- Do not evenly distribute word highlights over the script or sentence duration; it looks wrong because Chatterbox has real pauses and emphasis.
- Do not fix unnatural sentence-end emphasis by slowing Taylor down. Keep speed at `1.0`; rewrite the voice script into semantic chunks, reduce hard full-stop cadence, use shorter pauses around 520ms, and regenerate alignment/package hashes.
- Do not produce one-word-only captions by default; use stable phrase blocks with active-word highlight.
- Do not forget source punctuation when grouping ASR words; otherwise phrases can feel semantically odd even if timing is correct.
- Do not attach thumbnails unless explicitly requested; the current user workflow is manual thumbnail selection.
- Do not report success from package generation alone; verify actual MP4 hash, ffprobe metadata, and playable media-cache path.