podcast-shorts

podcast-shorts — transcript-anchored vertical clips

Raw recording → word-timestamped transcript → planned cuts → styled overlay render → one-pass master composite → QA gate → social encodes → Buffer drafts.

When to invoke

• A podcast/interview recording (ideally per-speaker video + WAV exports) needs to become vertical clips.
• The user describes moments by content ("the story about the pricing call") — the transcript layer turns that into timestamps.

Do NOT invoke for single-source talking-head recuts with no cutting plan, or for meme-style captioning.

Pack layout

<pack-dir>/
  pack.json            # the spec — see pack.example.json
  source/              # per-speaker video + lossless WAV exports
  transcripts/         # written by transcribe.py + plan_clips.py
  projects/clip_NN/    # HyperFrames overlay projects (compose_overlay.py)
  out/                 # masters + delivery encodes
  clips/               # word jsons, captions, buffer_urls.json
  review/framing.json  # optional: face_x overrides + cameo source ranges

pack.json schema

See pack.example.json. Per clip: slug, mode (square | wide | guest | duo), lead (speaker_a | speaker_b), start/end (source seconds), start_text/end_text (the words the clip must open and close on — anchors, not guesses), hook (two overlay lines), cta, optional kicker, speaker_names, cameo_text, tx_windows, drops, blocks. Top level: sources, framing_defaults, optional series (day-order slugs for Buffer).

Workflow

1. Transcribe — python3 transcribe.py <pack> [idx]. Whisper (word timestamps) per speaker track. Add your product names to ASR_FIXES first; whisper mangles proper nouns.
2. Plan cuts — python3 plan_clips.py <pack> <idx>. Anchors the cut on start_text/end_text word matches, jump-cuts silences, compensates whisper's early word-end stamps (END_COMP/BLEED), writes transcripts/clip_NN.cut.json including fade_start anchored to the last word.
3. Compose overlay — python3 compose_overlay.py <pack> <idx>. Graphics-only transparent HyperFrames project (footage never touches the browser). Keep every text card-host at data-start="0" — card hosts run their own scheduler clock, and a nonzero data-start fights the gsap timeline and flashes on frame 0.
4. Render — npx hyperframes render <pack>/projects/clip_NN/public --format mov -o <abs>/projects/clip_NN/renders/overlay.mov. ProRes 4444 alpha; delete after step 5 (300-800MB each).
5. Composite master — python3 final_composite.py <pack> <idx>. One ffmpeg pass: denoise, speed bake, crops, alpha overlay, loudnorm, end fade. The audio chain ends asetpts=N/SR/TB — do not remove it (see below).
6. Social encodes — ./make_delivery.sh. 8-bit yuv420p re-encode, both streams fresh, asetpts=N/SR/TB on audio.
7. QA gate — python3 qa_delivery.py delivery _social. Every clip must PASS before anything is hosted or drafted.
8. Stage drafts — host the encodes anywhere with public URLs, write clips/buffer_urls.json ({slug: url}) and clips/captions.json, then python3 buffer_schedule.py <pack> all go. Needs BUFFER_ACCESS_TOKEN and BUFFER_ORG_ID env vars. Drafts, not scheduled posts — a human reviews.