yt-carousel CLI

Power-user alternative to the YouTube Producer carousel web flow. Logs in once, then downloads + transcribes + frame-extracts on your own machine — much faster than browser upload — and syncs everything to your library. You finish editing on the web.

This is not a replacement for the web app. It's a second way in for people comfortable on the command line.

Install

brew install yt-dlp ffmpeg     # required
cd cli && npm install
npm link                        # makes `yt-carousel` available globally

You'll also need the same Supabase env vars the web app uses:

export YT_CAROUSEL_SUPABASE_URL="https://<project>.supabase.co"
export YT_CAROUSEL_SUPABASE_ANON_KEY="<anon-key>"

Add those to ~/.zshrc to make them permanent.

Usage

yt-carousel login                                # one-time browser auth
yt-carousel https://youtu.be/abc123              # extract + upload
yt-carousel https://youtu.be/abc123 --frames 80  # pick 80 frames instead of 50

When it's done, it prints an editor URL like https://carousel.youtubeproducer.app/?generation=<id> — open that and you're straight into the carousel editor with frames and transcript already there.

Local (Riverside) mode

For podcasts recorded on Riverside with per-speaker raw video tracks. Point it at a folder containing the speaker-tagged transcript (Name (MM:SS.ms) blocks) and one raw video per host — video filenames just need to contain the speaker's name:

yt-carousel local ./episode-folder --title "Episode 42"

# or fully explicit:
yt-carousel local \
  --transcript riverside.txt \
  --speaker "Becky=becky-raw.mp4" \
  --speaker "Bhav=bhav-raw.mp4"

What it does differently from YouTube mode:

1. Parses the Riverside transcript into speaker-attributed utterances
2. Generates quote sequences locally with your LLM CLI (claude by default — no Gemini call, no generation slot used). Same rules as the backend: verbatim minus filler words, 10–30 words per line, an even 10–20 lines per sequence (every 2 lines = 1 slide, max 10 slides). --parser gemini uses the backend API instead.
3. Verifies each line's speaker by word-overlap matching against the transcript
4. Extracts a separate frame pool from each host's own video (default 60 frames per speaker from 3× oversampled candidates — talking-head footage is full of blinks and mid-word faces, so the sharpness filter gets more to choose from; --frames N to change)
5. Pre-builds the top carousel with speaker-correct frames: each slide half shows the person who actually said that line, sampled near the moment they said it. The editor opens fully assembled.

The generation lands in your library like any other; frames are tagged speaker:<Name> in the frame pool so you can filter by person while editing.

What it does locally

1. yt-dlp downloads the video as HQ mp4 (≤1080p) + auto-generated subtitles
2. Parses the .vtt into a plain transcript
3. ffmpeg extracts 2× the target number of evenly-spaced frames
4. Scores each frame with Laplacian variance (sharpness) and keeps the sharpest per time bucket
5. Calls /api/generate-sequences on the live web app to get quote sequences (DeepSeek)
6. Uploads frames + transcript + sequences to Supabase under your account, exactly the way the web flow does

Your session is stored at ~/.config/yt-carousel/session.json (chmod 600).

Auth flow

yt-carousel login spins up http://127.0.0.1:7777, opens https://carousel.youtubeproducer.app/cli-auth?port=7777 in your browser, and waits for the page to POST your Supabase session back. If you're already logged in, it's a single click.