feat: 添加本地字幕生成功能

- 新增 subtitle_generator.py 核心模块
  - AudioDownloader: 使用 yt-dlp 下载视频音频
  - WhisperTranscriber: Whisper 语音识别器
  - SubtitleFormatter: SRT 格式化器
  - SubtitleCache: 缓存管理器
  - SubtitleGenerator: 统一接口

- 集成到 pipeline.py
  - 添加 _ensure_subtitle() 方法
  - 自动检测无字幕视频并生成字幕
  - 支持缓存机制避免重复处理

- 更新配置文件
  - config.yaml.example 添加字幕配置项
  - requirements.txt 添加依赖包

- 文档更新
  - SKILL.md 添加字幕生成说明
  - SUBTITLE_FEATURE.md 详细功能文档

- 测试脚本
  - test_subtitle_generator.py 完整测试套件

特性:
- 本地处理,数据不上传,隐私安全
- 支持中英文识别及自动检测
- 多种模型可选(tiny/base/small/medium/large)
- 智能缓存,提升处理速度
- 完善的错误处理和日志输出
This commit is contained in:
OpenClaw Agent
2026-02-07 01:57:13 +08:00
parent 42a8dd9642
commit 8bce4ac23b
7 changed files with 1382 additions and 92 deletions
+373
View File
@@ -0,0 +1,373 @@
# Obsidian KB - 本地字幕生成功能
## 📖 功能概述
为无字幕视频自动生成字幕,使 AI 分析功能不受字幕限制,覆盖更多视频内容。
### 核心特性
- ✅ **本地处理**: 使用 Whisper 本地模型,数据不上传,隐私安全
- ✅ **完全免费**: 无 API 费用,仅需一次性下载模型
- ✅ **缓存机制**: 避免重复生成,提升处理速度
- ✅ **多语言支持**: 支持中英文识别及自动检测
- ✅ **灵活配置**: 可选择不同大小的模型平衡速度与准确度
---
## 🏗️ 架构设计
### 核心模块
```
subtitle_generator.py
├── AudioDownloader # 音频下载器 (yt-dlp)
├── WhisperTranscriber # Whisper 识别器
├── SubtitleFormatter # SRT 格式化器
├── SubtitleCache # 缓存管理器
└── SubtitleGenerator # 统一接口
```
### 工作流程
```
用户请求视频处理
↓
检查是否有字幕
↓ [有字幕]
使用现有字幕
↓ [无字幕 + 功能已启用]
下载音频 (yt-dlp)
↓
语音识别 (Whisper)
↓
转换为 SRT 格式
↓
保存到缓存
↓
继续 AI 分析
```
---
## 🚀 快速开始
### 1. 安装依赖
```bash
cd skills/obsidian-kb
# 激活虚拟环境(如果使用)
source venv/bin/activate # Linux/Mac
# 或
./venv/Scripts/activate # Windows
# 安装依赖
pip install openai-whisper yt-dlp torch
```
### 2. 系统依赖
确保系统已安装 `ffmpeg`:
```bash
# Ubuntu/Debian
sudo apt install ffmpeg
# macOS
brew install ffmpeg
# Windows
# 从 https://ffmpeg.org/ 下载并安装
```
验证安装:
```bash
ffmpeg -version
```
### 3. 配置
编辑 `config.yaml`:
```yaml
# 字幕生成配置
subtitle:
enabled: true # 启用自动生成
model: base # Whisper 模型大小
language: null # 语言: zh/en/null(自动检测)
cache_dir: cache/subtitles # 字幕缓存目录
audio_cache_dir: cache/audio # 音频缓存目录
```
### 4. 使用
功能启用后,处理无字幕视频时会自动生成字幕:
```python
from src.pipeline import ProcessingPipeline
from src.models import Content
pipeline = ProcessingPipeline()
content = Content(url="https://www.bilibili.com/video/BVxxxxx")
# 处理时会自动生成字幕(如果需要)
pipeline.process_full(content)
```
---
## 📊 模型选择
Whisper 提供多种大小的模型,可根据需求选择:
| 模型 | 大小 | 10分钟视频处理时间 | 准确度 | 推荐场景 |
|------|------|-------------------|--------|----------|
| tiny | ~39MB | ~30秒 | ⭐⭐ | 快速测试、批量处理 |
| **base** | **~74MB** | **~2分钟** | **⭐⭐⭐⭐** | **日常使用(推荐)** |
| small | ~244MB | ~5分钟 | ⭐⭐⭐⭐⭐ | 高质量需求 |
| medium | ~769MB | ~10分钟 | ⭐⭐⭐⭐⭐ | 专业用途 |
| large | ~1550MB | ~15分钟+ | ⭐⭐⭐⭐⭐ | 最高准确度 |
### 推荐配置
- **默认**: `base` - 速度与准确度的最佳平衡
- **低配机器**: `tiny` - 最小资源占用
- **高质量需求**: `small` - 更好的识别效果
- **有 GPU**: `medium` / `large` - 充分利用硬件加速
---
## 🎯 使用场景
### 1. 无字幕视频
B站、YouTube 等平台的部分视频没有提供字幕,启用此功能后可以自动生成。
### 2. 批量处理
处理多个视频时,缓存机制会显著提升速度:
```python
# 第一次处理:下载 + 识别(约 2-5 分钟)
pipeline.process_full(content1)
# 第二次处理相同视频:直接读取缓存(约 1 秒)
pipeline.process_full(content1)
```
### 3. 多语言内容
支持中英文混合内容的自动识别:
```yaml
subtitle:
language: null # 自动检测语言
```
或指定语言:
```yaml
subtitle:
language: zh # 强制使用中文
```
---
## 🧪 测试
运行测试脚本验证功能:
```bash
cd skills/obsidian-kb
python test_subtitle_generator.py
```
测试覆盖:
- ✅ 音频下载
- ✅ Whisper 识别
- ✅ SRT 格式化
- ✅ 缓存机制
- ✅ 完整工作流程
---
## 📦 API 文档
### SubtitleGenerator
主要接口类,整合所有功能。
```python
from subtitle_generator import SubtitleGenerator
generator = SubtitleGenerator(
model_size='base', # 模型大小
cache_dir='cache/subtitles' # 缓存目录
)
# 生成字幕
srt_text = generator.generate(
url='https://www.bilibili.com/video/BVxxxxx',
content_id='unique_id',
language='zh', # 可选:指定语言
use_cache=True # 可选:使用缓存
)
```
### 便捷函数
快速生成字幕的便捷函数:
```python
from subtitle_generator import generate_subtitle
srt_text = generate_subtitle(
url='https://www.bilibili.com/video/BVxxxxx',
content_id='unique_id',
model='base',
language='zh'
)
```
---
## 🔧 高级配置
### GPU 加速
如果系统有 NVIDIA GPU 并安装了 CUDA,Whisper 会自动使用 GPU 加速:
```python
import torch
print(f"GPU 可用: {torch.cuda.is_available()}")
```
使用 GPU 时,处理速度可提升 5-10 倍。
### 清理缓存
手动清理字幕缓存:
```python
from subtitle_generator import SubtitleCache
cache = SubtitleCache()
cache.clear()
```
或直接删除目录:
```bash
rm -rf cache/subtitles/*
```
### 自定义模型路径
如果需要使用自定义模型文件:
```python
import whisper
model = whisper.load_model(
'/path/to/custom/model.pt',
device='cpu'
)
```
---
## ⚠️ 注意事项
### 1. 存储空间
- **模型文件**: ~150MB (tiny) - 3GB (large)
- **音频缓存**: 每分钟视频约 1-2MB(处理完成后自动清理)
- **字幕缓存**: 每分钟视频约 1-3KB(长期保留)
建议:
- 使用 `base` 模型作为默认
- 定期清理 `cache/audio` 目录
- 字幕缓存可以长期保留
### 2. 处理时间
- **无 GPU**: 10分钟视频约 2-5 分钟(base 模型)
- **有 GPU**: 10分钟视频约 20-40 秒(base 模型)
### 3. 隐私安全
- ✅ Whisper 本地处理,音频不上传
- ✅ 缓存文件在本地,不共享
- ✅ 开源软件,代码透明
### 4. 识别准确度
Whisper 的识别效果取决于:
- **音频质量**: 清晰的音频效果更好
- **背景噪音**: 嘈杂环境可能影响识别
- **说话方式**: 语速过快、口音过重可能降低准确度
建议:
- 优先处理高质量音频
- 对生成的字幕进行人工审核
- 复杂内容可考虑使用人工字幕
### 5. 错误处理
系统已完善的错误处理机制:
- **下载失败**: 记录错误,继续处理
- **识别失败**: 记录错误,继续处理
- **格式化失败**: 使用原始文本
任何错误都不会中断主流程。
---
## 🚀 后续优化方向
### 1. GPU 加速支持
- [ ] 自动检测 GPU 可用性
- [ ] 支持 CUDA / MPS (Apple Silicon)
- [ ] 多 GPU 支持
### 2. 模型优化
- [ ] 支持量化模型(减小体积)
- [ ] 支持蒸馏模型(提升速度)
- [ ] 支持自定义模型微调
### 3. 功能增强
- [ ] 批量处理多个视频
- [ ] 支持更多视频平台
- [ ] 字幕编辑器 Web 界面
- [ ] 实时字幕生成
### 4. 云端集成
- [ ] 可选切换到云 API(阿里云/腾讯云)
- [ ] 混合模式:本地优先,云端降级
- [ ] 分布式处理支持
---
## 📄 许可证
本功能使用以下开源组件:
- **openai-whisper**: MIT License
- **yt-dlp**: Unlicense
- **torch**: BSD License
---
## 🤝 贡献
欢迎贡献代码、报告问题或提出建议!
---
**最后更新**: 2026-02-07
**版本**: 1.0.0