一款为人类和 AI 智能体打造的 YouTube 转录 CLI

获取带有章节和时间戳上下文的英文 YouTube 字幕。使用 CLI 获取原始字幕或经模型编辑的 Markdown。你也可以将 AI 代理连接到 MCP 服务器。该工具不会下载音频或视频。该工具不需要 FFmpeg。

CLI：原始字幕、预览或经模型编辑的 Markdown
MCP：get_transcript，支持 filtered 和 full 模式
上下文：保留提供的章节，或添加带有原始视频时间的时间戳块
SponsorBlock：MCP 默认启用；CLI 需手动启用；包含完整字幕回退
无需模型：原始 CLI 输出和 MCP 纯文本不进行任何模型调用
可选模型编辑：默认使用 Pi；直接 API 后端包括 OpenRouter 和 DeepSeek

安装

要求：

uv
Python 3.14.7
Deno 2.3.0+
Pi，需单独安装，用于默认的 Markdown 后端

注意

默认后端使用 Pi 进行 Markdown 编辑，并在字幕提取后进行针对性清理。请单独安装并配置 Pi，或选择 OpenRouter，并指定明确的模型和仅通过环境变量提供的 API 密钥。原始转录输出和纯文本 MCP 输出不需要 Pi。

安装固定版本：

uv tool install --python 3.14.7 \
  'yt-transcript[mcp] @ git+https://github.com/nmdra/yt-transcript.git@v1.1.0'

yt-transcript --version
yt-transcript --doctor

此命令将应用固定为 1.1.0。

有关经验证的发布资产、校验和检查以及确切的依赖版本，请参阅安装指南。

重要：uvx yt-transcript 会选中一个不相关的 PyPI 项目。请改为从固定的 GitHub 发布版本安装此项目。

使用

将 URL 替换为 YouTube 视频 URL：

# Raw captions — no model call
yt-transcript URL --no-config --raw -o transcript.txt

# Preview planned processing without calling Pi
yt-transcript URL --no-config --preview

# Pi-edited Markdown
yt-transcript URL --no-config --max-chunks 3 -o transcript.md

# Focused editing removes separable non-substantive passages
yt-transcript URL --no-config --editorial-mode focused --max-chunks 3 -o focused.md

# Whole-video summary; the cap includes the final synthesis call
yt-transcript URL --no-config --editorial-mode summarized --max-chunks 3 -o summary.md

原始输出不需要模型。 --preview 获取字幕时不调用 Pi。预览会显示 Markdown 编辑前计划进行的调用次数。当字幕明确识别出预期词语时，所有 Markdown 模式都允许对普通词语进行保守的拼写纠正。名称、技术术语、数字、URL、代码、命令和不确定的词语保持受保护。这些是模型指令，并非有保证的拼写检查。原始输出和 MCP 纯文本保持不变。请参阅拼写纠正限制。如果你使用 -o，输出文件会包含 YAML 元数据。 Stdout 仅包含转录正文。

OpenRouter

直接使用 OpenRouter 格式化不需要 Pi：

# Set OPENROUTER_API_KEY in the environment first; do not store it in TOML.
yt-transcript URL --no-config --provider openrouter --model openai/gpt-4o --max-chunks 3 -o transcript.md
yt-transcript URL --no-config --provider openrouter --model openai/gpt-4o --editorial-mode summarized --max-chunks 20 -o summary.md

Pi 仍是默认后端。原始输出和 MCP 纯文本不使用模型。此版本使用 [formatting] 而非 [pi]，并带有单独的 [openrouter] token 限制。 OpenRouter 需要在进程环境中提供明确的模型 ID 和 OPENROUTER_API_KEY。默认 openrouter.max_output_tokens 为 每次模型调用 16384 个 token。推理 token 会消耗此额度。所选模型必须支持该限制。更大的额度并不保证完成。要保存设置，请使用 config.example.toml 编辑现有表格。对于 MCP，请在服务器 TOML 中选择后端，并确保密钥在服务器环境中可用。该工具不会自动重试，也不使用回退提供商。该工具不会返回部分输出。该工具会将转录文本发送到 OpenRouter 及其上游提供商。这可能会产生费用。请参阅CLI 提供商指南。从 dev7 更新时，请将 [pi] 重命名为 [formatting]。保留你现有的 Pi 设置。

DeepSeek 与思考控制

直接使用 DeepSeek 格式化不需要 Pi：

# Set DEEPSEEK_API_KEY in the environment first; never store it in TOML.
yt-transcript URL --no-config --provider deepseek --model deepseek-flash --max-chunks 3 -o transcript.md

DeepSeek 需要显式指定模型，并使用固定的 HTTPS 端点 https://api.deepseek.com/chat/completions。 deepseek-flash 和 deepseek-v4-pro 是模型示例，并非永久允许列表。 [deepseek].max_output_tokens 每次调用默认为 16384，允许 1 到 393216 之间的整数。所选模型必须支持该限制。转录文本直接发送到 DeepSeek，不经过 OpenRouter 的 data_collection="deny" 路由请求。不要假设具有同等的保留或隐私保证。

可选的 TOML 设置 formatting.thinking 和 formatting.thinking_level 控制全部三个后端。两者都省略时，摘要 Markdown 在每个阶段都以 medium 级别请求思考。 Standard 和 focused 保留 Pi/OpenRouter 默认值，并请求 DeepSeek 关闭思考。 thinking = false 始终请求关闭，包括摘要，并忽略已配置的级别。 thinking = true 使用配置的标量级别（low、medium 或 high），省略时为 medium。单独一个级别对 summarized 模式有效；在 summarized 模式之外，它需要显式 true，除非 thinking 被显式设为 false。 DeepSeek 将 medium 映射为 high。 Pi 和 OpenRouter 可以钳制、映射或拒绝请求的设置；某些模型始终进行推理。

思考会增加成本和延迟，并与可见输出争夺 token 配额。该工具不会自动提高 token 限制、重试、修复或发布部分输出。隐藏推理不会禁用思考或计费。此策略并不建立更好的摘要保真度。原始输出、纯文本 MCP 和检索工具仍然不调用模型。源字幕缓存不存储提供商生成的输出或推理。没有新的 CLI 思考标志或公开的 MCP 参数。参见思考策略和后端限制。这些更改不包含在上方固定的 1.0.0 安装中。

MCP

对于兼容的 MCP 客户端，请遵循 MCP 设置指南。

MCP 服务器提供 get_transcript：

filtered 是默认值，并尝试进行 SponsorBlock 过滤
full 跳过 SponsorBlock 过滤
纯文本输出不调用模型
output_format="markdown" 显式启用服务器选择的模型后端
纯文本保留提供的章节；否则，它会添加时间戳上下文
服务器配置的 summarized 模式为显式 Markdown 请求生成整段视频摘要
CLI 将进度写入终端 stderr

MCP 检索工具： 服务器还提供 get_video_info、get_transcript_segment、search_transcript 和 get_transcript_page。检索工具与 get_transcript 共享一个私有的本地源字幕缓存。默认情况下，缓存已启用，快照在创建 24 小时后过期。检索工具不调用模型。 Markdown 仍然在每次请求时调用模型。 Markdown 还可以发送可选的进度通知。参见检索工具和缓存。

使用 AI 代理安装

将此提示复制到具有本地 shell 和文件访问权限的代理中：

Install `nmdra/yt-transcript` `v1.1.0` for my user account with the MCP extra and exactly Python `3.14.7`.

First read the official installation guide, MCP guide, and release page:
https://github.com/nmdra/yt-transcript/blob/main/docs/installation.md
https://github.com/nmdra/yt-transcript/blob/main/docs/mcp.md
https://github.com/nmdra/yt-transcript/releases/tag/v1.0.0

Use the GitHub release wheel, not the unrelated PyPI package `yt-transcript`. Verify the wheel and source archive against the release `SHA256SUMS`. Stop if either check fails. Extract dependency constraints from that release source archive's `uv.lock` without executing archive content. Install the verified wheel in an isolated user-level `uv tool` environment with the MCP extra and exactly Python `3.14.7`.

Ask before replacing an existing installation, changing configuration, or installing missing runtimes/tools such as Python, Deno, Pi, or `uv`. Keep unrelated tools, environment variables, API keys, model credentials, and existing MCP servers unchanged. Preserve the existing backend, model, editorial mode, limits, and other TOML settings unless I approve a change. Do not overwrite an existing TOML file with the example configuration.

Configure MCP only for the client(s) I select. Read each client's official MCP documentation first. Use its native setup command or configuration format, not another client's schema. Use the installed executable's absolute path. Load the saved server TOML if I want its backend and editorial settings; explain that `--no-config` bypasses those settings.

Pi remains the default backend. If I select OpenRouter, require an explicit OpenRouter model ID and `OPENROUTER_API_KEY` in the MCP server's inherited process environment. Do not put the key in TOML, command arguments, MCP tool arguments, or chat. Explain that a running client does not inherit a key exported later in another terminal. The version 1.0.0 OpenRouter default is 16384 output tokens per model call; reasoning tokens can consume this allowance, and the selected model must support it. A larger allowance does not guarantee completion. Preserve any explicit output-token override.

Explain that version 1.0.0 permits only conservative ordinary-word spelling correction in model-generated Markdown. Uncertain words, names, technical terms, and protected literals remain unchanged. This is a prompt policy, not a guaranteed spelling checker. Raw output and MCP plain text remain model-free.

Explain that version 1.0.0 exposes five MCP tools, with `get_transcript` still primary and its public arguments unchanged. Source captions and metadata are stored privately in a shared local SQLite cache for 24 hours by default, with a 50 MiB retained-payload budget. Preserve any saved `[cache]` settings. The four retrieval helpers are model-free; Markdown still formats on each explicit request. Pagination needs a stored snapshot and expired cursors fail without refetching. No extra dependency or setup service is needed.

Perform offline installation checks only: inspect the installed version and Python version, run CLI help and doctor, and initialize MCP and list its tools if supported. Do not call any retrieval tool, fetch a video, run preview, or make a model request without separate approval. Doctor checks local readiness, not authentication or model accuracy. Explain how to reconnect the selected MCP client; for an active Pi session, use `/reload`.

If an asset, checksum, lockfile, compatibility detail, or configuration is ambiguous, stop and explain instead of guessing. Report the installed version, Python version, checksum results, release-locked dependency versions, install location, configuration changes, and offline startup/connectivity results without secrets.

文档

安装：先决条件、固定版本、更新和卸载
CLI 参考：模式、配置、预览和文件安全
MCP 设置：客户端配置、工具结果和限制
转录行为：章节、清理、聚焦编辑、元数据和过滤
故障排除：错误代码和恢复
开发与发布：测试、实时检查条件和发布工作流
更新日志

许可证

该代码采用 MIT 许可证。

除非授予单独许可，SponsorBlock 数据采用 CC BY-NC-SA 4.0 许可证。

GitHub 发布使用标签触发的公开发布工作流。 PyPI 发布需要单独批准。