Video Clip Extractor Skill

Run the video orchestrator to process videos and extract engaging highlights.

When Triggered

1. Get the source — if the user didn't provide a video URL or file path, ask for it.
2. Clarify intent (optional) — if the user wants clips focused on a specific topic, capture it for --user-intent. If unclear, ask: "Any specific topic or moments to focus on? (e.g. 'funny moments', 'key arguments')"
3. Check environment — does video_orchestrator.py exist in the current directory? If yes, run directly. Otherwise use the global install at ~/.local/share/openclip.
4. Verify prerequisites — check ffmpeg is installed and at least one API key is set. Warn if missing before running.
5. Run the command and stream output to user.
6. Report results — after completion, list the generated clips with timestamps and titles.

Setup (first use only)

Before running, determine the execution context:

1. Inside openclip repo — if video_orchestrator.py exists in the current directory, skip setup and run directly.
2. Global install — if ~/.local/share/openclip does not exist, run these steps:

Prerequisites: git and uv must be installed.

• Install uv if missing: macOS: brew install uv · Linux/Windows: pip install uv

git clone https://github.com/linzzzzzz/openclip.git ~/.local/share/openclip
cd ~/.local/share/openclip && uv sync

To update openclip later:

git -C ~/.local/share/openclip pull && cd ~/.local/share/openclip && uv sync

Execution

If inside the openclip repo (current directory contains video_orchestrator.py):

uv run python video_orchestrator.py [options] <source>

If running globally (from any other directory):

cd ~/.local/share/openclip && uv run python video_orchestrator.py -o "$OLDPWD/processed_videos" [options] <source>

$OLDPWD captures the user's original directory so clips are saved there, not inside the openclip install.

Where <source> is a video URL (Bilibili/YouTube) or local file path (MP4, WebM, AVI, MOV, MKV).

For local files with existing subtitles, place the .srt file in the same directory with the same filename (e.g. video.mp4 → video.srt).

Preflight Checklist

• Inside openclip repo: run from the repo root so relative paths (e.g. references/, prompts/) resolve correctly
• `ffmpeg` must be installed (required for all clip generation):
• macOS: brew install ffmpeg
• Ubuntu: sudo apt install ffmpeg
• Windows: download from ffmpeg.org
• If using --burn-subtitles: needs ffmpeg with libass (see README for details)
• Set one API key:
• QWEN_API_KEY (default provider: qwen), or
• OPENROUTER_API_KEY (if --llm-provider openrouter), or
• GLM_API_KEY (if --llm-provider glm), or
• MINIMAX_API_KEY (if --llm-provider minimax)
• If using --speaker-references: run uv sync --extra speakers and set HUGGINGFACE_TOKEN

CLI Reference

Required

Optional

Flags

Custom Filename Template (-f)

Uses yt-dlp template syntax. Common variables: %(title)s, %(uploader)s, %(upload_date)s, %(id)s, %(ext)s, %(duration)s.

Example: -f "%(upload_date)s_%(title)s.%(ext)s"

Environment Variables

Set the appropriate API key for the chosen --llm-provider:

• QWEN_API_KEY — for --llm-provider qwen
• OPENROUTER_API_KEY — for --llm-provider openrouter
• GLM_API_KEY — for --llm-provider glm
• MINIMAX_API_KEY — for --llm-provider minimax

Workflow

The orchestrator runs this pipeline automatically:

1. Download — fetch video + platform subtitles (Bilibili/YouTube) or accept local file
2. Split — divide videos longer than the built-in threshold into segments for parallel analysis
3. Transcribe — use platform subtitles or Whisper AI; --force-whisper overrides
4. Analyze — LLM scores transcript segments for engagement; --user-intent steers selection
5. Generate clips — ffmpeg cuts the video at identified timestamps
6. Add titles (opt-in) — render artistic text overlay using --title-style
7. Generate covers — create thumbnail image for each clip

Use --skip-clips, --skip-cover to skip specific steps. Use --add-titles to enable artistic titles. Use --skip-download and --skip-analysis to resume from intermediate results.

Output Example

After a successful run, report results like this:

✅ Processing complete — 5 clips generated
📁 processed_videos/video_name/clips/

  clip_01.mp4  [00:12:34 – 00:15:20]  "Title of the moment"
  clip_02.mp4  [00:28:45 – 00:31:10]  "Another highlight"
  clip_03.mp4  [00:45:00 – 00:47:30]  "Key discussion point"
  ...

Cover images: clips/*.jpg

Output Structure

processed_videos/{video_name}/
├── downloads/              # Original video, subtitles, and metadata (URL sources)
├── local_videos/           # Copied video and subtitles (local file sources)
├── splits/                 # Split parts and AI analysis results
├── clips/                  # Generated highlight clips + cover images
└── clips_post_processed/   # Post-processed clips when using --add-titles and/or --burn-subtitles

Option Selection Guide

Whisper model — Default base works for clear audio. Use small for background noise, multiple speakers, or accents. Use turbo for speed + accuracy. Use large/medium only when transcript quality is critical.

`--force-whisper` — Use when platform subtitles are auto-generated (often inaccurate), when "no engaging moments found" occurs (better transcripts improve analysis), or for non-native language content where platform captions are unreliable.

`--use-background` — Use for content featuring recurring personalities (streamers, hosts) where nicknames and community references matter. Reads from prompts/background/background.md.

Multi-part analysis — Videos that get split are analyzed per-segment, then aggregated to the top 5 engaging moments across all segments.

`--user-intent` — Steers LLM clip selection at both the per-segment and cross-segment aggregation stages. Useful when you want to find clips about a specific topic (e.g. "AI safety predictions", "funny moments").

`--burn-subtitles` — Hardcodes the SRT subtitle into the video frame. Use when you want subtitles always visible (e.g. for social media). Combine with --subtitle-translation to add a translated subtitle track below the original.

`--speaker-references` — Enables speaker diarization for interviews/podcasts. Provide a directory of 10–30 second clean WAV clips (one per speaker), named after the speaker (e.g. references/Host.wav).

Troubleshooting