SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsyoutube-clipper

youtube-clipper

Data & analytics

View repository

Updated 10-15 17:29

About this skill

YouTube Video Smart Clipping Tool

Installation: If you're installing this skill from GitHub, please refer to README.md for installation instructions. The recommended method is npx skills add https://github.com/op7418/Youtube-clipper-skill.

Workflow

You will execute the YouTube video clipping task in the following 6 stages:

Stage 1: Environment Detection

Goal: Ensure all required tools and dependencies are installed

  1. Detect whether yt-dlp is available 
    yt-dlp --version

  1. Detect FFmpeg version and libass support

    # 优先检查 ffmpeg-full（macOS）
/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg -version

# 检查标准 FFmpeg
ffmpeg -version

# 验证 libass 支持（字幕烧录必需）
ffmpeg -filters 2>&1 | grep subtitles

  2. Detect Python dependencies

    python3 -c "import yt_dlp; print('✅ yt-dlp available')"
python3 -c "import pysrt; print('✅ pysrt available')"

If environment detection fails:

  • yt-dlp not installed: prompt brew install yt-dlp or pip install yt-dlp
  • FFmpeg lacks libass: prompt to install ffmpeg-full 
    brew install ffmpeg-full  # macOS
  • Python dependencies missing: prompt pip install pysrt python-dotenv

Note:

  • Standard Homebrew FFmpeg does not include libass and cannot burn subtitles
  • ffmpeg-full path: /opt/homebrew/opt/ffmpeg-full/bin/ffmpeg (Apple Silicon)
  • You must pass environment detection before continuing

Stage 2: Download Video

Goal: Download the YouTube video and English subtitles

  1. Ask the user for the YouTube URL

  2. Call the download_video.py script

    cd ~/.claude/skills/youtube-clipper
python3 scripts/download_video.py <youtube_url>

  3. The script will:

    • Download the video (up to 1080p, mp4 format)
    • Download English subtitles (VTT format, with auto-generated subtitles as a fallback)
    • Output the file path and video information

  4. Show the user:

    • Video title
    • Video duration
    • File size
    • Download path

Output:

  • Video file: <id>.mp4(named using the video ID to avoid special character issues)
  • Subtitle file: <id>.en.vtt

Stage 3: Analyze Chapters (Core Differentiating Feature)

Goal: Use Claude AI to analyze the subtitle content and generate fine-grained chapters (at the 2-5 minute level)

  1. Call analyze_subtitles.py to parse the VTT subtitles

    python3 scripts/analyze_subtitles.py <subtitle_path>

  2. The script will output structured subtitle data:

    • Full subtitle text (with timestamps)
    • Total duration
    • Number of subtitle entries

  3. You need to perform AI analysis(this is the most critical step):

    • Read the full subtitle content
    • Understand the content semantics and topic transition points
    • Identify natural topic switch positions
    • Generate chapters at 2-5 minute granularity (avoid coarse half-hour segmentation)

  4. Generate for each chapter:

    • Title: A concise topic summary (10-20 characters)
    • Time range: Start and end time (format: MM:SS or HH:MM:SS)
    • Core summary: 1-2 sentences explaining what this section covers (50-100 characters)
    • Keywords: 3-5 core concept words

  5. Chapter generation principles：

    • Granularity: each chapter 2-5 minutes (avoid too short or too long)
    • Completeness: ensure all video content is covered, with no omissions
    • Meaningful: each chapter is a relatively independent topic
    • Natural segmentation: split at topic transition points, do not mechanically split by time

  6. Show the chapter list to the user:

    📊 分析完成，生成 X 个章节：

1. [00:00 - 03:15] AGI 不是时间点，是指数曲线
   核心: AI 模型能力每 4-12 月翻倍，工程师已用 Claude 写代码
   关键词: AGI、指数增长、Claude Code

2. [03:15 - 06:30] 中国在 AI 上的差距
   核心: 芯片禁运卡住中国，DeepSeek benchmark 优化不代表实力
   关键词: 中国、芯片禁运、DeepSeek

... (所有章节)

✓ 所有内容已覆盖，无遗漏

Stage 4: User Selection

Goal: Let the user select the chapters to edit and the processing options

  1. Use the AskUserQuestion tool to let the user select chapters

    • Provide chapter numbers for the user to choose from
    • Support multiple selection (can select multiple chapters)

  2. Ask about processing options:

    • Generate bilingual subtitles? (English + Chinese)
    • Burn subtitles into the video? (hard subtitles)
    • Generate summary copy?

  3. Confirm the user's selections and show the processing plan

Stage 5: Editing and Processing (core execution stage)

Goal: Execute multiple processing tasks in parallel

For each chapter selected by the user, perform the following steps:

5.1 Edit the video clip

python3 scripts/clip_video.py <video_path> <start_time> <end_time> <output_path>
  • Use FFmpeg for precise editing
  • Preserve the original video quality
  • Output: <章节标题>_clip.mp4

5.2 Extract the subtitle segment

  • Filter the subtitles for that time range from the complete subtitles
  • Adjust the timestamps (subtract the start time, starting from 00:00:00)
  • Convert to SRT format
  • Output: <章节标题>_original.srt

5.3 Translate the subtitles (if the user selects it)

python3 scripts/translate_subtitles.py <subtitle_path>
  • Batch translation optimization: Translate 20 subtitles together per batch (saves 95% of API calls)
  • Translation strategy:
    • Maintain the accuracy of technical terms
    • Colloquial expression (suitable for short videos)
    • Concise and fluent (avoid verbosity)
  • Output: <章节标题>_translated.srt

5.4 Generate bilingual subtitle files (if the user selects it)

  • Merge the English and Chinese subtitles
  • Format: SRT bilingual (each subtitle contains English and Chinese)
  • Style: English on top, Chinese below
  • Output: <章节标题>_bilingual.srt

5.5 Burn subtitles into the video (if the user selects it)

python3 scripts/burn_subtitles.py <video_path> <subtitle_path> <output_path>
  • Use ffmpeg-full (with libass support)
  • Use a temporary directory to solve path space issues(Critical!)
  • Subtitle style:
    • Font size: 24
    • Bottom margin: 30
    • Color: white text + black outline
  • Output: <章节标题>_with_subtitles.mp4

5.6 Generate summary copy (if the user selects it)

python3 scripts/generate_summary.py <chapter_info>
  • Based on the chapter title, summary, and keywords
  • Generate copy suitable for social media
  • Include: title, core viewpoints, suitable platforms (Xiaohongshu, Douyin, etc.)
  • Output: <章节标题>_summary.md

Progress display:

🎬 开始处理章节 1/3: AGI 不是时间点，是指数曲线

1/6 剪辑视频片段... ✅
2/6 提取字幕片段... ✅
3/6 翻译字幕为中文... [=====>    ] 50% (26/52)
4/6 生成双语字幕文件... ✅
5/6 烧录字幕到视频... ✅
6/6 生成总结文案... ✅

✨ 章节 1 处理完成

Stage 6: Output Results

Goal: Organize the output files and show them to the user

  1. Create the output directory

    ./youtube-clips/<日期时间>/

    The output directory is located under the current working directory

  2. Organize the file structure:

    <章节标题>/
├── <章节标题>_clip.mp4              # 原始剪辑（无字幕）
├── <章节标题>_with_subtitles.mp4   # 烧录字幕版本
├── <章节标题>_bilingual.srt        # 双语字幕文件
└── <章节标题>_summary.md           # 总结文案

  3. Show to the user:

    • Output directory path
    • File list (with file sizes)
    • Quick preview command
    ✨ 处理完成！

📁 输出目录: ./youtube-clips/20260121_143022/

文件列表:
  🎬 AGI_指数曲线_双语硬字幕.mp4 (14 MB)
  📄 AGI_指数曲线_双语字幕.srt (2.3 KB)
  📝 AGI_指数曲线_总结.md (3.2 KB)

快速预览:
open ./youtube-clips/20260121_143022/AGI_指数曲线_双语硬字幕.mp4

  4. Ask whether to continue editing other chapters

    • If yes, return to Stage 4 (User Selection)
    • If no, end the Skill

Key Technical Points

1. FFmpeg Path Space Issue

Problem: The FFmpeg subtitles filter cannot correctly parse paths containing spaces

Solution: burn_subtitles.py uses a temporary directory

  • Create a temporary directory without spaces
  • Copy files to the temporary directory
  • Run FFmpeg
  • Move the output file back to the target location

2. Batch Translation Optimization

Problem: Translating one by one generates a large number of API calls

Solution: Translate 20 subtitles together per batch

  • Save 95% of API calls
  • Improve translation speed
  • Maintain translation consistency

3. Chapter Analysis Granularity

Goal: Generate chapters at a 2-5 minute granularity, avoiding coarse half-hour granularity

Method:

  • Understand subtitle semantics and identify topic transitions
  • Find natural topic switching points
  • Ensure each chapter has a complete discussion
  • Avoid mechanical time-based splitting

4. FFmpeg vs ffmpeg-full

Difference:

  • Standard FFmpeg: no libass support, cannot burn subtitles
  • ffmpeg-full: includes libass, supports subtitle burning

Path:

  • Standard: /opt/homebrew/bin/ffmpeg
  • ffmpeg-full: /opt/homebrew/opt/ffmpeg-full/bin/ffmpeg (Apple Silicon)

Error Handling

Environment Issues

  • Missing tools → prompt installation command
  • FFmpeg without libass → guide installation of ffmpeg-full
  • Missing Python dependencies → prompt pip install

Download Issues

  • Invalid URL → prompt to check URL format
  • Missing subtitles → try automatic subtitles
  • Network error → prompt to retry

Processing Issues

  • FFmpeg execution failed → display detailed error information
  • Translation failed → retry mechanism (up to 3 times)
  • Insufficient disk space → prompt to free up space

Output File Naming Convention

  • Video clip: <章节标题>_clip.mp4
  • Subtitle file: <章节标题>_bilingual.srt
  • Burned version: <章节标题>_with_subtitles.mp4
  • Summary copy: <章节标题>_summary.md

File Name Handling:

  • Remove special characters (/, \, :, *, ?, ", <, >, |）
  • Replace spaces with underscores
  • Limit length (maximum 100 characters)

User Experience Highlights

  1. Visible progress: Each step shows progress and status
  2. Friendly errors: Clear error messages and solutions
  3. Controllability: Users choose which chapters to clip and processing options
  4. High quality: Chapter analysis is meaningful, translation is accurate and fluent
  5. Completeness: Provide multiple versions, both original and processed

Start Execution

When the user triggers this Skill:

  1. Immediately start Phase 1 (environment detection)
  2. Execute in order through the 6 phases
  3. Automatically proceed to the next phase after each phase is completed
  4. Provide clear solutions when problems are encountered
  5. Finally display the complete output results

Remember: the core value of this Skill lies in AI fine-grained chapter analysis and Seamless technical processing, enabling users to quickly extract high-quality short video clips from long videos.