podcast-shorts

name	podcast-shorts
description	Turn a raw podcast or interview recording into captioned vertical shorts staged as Buffer drafts. Invoke on "podcast to shorts", "cut podcast shorts", "clip this episode", "/podcast-shorts", or when the user hands over a long recording and asks for social clips.

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.

The hidden audio-pts gap (read this before changing any audio flag)

The master's audio filter graph (atrim → concat → atempo → loudnorm) can emit a timestamp jump at a cut seam while the audio CONTENT stays continuous. Players and platform ingests play sample-continuously and never show it — masters sound perfect. But any re-encode with a timestamp-aware filter materializes the gap: aresample=async=1 turns it into time-squeezed audio followed by seconds of real silence at the start of the clip.

Rules:

• The composite's audio chain ends asetpts=N/SR/TB (timestamps rebuilt from sample position — continuous by construction).
• Delivery encodes use -af "asetpts=N/SR/TB" and NEVER aresample=async=1.
• QA compares decoded audio, not just frames: a defect like this is invisible in every visual check.

QA gate spec (qa_delivery.py)

check	bar
silencedetect regions	count == the master's (a new region = injected dropout)
audio cross-correlation vs master	abs lag <= 25ms at 0.2/1/2/5/10s windows
first video packet	keyframe at pts 0
packet timing	uniform CFR
duration	within 0.1s of master

Gotchas

• Whisper word-END stamps run ~0.1s early: never clamp a cut to the next word's start minus epsilon, or continuous speech collapses the tail and chops the final word.
• Never overwrite a published object under the same filename — CDNs serve stale bytes for an hour or more. Version filenames and byte-verify (sha256) what the URL serves.
• Buffer: pace mutations ~1s apart (rate windows at 15m and 24h); editPost is a full replace, resend text + assets + metadata with any change.
• gsap is fetched from jsdelivr on first run (GreenSock license — not committed).