claude-video

claude-video — CLI-Native Video Editing for Claude Code

Quick Reference

Command	What it does
/video	Interactive mode — describe what you want in plain English
/video setup	Install all dependencies (faster-whisper, auto-editor, scenedetect, yt-dlp, mediainfo)
/video edit	Trim, cut, split, merge, speed, crop, overlay, stabilize, transitions
/video transcode	Convert codecs, compress, GPU-accelerated encoding, two-pass
/video audio	Normalize loudness, reduce noise, mix, extract, remove silence
/video caption	Transcribe speech → animated word-by-word subtitles (Whisper + ASS)
/video analyze	Inspect with ffprobe, measure quality (VMAF/SSIM/PSNR), detect scenes
/video export <platform>	One-command export: youtube, tiktok, instagram, linkedin, web, gif, podcast
/video download <url>	Download video via yt-dlp with format selection
/video create	Programmatic video creation via Remotion (React-based motion graphics)
/video shorts	Longform → shortform pipeline: transcribe, score, crop 9:16, caption, export
/video image	AI image generation (Gemini 3 Pro Image, FLUX.2 local, SD 3.5, OpenAI, rembg)
/video generate	AI video generation (Veo 3.1, Runway Gen-4, local SVD)
/video screenshot	Web capture via Playwright (screenshots, recordings, Ken Burns)
/video enhance-audio	AI audio (Demucs separation, DeepFilter denoise, TTS, diarize, AudioSR)
/video enhance	AI video (Real-ESRGAN upscale, RIFE interpolation, CodeFormer, rembg)
/video promo	Stock footage + Remotion promo videos with contrast-aware text overlays
/video setup --ai	Install AI dependencies (PyTorch, WhisperX, FLUX.2, Real-ESRGAN, etc.)

Orchestration Logic

Command Routing

When the user provides a specific command, load the matching sub-skill:

• /video edit or intent is trim/cut/split/merge/speed/crop/overlay/stabilize/transition → Read skills/claude-video-edit/SKILL.md
• /video transcode or intent is convert/compress/encode/codec/format change → Read skills/claude-video-transcode/SKILL.md
• /video audio or intent is audio normalize/noise/mix/extract/silence/volume/LUFS → Read skills/claude-video-audio/SKILL.md
• /video caption or intent is transcribe/subtitle/caption/whisper/SRT/ASS → Read skills/claude-video-caption/SKILL.md
• /video analyze or intent is inspect/info/quality/VMAF/metadata/scene detect/ffprobe → Read skills/claude-video-analyze/SKILL.md
• /video export or intent is export for youtube/tiktok/instagram/linkedin/web/gif/podcast → Read skills/claude-video-export/SKILL.md
• /video download or intent is download video from URL → Read skills/claude-video-download/SKILL.md
• /video create or intent is create/generate programmatic video/motion graphics/title card → Read skills/claude-video-create/SKILL.md
• /video shorts or intent is shortform/clips/TikTok shorts/reels from longform → Read skills/claude-video-shorts/SKILL.md
• /video image or intent is generate image/AI image/FLUX/stable diffusion/remove background → Read skills/claude-video-image/SKILL.md
• /video generate or intent is generate video/AI video/Veo/Runway/text-to-video → Read skills/claude-video-generate/SKILL.md
• /video screenshot or intent is screenshot/web capture/screen recording/Ken Burns → Read skills/claude-video-screenshot/SKILL.md
• /video enhance-audio or intent is separate vocals/denoise AI/diarize/TTS/voice clone/upsample audio → Read skills/claude-video-enhance-audio/SKILL.md
• /video enhance or intent is upscale/super resolution/interpolate/face restore/remove background video → Read skills/claude-video-enhance/SKILL.md
• /video promo or intent is promo video/stock footage/marketing video/stock clips with text → Read skills/claude-video-promo/SKILL.md
• /video setup → Run bash scripts/setup.sh
• /video setup --ai → Run bash scripts/setup.sh --ai

Interactive Mode

When user says /video without arguments or describes a task in natural language:

1. Run bash scripts/check_deps.sh to verify tools are available
2. Run bash scripts/detect_gpu.sh to know encoding capabilities
3. Identify intent from the user's description
4. Route to the appropriate sub-skill
5. If intent is ambiguous, ask the user to clarify

Multi-Step Pipelines

For complex requests that span multiple sub-skills (e.g., "download this YouTube video, remove silence, add captions, export for TikTok"), execute sub-skills sequentially:

1. Download → edit → caption → export
2. Pass output of each step as input to the next
3. Use temp files in /tmp/claude-video/ for intermediate outputs
4. Clean up temp files after final output is produced

Safety Rules — MANDATORY

1. Always use -n flag (no-overwrite) unless user explicitly requests overwrite
2. Never let output path equal input path — run bash scripts/preflight.sh "$INPUT" "$OUTPUT" before any write
3. Never delete source files — all operations produce new files
4. Run preflight before every write operation: bash scripts/preflight.sh <input> <output>
5. Confirm before: batch operations (>3 files), downloads, operations estimated >5 minutes
6. Auto-execute without confirmation: ffprobe analysis, thumbnail extraction, GPU detection, metadata reading
7. Temp file cleanup: use trap 'rm -f "$TEMP"' EXIT INT TERM pattern in all scripts
8. Disk space check: run bash scripts/estimate_size.sh before large encodes

AI Sub-Skill Routing Guide

• "separate vocals" / "isolate dialogue" → claude-video-enhance-audio (Demucs, AI model)
• "reduce noise" / "denoise" → claude-video-audio (FFmpeg afftdn) for quick fix, claude-video-enhance-audio (DeepFilterNet3) for AI quality
• "remove background" from image → claude-video-image (rembg), from video → claude-video-enhance (rembg batch + alpha assembly)
• "upscale" / "super resolution" → claude-video-enhance (Real-ESRGAN)
• "slow motion" (basic) → claude-video-edit (setpts), (AI frame interpolation) → claude-video-enhance (RIFE)
• "generate image/video" → claude-video-image / claude-video-generate
• "shorts" / "clips from long video" → claude-video-shorts

Python Virtual Environment

AI scripts require an isolated venv with PyTorch nightly cu128 (for RTX 5070 Ti Blackwell sm_120):

# Install the AI venv (one-time)
bash scripts/setup.sh --ai

# Venv location
~/.video-skill/bin/python3
~/.video-skill/bin/activate

All Python scripts in scripts/ that use AI models (segment_scorer.py, face_tracker.py, image_generate.py, video_generate.py, audio_enhance.py, video_enhance.py, web_capture.py) require activation: source ~/.video-skill/bin/activate

VRAM Management (16GB Budget — RTX 5070 Ti)

Before loading any GPU model, check free VRAM:

nvidia-smi --query-gpu=memory.free --format=csv,noheader,nounits

Tier	VRAM	Models	Rule
Exclusive (>10GB)	12-13GB	FLUX.2 klein, Bark TTS	Must be ONLY GPU model loaded
Heavy (5-10GB)	5-8GB	Demucs, WhisperX, AudioSR	One heavy at a time
Light (<5GB)	1-4GB	rembg, CodeFormer, RIFE, pyannote	Can coexist if total <12GB
NVENC	~500MB	Hardware encoder	Always available
CPU only	0	MediaPipe, PySceneDetect, Playwright, librosa	No VRAM needed

NEVER run two heavy/exclusive models simultaneously. Load → process → unload → next model.

Encoding Defaults

GPU-First Strategy

1. Run bash scripts/detect_gpu.sh at start of any encoding task
2. If NVENC available: use h264_nvenc/hevc_nvenc/av1_nvenc with -preset p5 -tune hq
3. If no GPU: fallback to libx264/libx265/libsvtav1 with -preset medium
4. Always add -movflags +faststart for MP4 output

Codec Selection Priority

• Stream copy (-c copy): when no re-encoding needed (trim, remux, extract)
• AV1 (av1_nvenc or libsvtav1): best compression, royalty-free — default for new encodes
• H.264 (h264_nvenc or libx264): maximum compatibility (social media, older devices)
• H.265 (hevc_nvenc or libx265): good compression + wide support — use when user requests

Quality Defaults

• H.264: CRF 20 (CPU) / CQ 21 (NVENC)
• H.265: CRF 24 (CPU) / CQ 26 (NVENC)
• AV1: CRF 28 (CPU) / CQ 30 (NVENC)
• Audio: AAC 192k for video, 128k for web, Opus 128k for WebM

Reference Files

Load on-demand as needed — do NOT load all at startup:

• references/transcode.md — Codec comparison, CRF guide, two-pass encoding, containers
• references/filters.md — Complete video filter catalog with exact FFmpeg commands
• references/audio.md — Loudness targets, noise reduction, audio processing
• references/captions.md — Whisper setup, ASS karaoke format, word-level styling
• references/analyze.md — FFprobe patterns, VMAF/SSIM/PSNR quality assessment
• references/export-presets.md — Platform-specific export commands (YouTube, TikTok, etc.)
• references/gpu-accel.md — NVENC commands, CUDA filters, RTX-specific settings
• references/remotion.md — Remotion setup, React video patterns, headless rendering
• references/shorts-pipeline.md — WhisperX models, scoring algorithm, face tracking, platform limits
• references/image-generation.md — FLUX.2, SD 3.5, OpenAI/Google APIs, rembg, video-native dimensions
• references/video-generation.md — Veo 3.1, Runway Gen-4, SVD local, polling, cost formulas
• references/web-capture.md — Playwright setup, device emulation, Ken Burns FFmpeg commands
• references/audio-enhance.md — Demucs, DeepFilterNet3, pyannote, TTS comparison, AudioSR
• references/video-enhance.md — Real-ESRGAN, RIFE, CodeFormer, rembg, frame pipelines
• references/batch-processing.md — GNU parallel + NVENC concurrency, batch AI, error handling

Sub-Skills

• claude-video-edit — Video editing: trim, cut, split, merge, speed, crop, overlay, stabilize, transitions
• claude-video-transcode — Codec conversion, compression, GPU encoding, two-pass, container remux
• claude-video-audio — Audio normalization, noise reduction, mixing, extraction, silence removal
• claude-video-caption — Speech-to-text transcription, animated subtitles, burn-in styling
• claude-video-analyze — Video inspection, quality metrics, scene detection, metadata analysis
• claude-video-export — Platform-optimized exports (YouTube, TikTok, Instagram, LinkedIn, Web, GIF, Podcast)
• claude-video-download — Video downloading via yt-dlp with format and quality selection
• claude-video-create — Programmatic video creation via Remotion (React-based motion graphics)
• claude-video-shorts — Longform → shortform pipeline: transcribe, score, crop 9:16, caption, export
• claude-video-image — AI image generation: Gemini 3 Pro Image, FLUX.2 local, SD 3.5, OpenAI API, rembg
• claude-video-generate — AI video generation: Veo 3.1, Runway Gen-4 Turbo, local SVD
• claude-video-screenshot — Web capture: Playwright screenshots, recordings, Ken Burns animation
• claude-video-enhance-audio — AI audio: Demucs separation, DeepFilter denoise, TTS, diarize, AudioSR
• claude-video-enhance — AI video: Real-ESRGAN upscale, RIFE interpolation, CodeFormer face restore, rembg

Scripts

• scripts/setup.sh — Install all dependencies with user confirmation
• scripts/detect_gpu.sh — Detect NVIDIA NVENC, list encoders (JSON output)
• scripts/check_deps.sh — Verify all tools installed with versions (JSON output)
• scripts/preflight.sh — Safety check: input exists, output != input, disk space ok
• scripts/estimate_size.sh — Estimate output file size from duration + target codec
• scripts/caption_pipeline.sh — End-to-end: audio extract → whisper → ASS → burn-in
• scripts/shorts_pipeline.sh — Full shortform pipeline: transcribe → score → crop → caption → export
• scripts/segment_scorer.py — WhisperX transcription + engagement scoring (requires venv)
• scripts/face_tracker.py — MediaPipe face detection + smart crop to 9:16 (requires venv)
• scripts/image_generate.py — FLUX.2 / SD 3.5 / OpenAI image generation (requires venv)
• scripts/video_generate.py — Veo / Runway / SVD video generation (requires venv)
• scripts/web_capture.py — Playwright screenshots, recording, Ken Burns (requires venv)
• scripts/audio_enhance.py — Demucs / DeepFilter / pyannote / TTS / AudioSR (requires venv)
• scripts/video_enhance.py — Real-ESRGAN / RIFE / CodeFormer / rembg (requires venv)
• scripts/screen_shorts_pipeline.sh — V3 screen-aware shorts pipeline (VLM + framed layout)
• scripts/frame_analyzer.py — VLM frame analysis via Gemini 2.5 Flash (requires venv + GOOGLE_API_KEY)
• scripts/topic_segmenter.py — Topic boundary detection + multi-modal scoring (requires venv)
• scripts/smart_reframe.py — Content-aware vertical reframe with framed layout (requires venv)

Agents

For complex multi-step tasks, delegate to specialized agents via Task tool:

• claude-video-encoder — Complex encoding pipelines (multi-pass, multi-output, batch)
• claude-video-analyst — Deep quality assessment and comprehensive video analysis
• claude-video-producer — Production pipeline specialist (multi-step, VRAM management, cost tracking)