介绍
# TubeScribe 🎬
**将任意 YouTube 视频转换为精美的文档 + 音频摘要。**
粘贴 YouTube 链接 → 获取带有说话人标签、关键语录、可链接回视频的时间戳的精美转录文本，以及可以随时收听的音频摘要。
### 💸 免费且无付费 API
- **无订阅或 API 密钥** —— 开箱即用 - **本地处理** —— 转录、说话人检测和 TTS 均在您的机器上运行 - **网络访问** —— 从 YouTube 获取（字幕、元数据、评论）需要联网 - **无数据上传** —— 不会发送任何内容到外部服务；所有处理均在本地完成 - **安全的子代理** —— 生成的子代理有严格指令：不安装软件，除 YouTube 外不进行网络调用
### ✨ 功能特性
- **📄 带有摘要和关键语录的转录文本** —— 可导出为 DOCX、HTML 或 Markdown - **🎯 智能说话人检测** —— 自动识别参与者 - **🔊 音频摘要** —— 收听关键点 (MP3/WAV) - **📝 可点击的时间戳** —— 每条语录直接链接到视频中的对应时刻 - **💬 YouTube 评论** —— 观众情绪分析和精彩评论 - **📋 队列支持** —— 发送多个链接，它们将按顺序处理 - **🚀 非阻塞工作流** —— 视频在后台处理时对话可以继续
### 🎬 适用于任何视频
- 访谈和播客（多说话人检测） - 讲座和教程（单人说话） - 音乐视频（歌词提取） - 新闻和纪录片 - 任何带有字幕的 YouTube 内容
## 快速开始
当用户发送 YouTube URL 时： 1. 立即生成带有完整流水线任务的子代理 2. 回复："🎬 TubeScribe 正在处理 —— 准备好后我会通知您！" 3. 继续对话（不要等待！） 4. 子代理通知将宣布完成情况，包含标题和详细信息
**不要阻塞** —— 立即生成并继续。
## 首次设置
运行 setup 以检查依赖项并配置默认值：
```bash python skills/tubescribe/scripts/setup.py ```
此操作会检查：`summarize` CLI、`pandoc`、`ffmpeg`、`Kokoro TTS`
## 完整工作流（单个子代理）
生成一个执行整个流水线的子代理：
```python sessions_spawn( task=f""" ## TubeScribe: Process {youtube_url}
⚠️ CRITICAL: Do NOT install any software. No pip, brew, curl, venv, or binary downloads. If a tool is missing, STOP and report what's needed.
Run the COMPLETE pipeline — do not stop until all steps are done.
### Step 1: Extract ```bash python3 skills/tubescribe/scripts/tubescribe.py "{youtube_url}" ``` Note the **Source** and **Output** paths printed by the script. Use those exact paths in subsequent steps.
### Step 2: Read source JSON Read the Source path from Step 1 output and note: - metadata.title (for filename) - metadata.video_id - metadata.channel, upload_date, duration_string
### Step 3: Create formatted markdown Write to the Output path from Step 1:
1. `# **<title>**` --- 2. Video info block — Channel, Date, Duration, URL (clickable). Empty line between each field. --- 3. `## **Participants**` — table with bold headers: ``` | **Name** | **Role** | **Description** | |----------|----------|-----------------| ``` --- 4. `## **Summary**` — 3-5 paragraphs of prose --- 5. `## **Key Quotes**` — 5 best with clickable YouTube timestamps. Format each as: ``` "此处引用语录。" - [12:34](https://www.youtube.com/watch?v=ID&t=754s)
"另一条语录。" - [25:10](https://www.youtube.com/watch?v=ID&t=1510s) ``` Use regular dash `-`, NOT em dash `—`. Do NOT use blockquotes `>`. Plain paragraphs only. --- 6. `## **Viewer Sentiment**` (if comments exist) --- 7. `## **Best Comments**` (if comments exist) — Top 5, NO lines between them: ``` 评论内容在此。
*- ▲ 123 @AuthorName*
下一条评论内容在此。
*- ▲ 45 @AnotherAuthor* ``` Attribution line: dash + italic. Just blank line between comments, NO `---` separators.
--- 8. `## **Full Transcript**` — merge segments, speaker labels, clickable timestamps
### Step 4: Create DOCX Clean the title for filename (remove special chars), then: ```bash pandoc <output_path> -o ~/Documents/TubeScribe/<safe_title>.docx ```
### Step 5: Generate audio Write the summary text to a temp file, then use TubeScribe's built-in audio generation: ```bash # 将摘要写入临时文件（使用 python3 写入，避免 shell 转义问题） python3 -c " text = '''在此处填入您的摘要文本''' with open('<temp_dir>/tubescribe_<video_id>_summary.txt', 'w') as f: f.write(text) "
# 生成音频（从配置自动检测引擎、语音、格式） python3 skills/tubescribe/scripts/tubescribe.py \ --generate-audio <temp_dir>/tubescribe_<video_id>_summary.txt \ --audio-output ~/Documents/TubeScribe/<safe_title>_summary ``` This reads `~/.tubescribe/config.json` and uses the configured TTS engine (mlx/kokoro/builtin), voice blend, and speed automatically. Output format (mp3/wav) comes from config.
### Step 6: Cleanup ```bash python3 skills/tubescribe/scripts/tubescribe.py --cleanup <video_id> ```
### Step 7: Open folder ```bash open ~/Documents/TubeScribe/ ```
### Report Tell what was created: DOCX name, MP3 name + duration, video stats. """, label="tubescribe", runTimeoutSeconds=900, cleanup="delete" ) ```
**生成后，立即回复：** > 🎬 TubeScribe 正在处理 - 准备好后我会通知您！ 然后继续对话。子代理通知会宣布完成情况。
## 配置
配置文件：`~/.tubescribe/config.json`
```json { "output": { "folder": "~/Documents/TubeScribe", "open_folder_after": true, "open_document_after": false, "open_audio_after": false }, "document": { "format": "docx", "engine": "pandoc" }, "audio": { "enabled": true, "format": "mp3", "tts_engine": "mlx" }, "mlx_audio": { "path": "~/.openclaw/tools/mlx-audio", "model": "mlx-community/Kokoro-82M-bf16", "voice": "af_heart", "lang_code": "a", "speed": 1.05 }, "kokoro": { "path": "~/.openclaw/tools/kokoro", "voice_blend": { "af_heart": 0.6, "af_sky": 0.4 }, "speed": 1.05 }, "processing": { "subagent_timeout": 600, "cleanup_temp_files": true } } ```
### 输出选项 | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `output.folder` | `~/Documents/TubeScribe` | 保存文件的位置 | | `output.open_folder_after` | `true` | 完成后打开输出文件夹 | | `output.open_document_after` | `false` | 自动打开生成的文档 | | `output.open_audio_after` | `false` | 自动打开生成的音频摘要 |
### 文档选项 | 选项 | 默认值 | 可选值 | 描述 | |--------|---------|--------|-------------| | `document.format` | `docx` | `docx`, `html`, `md` | 输出格式 | | `document.engine` | `pandoc` | `pandoc` | DOCX 转换器（回退到 HTML） |
### 音频选项 | 选项 | 默认值 | 可选值 | 描述 | |--------|---------|--------|-------------| | `audio.enabled` | `true` | `true`, `false` | 生成音频摘要 | | `audio.format` | `mp3` | `mp3`, `wav` | 音频格式（mp3 需要 ffmpeg） | | `audio.tts_engine` | `mlx` | `mlx`, `kokoro`, `builtin` | TTS 引擎（mlx 在 Apple Silicon 上最快） |
### MLX-Audio 选项（Apple Silicon 首选） | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `mlx_audio.path` | `~/.openclaw/tools/mlx-audio` | mlx-audio venv 位置 | | `mlx_audio.model` | `mlx-community/Kokoro-82M-bf16` | 使用的 MLX 模型 | | `mlx_audio.voice` | `af_heart` | 语音预设（未设置 voice_blend 时使用） | | `mlx_audio.voice_blend` | `{af_heart: 0.6, af_sky: 0.4}` | 自定义语音混合（加权混合） | | `mlx_audio.lang_code` | `a` | 语言代码 (a=美式英语) | | `mlx_audio.speed` | `1.05` | 播放速度 (1.0 = 正常, 1.05 = 快 5%) |
### Kokoro PyTorch 选项（备选） | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `kokoro.path` | `~/.openclaw/tools/kokoro` | Kokoro 仓库位置 | | `kokoro.voice_blend` | `{af_heart: 0.6, af_sky: 0.4}` | 自定义语音混合 | | `kokoro.speed` | `1.05` | 播放速度 (1.0 = 正常, 1.05 = 快 5%) |
### 处理选项 | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `processing.subagent_timeout` | `600` | 子代理超时时间（长视频需增加） | | `processing.cleanup_temp_files` | `true` | 完成后删除 /tmp 文件 |
### 评论选项 | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `comments.max_count` | `50` | 获取的评论数量 | | `comments.timeout` | `90` | 获取评论的超时时间（秒） |
### 队列选项 | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `queue.stale_minutes` | `30` | 超过此分钟数后认为处理任务已过期 |
## 输出结构
``` ~/Documents/TubeScribe/ ├── {Video Title}.html # Formatted document (or .docx / .md) └── {Video Title}_summary.mp3 # Audio summary (or .wav) ```
生成后，打开文件夹（不是单个文件），以便您访问所有内容。
## 依赖项
**必需：** - `summarize` CLI —— `brew install steipete/tap/summarize` - Python 3.8+
**可选（质量更好）：** - `pandoc` —— DOCX 输出：`brew install pandoc` - `ffmpeg` —— MP3 音频：`brew install ffmpeg` - `yt-dlp` —— YouTube 评论：`brew install yt-dlp` - mlx-audio —— Apple Silicon 上最快的 TTS：`pip install mlx-audio` （使用 MLX 后端运行 Kokoro） - Kokoro TTS —— PyTorch 备选方案：参见 https://github.com/hexgrad/kokoro
### yt-dlp 搜索路径
TubeScribe 按顺序检查以下位置：
| 优先级 | 路径 | 来源 | |----------|------|--------| | 1 | `which yt-dlp` | 系统 PATH | | 2 | `/opt/homebrew/bin/yt-dlp` | Homebrew (Apple Silicon) | | 3 | `/usr/local/bin/yt-dlp` | Homebrew (Intel) / Linux | | 4 | `~/.local/bin/yt-dlp` | pip install --user | | 5 | `~/.local/pipx/venvs/yt-dlp/bin/yt-dlp` | pipx | | 6 | `~/.openclaw/tools/yt-dlp/yt-dlp` | TubeScribe 自动安装 |
如果未找到，setup 会将独立二进制文件下载到工具目录。 工具目录版本不会与系统安装冲突。
## 队列处理
当一个视频正在处理时，用户发送多个 YouTube URL：
### 开始前检查 ```bash python skills/tubescribe/scripts/tubescribe.py --queue-status ```
### 如果正在处理 ```bash # Add to queue instead of starting parallel processing python skills/tubescribe/scripts/tubescribe.py --queue-add "NEW_URL" # → Replies: "📋 Added to queue (position 2)" ```
### 完成后 ```bash # Check if more in queue python skills/tubescribe/scripts/tubescribe.py --queue-next # → Automatically pops and processes next URL ```
### 队列命令 | 命令 | 描述 | |---------|-------------| | `--queue-status` | 显示正在处理的内容 + 队列项目 | | `--queue-add URL` | 添加 URL 到队列 | | `--queue-next` | 处理队列中的下一项 | | `--queue-clear` | 清空整个队列 |
### 批量处理（一次处理多个 URL） ```bash python skills/tubescribe/scripts/tubescribe.py url1 url2 url3 ``` 按顺序处理所有 URL，并在最后给出摘要。
## 错误处理
脚本会检测并报告以下错误，并附带清晰的消息：
| 错误 | 消息 | |-------|---------| | Invalid URL | ❌ 无效的 YouTube URL | | Private video | ❌ 视频为私密 — 无法访问 | | Video removed | ❌ 视频未找到或已删除 | | No captions | ❌ 此视频没有可用的字幕 | | Age-restricted | ❌ 年龄限制视频 — 未登录无法访问 | | Region-blocked | ❌ 视频在您的地区被屏蔽 | | Live stream | ❌ 不支持直播流 — 请等待结束 | | Network error | ❌ 网络错误 — 请检查您的连接 | | Timeout | ❌ 请求超时 — 请稍后重试 |
发生错误时，向用户报告并跳过该视频。
## 提示
- 对于长视频（>30 分钟），将子代理超时时间增加到 900s - 说话人检测在清晰的访谈/播客格式下效果最佳 - 单说话人视频（教程、讲座）会自动跳过说话人标签 - 时间戳直接链接到 YouTube 的对应时刻 - 对多个视频使用批量模式：`tubescribe url1 url2 url3`