Skip to content
Back to search

stream-clipper

SkillWorks with Claude CodeGitHub

Turn a Twitch, YouTube or Kick stream (a recording, or live while it is on) into ready-to-post vertical clips. Finds the moments where the streamer suddenly gets loud and chat explodes, scores them, and renders 1080x1920 Shorts/TikToks in the proven clipping-channel format - webcam big on top, gameplay below, one word at a time on the seam with exact word timing, jump cuts through dead air. Use for "clip this stream", "find the best moments in this VOD", "make shorts from this stream", "watch this stream live and clip it", clipping campaigns.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vladgermanyuk--stream-clipper/badge.svg)](/listings/vladgermanyuk--stream-clipper)

HTML

<a href="/listings/vladgermanyuk--stream-clipper"><img src="/api/listings/vladgermanyuk--stream-clipper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements: macOS (Apple Silicon recommended) or Linux, Python 3.10+, ~3 GB of disk for models, [Claude Code](https://claude.com/claude-code).

git clone https://github.com/vladgermanyuk/stream-clipper ~/.claude/skills/stream-clipper
cd ~/.claude/skills/stream-clipper
./setup.sh

`setup.sh` installs ffmpeg, yt-dlp, whisper.cpp and uv (Homebrew), creates two Python environments (`.venv` for the pipeline, `.align-venv` with PyTorch for voice separation and alignment) and downloads the models. On Linux, install those four tools with your package manager and run `SKIP_BREW=1 ./setup.sh`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 134 lines
  1. ---
  2. name: stream-clipper
  3. description: Turn a Twitch, YouTube or Kick stream (a recording, or live while it is on) into ready-to-post vertical clips. Finds the moments where the streamer suddenly gets loud and chat explodes, scores them, and renders 1080x1920 Shorts/TikToks in the proven clipping-channel format - webcam big on top, gameplay below, one word at a time on the seam with exact word timing, jump cuts through dead air. Use for "clip this stream", "find the best moments in this VOD", "make shorts from this stream", "watch this stream live and clip it", clipping campaigns.
  4. ---
  5. # stream-clipper
  6. One stream link in, a handful of clips worth posting out. Scripts do the heavy lifting: download,
  7. spike finding, transcription, layout, rendering, checks. You do the judging: which moments are funny
  8. or shocking to a stranger, where the clip starts and ends, and whether the finished clip is good.
  9. Run everything from this folder with `.venv/bin/python`.
  10. **Rules first.** Clip only streamers who allow it: an official clipping campaign or written permission.
  11. A campaign license usually covers posting the campaign's clips only, not reusing the footage elsewhere.
  12. Read the campaign rules before posting (name in the caption, hashtag, submission window, no cutscenes,
  13. no logos). Some campaigns ban "AI-generated videos": these clips are cut from real footage and nothing
  14. is generated, but if a campaign is unclear, tell the user to ask in its Discord. Posting is the user's job.
  15. ## Setup (once)
  16. `./setup.sh` (macOS with Homebrew; see README for Linux/Windows). It installs ffmpeg, yt-dlp,
  17. whisper.cpp and uv, creates two Python environments and downloads the models:
  18. | What | Used for |
  19. |---|---|
  20. | `.venv` (Python 3.10+): pillow, numpy, opencv-python-headless | everything except alignment |
  21. | `.align-venv` (Python 3.12): torch, torchaudio, soundfile, demucs | clean voice + exact word timing |
  22. | `models/ggml-base.en.bin` (148 MB) | quick transcripts of 60 candidate moments |
  23. | `models/ggml-large-v3-q5_0.bin` (1.1 GB) | caption text |
  24. | `models/face_detection_yunet.onnx` | finding the webcam |
  25. The renderer falls back step by step when something is missing (no `.align-venv` -> no voice separation
  26. and no alignment; no large-v3 -> turbo/small/base), so a half setup still works, with worse captions.
  27. ## The run (a recording)
  28. Work folder per stream: `work/<name>/`. Note the start time; the user will ask how long it took.
  29. 1. **Audio** (about 40 s for a 9-hour Twitch VOD; pieces download in parallel):
  30. `scripts/fetch.py audio <url> work/<name>/audio.mp4`
  31. Chat: YouTube replays may have one (`yt-dlp --skip-download --write-subs --sub-langs live_chat`).
  32. Twitch has no official chat download; use a chat file only if the user exported it themselves.
  33. 2. **Spikes** (about 20 s per 9 h): `scripts/signals.py work/<name>/audio.mp4 work/<name> [--chat chat.json]`
  34. The 60 biggest moments that are loud against the streamer's own 10-minute level AND loud in absolute
  35. terms. Sleep and AFK hours of marathons are ignored (`--all-hours` turns that off).
  36. 3. **Transcripts** (about 1 min): `scripts/transcribe_candidates.py work/<name>/audio.mp4 work/<name>`
  37. 40 s around each spike -> `candidates.md`. The stream is decoded once into an exact timeline
  38. (`audio16k.s16`), so this also works on 40+ hour marathons. Game dialogue gets mixed in; that is fine.
  39. 4. **Judge. This is your job.** Read `candidates.md` and score every moment 0-10:
  40. - 9-10: a stranger scrolling stops and gets it instantly (a clear funny or shocking event and the
  41. streamer's reaction to it).
  42. - 7-8: strong reaction with a clear cause.
  43. - 4-6: loud but no context (yelling at chat, music, donation sounds, inside jokes).
  44. - 0-3: ads, menus, story cutscenes, game TV, dark scenes, the streamer asleep.
  45. Write `scores.md` (every moment, score, one-line reason) and `picks.json` for the 7+ ones:
  46. `{"id": "c1-crash", "start": <first second of the hook line>, "peak": <the payoff>, "end": <right after the punchline>, "title": "...", "beats": [{"t": <stream second>, "text": "*CHECKING*"}]}`
  47. Times are stream seconds. Aim for 8-20 s after jump cuts. Start on the line or action that hooks
  48. (a question, a dare, "watch this"), end right after the payoff, no trailing chatter. `beats` are
  49. optional one- or two-word action captions for silent action the viewer must follow.
  50. Title (for the post caption, not drawn on the clip): streamer's name first, what happens, plain
  51. words, under 55 characters.
  52. 5. **Look before you render.** For each pick, preview the picture:
  53. `scripts/fetch.py video <url> <start> <end> work/<name>/prev-<id>.mp4 --format "480p/360p"`
  54. then a frame strip (`ffmpeg -i prev.mp4 -vf "fps=1/3,scale=240:135,tile=15x1" -frames:v 1 strip.jpg`).
  55. Drop the pick if the payoff is not visible (dark scene, happens off screen, cutscene). Candidate
  56. timings can be 2-3 s off; set `peak` where the payoff actually is on screen.
  57. 6. **Layout:** `scripts/find_layout.py <url> work/<name> [--at <a second inside the stream>]`
  58. Finds the webcam (the face that stays in one place; game faces move) and writes `layout.json`. Look
  59. at the probe frame. If the streamer moves the camera, put `"facecam"`/`"face"` into that pick.
  60. 7. **Render** (about 15 s per clip): `scripts/render.py <url> work/<name> [--only c1-crash]` -> `work/<name>/clips/`
  61. 8. **Check:** `scripts/check_clip.py work/<name>`. Hard checks (fail = fix before showing anyone):
  62. audio and video start together, no two captions at once. It also lists every word with its time and
  63. flags words that do not sit on the streamer's voice, and writes `check/<id>.jpg` (the caption band at
  64. 5 fps). Read the words, look at the sheet, fix picks and re-render with `--only`.
  65. 9. **Report** in plain words: stream length, moments found, kept, minutes taken, the clips. Remind the
  66. user of the campaign's caption, hashtag and submission window.
  67. ## Clip style (`split`, default)
  68. Copied from a top clipping-channel Short (399K views, 6.9 s), measured frame by frame:
  69. - 1080x1920. Webcam on top, 796 px (41%), cropped tight on the face (face about a third of the width,
  70. `face_zoom` 3.4). Game below, 1124 px, centre crop zoomed 1.2x. Hard seam, no border.
  71. - Captions: one word at a time, held until the next word, caps, narrow bold sans (DIN Condensed Bold;
  72. Impact as fallback), white with a thick black outline and a hard black shadow, centred on the seam.
  73. - `*ACTION*` captions only in real silences of 0.7 s or more.
  74. - Jump cuts: silent stretches over 1.2 s shrink to two 0.35 s pieces, except around the payoff, which
  75. always plays in full. A 0.13 s red flash on the loudest moment near the peak.
  76. - If the game goes to a black loading screen ("wasted", "busted"), the last game frame is frozen over it.
  77. - No title card, no repeated hook: the clip starts on its own hook line.
  78. - `"style": "classic"` (in layout.json or a pick) gives the older look: title card, peak shown first.
  79. ## Captions: exact words
  80. Captions are burned in, so they must be right. Pipeline (render.py `words_of`, about 15 s per clip):
  81. 1. **Clean voice.** Demucs (htdemucs) separates the streamer's voice from game sound and music. Speech
  82. over a game is what makes whisper mishear ("five" -> "well").
  83. 2. **Text.** whisper.cpp large-v3 (q5_0) with DTW token timing (`-dtw large.v3 -nfa`; DTW needs flash
  84. attention off) on the clean voice. Turbo, small and base dropped or misheard words in testing.
  85. 3. **Exact timing.** `scripts/align_words.py` (in `.align-venv`): wav2vec2 forced alignment
  86. (torchaudio WAV2VEC2_ASR_LARGE_LV60K_960H, the WhisperX method) pins every word to the clean voice.
  87. Each phrase is aligned only in its own window; where the aligner and whisper disagree by more than
  88. 0.35 s (it can latch onto the wrong one of "okay okay okay"), whisper's time is kept.
  89. 4. **Safety.** Stacked or zero-length timings are spread out; sound tags `(...)`, `[...]`, `*...*`, `♪`
  90. are dropped; never two captions on screen; slurs are dropped and swears masked (F*CK, SH*T). The
  91. audio itself is left as is.
  92. Measured on test clips: whisper timing alone ran 0.1-0.26 s late; after alignment captions land within
  93. a few hundredths of a second of the voice.
  94. ## Live mode (clip while the stream is on)
  95. `scripts/live.py <twitch_channel> work/live-<name> --minutes 60 [--min-score 7] [--model sonnet]`
  96. - Pulls the live video in 2-second pieces (old MPEG-TS and newer fMP4 Twitch streams both work), keeps
  97. the last 20 minutes, reads the public chat anonymously (read-only IRC), and watches two signals:
  98. chat much faster than its own 10-minute normal, and the streamer much louder than usual.
  99. - A moment needs chat AND loudness (or a flood of "clip" in chat). It cuts 25 s before and 22 s after,
  100. transcribes, and asks headless `claude -p` (Sonnet) to open four frames and give a 0-10 score, clip
  101. bounds, beats and a title. 7+ is rendered straight away into `clips/`. Everything is logged to
  102. `events.log` (`MOMENT`, `SCORE`, `CLIP`), one line each, for a monitor to follow.
  103. - A verdict reason like "I didn't view the frames" means its beats are guesses: drop them.
  104. - Near misses (score 6) can be rendered by hand: `scripts/render_candidate.py work/live-<name> m07 m12`.
  105. - First 2 minutes are calibration. Anonymous viewers get Twitch ad breaks: the stream is not served
  106. during an ad, so moments in that gap are lost. Sleep streams produce nothing; check the stream is active.
  107. - Moment to finished clip: about 1 minute (plus ~15 s for exact captions). Mac and Claude Code must stay on.
  108. ## Known pitfalls (all handled in the scripts; keep them handled)
  109. - Twitch pieces start audio and video at different times: cut sections with output seeking
  110. (`-i joined -ss off`), never input seeking, or video lands 1.5 s off the audio.
  111. - Seeking inside a stream stitched from HLS pieces drifts after ~20 h: use the decoded timeline.
  112. - whisper.cpp small/base word timestamps collapse (several words on one time); never caption with them
  113. without alignment.
  114. - A face in the game is not the webcam: pick the face that stays put across frames.
  115. - Judge frames must be absolute paths (`claude -p` runs with cwd = the candidate folder).
README.md · README · 119 lines
  1. # stream-clipper
  2. A Claude Code skill that turns a stream into ready-to-post vertical clips. It works on a recording
  3. (Twitch, YouTube or Kick VOD) or **live, while the stream is on**.
  4. You give Claude a link. It finds the moments where the streamer suddenly gets loud and chat explodes,
  5. reads what was said, judges which moments a stranger would stop scrolling for, and renders 1080x1920
  6. Shorts / TikToks / Reels in the format top clipping channels use:
  7. - webcam big on top, gameplay below, hard seam
  8. - one word at a time on the seam, timed to the voice within a few hundredths of a second
  9. - jump cuts through dead air, the payoff always plays in full
  10. - a short red flash on the payoff, `*ACTION*` captions over silent action
  11. - swears masked, slurs never shown
  12. Then it checks every clip (sync, captions, word timing) before you see it.
  13. > **Clip only streamers who allow it** (an official clipping campaign or written permission), and follow
  14. > the campaign's rules. Posting is up to you.
  15. ## How it works
  16. ```
  17. stream link
  18. -> audio, downloaded in parallel pieces (a 9-hour VOD in ~40 s)
  19. -> loudness spikes vs the streamer's own level (+ chat speed, live)
  20. -> 40 s transcript around each spike
  21. -> Claude scores each moment 0-10 and picks start / payoff / end
  22. -> webcam found automatically (the face that stays put)
  23. -> clean voice (Demucs) -> whisper large-v3 -> wav2vec2 forced alignment = exact captions
  24. -> render: split layout, jump cuts, captions, flash
  25. -> check: sync, overlaps, every word on the voice
  26. ```
  27. Live mode does the same on a rolling 20-minute buffer: from moment to finished clip in about a minute.
  28. ## Install
  29. Requirements: macOS (Apple Silicon recommended) or Linux, Python 3.10+, ~3 GB of disk for models,
  30. [Claude Code](https://claude.com/claude-code).
  31. ```bash
  32. git clone https://github.com/vladgermanyuk/stream-clipper ~/.claude/skills/stream-clipper
  33. cd ~/.claude/skills/stream-clipper
  34. ./setup.sh
  35. ```
  36. `setup.sh` installs ffmpeg, yt-dlp, whisper.cpp and uv (Homebrew), creates two Python environments
  37. (`.venv` for the pipeline, `.align-venv` with PyTorch for voice separation and alignment) and downloads
  38. the models. On Linux, install those four tools with your package manager and run `SKIP_BREW=1 ./setup.sh`.
  39. ## Use
  40. In Claude Code:
  41. ```
  42. Clip this stream with the stream-clipper skill and make the top 3 clips: https://www.twitch.tv/videos/...
  43. ```
  44. ```
  45. Watch <streamer>'s live stream on Twitch and clip the best moments for the next 30 minutes.
  46. ```
  47. Clips land in `work/<name>/clips/`. Every step is also a plain script you can run yourself; see `SKILL.md`.
  48. | Script | Does |
  49. |---|---|
  50. | `scripts/fetch.py` | fast parallel download of audio or a video section |
  51. | `scripts/signals.py` | loudness spikes (ignores sleep/AFK hours of marathons) |
  52. | `scripts/transcribe_candidates.py` | 40 s transcript around each spike |
  53. | `scripts/find_layout.py` | finds webcam and face, writes `layout.json` |
  54. | `scripts/render.py` | renders the picks |
  55. | `scripts/check_clip.py` | checks finished clips |
  56. | `scripts/live.py` | live mode |
  57. | `scripts/render_candidate.py` | renders a live near-miss by hand |
  58. | `scripts/align_words.py` | exact word timing (runs in `.align-venv`) |
  59. ## Speed (Apple M-series)
  60. | Step | Time |
  61. |---|---|
  62. | Audio of a 9-hour VOD | ~40 s |
  63. | Spikes | ~20 s |
  64. | 60 candidate transcripts | ~1 min |
  65. | One clip with exact captions | ~15 s |
  66. | Live: moment to clip | ~1-1.5 min |
  67. ## Limits
  68. - Twitch serves anonymous viewers ads; in live mode, moments during an ad break are lost.
  69. - English captions only (the aligner model is English).
  70. - The judge is Claude: it needs Claude Code (`claude -p` in live mode).
  71. - Captions are as good as what can be heard: the clean-voice step helps a lot, but shouting over loud
  72. game audio can still be misheard. `check_clip.py` lists every word so you can read it before posting.
  73. ## What the scripts touch (security notes)
  74. Skill scanners flag this skill for running programs and using the network; that is what it does, so
  75. here is the full list:
  76. - **Network:** stream playlists and video pieces from Twitch / YouTube / Kick (via yt-dlp), public
  77. Twitch chat in live mode (anonymous read-only IRC login, nothing is ever sent to chat), model downloads
  78. in `setup.sh` (Hugging Face, GitHub opencv_zoo) and on first use (PyTorch weights for wav2vec2 and Demucs).
  79. - **Programs it runs:** `ffmpeg`, `ffprobe`, `yt-dlp`, `whisper-cli`, the two local Python environments,
  80. and in live mode `claude -p` (to score moments; it is allowed only the Read tool).
  81. - All commands are passed as argument lists, never through a shell. No credentials, tokens or cookies are
  82. read or stored. Everything it writes stays in `work/`.
  83. ## Credits
  84. [whisper.cpp](https://github.com/ggerganov/whisper.cpp) (MIT) and OpenAI Whisper models (MIT),
  85. [Demucs](https://github.com/facebookresearch/demucs) (MIT), wav2vec2 via
  86. [torchaudio](https://github.com/pytorch/audio) (BSD), forced-alignment approach from
  87. [WhisperX](https://github.com/m-bain/whisperX), [YuNet](https://github.com/opencv/opencv_zoo) face
  88. detector (MIT), [yt-dlp](https://github.com/yt-dlp/yt-dlp), [FFmpeg](https://ffmpeg.org).
  89. ## License
  90. MIT, see `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.