Skip to content
Back to search

video-chapter-splitter

基于字幕语义自动识别章节边界,精准切割视频的 Claude Code Skill

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/qiyongchuan--video-chapter-splitter/badge.svg)](/listings/qiyongchuan--video-chapter-splitter)

HTML

<a href="/listings/qiyongchuan--video-chapter-splitter"><img src="/api/listings/qiyongchuan--video-chapter-splitter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install openai-whisper
# Install FFmpeg system-wide

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 155 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 视频语义章节切割工具 v2.0
  2. 根据字幕语义自动识别章节边界,精准切割视频为独立片段。
  3. ## 何时使用
  4. - 长视频需要按内容章节切割成 demo/教学片段
  5. - 网课/演讲需要提取独立案例
  6. - 内容创作者需要批量生成短视频素材
  7. - 任何需要"按语义理解"而非"按时间等分"切割视频的场景
  8. ## 工作原理(v2.0 优化)
  9. ```
  10. 视频文件 (1.5GB)
  11. ↓ FFmpeg 提取音频 (~3秒)
  12. 16kHz mono WAV (~180MB)
  13. ↓ Whisper 本地转录 (~5分钟, CPU small模型)
  14. 字幕文本(带精确时间戳)
  15. ↓ Claude 语义分析 (subagent, ~72K token)
  16. 章节边界 JSON
  17. ↓ FFmpeg 精准切割 (~10分钟)
  18. 独立视频片段
  19. ```
  20. **v2.0 关键优化**: 先提取音频再转录,速度提升 10x+。
  21. 直接丢视频给 Whisper 会导致 CPU 下极慢(1.5GB 视频预计 10+ 小时),
  22. 提取音频后同样的视频只需 5 分钟。
  23. ## 依赖安装
  24. ```bash
  25. # Python 3.8+
  26. pip install openai-whisper
  27. # FFmpeg(需系统安装)
  28. # Windows: winget install Gyan.FFmpeg
  29. # Mac: brew install ffmpeg
  30. # Linux: apt install ffmpeg
  31. ```
  32. ## 使用方法
  33. ### 第一步:提取字幕
  34. ```bash
  35. python video_chapter_splitter.py "你的视频.mp4" --extract-only
  36. ```
  37. 内部流程:FFmpeg 提取音频 -> Whisper 转录 -> 自动清理中间音频文件
  38. 输出:
  39. - `xxx_subtitles.md` - 可读字幕文本
  40. - `xxx_segments.json` - 精确时间戳数据
  41. ### 第二步:创建章节配置
  42. 让 Claude 分析字幕文件,创建 `xxx_chapters.json`:
  43. ```json
  44. {
  45. "chapters": [
  46. {
  47. "title": "01_开篇介绍",
  48. "start_time": "00:00:00",
  49. "end_time": "00:05:10",
  50. "summary": "介绍系统架构",
  51. "type": "knowledge"
  52. },
  53. {
  54. "title": "02_问答环节",
  55. "start_time": "00:05:10",
  56. "end_time": "00:12:00",
  57. "summary": "学员提问与解答",
  58. "type": "qa"
  59. }
  60. ]
  61. }
  62. ```
  63. ### 第三步:切割视频
  64. ```bash
  65. python video_chapter_splitter.py "你的视频.mp4" --split-only
  66. ```
  67. 输出:`xxx_chapters/` 目录下的独立视频文件
  68. ## 参数说明
  69. | 参数 | 默认值 | 说明 |
  70. |------|--------|------|
  71. | `--model` | small | Whisper 模型 (CPU 推荐 small, GPU 推荐 medium) |
  72. | `--extract-only` | - | 只提取字幕 |
  73. | `--split-only` | - | 只按 chapters.json 切割 |
  74. | `--keep-audio` | false | 保留中间音频文件 |
  75. | `--output-dir` | 视频名_chapters | 自定义输出目录 |
  76. ## Whisper 模型选择
  77. | 模型 | CPU 速度 | 准确率 | 推荐场景 |
  78. |------|----------|--------|----------|
  79. | tiny | 最快 | 一般 | 快速预览 |
  80. | base | 快 | 较好 | 英文内容 |
  81. | **small** | **中等** | **好** | **CPU 中文首选** |
  82. | medium | 较慢 | 很好 | GPU 中文首选 |
  83. | large | 最慢 | 最好 | 高精度需求 |
  84. ## 成本估算(实测数据)
  85. 以 1.5GB / 1小时38分钟直播课为例:
  86. | 环节 | Token | 时间 | 费用 |
  87. |------|-------|------|------|
  88. | FFmpeg 提取音频 | 0 | 3秒 | 免费 |
  89. | Whisper 转录 (small/CPU) | 0 | ~5分钟 | 免费 |
  90. | Claude 语义分析 | ~72K | ~3分钟 | ~$1.2 |
  91. | FFmpeg 切割 | 0 | ~10分钟 | 免费 |
  92. **每小时视频约 67K token, 约 $0.74 (¥5)**
  93. ## 关键技术细节
  94. ### 音频提取优化
  95. Whisper 只处理音频,但直接传视频时内部解码效率极低(尤其 CPU)。
  96. 预先用 FFmpeg 提取 16kHz mono WAV 是 Whisper 的最优输入格式:
  97. - 采样率匹配,无需内部重采样
  98. - 单声道,减少数据量
  99. - PCM 格式,无需解码
  100. ### FFmpeg 切割精度
  101. 使用 output seeking(`-ss` 在 `-i` 后),精度高于 input seeking。
  102. ### Windows 兼容
  103. - 所有输出使用纯 ASCII,避免 GBK 编码错误
  104. - 文件名自动清理特殊字符
  105. - 中间音频文件默认自动清理
  106. ## 故障排除
  107. ### Whisper 识别慢
  108. 换 small 模型 + 先提取音频(v2.0 默认行为)
  109. ### FFmpeg 切割点不准
  110. 手动微调 chapters.json 的时间戳,重新 --split-only
  111. ### Windows 编码错误
  112. v2.0 已修复,所有输出使用纯 ASCII
  113. ## 文件位置
  114. 脚本路径:skill 目录下 `video_chapter_splitter.py`
README.md · README · 209 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Video Chapter Splitter v2.0
  2. 基于字幕语义自动识别章节边界,精准切割视频为独立片段的 Claude Code Skill。
  3. [English](#english) | [中文](#中文)
  4. ---
  5. ## 中文
  6. ### v2.0 更新
  7. - **先提取音频再转录,速度提升 10x+**:直接丢视频给 Whisper 在 CPU 下极慢(1.5GB 视频预计 10+ 小时),提取音频后只需 5 分钟
  8. - **默认使用 small 模型**:CPU 下性价比最高,中文识别准确率够用
  9. - **修复 Windows GBK 编码问题**:移除所有 emoji,纯 ASCII 输出
  10. - **文件名安全处理**:自动清理特殊字符,避免跨平台问题
  11. - **自动清理中间文件**:提取的音频文件默认自动删除
  12. ### 功能
  13. - **音频提取**:FFmpeg 提取 16kHz mono WAV(Whisper 最优格式),1.5GB 视频 3 秒搞定
  14. - **字幕提取**:Whisper 本地转录音频,生成带时间戳的字幕
  15. - **语义分析**:AI 理解内容,按知识点/问答自动识别章节边界
  16. - **精准切割**:FFmpeg 按语义章节切割,非固定时长
  17. ### 工作原理
  18. ```
  19. 视频文件 (1.5GB)
  20. ↓ FFmpeg 提取音频 (~3秒)
  21. 16kHz mono WAV (~180MB)
  22. ↓ Whisper 本地转录 (~5分钟, CPU small模型)
  23. 字幕文本(带精确时间戳)
  24. ↓ Claude 语义分析 (~72K token)
  25. 章节边界 JSON
  26. ↓ FFmpeg 精准切割 (~10分钟)
  27. 独立视频片段
  28. ```
  29. ### 成本(实测数据)
  30. 以 1.5GB / 1小时38分钟直播课为例:
  31. | 环节 | Token | 时间 | 费用 |
  32. |------|-------|------|------|
  33. | FFmpeg 提取音频 | 0 | 3秒 | 免费 |
  34. | Whisper 转录 (small/CPU) | 0 | ~5分钟 | 免费 |
  35. | Claude 语义分析 | ~72K | ~3分钟 | ~$1.2 |
  36. | FFmpeg 切割 | 0 | ~10分钟 | 免费 |
  37. **每小时视频约 67K token,约 $0.74(¥5)**
  38. ### 安装依赖
  39. ```bash
  40. # Python 3.8+
  41. pip install openai-whisper
  42. # FFmpeg(系统安装)
  43. # Windows: winget install Gyan.FFmpeg
  44. # Mac: brew install ffmpeg
  45. # Linux: apt install ffmpeg
  46. ```
  47. ### 使用方法
  48. ```bash
  49. # 第一步:提取字幕(自动先分离音频再转录)
  50. python video_chapter_splitter.py "视频.mp4" --extract-only
  51. # 第二步:查看生成的 xxx_subtitles.md,创建 xxx_chapters.json
  52. # 或让 Claude 分析字幕自动生成章节 JSON
  53. # 第三步:按章节切割
  54. python video_chapter_splitter.py "视频.mp4" --split-only
  55. ```
  56. ### 参数说明
  57. | 参数 | 默认值 | 说明 |
  58. |------|--------|------|
  59. | `--model` | small | Whisper 模型 (CPU 推荐 small, GPU 推荐 medium) |
  60. | `--extract-only` | - | 只提取字幕 |
  61. | `--split-only` | - | 只按 chapters.json 切割 |
  62. | `--keep-audio` | false | 保留中间音频文件 |
  63. | `--output-dir` | 视频名_chapters | 自定义输出目录 |
  64. ### chapters.json 格式
  65. ```json
  66. {
  67. "chapters": [
  68. {
  69. "title": "01_开篇介绍",
  70. "start_time": "00:00:00",
  71. "end_time": "00:05:10",
  72. "summary": "介绍系统架构",
  73. "type": "knowledge"
  74. },
  75. {
  76. "title": "02_问答环节",
  77. "start_time": "00:05:10",
  78. "end_time": "00:12:00",
  79. "summary": "学员提问与解答",
  80. "type": "qa"
  81. }
  82. ]
  83. }
  84. ```
  85. ### 技术亮点
  86. **音频预提取优化**
  87. Whisper 只处理音频,但直接传视频时内部解码效率极低。预先用 FFmpeg 提取 16kHz mono WAV:
  88. - 采样率匹配 Whisper,无需内部重采样
  89. - 单声道减少数据量
  90. - PCM 格式无需解码
  91. **FFmpeg 切割精度**
  92. 使用 output seeking 模式(`-ss` 在 `-i` 后),实现帧级精度:
  93. ```bash
  94. # 不推荐:快但不准,可能漂移 5-10 秒
  95. ffmpeg -ss 00:01:00 -i input.mp4 ...
  96. # 推荐:稍慢但精准到帧
  97. ffmpeg -i input.mp4 -ss 00:01:00 ...
  98. ```
  99. ---
  100. ## English
  101. ### v2.0 Updates
  102. - **Extract audio before transcription, 10x+ faster**: Feeding video directly to Whisper on CPU is extremely slow; extracting audio first reduces processing from 10+ hours to ~5 minutes
  103. - **Default to small model**: Best cost-performance ratio on CPU
  104. - **Fixed Windows GBK encoding issues**: Pure ASCII output
  105. - **Auto-cleanup of intermediate files**
  106. ### Features
  107. - **Audio Extraction**: FFmpeg extracts 16kHz mono WAV (Whisper's optimal format), ~3 seconds for 1.5GB video
  108. - **Subtitle Extraction**: Local Whisper transcription with timestamps
  109. - **Semantic Analysis**: AI detects chapter boundaries by knowledge points and Q&A sections
  110. - **Precise Cutting**: FFmpeg cuts by semantic chapters, not fixed duration
  111. ### How it works
  112. ```
  113. Video (1.5GB)
  114. ↓ FFmpeg extract audio (~3s)
  115. 16kHz mono WAV (~180MB)
  116. ↓ Whisper transcribe (~5min, CPU small)
  117. Timestamped subtitles
  118. ↓ Claude semantic analysis (~72K tokens)
  119. Chapter boundaries JSON
  120. ↓ FFmpeg precise cut (~10min)
  121. Individual video clips
  122. ```
  123. ### Cost (Real-world data)
  124. For a 1.5GB / 1h38m live stream:
  125. | Step | Tokens | Time | Cost |
  126. |------|--------|------|------|
  127. | FFmpeg extract audio | 0 | 3s | Free |
  128. | Whisper transcribe (small/CPU) | 0 | ~5min | Free |
  129. | Claude semantic analysis | ~72K | ~3min | ~$1.2 |
  130. | FFmpeg split | 0 | ~10min | Free |
  131. **~67K tokens per hour of video, ~$0.74 per hour**
  132. ### Installation
  133. ```bash
  134. pip install openai-whisper
  135. # Install FFmpeg system-wide
  136. ```
  137. ### Usage
  138. ```bash
  139. # Step 1: Extract subtitles (auto extracts audio first)
  140. python video_chapter_splitter.py "video.mp4" --extract-only
  141. # Step 2: Review xxx_subtitles.md, create xxx_chapters.json
  142. # Step 3: Split by chapters
  143. python video_chapter_splitter.py "video.mp4" --split-only
  144. ```
  145. ---
  146. ## 相关文章
  147. - v1.0: [10 分钟,我用 Claude Code 造了一个视频语义切割工具](https://x.com/nopinduoduo/status/2029112063256346969)
  148. - v2.0: [10 分钟完成 1.5 小时视频语义切割,成本不到 1 元](https://x.com/nopinduoduo/status/2032590321721421945)
  149. ## 作者
  150. Created with Claude Code. v1.0 in 5 minutes, v2.0 optimized through real-world usage.
  151. ## License
  152. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.