---
name: video-text-clipper
description: 基于字幕文本特征的视频自动剪辑工具。通过语音转录识别视频字幕，根据关键词密度自动定位并剪辑出符合特征的片段，生成带字幕的精华视频。适用于任何通过字幕文本特征来截取拼接视频的场景。
---

# 基于文本特征的视频剪辑工具

## 功能说明
通过语音转录识别视频中的字幕文本，根据关键词密度自动定位并剪辑出符合特征的片段，生成带字幕的精华视频。

## 适用场景
- 根据关键词密度提取视频片段（如密集出现"大"字的打拍子片段）
- 长视频中特定内容片段的自动剪辑
- 任何通过字幕文本特征来截取视频的场景

## 环境要求

| 项 | 要求 | 说明 |
|------|--------|------|
| Python版本 | 3.12 | **必须使用 `D:\ProgramData\anaconda3\envs\py312_cuda\python.exe`** |
| CUDA版本 | 12.1 | RTX3080显卡，PyTorch 2.5.1+cu121 |
| 模型路径 | `D:/AI/LM-Models/faster-whisper/large-v3` | 本地预下载的faster-whisper large-v3模型 |
| ffmpeg版本 | 支持drawtext+subtitles滤镜 | 当前环境已满足 |

**⚠️ 环境路径**：
- `D:\AI\Miniconda3\python.exe` → ❌ CPU 版本，不能用
- `D:\ProgramData\anaconda3\envs\py312_cuda\python.exe` → ✅ **用这个**

## 依赖安装

```bash
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" -m pip install faster-whisper ffmpeg-python pyyaml zhconv pypinyin
```

## 调用方式

```bash
cd .opencode/skills/video-text-clipper
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" scripts/extract_by_text_pattern.py --config 配置文件路径.yaml
```

## 配置文件格式（YAML）

```yaml
video_src: "视频文件路径.mp4"
output_dir: "输出目录路径"

# 文本特征配置
text_pattern:
  # 特征关键词
  keyword: "大"
  # 窗口大小（秒）：在这个时间窗口内统计关键词出现次数
  window_size: 10
  # 阈值：窗口内关键词出现次数 >= 阈值 时，认为匹配
  threshold: 3
  # 片段最小时长（秒）
  min_clip_duration: 5
  # 片段最大时长（秒）
  max_clip_duration: 30
  # 相邻片段合并间隔（秒）：间隔小于此值的片段合并为一个
  merge_gap: 5

# 视频参数
video_params:
  fade_duration: 1          # 淡入淡出时长（秒）
  title_text: "精华片段"     # 片头标题
  title_duration: 3         # 标题显示时长（秒）
  title_fontsize: 90        # 标题字号
  title_color: FFFF00       # 标题颜色（黄色）
  subtitle_fontsize: 24     # 字幕字号
  subtitle_color: FFFFFF    # 字幕颜色（白色）
  whisper_model: large      # Whisper模型
  use_fast_whisper: true    # 使用GPU加速
  whisper_model_path: "D:/AI/LM-Models/faster-whisper/large-v3"
```

## 工作流程

### 1. 全视频转录
- 将视频分段（每5分钟一段）转录
- 输出带时间戳的JSON转录文件

### 2. 文本特征匹配
- 扫描所有转录文本，统计关键词出现频率
- 使用滑动窗口检测关键词密集区域
- 自动合并相邻的匹配区域

### 3. 片段提取
- 根据匹配的时间点提取视频片段
- 每个片段添加1秒淡入 + 1秒淡出

### 4. 视频合成
- **片头标题**：3秒90号黄色大字（带4px黑边），画面居中
- **字幕**：底部24号白字黑边
- **转场**：片段间1秒淡入淡出
- 输出：vN_final.mp4

## 输出文件结构

```
<项目目录>/
├── output/
│   ├── v1_final.mp4              # 最终视频
│   ├── subs/
│   │   └── v1_ai.srt             # AI纠正后的字幕
│   └── intermediates/
│       ├── clip1.mp4             # 原始片段
│       ├── clip1_fade.mp4        # 带淡入淡出的片段
│       ├── full_transcript.json  # 完整转录
│       └── concated.mp4          # 合并后的片段
└── config.yaml
```

## 已知限制

1. **Python版本限制**：Python 3.13不支持CUDA版PyTorch，必须使用3.11/3.12
2. **GPU依赖**：必须使用GPU加速，CPU转录速度慢10倍以上
3. **转录精度**：Whisper对音乐术语可能有识别误差
4. **文本特征**：特征关键词需要根据实际转录结果调整阈值