global-clip-forge
Use when the user wants to turn a long YouTube interview, talk, or podcast into 5 to 8 short clips for a target audience language. This skill downloads the source video and any available subtitles, ca
SKILL.mdSKILL.md
GitHubGlobal Clip Forge
Overview
Use this skill to convert one long YouTube interview into multiple short hard-sub clips that are ready to review or post for a specific audience language. It bundles the download, transcript parsing, optional Whisper transcription fallback, AI-driven target-language subtitle translation, clip cutting, subtitle windowing, bilingual subtitle merge, and hard-sub burn-in helpers.
Key implementation points to keep in sync with the repository:
- The downloader can accept user-specified subtitle language priorities instead of being locked to English and Chinese.
- The source fetch path prefers Chrome cookies and uses the Android client route for a simpler MP4 download.
- The transcription helper supports both Whisper
transcribeandtranslatetasks. - When local transcription is needed, use the shared virtual environment under
work/.venv/and install the standardopenai-whisperpackage there instead of tryingmlx-whisperfirst. - For subtitle-free videos longer than 1 hour, prefer Whisper
baseto keep local transcription practical. For videos up to 1 hour, prefersmallfor better subtitle quality. - Target-language translation is normally done by the calling AI so the workflow stays flexible across languages and environments.
translate_subtitles.pyremains available as an optional helper when you explicitly want a script-driven subtitle translation step.- The hard-sub renderer uses transparent PNG overlays with
ffmpeg overlay, so it does not depend onlibassordrawtext. - Subtitle-only export is the default. Only add a title card when the user explicitly asks for one, and keep title text in the target language only.
- Once the clip subtitle files are ready, the workflow should go straight to
clip.hardsub.mp4export without asking for another confirmation step.
When To Use
- The user gives a YouTube interview, talk, keynote, or podcast URL and wants multiple short clips.
- The user wants clips localized for a target audience language, with bilingual subtitles when helpful.
- The source video may not have platform subtitles, so the workflow needs a local transcription fallback.
- The user wants review-friendly candidate clip suggestions before export, or explicitly wants you to pick the best set yourself.
Workflow
Confirm prerequisites. Check
yt-dlpandffmpegavailability first. The helper scripts can use systemffmpegor theimageio-ffmpegbinary fallback.Create a work layout. Use a layout like:
work/<video-slug>/
source/
transcripts/
analysis/
clips/
- Decide the localization plan up front. Identify:
- the source language spoken in the video if known
- the target audience language requested by the user
- whether the export should be bilingual or target-language only
- whether title cards should be shown, and if so, keep them in the target language only
Download source assets. Run fetch_source.py with the YouTube URL and the
source/directory. Pass--subtitle-langsin priority order when the user has a target language preference, for example--subtitle-langs 'ja,ja-JP' --subtitle-langs 'en,en-US'. This downloader prefers browser cookies and uses the more reliable Android client path for the MP4 download.Inspect the downloaded files. Identify:
- the source
.mp4 - the subtitle
.srt - any sidecar files such as
.ytdl
If the video has no usable subtitles, transcribe it locally. Run transcribe_subtitles.py against the downloaded video and save the generated SRT into
work/<video-slug>/transcripts/. Use the defaulttranscribetask to create source-language subtitles, ortranslatewhen you specifically need Whisper to emit English subtitles from non-English speech. Keep all original, translated, and merged subtitle artifacts in thattranscripts/folder for unified management. If Whisper is not already available, create and usework/.venv/as the shared local install location, then install the standardopenai-whisperpackage there. Reuse that environment across subtitle-free tasks instead of reinstalling for each video. Do not trymlx-whisperfirst. When you do not explicitly pass--model, let the helper auto-picksmallfor videos up to 1 hour andbasefor videos longer than 1 hour.Create the target-language subtitle track. If the target audience language differs from the source language, have the calling AI translate the subtitle text into the target language while preserving timestamps and write
source.<target>.srtorclip.<target>.srt. Use the translated target-language file for packaging copy and for the title card text. If you explicitly want a script-driven translation step, translate_subtitles.py can still be used as an optional helper.Parse the working subtitle file into JSON. Use parse_subtitles.py and save the artifact into
analysis/transcript.json.Analyze before cutting. Read clip-schema.md and analysis-prompt.md. Generate a generous candidate list, then write
analysis/selected_clips.jsonandanalysis/candidate-review.txt.Candidate rules.
- Target 5 to 8 exported clips unless the user asks for another count.
- Prefer clips between 20 and 180 seconds.
- Favor one clear idea per clip.
- Favor strong opening lines, complete endings, and minimal dependency on missing context.
- Reject filler, greetings, sponsor reads, and fragments that end mid-thought.
- Export each chosen clip.
- Cut the video with cut_clip.py
- Window both subtitle tracks with trim_subtitles.py when you have separate source-language and target-language subtitle files
- If the target language differs from the source language, have the calling AI translate the local clip SRT into the target language while preserving timestamps
- If bilingual output is requested, merge the source-language and target-language subtitle files into one stacked bilingual SRT with merge_bilingual_subtitles.py
- Burn subtitles with render_hardsubs.py, and if a title card is requested pass the title in the target language only
- Do not stop for an extra approval round once subtitle assets are ready; export the final hard-sub video in the same run whenever feasible
- Packaging copy. For each exported clip, create:
- one short, sharp title in the target language
- one target-language description under 140 characters
Write per-clip metadata into each clip folder and also compile a combined analysis/clip-packaging.txt.
File Layout
Use:
work/<video-slug>/
source/
original.mp4
original.<lang>.srt
transcripts/
source.<source-lang>.srt
source.<target-lang>.srt
source.bilingual.srt
analysis/
transcript.json
selected_clips.json
candidate-review.txt
clip-packaging.txt
clips/
01-<slug>/
clip.mp4
clip.<source-lang>.srt
clip.<target-lang>.srt
clip.bilingual.srt
clip.hardsub.mp4
metadata.txt
Script Notes
- Run the helper scripts from the skill root with
PYTHONPATH="$PWD"when usingpython3 -m scripts.<name>. - For local transcription tasks, keep Python packages isolated inside the shared
work/.venv/instead of installing Whisper globally on the machine. - Prefer the standard
openai-whisperpackage inside that shared venv. Only deviate if the user explicitly asks for another runtime. - Prefer a font that comfortably supports the target audience language. If no better font is available, let the script fall back to the system default.
- The hard-sub renderer now defaults to subtitle-only exports. Only pass
--titlewhen the user explicitly wants an opening title card. - If a title card is used, keep it in the target language only instead of rendering bilingual title text.
- Subtitle parsing keeps line breaks intact so bilingual subtitles can stay stacked as
target languageplussource language. - When
clip.<target-lang>.srtorclip.bilingual.srtis already prepared, proceed directly toclip.hardsub.mp4creation instead of pausing for another user confirmation. - The downloader uses Chrome cookies when available. If download fails because cookies are stale, refresh browser login state before changing the workflow.
ffmpegcan come from either the system path or theimageio-ffmpegfallback helper.transcribe_subtitles.pynow auto-selects Whisperbasefor videos longer than 1 hour andsmallotherwise, unless the user explicitly overrides--model.
Resources
- Scripts: fetch_source.py, parse_subtitles.py, transcribe_subtitles.py, translate_subtitles.py, trim_subtitles.py, merge_bilingual_subtitles.py, cut_clip.py, render_hardsubs.py
- References: clip-schema.md, analysis-prompt.md
Output Contract
Return:
- the source asset folder
- the candidate clip list with timestamps, duration, title, and two-sentence summaries
- the packaging text file path
- the final
clip.hardsub.mp4path for each exported short
If the workflow cannot finish, report the exact blocker, such as stale cookies, failed download, missing ffmpeg, unavailable Whisper runtime, or unusable transcript quality.