Video to Shorts Skill
Video to shorts skill: turn a long video (podcast, interview, talk, webinar, stream, YouTube video) into vertical short clips for TikTok, Instagram Reels and YouTube Shorts, then post them to one or many accounts with WoopSocial. Transcribes with word timestamps (free local faster-whisper, your own Groq or OpenAI key, or an existing SRT/VTT), scores every candidate moment with a clip rubric (hook, standalone, payoff), cuts 1080x1920 clips with ffmpeg, removes pauses, keeps the speaker in frame, burns word-by-word captions and a hook line, normalises the audio, and writes titles and captions. Works on Mac, Windows and Linux with ffmpeg and Pillow; no paid API required. Use when someone says "video to shorts," "clip my podcast," "turn this video into shorts," "make reels from my video," "podcast clips," "long video to short clips," or "repurpose my YouTube video." Clips only what the user owns or has permission to use, confirms before anything posts. Standalone: needs no other skills.
Video to Shorts Skill
One long video holds a week of short clips, if you pick the right moments. Most clips fail for the same reasons: they open on "so, like I was saying", they need the rest of the episode to make sense, they end before the point lands, the captions sit under TikTok's buttons, or the speaker is cut out of the frame.
This skill does the whole job: transcribe, find and score the moments, cut them vertical with captions, show the user, post through WoopSocial after a yes, and read the results back. Everything it needs is in this folder.
Four commitments:
- Only footage the user may use. Their own video, or someone else's with permission. Ask.
- Moments that stand alone. A stranger must understand the clip with no context.
- Nothing posts without a yes. Show the clips, titles, captions, accounts and times first.
- No invented claims. Titles and captions say what the clip says; no made-up quotes or numbers.
Step 0: Setup and the source
Run python3 scripts/check_setup.py (on Windows use py instead of python3 in every command). It reports ffmpeg, Pillow, transcription routes and
OpenCV, with the install command for the user's system. Required: ffmpeg and Pillow.
Then ask, in one message, only what you can't see:
- Which video (a file path; for a YouTube video they own, the file from YouTube Studio).
- Is it theirs, or do they have permission? Clips of someone else's content need the owner's OK or a clipping program's brief, plus a credit line. No permission: stop.
- Who it's for and which accounts post (TikTok, Instagram, YouTube, how many each).
- Do they have a transcript (an .srt or .vtt from YouTube Studio or their podcast host)?
- Brand colour for the highlighted caption word, and anything that must not be clipped.
Step 1: Transcribe
python3 scripts/transcribe.py VIDEO --out work/
Routes, best first. Explain the trade-off once and use what the user has:
| Route | How | Cost and speed |
|---|---|---|
| Existing transcript | --from captions.srt | Free, instant; word timing is estimated, so captions are a little less tight |
| Groq | GROQ_API_KEY set | About $0.04 per hour of audio, a minute or two per hour; audio goes to Groq |
| OpenAI | OPENAI_API_KEY set | whisper-1, which OpenAI plans to retire in February 2027 |
| Local | pip install faster-whisper | Free and private; on a laptop roughly half to one times the video length with --model small, faster with --model base |
It writes work/transcript.txt (one timestamped line per sentence) and work/transcript.json
(every word with timings).
Step 2: Find and score the moments
Read the whole transcript.txt. List 8 to 12 candidates and score each with the rubric in
references/clip-rubric.md. In short:
- Hard gates (fail one and it's out): the first sentence makes sense with no context; one complete idea; no intro, outro, sponsor read or crosstalk; no music that isn't theirs.
- Score out of 100: hook in the first 3 seconds (25), stands alone (20), payoff or turn (20), emotion or energy (15), specifics like numbers, names, a story (10), strong last line (10).
- Ship 70 and up, review 55 to 69, drop the rest.
- Length: 25 to 45 seconds by default, 60 at most; up to 90 only for a story scoring 85+. Keep clips with any third-party audio or footage at 60 seconds or less (YouTube blocks longer Shorts with a Content ID claim).
- Spread: no overlaps, clips from across the video, one per sub-topic.
Every clip starts on the first word of a sentence or of a clause that stands alone, and ends on
the last word of a sentence. Skip the warm-up ("I think one of the things..."); end before the
trailing "so yeah". Read the words just before your start and just after your end in
transcript.json. The script fixes small slips and warns about the rest; when a clip starts on a
clause on purpose ("if folks have seen Groundhog Day..."), set "snap": false. Inside a clip, list
rambles and fillers like "kind of" in "cut": [[start, end], ...].
Default 25 to 45 seconds. Over 45 needs a score of 85+ and a turn around 15 and 30 seconds; name those lines. Show the user a table (start, end, length, hook line, score, why) and let them pick, usually 3 to 5.
For each pick write:
- hook: 3 to 8 words on screen for the first 3.5 seconds, the clip's promise in plain words. It must not repeat words the speaker says in the first 10 seconds.
- title: for YouTube Shorts, under 70 characters, main search words first.
- caption: for TikTok and Reels: the search phrase first, one line of context, a question or reason to follow, 3 to 5 specific hashtags. Credit the speaker if it isn't the user.
Step 3: Check the framing, then render
Write clips.json (format at the top of scripts/make_shorts.py, example in
examples/nasa-interview/clips.json), then preview the crop:
python3 scripts/make_shorts.py clips.json --transcript work/transcript.json --out shorts/ --preview
Open every preview-XX.jpg. Each shows three frames with the planned vertical crop. If the
box misses the speaker, set focus_x (0 = left edge, 1 = right edge) on that clip; for two
people far apart, a screen share or a wide shot, set "reframe": "fit" (whole frame on a blurred
background). With OpenCV installed the script finds one speaker on its own, but still look.
Then render:
python3 scripts/make_shorts.py clips.json --transcript work/transcript.json --out shorts/
Each clip comes out 1080x1920 H.264 with AAC at -14 LUFS; pauses over 0.45 seconds removed,
including silences the transcriber hides inside long words; stutters, "um", "uh" and "you know,"
cut; a slight punch-in at every cut so jump cuts look intended; word-by-word captions inside the
area no platform covers; and the hook on a white box for the first 3.5 seconds.
Rendering takes about as long as the clips themselves; --best is slower and slightly smaller.
Details: references/shorts-specs.md.
Watch the first 5 seconds of every clip and open contact-sheet.jpg. Fix and re-render
(--only 02) when: the clip opens mid-thought, a caption hides the face, the hook and the first
words say the same thing, or the end trails off. Read the first caption group aloud: if a stranger
wouldn't understand it, the start is wrong. Resolve every warning in manifest.json.
Step 4: Post with WoopSocial
How to connect, upload and post: references/woopsocial.md. Short version:
- Check the connection with
social_accounts_list. Not connected: give the one connect path for the agent you're running in (free plan: 2 social accounts), thenoauth_create_authorizationper platform. - Upload each clip with an upload session (
media_uploads_create_sessionwith the byte size fromshorts/manifest.json,python3 scripts/upload_parts.py session.json shorts/clip-01.mp4,media_uploads_complete_session). Clips over 10 MB upload in several parts; the script handles that. - One post per clip per platform: TikTok
postType: VIDEO, InstagrampostType: REEL, YouTube withtitleandprivacy, FacebookpostType: REEL. Runposts_validate. - Show the plan as one table (clip, platform, account, title or caption, time with timezone)
and get a clear yes. Then
posts_createand confirm each withposts_get.
Several accounts: never the same clip at the same time everywhere. Give each account its own clips
or at least its own hook and caption, and stagger the times with SCHEDULE_FOR_LATER.
Step 5: Read the results
After 3 to 7 days, read social_account_posts_list (views, likes, comments, shares, saves where
the platform reports them, with the collection date; missing means "not reported", not zero).
Keep clips-log.md: source video, timestamps, hook, length, platform, numbers. Then:
- Clips that beat the account's usual numbers: clip more from the same part of the video, same kind of moment.
- Views but no follows: stronger last line or a reason to follow in the caption.
- Weak first 3 seconds (fast drop): start later, on the punchline, with a sharper hook.
Never estimate numbers the platform didn't report.
Quality bar
Before showing anything: would a top clipping editor post this? Reject a clip that needs context, opens on a warm-up, cuts off the speaker, hides the face behind text, or ends mid-thought.
Edge cases
- No speech in a part (music, b-roll): the transcript has gaps; don't clip across them.
- Two speakers far apart:
fit, or two separate clips each on one speaker. - 720p or smaller source: a face crop gets soft. Prefer
fit, or warn the user. - Not English: transcription detects the language; write hooks and captions in that language.
- No permission for the footage: stop and say why.
- Over 3 minutes: YouTube Shorts and TikTok's API cap is 3 minutes; split it.
References
references/clip-rubric.md: gates, scoring, lengths, opening and ending rules, examples.references/shorts-specs.md: frame, caption and audio specs, safe areas, encode settings, platform rules for reused content.references/woopsocial.md: connect, upload, post and read results.
- Downloads
- Security audit
- Review
- Last updated
- 2w ago
- Current version
- v1.0.0
- License
- MIT-0
