Back to Details

pp-youtube

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- GENERATED FILE — DO NOT EDIT. This file is a verbatim mirror of library/media-and-entertainment/youtube/SKILL.md, regenerated post-merge by tools/generate-skills/. Hand-edits here are silently overwritten on the next regen. Edit the library/ source instead. See AGENTS.md "Generated artifacts: registry.json, cli-skills/". -->
<!-- 生成文件 — 请勿编辑。 此文件是library/media-and-entertainment/youtube/SKILL.md的完全镜像， 由tools/generate-skills/在合并后重新生成。此处的手动编辑会在下次重新生成时被静默覆盖。请改为编辑library/源文件。 参见AGENTS.md中的“生成产物：registry.json, cli-skills/”。 -->

YouTube — Printing Press CLI

YouTube — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the 
youtube-pp-cli
binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
  1. Install via the Printing Press installer:
    bash
    npx -y @mvanhorn/printing-press-library install youtube --cli-only
  2. Verify: 
    youtube-pp-cli --version
  3. Ensure 
    $GOPATH/bin
    (or 
    $HOME/go/bin
    ) is on 
    $PATH
    .
If the 
npx
install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):
bash
go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/youtube/cmd/youtube-pp-cli@latest
If 
--version
reports "command not found" after install, the install step did not put the binary on 
$PATH
. Do not proceed with skill commands until verification succeeds.
本技能驱动
youtube-pp-cli
二进制文件。在调用本技能的任何命令之前，您必须确认CLI已安装。如果未安装，请先执行以下步骤安装：
  1. 通过Printing Press安装程序安装：
    bash
    npx -y @mvanhorn/printing-press-library install youtube --cli-only
  2. 验证安装：
    youtube-pp-cli --version
  3. 确保
    $GOPATH/bin
    （或
    $HOME/go/bin
    ）已添加到
    $PATH
    环境变量中。
如果
npx
安装失败（无Node环境、离线等），可以回退到直接通过Go安装（要求Go 1.26.3或更高版本）：
bash
go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/youtube/cmd/youtube-pp-cli@latest
如果安装后执行
--version
返回“command not found”，说明安装步骤未将二进制文件添加到
$PATH
中。在验证成功之前，请不要继续使用技能命令。

When to Use This CLI

何时使用此CLI

Use this CLI when you have search terms (from photo tags, image labels, or notes) and want relevant YouTube videos back — with transcripts to verify relevance and embed snippets to drop into a blog draft. It's read-only and local; not a webapp backend, not a write tool.
当您拥有搜索词（来自图片标签、图像标注或笔记），并希望获取相关YouTube视频——同时获取字幕以验证相关性，以及嵌入代码片段以便直接插入博客草稿时，可以使用此CLI。它是只读且本地运行的工具，不是Web应用后端，也不是内容创作工具。

When Not to Use This CLI

何时不使用此CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.
请勿针对需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求激活此CLI。本CLI仅提供用于查看、导出、同步和分析的只读命令。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.
这些功能是其他同类型API工具所不具备的。

Blog-post composition

博客文章创作

  • youtube search-bulk
     — Take a list of search terms from stdin or args, return top-N YouTube videos per term in one JSON document with titles, channels, embed URLs, and thumbnails.
    When you have N search terms from an upstream pipeline (image labels, photo tags, scraped keywords), reach for this instead of looping single searches.
    bash
    youtube-pp-cli youtube search-bulk "sourdough scoring" "latte art" --top 3
  • youtube videos-transcript
     — Fetch the spoken-content transcript of a YouTube video using the timedtext endpoint. Works for auto-generated and manual captions on any public video. Caches into the local store.
    Read the transcript before deciding whether a candidate video actually fits the topic of the blog post or photo.
    bash
    youtube-pp-cli youtube videos-transcript dQw4w9WgXcQ --lang en --json
  • youtube videos-embed
     — Print embed HTML, iframe, or markdown-style embed for a video ID. Direct copy-paste into a blog draft.
    Once you've picked a video for the blog, get the embed snippet without remembering the exact iframe URL pattern.
    bash
    youtube-pp-cli youtube videos-embed dQw4w9WgXcQ --format markdown
  • youtube search-bulk
     — 从标准输入或参数中获取搜索词列表，返回每个搜索词对应的前N个YouTube视频，结果以单个JSON文档形式呈现，包含标题、频道、嵌入URL和缩略图。
    当您有来自上游流程（图像标注、图片标签、抓取的关键词）的N个搜索词时，请使用此命令，而非循环执行单个搜索。
    bash
    youtube-pp-cli youtube search-bulk "sourdough scoring" "latte art" --top 3
  • youtube videos-transcript
     — 使用timedtext端点获取YouTube视频的语音内容字幕。适用于任何公开视频的自动生成字幕和手动添加字幕。字幕会缓存到本地存储中。
    在决定候选视频是否符合博客文章或图片的主题之前，请先查看字幕。
    bash
    youtube-pp-cli youtube videos-transcript dQw4w9WgXcQ --lang en --json
  • youtube videos-embed
     — 输出视频ID对应的嵌入HTML、iframe或Markdown格式嵌入代码。可直接复制粘贴到博客草稿中。
    当您为博客选定视频后，无需记忆确切的iframe URL格式，直接使用此命令获取嵌入代码片段。
    bash
    youtube-pp-cli youtube videos-embed dQw4w9WgXcQ --format markdown

Reachability mitigation

可达性缓解

  • youtube videos-related
     — Find videos related to a target video using topicDetails + same-channel + tag overlap from the local store. Best-effort replacement for the deprecated relatedToVideoId parameter.
    When one candidate video is on-topic but you want more like it, this is the working stand-in for the deprecated parameter.
    bash
    youtube-pp-cli youtube videos-related dQw4w9WgXcQ --limit 10 --json
  • youtube videos-related
     — 使用本地存储中的topicDetails + 同频道 + 标签重叠信息，查找与目标视频相关的视频。是已弃用的relatedToVideoId参数的最佳替代方案。
    当某个候选视频符合主题，但您需要更多类似视频时，此命令可替代已弃用的参数。
    bash
    youtube-pp-cli youtube videos-related dQw4w9WgXcQ --limit 10 --json

Audience signal

受众信号

  • youtube videos-comments
     — Fetch top comments on a video, ranked locally by likeCount. Pulls up to 5 pages from commentThreads.list and sorts so most-liked floats regardless of API order.
    Use to gauge whether a video is actually well-received before embedding, or to surface viewer-supplied context the description doesn't mention.
    bash
    youtube-pp-cli youtube videos-comments dQw4w9WgXcQ --top 10
  • youtube videos-comments
     — 获取视频的热门评论，按点赞数本地排序。从commentThreads.list最多拉取5页内容，并按点赞数排序，不受API默认顺序影响。
    在嵌入视频前，使用此命令判断视频是否真的受欢迎，或获取视频描述中未提及的观众提供的上下文信息。
    bash
    youtube-pp-cli youtube videos-comments dQw4w9WgXcQ --top 10

Channel discovery

频道发现

  • youtube channel-uploads
     — List a channel's most recent uploads in one call. Resolves @handle or channelId, walks the auto-generated uploads playlist, returns video IDs + titles + publish times.
    Replaces the manual two-step lookup. Pairs naturally with --for-handle workflows.
    bash
    youtube-pp-cli youtube channel-uploads @veritasium --top 10
  • youtube channel-uploads
     — 一次调用列出频道的最新上传视频。支持解析@用户名或channelId，遍历自动生成的上传播放列表，返回视频ID + 标题 + 发布时间。
    替代手动两步查找流程。与--for-handle工作流天然适配。
    bash
    youtube-pp-cli youtube channel-uploads @veritasium --top 10

Command Reference

命令参考

youtube — Manage youtube
  • youtube-pp-cli youtube channels-list
    — Retrieves a list of resources, possibly filtered. Now supports 
    --for-handle @handle
    for modern channel resolution.
  • youtube-pp-cli youtube comment-threads-list
    — Retrieves top-level comment threads, filterable by video, channel, or thread id.
  • youtube-pp-cli youtube playlist-items-list
    — Retrieves a list of resources, possibly filtered.
  • youtube-pp-cli youtube playlists-list
    — Retrieves a list of resources, possibly filtered.
  • youtube-pp-cli youtube search-list
    — Retrieves a list of search resources
  • youtube-pp-cli youtube videos-list
    — Retrieves a list of resources, possibly filtered.
youtube — 管理YouTube相关操作
  • youtube-pp-cli youtube channels-list
    — 获取资源列表，可筛选。现已支持
    --for-handle @handle
    用于现代频道解析。
  • youtube-pp-cli youtube comment-threads-list
    — 获取顶级评论线程，可按视频、频道或线程ID筛选。
  • youtube-pp-cli youtube playlist-items-list
    — 获取资源列表，可筛选。
  • youtube-pp-cli youtube playlists-list
    — 获取资源列表，可筛选。
  • youtube-pp-cli youtube search-list
    — 获取搜索资源列表
  • youtube-pp-cli youtube videos-list
    — 获取资源列表，可筛选。

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:
bash
youtube-pp-cli which "<capability in your own words>"
which
resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 
0
means at least one match; exit code 
2
means no confident match — fall back to 
--help
or use a narrower query.
当您知道要做什么但不知道对应命令时，可直接询问CLI：
bash
youtube-pp-cli which "<用您自己的话描述功能>"
which
命令会将自然语言的功能查询解析为此CLI精选功能索引中最匹配的命令。退出码
0
表示至少有一个匹配项；退出码
2
表示没有确定的匹配项——请回退到
--help
或使用更精确的查询。

Recipes

使用示例

Sample use case: justinwfu/pictovideo puts the recipes below into a real photo-keywords → candidate-video → embedded blog draft pipeline. Look there if you want to see the commands wired end-to-end before composing your own flow.
示例用例： justinwfu/pictovideo 将以下示例整合到了完整的图片关键词 → 候选视频 → 嵌入博客草稿流程中。如果您想查看命令的端到端关联方式，再构建自己的流程，请参考该项目。

Photo keywords to candidate videos

图片关键词转候选视频

bash
cat photo-keywords.txt | youtube-pp-cli youtube search-bulk --stdin --top 5 --json --select "results[].videoId,results[].title,results[].channelTitle,results[].embedUrl"
Reads keywords (one per line), searches each, returns webapp-ready embed-URL JSON. Use --select with dotted paths to keep the output tight.
bash
cat photo-keywords.txt | youtube-pp-cli youtube search-bulk --stdin --top 5 --json --select "results[].videoId,results[].title,results[].channelTitle,results[].embedUrl"
读取关键词（每行一个），逐个搜索，返回适合Web应用的嵌入URL JSON。使用--select和点路径精简输出内容。

Verify a candidate via transcript

通过字幕验证候选视频

bash
youtube-pp-cli youtube videos-transcript dQw4w9WgXcQ --lang en --json --select "text" | head -c 2000
Pull the first 2KB of the transcript to confirm the video is actually about the topic before adding it to the blog.
bash
youtube-pp-cli youtube videos-transcript dQw4w9WgXcQ --lang en --json --select "text" | head -c 2000
获取字幕的前2KB内容，确认视频确实符合主题后再将其添加到博客中。

Get a markdown embed for the draft

获取用于草稿的Markdown嵌入代码

bash
youtube-pp-cli youtube videos-embed dQw4w9WgXcQ --format markdown
Drops a ready-to-paste markdown video reference into your editor buffer.
bash
youtube-pp-cli youtube videos-embed dQw4w9WgXcQ --format markdown
生成可直接粘贴到编辑器缓冲区的Markdown视频引用。

Find more candidates like a picked one

查找与选定视频类似的更多候选视频

bash
youtube-pp-cli youtube videos-related dQw4w9WgXcQ --limit 5 --json --select "results[].videoId,results[].title"
Heuristic-based replacement for the deprecated relatedToVideoId. Uses topic + channel + tag overlap from synced local data.
bash
youtube-pp-cli youtube videos-related dQw4w9WgXcQ --limit 5 --json --select "results[].videoId,results[].title"
基于启发式的方案，替代已弃用的relatedToVideoId参数。使用同步的本地数据中的主题 + 频道 + 标签重叠信息。

Bulk-research pipeline

批量研究流程

bash
cat photo-keywords.txt | youtube-pp-cli youtube search-bulk --stdin --top 3 --json | jq '.results[].videoId' | xargs -I {} youtube-pp-cli youtube videos-transcript {} --json
End-to-end: keywords in, transcripts out, ready for a quality filter before blog composition.
bash
cat photo-keywords.txt | youtube-pp-cli youtube search-bulk --stdin --top 3 --json | jq '.results[].videoId' | xargs -I {} youtube-pp-cli youtube videos-transcript {} --json
端到端流程：输入关键词，输出字幕，可在博客创作前进行质量筛选。

Auth Setup

认证设置

API-key only — set 
YOUTUBE_API_KEY
and you're done. Read-only public-data operations only (10,000 quota units/day default). Write operations are not configured; this CLI is for discovery and research, not channel management.
Run 
youtube-pp-cli doctor
to verify setup.
仅需API密钥——设置
YOUTUBE_API_KEY
即可完成配置。仅支持只读的公开数据操作（默认每日10,000配额单位）。未配置写入操作；此CLI仅用于发现和研究，不用于频道管理。
执行
youtube-pp-cli doctor
验证设置是否正确。

Agent Mode

Agent模式

Add 
--agent
to any command. Expands to: 
--json --compact --no-input --no-color --yes
.
  • Pipeable — JSON on stdout, errors on stderr
  • Filterable — 
    --select
    keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
    bash
    youtube-pp-cli youtube channels-list --agent --select id,name,status
  • Previewable — 
    --dry-run
    shows the request without sending
  • Offline-friendly — sync/search commands can use the local SQLite store when available
  • Non-interactive — never prompts, every input is a flag
  • Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests
在任何命令后添加
--agent
参数。等效于：
--json --compact --no-input --no-color --yes
。
  • 可管道化 — 标准输出为JSON，错误信息输出到标准错误
  • 可筛选 — 
    --select
    参数保留字段子集。点路径可深入嵌套结构；数组会遍历每个元素。对于输出冗长的API，此参数对精简上下文至关重要：
    bash
    youtube-pp-cli youtube channels-list --agent --select id,name,status
  • 可预览 — 
    --dry-run
    参数显示请求内容但不发送
  • 离线友好 — 同步/搜索命令可在本地SQLite存储可用时使用该存储
  • 非交互式 — 从不提示，所有输入均通过标志参数提供
  • 只读 — 请勿使用此CLI执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

Response envelope

响应包

Commands that read from the local store or the API wrap output in a provenance envelope:
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
Parse 
.results
for data and 
.meta.source
to know whether it's live or local. A human-readable 
N results (live)
summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
从本地存储或API读取数据的命令会将输出包装在来源信息包中：
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
解析
.results
获取数据，解析
.meta.source
判断数据来自在线API还是本地存储。仅当标准输出为终端时，才会向标准错误输出人类可读的
N results (live)
摘要——管道/Agent消费者会在标准输出获取纯JSON内容。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:
youtube-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
youtube-pp-cli feedback --stdin < notes.txt
youtube-pp-cli feedback list --json --limit 10
Entries are stored locally at 
~/.youtube-pp-cli/feedback.jsonl
. They are never POSTed unless 
YOUTUBE_FEEDBACK_ENDPOINT
is set AND either 
--send
is passed or 
YOUTUBE_FEEDBACK_AUTO_SEND=true
. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
当您（或Agent）发现此CLI存在问题时，可记录反馈：
youtube-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
youtube-pp-cli feedback --stdin < notes.txt
youtube-pp-cli feedback list --json --limit 10
反馈条目存储在本地
~/.youtube-pp-cli/feedback.jsonl
文件中。除非设置了
YOUTUBE_FEEDBACK_ENDPOINT
且传递了
--send
参数或设置了
YOUTUBE_FEEDBACK_AUTO_SEND=true
，否则反馈不会被POST到远程服务器。默认行为仅存储在本地。
请记录让您感到意外的内容，而非正式的错误报告。简短、具体、单行描述：这样的反馈更有价值。

Output Delivery

输出交付

Every command accepts 
--deliver <sink>
. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
SinkEffect
stdout
Default; write to stdout only
file:<path>
Atomically write output to 
<path>
(tmp + rename)
webhook:<url>
POST the output body to the URL (
application/json
or 
application/x-ndjson
when 
--compact
)
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
每个命令都支持
--deliver <sink>
参数。输出会发送到指定的目标，同时（或替代）输出到标准输出，因此Agent无需手动管道即可路由命令结果。支持三种目标：
目标效果
stdout
默认值；仅输出到标准输出
file:<path>
原子性地将输出写入
<path>
（先写入临时文件再重命名）
webhook:<url>
将输出体POST到指定URL（当使用
--compact
时，内容类型为
application/json
或
application/x-ndjson
）
不支持的协议会返回结构化错误，并列出支持的类型。Webhook失败会返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
youtube-pp-cli profile save briefing --json
youtube-pp-cli --profile briefing youtube channels-list
youtube-pp-cli profile list --json
youtube-pp-cli profile show briefing
youtube-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. 
agent-context
lists all available profiles under 
available_profiles
so introspecting agents discover them at runtime.
配置文件是一组保存的标志值，可在多次调用中复用。当定时Agent每次运行都使用相同配置调用同一命令时，可使用此功能——即HeyGen的“Beacon”模式。
youtube-pp-cli profile save briefing --json
youtube-pp-cli --profile briefing youtube channels-list
youtube-pp-cli profile list --json
youtube-pp-cli profile show briefing
youtube-pp-cli profile delete briefing --yes
显式标志始终优先于配置文件值；配置文件值优先于默认值。
agent-context
会在
available_profiles
下列出所有可用配置文件，以便自省Agent在运行时发现它们。

Exit Codes

退出码

CodeMeaning
0Success
2Usage error (wrong arguments)
3Resource not found
4Authentication required
5API error (upstream issue)
7Rate limited (wait and retry)
10Config error
代码含义
0成功
2使用错误（参数错误）
3资源未找到
4需要认证
5API错误（上游问题）
7速率限制（请等待后重试）
10配置错误

Argument Parsing

参数解析

Parse 
$ARGUMENTS
:
  1. Empty, 
    help
    , or 
    --help
     → show 
    youtube-pp-cli --help
    output
  2. Starts with 
    install
     → ends with 
    mcp
    → MCP installation; otherwise → see Prerequisites above
  3. Anything else → Direct Use (execute as CLI command with 
    --agent
    )
解析
$ARGUMENTS
的规则：
  1. 为空、
    help
    或
    --help
     → 显示
    youtube-pp-cli --help
    输出
  2. 以
    install
    开头     → 如果结尾为
    mcp
    → 安装MCP；否则 → 参见顶部的前提条件部分
  3. 其他情况 → 直接使用（以
    --agent
    标志执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
bash
claude mcp add youtube-pp-mcp -- youtube-pp-mcp
Verify: 
claude mcp list
从此CLI的已发布公共库条目或预构建版本安装MCP二进制文件，然后注册：
bash
claude mcp add youtube-pp-mcp -- youtube-pp-mcp
验证安装：
claude mcp list

Direct Use

直接使用

  1. Check if installed: 
    which youtube-pp-cli
    If not found, offer to install (see Prerequisites at the top of this skill).
  2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
  3. Execute with the 
    --agent
    flag:
    bash
    youtube-pp-cli <command> [subcommand] [args] --agent
  4. If ambiguous, drill into subcommand help: 
    youtube-pp-cli <command> --help
    .
  1. 检查是否已安装：
    which youtube-pp-cli
    如果未找到，提供安装选项（参见顶部的前提条件部分）。
  2. 将用户查询与上述独特功能和命令参考中的最佳命令匹配。
  3. 使用
    --agent
    标志执行命令：
    bash
    youtube-pp-cli <command> [subcommand] [args] --agent
  4. 如果存在歧义，查看子命令帮助：
    youtube-pp-cli <command> --help
    。