Media Clipper — source-agnostic video clipping (any URL → HD clip + transcript)

TRIGGER

• The user gives a video URL (YouTube, Vimeo, X/Twitter, Instagram, TikTok, Twitch, Facebook, or any of 1731+ sites) plus start/end timestamps (or asks you to pick them).
• The user says: "clip this video", "cut a segment from this link", "download a clip of ...", "make a clip from 3:00 to 3:45", "extract the best quote from this video".
• The user wants a short clip + transcript + suggested hook/caption for posting.

Idea reference: https://x.com/hooeem/status/2092174022070936051 — the "YouTube Clipper" workflow this skill generalizes.

What this skill does

Takes any video URL + timestamps and produces: a frame-accurate HD clip (MP4), a plain-text transcript of the clip, and (via sub-agents) best quotes, a hook, and an X caption. Source-agnostic from day one: yt-dlp supports 1731+ sites — no site is special-cased.

The 6-stage pipeline

Steps 1–3 are executed by the scripts in scripts/. Steps 4–5 are executed by the agent via delegate_task sub-agents (the scripts are NOT involved). Step 6 delivers the result.

1. acquire    download.py  <url>              -> best-quality video+audio (merged MP4)
2. cut        clip.py      in.mp4 --start --end -> frame-accurate HD clip (re-encode)
3. transcribe transcribe.py clip.mp4           -> plain-text transcript (faster-whisper)
4. analyze    Researcher sub-agent            -> best quotes / hooks / claims / interesting points
5. write      Writer sub-agent                -> X post / caption from the analysis
6. deliver    return clip + transcript + quotes + hook + caption to the user

Audio-only variant: add --audio-only (to clip.py or pipeline.py) and step 1 downloads the best audio stream, step 2 writes a standalone .m4a instead of a video clip — e.g. to rip a song or a chorus from a music video. Steps 3–6 are unchanged (the transcript is still produced and analyzed).

Step 4 — Researcher sub-agent (delegate_task)

You are a Researcher. I have a video clip and its transcript.
TRANSCRIPT:
<paste the full transcript from transcribe.py here>

CLIP METADATA: <title, uploader, duration, source URL>

Task: identify the 3-5 most quotable, shareable moments from the transcript —
verbatim quotes (exact wording), the single best hook sentence, any surprising
claims or facts, and the emotional high point. For each quote give the exact
text and why it would land on X (Twitter). Output a concise markdown list.
Rules: quotes must be VERBATIM from the transcript — never paraphrase inside
quotation marks. If the transcript is empty or unintelligible, say so and
suggest the next best step (e.g. re-cut a longer segment).

Step 5 — Writer sub-agent (delegate_task)

You are a Writer. Here is the Researcher's analysis of a video clip:
<paste the Researcher's output here>

CLIP METADATA: <title, uploader, duration, source URL>

Task: write (1) a punchy X post (<=280 chars) with the hook + best quote,
(2) 2 alternative hooks (<=80 chars each), (3) 3 hashtags, and (4) a 1-line
caption for reposting elsewhere. Match the source's tone. Do not invent facts
not present in the analysis. Output a clean copy-paste-ready block.

Step 6 — Deliver

Return to the user: the finished clip path, the transcript path, the best quotes, the suggested hook, and the suggested X caption. Never deliver an unverified clip — see Verification below.

Source-agnostic note

yt-dlp supports 1731+ sites (YouTube, Vimeo, X/Twitter, Instagram, TikTok, Twitch, Facebook, Reddit, SoundCloud, and more). No site is special-cased: the same URL + timestamps flow works for all of them. If a specific site breaks, it is a yt-dlp extractor issue — update yt-dlp (python bin/yt-dlp -U) and retry.

Script reference table (scripts in scripts/)

Script details

• download.py <url> [--out DIR] [--format best|bestvideo+bestaudio|audio] — default bestvideo+bestaudio (merged HD via ffmpeg, MP4). Saves to --out dir, or ./clips/<title>-<id>/ by default. Prints title, duration, resolution, uploader, file path.
• clip.py <in.mp4> <out.mp4|out.m4a> --start MM:SS|SS[.frac] --end MM:SS|SS[.frac] [--duration MM:SS] [--audio-only] — frame-accurate: -ss after -i, re-encode libx264 -crf 18 -pix_fmt yuv420p -c:a aac, original resolution preserved. Exactly one of --end/--duration required. Output parent dir must exist (no auto-create). --audio-only drops the video stream and writes a standalone audio file (AAC, use a .m4a output name) — e.g. to rip a song or a song segment from a music video.
• transcribe.py <in.mp4|in.m4a|in.wav> [--out TXT] [--model tiny|base|small|medium] [--language en] — default model base, CPU int8. First run downloads the model to the HF cache. Writes a clean plain-text transcript (no timestamps in the TXT).
• pipeline.py <url> <start> <end> [--out DIR] [--model base] [--keep] [--audio-only] — orchestrates the three stages; removes the large source download after clipping unless --keep. The clip and transcript are always kept. --audio-only downloads the best audio stream and cuts a standalone .m4a instead of a video — handy for ripping a song or a song segment from a music video.

Portability

• Bundled bin/yt-dlp — the skill ships its own yt-dlp (Python zip-app, runs under python on Windows), so no install step is needed on the target machine.
• Relative paths only — scripts take file paths as arguments (CWD-relative); no hardcoded absolute paths anywhere. Works from any working directory.
• Python 3 stdlib for common/download/clip/pipeline; transcribe.py additionally needs faster-whisper (pip install faster-whisper).
• Copy the whole folder to any profile or machine (Windows/Linux/macOS) and it works as-is — only ffmpeg/ffprobe (or FFMPEG_PATH/FFPROBE_PATH) must be present.

Pitfalls

• Keyframe snap on fast cuts — -ss before -i with stream copy (-c copy) snaps to keyframes and can be off by seconds. clip.py always re-encodes with -ss AFTER -i for frame accuracy (slightly slower on long videos — that is the price of accuracy).
• faster-whisper first-run model download — the first transcription downloads the model (e.g. base ≈ 150 MB) into the HF cache; it can take a minute. Use --model tiny for a quick check, base/small for real work. If the machine is offline, transcription fails with a clean ERROR.
• yt-dlp site breakage — extractors break when sites change. Error message is clean; update yt-dlp (python bin/yt-dlp -U) and retry.
• Geo-blocks / private videos / 404s — yt-dlp fails with a clean ERROR + exit 1 (never a traceback). Tell the user the video is unavailable in this environment; do not attempt workarounds beyond updating yt-dlp.
• Audio-only fallback — if a source has no video stream (e.g. a podcast link), use --format audio in download.py; clip.py maps audio only if present (-map 0:a:0?) so video-only clips still cut fine. To extract a standalone song/segment from a music video (YouTube, Instagram, etc.), use --audio-only — e.g. python scripts/pipeline.py <url> 1:30 2:15 --audio-only writes an .m4a of just that segment.
• Long videos — the accurate cut decodes from the start of the source; for a 2-hour source, prefer cutting near the start or accept the decode cost. (Alternative: cut in two passes — fast keyframe seek then verify.)
• Windows paths in bash — pass native C:\... paths to the scripts; quote paths containing spaces.

Verification (mandatory before delivery)

1. After cutting, extract frames from the CLIP (use the sibling clip-editing skill's frames.py, or ffmpeg -ss 0.2 -i clip.mp4 -frames:v 1 frame.png) and visually confirm the content matches the requested segment.
2. ffprobe/probe.py the clip: duration ≈ end−start, resolution = source resolution.
3. Read the transcript TXT: word count > 0, content matches the clip's audio.
4. Only then deliver clip + transcript + quotes + caption. Never deliver an unverified clip.