video-clipper

name	Video Clipper
description	Create video clips from chapter timestamps using ffmpeg. Use when given a video file and timestamps/chapters to split into separate clips.
version	1.0.0
dependencies	ffmpeg
allowed-tools	["Bash","Read"]

Video Clipper

Overview

This Skill uses ffmpeg to create video clips from a source video file. It supports two modes:

1. Multi-chapter mode: Split a video into multiple clips based on chapter timestamps
2. Single snippet mode: Extract one clip from a time range (e.g., "55s to 2m35s")

Supports multiple video formats (MP4, MOV, AVI, MKV) and offers both fast stream copy mode and re-encode mode for consistent quality.

When to Apply

Use this Skill when:

• User has a video file and wants to split it into clips
• User provides chapter markers or timestamps with topic names
• User wants to extract a specific segment with a time range (e.g., "55s to 2m35s", "1:30 to 5:45")
• User wants to create a single clip snippet from a time range
• User has completed Video Transcript Analyzer skill and now wants to create clips from those timestamps
• User asks to "split video by chapters", "create clips from timestamps", "extract video segments", or "create a clip from X to Y"

Do NOT use this Skill for:

• Video editing (adding effects, transitions, etc.)
• Audio-only files (use audio processing tools instead)
• Combining/merging multiple videos
• Format conversion only (use ffmpeg directly)

Inputs

For Multi-Chapter Mode:

1. Video file path - Full path to source video (MP4, MOV, AVI, MKV, etc.)
2. Chapter list with timestamps - One of these formats:
   • 00:00:00 - Chapter Name
   • 00:05:30 - Another Chapter
   • HH:MM:SS - Chapter Name
   • MM:SS - Chapter Name (for videos under 1 hour)
3. Output directory (optional) - Where to save clips
4. Encoding preference (optional) - "copy" or "encode"

For Single Snippet Mode:

1. Video file path - Full path to source video
2. Time range - Natural language or standard formats:
   • 55s to 2m35s (natural language)
   • 1:30 to 5:45 (MM:SS format)
   • 00:01:30 to 00:05:45 (HH:MM:SS format)
   • Start and end time in any mix of formats
3. Output filename (optional) - Name for the clip file
4. Encoding preference (optional) - "copy" or "encode"

Outputs

For Multi-Chapter Mode:

• Individual video clip file for each chapter with sanitized filename
• Format: 01-Chapter_Name.mp4 (numbered, spaces replaced with underscores)
• Summary report with all clips, durations, sizes, and commands used

For Single Snippet Mode:

• One video clip file with specified or auto-generated name
• Format: [video_name]_[start]-[end].mp4 or custom filename
• Brief report with clip duration, size, and command used

Instructions for Claude

Step 1: Validate Prerequisites

First, check if ffmpeg is installed:

which ffmpeg && ffmpeg -version

If not installed, provide installation instructions:

• macOS: brew install ffmpeg
• Linux (Ubuntu/Debian): sudo apt-get install ffmpeg
• Linux (RHEL/CentOS): sudo yum install ffmpeg

Ask user to install ffmpeg before proceeding if missing.

Step 2: Detect Mode (Single Snippet vs Multi-Chapter)

Check the user's request to determine which mode to use:

Single Snippet Mode indicators:

• User provides a time range: "55s to 2m35s", "from 1:30 to 5:45", "extract 0:55 to 2:35"
• User says: "create a clip from X to Y", "extract segment", "get the part between X and Y"
• User provides start and end times without chapter names
• Only ONE time range is mentioned

Multi-Chapter Mode indicators:

• User provides multiple timestamps with names/descriptions
• User says: "split into chapters", "create clips from these timestamps"
• User has a list of timestamps with chapter names
• Multiple time ranges or chapter markers

If Single Snippet Mode detected, skip to Step 2a: Single Snippet Workflow below. If Multi-Chapter Mode detected, continue to Step 2b: Multi-Chapter Workflow below. If unclear, ask user: "Would you like to create (1) a single clip from a time range, or (2) multiple clips from chapter timestamps?"

Step 2a: Single Snippet Workflow

For creating one clip from a time range:

1. Get video file path:

   • If not provided, ask: "Please provide the full path to your video file"
   • Validate file exists: ls -lh [filepath]
   • Show file size and duration

2. Parse time range:

   • Look for patterns like:
     • 55s to 2m35s → convert to seconds: 55 to 155
     • 1:30 to 5:45 → convert to seconds: 90 to 345
     • 00:01:30 to 00:05:45 → already in HH:MM:SS format
   • Support formats:
     • Xs (seconds): 55s = 55 seconds
     • Xm or XmYs (minutes): 2m35s = 155 seconds, 5m = 300 seconds
     • XhYm or XhYmZs (hours): 1h30m = 5400 seconds
     • MM:SS: 1:30 = 90 seconds
     • HH:MM:SS: 00:01:30 = 90 seconds
   • If time range not clear, ask: "What time range would you like to extract? (e.g., '55s to 2m35s' or '1:30 to 5:45')"

3. Get output filename:

   • If not provided, generate: [video_name]_[start]-[end].mp4
   • Example: customer-call_00-55_02-35.mp4
   • Ask: "What would you like to name this clip? (Press Enter for: [suggested_name])"

4. Get encoding preference:

   • Ask: "Encoding mode: 'copy' (fast) or 'encode' (precise)? Default: copy"

5. Convert times to HH:MM:SS format for ffmpeg:

   def seconds_to_timestamp(seconds):
       h = seconds // 3600
       m = (seconds % 3600) // 60
       s = seconds % 60
       return f"{h:02d}:{m:02d}:{s:02d}"
   

6. Generate ffmpeg command:

   • Copy mode: ffmpeg -i [video] -ss [start] -to [end] -c copy -avoid_negative_ts 1 "[output]"
   • Encode mode: ffmpeg -i [video] -ss [start] -to [end] -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "[output]"

7. Execute command:

   • Show command to user
   • Execute and capture output
   • Verify clip was created

8. Report results:

   # Video Clip Created
   
   **Source:** [video_path]
   **Time Range:** [start] to [end] ([duration])
   **Output:** [output_path]
   **Size:** [file_size]
   **Encoding:** [copy/encode]
   
   **Command used:**
   ```bash
   [ffmpeg command]
   

9. Skip to Step 9 (Quality Checks)

Step 2b: Multi-Chapter Workflow

For creating multiple clips from chapter timestamps:

(Continue with existing workflow below...)

Step 3: Gather Required Information (Multi-Chapter Mode)

Check what information is provided. If missing, prompt for:

1. Video file path:

   • Ask: "Please provide the full path to your video file (e.g., /Users/name/video.mp4)"
   • Validate file exists using ls -lh [filepath]
   • Show file size and confirm with user

2. Chapter timestamps:

   • Ask: "Please provide your chapter list with timestamps in this format:

     00:00:00 - Introduction
     00:05:30 - Main Topic
     00:15:45 - Q&A
     

     (Tip: If you have a video transcript, try the Video Transcript Analyzer skill first to generate timestamps)"
   • Wait for user to provide timestamps

3. Output directory:

   • Ask: "Where would you like to save the clips? (Press Enter for default: same folder as source video with '_clips' suffix)"
   • Default: [video_directory]/[video_name]_clips/

4. Encoding mode:

   • Ask: "Choose encoding mode:
     • 'copy' (fast, no re-encode, may have keyframe issues at boundaries)
     • 'encode' (slower, consistent quality, precise cuts) Default: copy"

Step 4: Parse and Validate Timestamps (Multi-Chapter Mode)

1. Parse timestamp format:

   import re
   from datetime import datetime, timedelta
   
   def parse_timestamp(ts_str):
       """Convert HH:MM:SS or MM:SS to seconds"""
       parts = ts_str.strip().split(':')
       if len(parts) == 3:  # HH:MM:SS
           h, m, s = map(int, parts)
           return h * 3600 + m * 60 + s
       elif len(parts) == 2:  # MM:SS
           m, s = map(int, parts)
           return m * 60 + s
       else:
           raise ValueError(f"Invalid timestamp format: {ts_str}")
   
   def parse_chapter_line(line):
       """Parse '00:05:30 - Chapter Name' format"""
       match = re.match(r'(\d{1,2}:\d{2}:\d{2}|\d{1,2}:\d{2})\s*-\s*(.+)', line.strip())
       if match:
           timestamp, name = match.groups()
           return parse_timestamp(timestamp), name.strip()
       return None
   

2. Validate timestamps:

   • Check all timestamps are in ascending order
   • Warn if any timestamps are out of order
   • Check for duplicate timestamps
   • Ensure first timestamp is 00:00:00 or close to start

3. Get video duration:

   ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 [video_file]
   

4. Calculate end times:

   • For each chapter, end time = next chapter's start time
   • For last chapter, end time = video duration
   • Validate no chapter extends beyond video duration

Step 5: Sanitize Filenames (Multi-Chapter Mode)

Create safe filenames from chapter names:

import re

def sanitize_filename(name):
    """Convert chapter name to safe filename"""
    # Remove or replace special characters
    name = re.sub(r'[<>:"/\\|?*]', '', name)
    # Replace spaces with underscores
    name = name.replace(' ', '_')
    # Replace multiple underscores with single
    name = re.sub(r'_+', '_', name)
    # Remove leading/trailing underscores
    name = name.strip('_')
    # Limit length to 100 chars
    if len(name) > 100:
        name = name[:100]
    return name

Generate filenames:

• Format: {number:02d}-{sanitized_name}.{extension}
• Example: 01-Introduction.mp4, 02-Main_Topic.mp4
• Number chapters sequentially starting from 01

Step 6: Create Output Directory (Multi-Chapter Mode)

mkdir -p [output_directory]

Show user where clips will be saved.

Step 7: Generate ffmpeg Commands (Multi-Chapter Mode)

For "copy" mode (fast, no re-encode):

ffmpeg -i [input_video] -ss [start_time] -to [end_time] -c copy -avoid_negative_ts 1 "[output_file]"

For "encode" mode (slower, precise):

ffmpeg -i [input_video] -ss [start_time] -to [end_time] -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "[output_file]"

Key parameters:

• -ss [start_time]: Start time in HH:MM:SS format
• -to [end_time]: End time in HH:MM:SS format
• -c copy: Stream copy (no re-encode)
• -c:v libx264: Video codec for encoding
• -preset medium: Encoding speed/quality balance
• -crf 23: Quality level (18-28, lower is better)
• -c:a aac: Audio codec
• -avoid_negative_ts 1: Fix timestamp issues in copy mode

Step 8: Execute Clipping Commands (Multi-Chapter Mode)

1. Show execution plan:

   Creating [N] clips from [video_name]:
   1. [00:00:00 - 00:05:30] → 01-Introduction.mp4
   2. [00:05:30 - 00:15:45] → 02-Main_Topic.mp4
   ...
   

2. Execute commands sequentially:

   • Run one ffmpeg command at a time
   • Show progress: "Creating clip 1 of N..."
   • Capture any errors or warnings
   • Validate each output file was created and has size > 0

3. For parallel execution (optional, if user wants speed):

   • Can run multiple ffmpeg commands in background
   • Monitor all processes
   • Wait for all to complete before reporting
   • Only use if system has multiple cores and user approves

Step 9: Verify and Report Results (Both Modes)

1. Check each output file:

   ls -lh [output_directory]/*.mp4
   

2. Get clip durations:

   for file in [output_directory]/*.mp4; do
     ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$file"
   done
   

3. Generate summary report:

   # Video Clipping Complete
   
   ## Source Video
   - File: [path]
   - Duration: [HH:MM:SS]
   - Size: [size]
   
   ## Created Clips
   
   | # | Clip Name | Duration | Size | Time Range |
   |---|-----------|----------|------|------------|
   | 1 | 01-Introduction.mp4 | 05:30 | 15.2 MB | 00:00:00 - 00:05:30 |
   | 2 | 02-Main_Topic.mp4 | 10:15 | 28.4 MB | 00:05:30 - 00:15:45 |
   
   ## Summary
   - Total clips created: [N]
   - Total size: [total_size]
   - Output location: [directory]
   - Encoding mode: [copy/encode]
   
   ## Warnings/Errors
   [List any issues encountered]
   
   ## Commands Used
   ```bash
   [Show all ffmpeg commands for reference]
   

Step 10: Quality Checks (Both Modes)

Before finalizing:

• All expected clip files exist
• Each file has size > 0 bytes
• Clip durations match expected ranges (within 1-2 seconds)
• Filenames are properly sanitized (no special characters) [Multi-chapter only]
• No ffmpeg errors in output
• Summary report shows all clips

If using "copy" mode, warn user:

Note: Copy mode may result in clips that don't start exactly at the specified timestamp due to keyframe positions. If precise cuts are needed, re-run with "encode" mode.

Error Handling

Common errors and solutions:

1. ffmpeg not found:

   • Error: command not found: ffmpeg
   • Solution: Provide installation instructions

2. Invalid timestamp:

   • Error: Timestamp parsing fails
   • Solution: Show expected format, ask user to correct

3. Timestamp beyond video duration:

   • Error: End time > video length
   • Solution: Adjust last chapter to end at video duration

4. File not found:

   • Error: Input video doesn't exist
   • Solution: Ask user to verify path, suggest using tab completion

5. Permission denied:

   • Error: Cannot write to output directory
   • Solution: Check directory permissions, suggest alternative location

6. Codec errors in copy mode:

   • Error: "Non-monotonous DTS in output stream"
   • Solution: Re-run with encode mode or add -avoid_negative_ts 1

7. Overlapping timestamps:

   • Error: Timestamps out of order
   • Solution: Sort timestamps, ask user to confirm order

Examples

Example 1: Single Snippet from Time Range

User says: "Create a clip from 55s to 2m35s" User provides: /Users/alice/videos/customer-call.mp4

Workflow:

1. Validate ffmpeg installed ✓
2. Detect Single Snippet Mode (time range provided)
3. Parse time range: 55s = 55 seconds, 2m35s = 155 seconds
4. Convert to HH:MM:SS: 00:00:55 to 00:02:35
5. Suggest filename: customer-call_00-55_02-35.mp4
6. User accepts default filename
7. Ask encoding preference: user chooses "copy"
8. Generate ffmpeg command:

   ffmpeg -i /Users/alice/videos/customer-call.mp4 -ss 00:00:55 -to 00:02:35 -c copy -avoid_negative_ts 1 "customer-call_00-55_02-35.mp4"
   

9. Execute command
10. Report results:

    # Video Clip Created
    
    **Source:** /Users/alice/videos/customer-call.mp4
    **Time Range:** 00:00:55 to 00:02:35 (1m 40s)
    **Output:** /Users/alice/videos/customer-call_00-55_02-35.mp4
    **Size:** 8.2 MB
    **Encoding:** copy
    

Output file:

/Users/alice/videos/customer-call_00-55_02-35.mp4 (8.2 MB, 1m 40s)

Example 2: Basic Usage with SRT Timestamps (Multi-Chapter)

User provides:

Video: /Users/alice/videos/customer-call.mp4
Chapters:
00:00:00 - Introduction
00:02:57 - Memberships & Registration
00:09:41 - Lists vs Views
00:15:30 - API Limitations

Workflow:

1. Validate ffmpeg installed
2. Check video file exists (352 MB, 18:45 duration)
3. Parse 4 chapters with timestamps
4. Ask for encoding preference (user chooses "copy")
5. Create output directory: /Users/alice/videos/customer-call_clips/
6. Generate 4 ffmpeg commands
7. Execute sequentially
8. Verify all 4 clips created

Output files:

/Users/alice/videos/customer-call_clips/
  01-Introduction.mp4 (15.2 MB, 02:57)
  02-Memberships_Registration.mp4 (28.4 MB, 06:44)
  03-Lists_vs_Views.mp4 (24.1 MB, 05:49)
  04-API_Limitations.mp4 (12.8 MB, 03:15)

Example 3: From Video Transcript Analyzer Output (Multi-Chapter)

User says: "I just ran Video Transcript Analyzer on my interview. Can you create clips from those chapters?"

Workflow:

1. Ask user: "Please share the video file path and the chapter timestamps from the analysis"
2. User provides video path and copies the "Topical Breakdown" section timestamps
3. Parse timestamps:

   00:02:57 - Memberships & Registration Management
   00:09:41 - Lists vs Views Disconnect
   00:15:30 - API Limitations
   00:20:15 - Workflow Automation Issues
   

4. Get video duration: 25:42
5. Calculate last chapter ends at 25:42
6. Ask encoding preference (user chooses "encode" for precise cuts)
7. Create clips with re-encoding
8. Report: 4 clips created, 156 MB total

Example 4: Simple Timestamps - MM:SS format (Multi-Chapter)

User provides:

Video: /home/user/videos/tutorial.mp4
Chapters:
0:00 - Intro
5:30 - Setup
12:45 - Demo
18:20 - Q&A

Workflow:

1. Parse MM:SS format timestamps (convert to seconds)
2. Validate video is 22:15 long
3. Calculate end times:
   • Intro: 0:00 - 5:30
   • Setup: 5:30 - 12:45
   • Demo: 12:45 - 18:20
   • Q&A: 18:20 - 22:15
4. Create 4 clips in encode mode (user requested precise cuts)
5. Success: All clips created

Testing Checklist

• ffmpeg detection works correctly
• Handles both HH:MM:SS and MM:SS timestamp formats
• Validates timestamps are in ascending order
• Correctly calculates end times from next chapter start
• Last chapter uses video duration as end time
• Sanitizes filenames (removes special chars, replaces spaces)
• Creates output directory if it doesn't exist
• Both "copy" and "encode" modes work
• Generates proper ffmpeg commands
• Verifies all output files created
• Reports file sizes and durations accurately
• Handles errors gracefully (missing video, invalid timestamps)
• Warns about copy mode keyframe limitations
• Provides summary report with all details

Security and Privacy

File Access:

• Only reads user-specified video file
• Only writes to user-specified output directory
• Does not modify source video file
• Validates all paths before execution

Command Execution:

• All ffmpeg commands shown to user before execution
• No arbitrary command injection
• Filenames sanitized to prevent shell injection
• Uses absolute paths to prevent directory traversal

Privacy:

• Video content never sent to external services
• All processing done locally with ffmpeg
• Chapter names may contain sensitive info - handle appropriately
• Output files remain in user's filesystem

Resources

See resources/ folder for:

• EXAMPLES.md: Detailed examples with full input/output
• REFERENCE.md: ffmpeg command reference, timestamp formats, troubleshooting guide
• README.md: User-facing documentation

Related Skills (Workflow Chain)

This skill is part of the video processing workflow:

┌─────────────────────┐
│   wistia-uploader   │  → Upload video, get transcript
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────────┐
│  video-transcript-analyzer  │  → Analyze transcript, get timestamps
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────┐
│    video-clipper    │  ← YOU ARE HERE
│   (create clips)    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   wistia-uploader   │  → (Optional) Upload clips to Wistia
└─────────────────────┘

Preceding skill: video-transcript-analyzer - Use this first to generate chapter timestamps from a transcript

Following skill: wistia-uploader - Optionally upload the created clips to Wistia for hosting