A Short is a Top 3 countdown of moments from one source video: the audience picks the moments through YouTube's most-replayed heatmap, only the bytes around them are downloaded, and a Diffusion Studio project built from the bundled template crops each moment to 9:16, captions it word by word, and bleeps its swears. The pipeline runs in order, research, moments, download, project, framing, captions and bleeps, verification, export, and every stage has a bundled script or template in this folder (scripts/, template/) so the agent fills in parameters rather than rewriting the plumbing. Free paths come first everywhere, YouTube's heatmap and auto-captions instead of Diffusion's paid media listen and media transcribe, since credits cost real money and the free plan is a one-time 50.

Before any download, state its size in MB or GB and choose the smallest viable option, never a full video (a 54-minute 4K stream is about 5 GB), this is a hard preference, not a courtesy. Channel format decisions live in the channel's own docs (for TheShortlist, C:\Users\DavidOdunjo\Codebase\YouTube\TheShortlistOfficial\docs\decisions.md), read them first and let them win over the house style below when they disagree.

Diffusion Studio docs

Defer to the app's own agent docs for every JSX and tool detail, they are versioned with the install and this skill doesn't repeat them. They live at %LOCALAPPDATA%\DiffusionStudio\app-<version>\resources\docs, the version changes on update, so glob app-* or take the path from the MCP server's instructions. Read skills/editor.md first, then guides/walkthroughs/podcast-clip.md (the closest workflow to this one) and the reference/jsx pages for whatever is being touched: captions.md, transitions.md, keyframes.md, rect.md for masks, sequences.md, and the Ids section of module.md. Drive the app from the CLI at %LOCALAPPDATA%\DiffusionStudio\bin\diffusion.cmd when the MCP server is down, both surfaces take the same tools.

Finding moments

Search with yt-dlp --flat-playlist "ytsearch10:<streamer> <topic>" and confirm the uploader from each result's channel_url, since guessed handles are often someone else (@marlon is not Marlon). Keep yt-dlp current with yt-dlp -U, winget's upgrade fails on the portable package. Pipe yt-dlp -j --skip-download <url> into bun scripts/peaks.ts for the top most-replayed peaks, a video only days old may have no heatmap yet, so pick an older one or wait. Then fetch the free word-level captions with yt-dlp --skip-download --write-auto-subs --sub-langs en --sub-format json3 -o "<project>/_session/%(id)s" <url> and read about a minute either side of each peak to learn what actually happens there. Rank by heatmap value, highest is #1, so the order is audience-ranked rather than the agent's taste. A moment must stand alone with no prior context, open on its hook, and end on a clean line, never on a swear sitting on the cut; the whole Short lands around 45 to 55 seconds.

Downloading

yt-dlp --download-sections does not work for this, YouTube's fragmented MP4 cannot be seeked so ffmpeg reads from the start, ffmpeg's HTTP seeks on VP9 hang, and --force-keyframes-at-cuts re-encodes 4K on the CPU. Use python scripts/clip.py <url> <project> <name>=<start>-<end> ... --estimate to print the size (it only fetches the two stream headers, about 2 MB), report it, then rerun without --estimate. It reads each WebM stream's Cues index, fetches only the clusters covering each range padded by 8 seconds, and writes assets/a-roll/<name>.mp4, VP9 1080p (format 303) and Opus (251) by default; three moments of about 2.5 minutes is roughly 50 MB. It aligns audio to video itself, because the spliced audio starts up to 8 seconds before the video and ffmpeg rebases each input to zero separately, and it fails loudly if the muxed streams don't both start at zero. Each clip prints its src, fileZero (the source time of its first frame) and the unpadded sourceIn/sourceOut in the file's own time, paste those into segments.ts with a rank. Stream URLs expire after a few hours, rerun if a fetch starts failing.

Building the project

Each Short is its own folder, named by its number then its slug (for TheShortlist, C:\Users\DavidOdunjo\Videos\TheShortlist\<NNN>-<slug>\, e.g. 001-marlon-vs-speed-10k-fifa-wager-top-3). Only the folder carries the number. Copy template/index.tsx, template/segments.ts and template/bleeps.ts into it, then diffusion open -b <abs dir>, which keeps the files and adds the project record to package.json. segments.ts is the single source of truth for rank, clip, fileZero and trim, in countdown order #3, #2, #1, and everything else derives from it. The app rewrites index.tsx after every compile to stamp ids, so re-read it before each edit. The scene carries id="short", so check short, capture short and export short address it without looking the id up. Name the scene, the export file and upload.json's video path after the content, one lower-kebab-case slug for all three, never a generic name like short-001 (marlon-vs-speed-10k-fifa-wager-top-3).

clipping-streamer-shorts