TubeScribe 🎬

将任何YouTube视频转化为精美的文档+音频摘要。

粘贴一个YouTube链接 → 即可获得一份精美的文字记录，包含说话者标签、关键引语、可链接回视频的时间戳，以及一份可供随时收听的音频摘要。

💸 免费且无需付费API

• 无需订阅或API密钥— 开箱即用
• 本地处理— 转录、说话者检测和文本转语音都在您的设备上运行
• 网络访问— 从YouTube获取数据（字幕、元数据、评论）需要互联网连接
• 无数据上传— 不会向外部服务发送任何数据；所有处理都保留在您的设备上
• 安全的子代理— 生成的子代理有严格指令：不安装软件，除YouTube外不进行网络调用

✨ 功能特色

• 📄 带摘要和关键引语的文字记录— 导出为DOCX、HTML或Markdown格式
• 🎯 智能说话者检测— 自动识别参与者
• 🔊 音频摘要— 收听关键要点（MP3/WAV格式）
• 📝 可点击的时间戳— 每条引述都直接链接到视频中的对应时刻
• 💬 YouTube评论— 观众情绪分析和精选评论
• 📋 队列支持— 发送多个链接，它们会按顺序处理
• 🚀 非阻塞工作流— 后台处理视频时，对话可继续进行

🎬 适用于任何视频

• 访谈与播客（多说话人检测）
• 讲座与教程（单人讲话）
• 音乐视频（歌词提取）
• 新闻与纪录片
• 任何带有字幕的YouTube内容

快速开始

当用户发送YouTube链接时：

1. 立即创建子代理并分配完整处理流程任务立即
2. 回复："🎬 TubeScribe正在处理中——完成后我会通知您！"
3. 继续对话（无需等待！）
4. 子代理通知将在完成时公布标题和详细信息

不要阻塞——立即生成并继续。

首次设置

运行设置以检查依赖项并配置默认值：

python skills/tubescribe/scripts/setup.py

此项检查包括：摘要命令行界面pandoc、ffmpeg、Kokoro TTS

完整工作流程（单一子代理）

生成一个子代理来执行整个流水线：

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}"

请注意脚本打印的源文件和输出路径。在后续步骤中使用这些确切路径。

步骤 2：读取源 JSON

读取步骤1输出的源路径并注意：

• metadata.title（用于文件名）
• metadata.video_id
• metadata.channel、upload_date、duration_string

步骤3：创建格式化markdown

写入步骤1中的输出路径：

1. # **<标题>**

2. 视频信息块 — 频道、日期、时长、URL（可点击）。每个字段之间空一行。

3. ## **参与者**— 包含加粗标题的表格：

   | **Name** | **Role** | **Description** |
   |----------|----------|-----------------|
   

4. ## **总结**— 3-5段叙述性文字

5. ## **关键引述**— 最佳5条，附带可点击的YouTube时间戳。每条格式如下：

   "Quote text here." - [12:34](https://www.youtube.com/watch?v=ID&t=754s)
   
   "Another quote." - [25:10](https://www.youtube.com/watch?v=ID&t=1510s)
   

   使用常规短横线-，而非长破折号—。请勿使用块引用>。仅使用纯文本段落。

6. ## **观众情绪分析**（如果存在评论）

7. ## **最佳评论**（如果存在评论）— 前5条，它们之间没有空行：

   Comment text here.
   
   *- ▲ 123 @AuthorName*
   
   Next comment text here.
   
   *- ▲ 45 @AnotherAuthor*
   

   署名行：短横线 + 斜体。评论之间只有空行，没有分隔符。## **完整转录稿**

8. — 合并片段、说话人标签、可点击的时间戳第4步：创建DOCX文件

清理标题作为文件名（移除特殊字符），然后：

第5步：生成音频

pandoc <output_path> -o ~/Documents/TubeScribe/<safe_title>.docx

将摘要文本写入临时文件，然后使用TubeScribe内置的音频生成功能：

读取

# Write summary to temp file (use python3 to write, avoids shell escaping issues)
python3 -c "
text = '''YOUR SUMMARY TEXT HERE'''
with open('<temp_dir>/tubescribe_<video_id>_summary.txt', 'w') as f:
    f.write(text)
"

# Generate audio (auto-detects engine, voice, format from config)
python3 skills/tubescribe/scripts/tubescribe.py \
  --generate-audio <temp_dir>/tubescribe_<video_id>_summary.txt \
  --audio-output ~/Documents/TubeScribe/<safe_title>_summary

~/.tubescribe/config.json并自动使用配置的TTS引擎（mlx/kokoro/builtin）、语音混合和速度。输出格式（mp3/wav）来自配置。第6步：清理

第7步：打开文件夹

python3 skills/tubescribe/scripts/tubescribe.py --cleanup <video_id>

报告

open ~/Documents/TubeScribe/

告知创建的内容：DOCX文件名、MP3文件名 + 时长、视频统计信息。""", label="tubescribe", runTimeoutSeconds=900, cleanup="delete" )

Tell what was created: DOCX name, MP3 name + duration, video stats. """, label="tubescribe", runTimeoutSeconds=900, cleanup="delete" )

**After spawning, reply immediately:**
> 🎬 TubeScribe is processing - I'll let you know when it's ready!
Then continue the conversation. The sub-agent notification announces completion.

## Configuration

Config file: `~/.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
  }
}

输出选项

文档选项

音频选项

MLX-Audio 选项 (在 Apple Silicon 上首选)

Kokoro PyTorch 选项（备用方案）

处理选项

评论选项

队列选项

输出结构

~/Documents/TubeScribe/
├── {Video Title}.html         # Formatted document (or .docx / .md)
└── {Video Title}_summary.mp3  # Audio summary (or .wav)

生成后，打开文件夹（而非单个文件），以便您可以访问所有内容。

依赖项

必需：

• summarize命令行界面 —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 按顺序检查以下位置：

如果未找到，设置会将独立的二进制文件下载到工具目录。 工具目录版本不会与系统安装冲突。

队列处理

当用户在处理一个YouTube URL时发送多个URL：

开始前检查

python skills/tubescribe/scripts/tubescribe.py --queue-status

如果已在处理

# Add to queue instead of starting parallel processing
python skills/tubescribe/scripts/tubescribe.py --queue-add "NEW_URL"
# → Replies: "📋 Added to queue (position 2)"

完成后

# Check if more in queue
python skills/tubescribe/scripts/tubescribe.py --queue-next
# → Automatically pops and processes next URL

队列命令

批处理（一次处理多个URL）

python skills/tubescribe/scripts/tubescribe.py url1 url2 url3

依次处理所有URL，并在最后提供摘要。

错误处理

脚本会检测并报告以下错误，并提供明确信息：

当发生错误时，向用户报告并不要继续处理该视频。

提示

• 对于长视频（>30分钟），请将子代理超时时间增加至900秒
• 说话人检测在清晰的访谈/播客格式下效果最佳
• 单人讲话视频（教程、讲座）会自动跳过说话人标签
• 时间戳可直接链接到YouTube的对应时刻
• 处理多个视频时请使用批处理模式：tubescribe 网址1 网址2 网址3