youtube-transcript

YouTube 长视频（>1 小时）完整的逐字转录和翻译工作流程。当用户需要 (1) 从 YouTube 视频中提取字幕，(2) 将英文文本翻译成中文，(3) 处理超出会话限制的长视频，(4) 处理 DownSub API 响应并生成格式化文档时使用。

# YouTube Long Video Transcript & Translation

Full verbatim transcription and translation workflow for long YouTube videos (>1 hour).

## Prerequisites

- DownSub API key (Bearer token starting with `AIza...`)
- `zhiyan` tool (optional, for online doc generation)
- Sub-agent spawn capability (for long videos)

## DownSub API Configuration

**Endpoint**: `https://api.downsub.com/download`
**Method**: `POST`
**Headers**:
```
Authorization: Bearer AIzaM9ifctIOxusNAldvGeajHqq4rH6e7MJNfN
Content-Type: application/json
```
**Body**:
```json
{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}
```

**⚠️ CRITICAL**: Always check the `lang` field in response. **Use ONLY `en` or `en-auto`**. Do NOT use random languages (e.g., `lt` for Lithuanian).

## Pre-flight Check (Run First)

1. **Check DownSub API Access**
   - Verify `Authorization` header is configured
   - Common error: "401 Unauthorized" = missing/invalid API key

2. **Check Output Capabilities**
   - Has `zhiyan` tool? → Can generate online docs
   - No `zhiyan`? → Output local `.md` file

3. **Check Session Budget**
   - Ensure sub-agent spawn capability for long context processing

## Workflow

### Step 1: Preparation (Main Session)

1. **Environment Check**: Confirm DownSub API key present
2. **Get video link**
3. **Verify Language**: Use DownSub to check `lang`
   - IF `lang="en"` or `"en-auto"` → Proceed
   - IF `lang="lt"` or other → STOP, do not translate
4. **Check Length**: If >1000 lines, DO NOT process in main session
5. **Spawn Sub-Agent**:
   ```
   Task: Translate transcript.txt to Chinese verbatim.
   Process in 500-line chunks to separate files (part1.md, etc.).
   Merge to full_transcript.md.
   Add Executive Summary and Key Metrics Table (Chinese) at top.
   Do NOT use zhiyan.
   Budget: 30 minutes or $2 cost limit.
   ```

### Step 2: Execution (Sub-Agent)

1. **Read & Slice**: Read in chunks (limit=500). Do NOT read full file at once.
2. **Translate & Format**: Translate verbatim to Chinese. Add headers (e.g., `## 开场`).
3. **Stream Write**: Write each chunk to separate files or use `cat >>` to append.
4. **Enhance**:
   - Read first 500 lines to extract Key Metrics (Revenue, Growth, etc.)
   - Generate Executive Summary (3-5 bullets, Chinese)
   - Create Key Metrics Table (Markdown)
   - Prepend to final file
5. **Report**: Return path to `full_transcript.md`

### Step 3: Delivery (Main Session)

1. Receive file path from sub-agent
2. **Upload**: Run `zhiyan` MCP (`parse_markdown`) if available
3. Send doc link/file to user

## Troubleshooting

**Q: "What is the DownSub API Key?"**
→ API key missing. Provide Bearer token or configure in secrets.

**Q: "Tool `zhiyan` not found"**
→ `zhiyan` MCP not installed. **Solution**: Skip upload, send `.md` file directly.

**Q: Translates into nonsense/random text**
→ Downloaded wrong subtitle track (e.g., Lithuanian). **Solution**: Check `lang` field, use only `en`.

**Q: Task times out or stops responding**
→ Video too long for single session. **Solution**: Spawn sub-agent to process in background.

---

## 中文说明

# YouTube 长视频转录与翻译

针对长 YouTube 视频（>1 小时）的完整逐字转录与翻译工作流。

## 前置条件

- DownSub API 密钥（以 `AIza...` 开头的 Bearer token）
- `zhiyan` 工具（可选，用于在线文档生成）
- 子智能体生成能力（用于长视频）

## DownSub API 配置

**端点**：`https://api.downsub.com/download`
**方法**：`POST`
**请求头**：
```
Authorization: Bearer AIzaM9ifctIOxusNAldvGeajHqq4rH6e7MJNfN
Content-Type: application/json
```
**请求体**：
```json
{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}
```

**⚠️ 关键**：始终检查响应中的 `lang` 字段。**仅使用 `en` 或 `en-auto`**。不要使用随机语言（例如，代表立陶宛语的 `lt`）。

## 预检（先运行）

1. **检查 DownSub API 访问**
   - 验证 `Authorization` 请求头是否已配置
   - 常见错误："401 Unauthorized" = 缺失/无效的 API 密钥

2. **检查输出能力**
   - 有 `zhiyan` 工具？→ 可生成在线文档
   - 无 `zhiyan`？→ 输出本地 `.md` 文件

3. **检查会话预算**
   - 确保具备处理长上下文的子智能体生成能力

## 工作流

### 步骤 1：准备（主会话）

1. **环境检查**：确认 DownSub API 密钥存在
2. **获取视频链接**
3. **验证语言**：使用 DownSub 检查 `lang`
   - 如果 `lang="en"` 或 `"en-auto"` → 继续
   - 如果 `lang="lt"` 或其他 → 停止，不要翻译
4. **检查长度**：如果超过 1000 行，不要在主会话中处理
5. **生成子智能体**：
   ```
   Task: Translate transcript.txt to Chinese verbatim.
   Process in 500-line chunks to separate files (part1.md, etc.).
   Merge to full_transcript.md.
   Add Executive Summary and Key Metrics Table (Chinese) at top.
   Do NOT use zhiyan.
   Budget: 30 minutes or $2 cost limit.
   ```

### 步骤 2：执行（子智能体）

1. **读取与切片**：分块读取（limit=500）。不要一次读取整个文件。
2. **翻译与格式化**：逐字翻译成中文。添加标题（例如，`## 开场`）。
3. **流式写入**：将每个分块写入单独文件，或使用 `cat >>` 追加。
4. **增强**：
   - 读取前 500 行以提取关键指标（营收、增长等）
   - 生成执行摘要（3-5 个要点，中文）
   - 创建关键指标表格（Markdown）
   - 前置到最终文件
5. **报告**：返回 `full_transcript.md` 的路径

### 步骤 3：交付（主会话）

1. 接收来自子智能体的文件路径
2. **上传**：如果可用，运行 `zhiyan` MCP（`parse_markdown`）
3. 将文档链接/文件发送给用户

## 故障排查

**问：“DownSub API 密钥是什么？”**
→ API 密钥缺失。提供 Bearer token 或在 secrets 中配置。

**问：“找不到工具 `zhiyan`”**
→ 未安装 `zhiyan` MCP。**解决方案**：跳过上传，直接发送 `.md` 文件。

**问：翻译成了无意义/随机的文本**
→ 下载了错误的字幕轨道（例如立陶宛语）。**解决方案**：检查 `lang` 字段，仅使用 `en`。

**问：任务超时或停止响应**
→ 视频对于单次会话来说太长。**解决方案**：生成子智能体在后台处理。