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:
@@ -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
|
||||
Reference in New Issue
Block a user