youtube-podcast-to-md

YouTube 播客 → 中文 Markdown

概述

将 YouTube 播客视频的字幕提取，整理为高质量中文 Markdown 文档，默认针对英文播客优化；其他语言也可尽力处理。两种输出模式：

• 精简版（summary）：提取核心观点、关键数据、结构化摘要，过滤闲聊和重复表达
• 完整版（full）：高保真还原整个对话，保留对话结构、论述逻辑和信息完整性，经轻度书面化处理后呈现为自然流畅的中文对话

工作流（必须按顺序执行）

全局约定：

• 临时根目录默认使用 ${YTP2MD_TMP_DIR:-/tmp/youtube-podcast-to-md/}，每次任务必须在其中创建独立运行目录
• 最终 Markdown 默认输出到 ${YTP2MD_OUTPUT_DIR:-$PWD}；若用户想直接落到某个笔记库或知识库目录，请显式把 YTP2MD_OUTPUT_DIR 指向目标目录
• 任务结束后只清理本次独立运行目录，不删除用户指定的临时根目录
• 本技能可任意目录下执行，不依赖当前工作目录
• 所有命令使用 python3
• yt-dlp 可以直接在 PATH 中可用，或通过 python3 -m yt_dlp 可用；不要依赖某台机器上的固定 PATH
• 运行脚本时，把 SKILL_DIR 视为当前 skill 根目录（即包含本 SKILL.md 的目录）

Step 1：确认输入参数

从用户消息中提取：

• URL：YouTube 视频链接
• 模式：精简版 or 完整版；用户未指定时默认精简版，只有高保真要求明显影响成本或结果时再确认

Step 2：环境准备

SKILL_DIR="/absolute/path/to/youtube-podcast-to-md"
TMP_ROOT="${YTP2MD_TMP_DIR:-/tmp/youtube-podcast-to-md}"
OUTPUT_DIR="${YTP2MD_OUTPUT_DIR:-$PWD}"

mkdir -p "$TMP_ROOT" "$OUTPUT_DIR"
TMP_DIR="$(mktemp -d "$TMP_ROOT/run.XXXXXX")"
trap 'rm -rf -- "$TMP_DIR"' EXIT

python3 -m venv "$TMP_ROOT/.venv"
PYTHON="$TMP_ROOT/.venv/bin/python"
"$PYTHON" -m pip install --quiet -r "$SKILL_DIR/requirements.txt"

若需 Whisper 兜底，额外安装以下其一：

"$PYTHON" -m pip install --quiet -r "$SKILL_DIR/requirements-whisper.txt"

Whisper 还要求系统可调用 ffmpeg。安装失败时报告缺失依赖，不要静默退回不可靠结果。

Step 3：获取字幕

运行 "$PYTHON" "$SKILL_DIR/scripts/fetch_transcript.py" <URL> "$TMP_DIR"，脚本按优先级自动选择：

1. YouTube 手动上传的英文字幕（质量最高）
2. YouTube 自动生成的英文字幕
3. YouTube 上其他可用字幕（自动适配）
4. 若以上均不可用 → 运行 "$PYTHON" "$SKILL_DIR/scripts/fetch_with_whisper.py" <URL> "$TMP_DIR" 使用 Whisper 离线转录

补充说明：

• fetch_transcript.py 会优先拿英文字幕；如果只有其他语言字幕，会继续返回该语言字幕
• fetch_with_whisper.py 默认使用 --language auto 自动识别语言；若你明确只想按英文转录，可传 --language en

中间文件（位于 "$TMP_DIR"）：

• transcript_raw.txt — 原始字幕文本（含 [TS:MM:SS] 时间戳标记）
• transcript_meta.json — 视频元数据（标题、频道、时长、字幕来源等）

Step 4：字幕清洗与分块

运行 "$PYTHON" "$SKILL_DIR/scripts/clean_transcript.py" "$TMP_DIR/transcript_raw.txt" "$TMP_DIR"，执行：