openclaw-skills/skills/obsidian-kb/SUBTITLE_FEATURE.md

# 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