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. 安装依赖

cd skills/obsidian-kb

# 激活虚拟环境（如果使用）
source venv/bin/activate  # Linux/Mac
# 或
./venv/Scripts/activate  # Windows

# 安装依赖
pip install openai-whisper yt-dlp torch

2. 系统依赖

确保系统已安装 ffmpeg:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
# 从 https://ffmpeg.org/ 下载并安装

验证安装:

ffmpeg -version

3. 配置

编辑 config.yaml:

# 字幕生成配置
subtitle:
  enabled: true              # 启用自动生成
  model: base                # Whisper 模型大小
  language: null             # 语言: zh/en/null(自动检测)
  cache_dir: cache/subtitles  # 字幕缓存目录
  audio_cache_dir: cache/audio  # 音频缓存目录

4. 使用

功能启用后，处理无字幕视频时会自动生成字幕：

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. 批量处理

处理多个视频时，缓存机制会显著提升速度：

# 第一次处理：下载 + 识别（约 2-5 分钟）
pipeline.process_full(content1)

# 第二次处理相同视频：直接读取缓存（约 1 秒）
pipeline.process_full(content1)

3. 多语言内容

支持中英文混合内容的自动识别：

subtitle:
  language: null  # 自动检测语言

或指定语言：

subtitle:
  language: zh  # 强制使用中文

---

🧪 测试

运行测试脚本验证功能：

cd skills/obsidian-kb
python test_subtitle_generator.py

测试覆盖：

• ✅ 音频下载
• ✅ Whisper 识别
• ✅ SRT 格式化
• ✅ 缓存机制
• ✅ 完整工作流程

---

📦 API 文档

SubtitleGenerator

主要接口类，整合所有功能。

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  # 可选：使用缓存
)

便捷函数

快速生成字幕的便捷函数：

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 加速：

import torch
print(f"GPU 可用: {torch.cuda.is_available()}")

使用 GPU 时，处理速度可提升 5-10 倍。

清理缓存

手动清理字幕缓存：

from subtitle_generator import SubtitleCache

cache = SubtitleCache()
cache.clear()

或直接删除目录：

rm -rf cache/subtitles/*

自定义模型路径

如果需要使用自定义模型文件：

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