Question 1

为什么 yt-dlp Python API 的 SponsorBlock postprocessor 报告 'No matching segments were found'，而 CLI 却能正常工作？

Accepted Answer

这个 bug 出在 `'categories': 'ModifyChapters'` —— `categories` 必须是 SponsorBlock 类别名称的集合，而 `ModifyChapters` 是一个独立的后处理器，必须单独添加才能将章节写入文件。传入单个字符串会匹配到零个类别，因此什么也找不到。

CLI 参数 `--sponsorblock-mark all` 实际上会配置两个后处理器。可以使用 [devscripts/cli_to_api.py](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py) 将任何 CLI 命令转换为 API 选项。正确的配置如下：

```python
ydl_opts = {
    'format': 'worstvideo+worstaudio',
    'outtmpl': '%(title)s.%(ext)s',
    'merge_output_format': 'mkv',
    'postprocessors': [{
        'key': 'SponsorBlock',
        'api': 'https://sponsor.ajay.app',
        'categories': {'sponsor', 'selfpromo', 'interaction', 'intro',
                       'outro', 'preview', 'music_offtopic', 'filler',
                       'poi_highlight', 'chapter'},
        'when': 'after_filter',
    }, {
        'key': 'ModifyChapters',
        'force_keyframes': False,
        'remove_chapters_patterns': [],
        'remove_ranges': [],
        'remove_sponsor_segments': set(),
        'sponsorblock_chapter_title': '[SponsorBlock]: %(category_names)l',
    }]
}
```

API 选项的文档位于 `yt_dlp/YoutubeDL.py` 中 `YoutubeDL` 的 docstring 里；对于任何未写入文档的内容，可以将你能正常工作的 CLI 命令通过 `cli_to_api.py` 运行，以获得完全等价的 Python 写法。

Question 2

为什么 yt-dlp 只显示 storyboard(sb0/sb1)格式,并在 YouTube 上报错 "challenge solving failed: Some formats may be missing"?

Accepted Answer

YouTube 需要解决 JavaScript 挑战才能解锁真实的视频格式，但未检测到 JS 运行时（详细日志显示 `JS runtimes: none`，且所有 JS Challenge Providers 均为 'unavailable'），因此 yt-dlp 仅列出 storyboard 格式，随后报错 'Requested format is not available'。解决方法：安装受支持的 JavaScript 运行时，以便 EJS 挑战求解器 (yt_dlp_ejs) 能够正常工作——例如安装 Node.js (LTS)、Deno 或 Bun，并确保它已加入你的 PATH，然后重新运行 yt-dlp。尤其是在使用 `--cookies` 时，这一步是必需的。请参阅官方指南：https://github.com/yt-dlp/yt-dlp/wiki/EJS#step-1-install-a-supported-javascript-runtime

Question 3

如何修复使用 yt-dlp 和 FFmpeg 8.0 提取 YouTube 音频时出现的"Error parsing Opus packet header"错误？

Accepted Answer

这是 FFmpeg 解析 Google 所提供的 WebM/Opus 文件时出现的问题，而非 yt-dlp 下载损坏。该问题已在 FFmpeg 上游修复（issue #20954）。请将 FFmpeg 升级到已包含补丁的 8.x 或更高版本的构建，或包含该修复的发行版软件包。可使用 `ffmpeg -version` 进行验证。对于无法获取该修复的发行版（例如 Nixpkgs 稳定分支），请使用 Nixpkgs unstable 或官方静态 FFmpeg 构建。作为变通方法，可以使用 yt-dlp 的 `--extract-audio` 生成的 `.opus` 文件；即使原始 `.webm` 文件触发警告，重新封装后的 Opus 文件通常也能通过验证。如果 FFmpeg 成功完成且输出的音频可以正常播放，您也可以忽略该警告。

Question 4

为什么用 yt-dlp 下载 YouTube 视频后，在 mpv 中播放时音频音调会变低？

Accepted Answer

这是 mpv 的播放/配置问题，并非 yt-dlp 下载的文件损坏。可以通过在 VLC 中播放该文件或运行 `mpv --no-config video.mkv` 来验证。如果音调正常，请删除或注释掉 mpv 配置中自定义的 `video-sync-max-video-change` 行（Linux/macOS 上位于 `~/.config/mpv/mpv.conf`，Windows 上位于 `%APPDATA%\mpv\mpv.conf`），然后重启 mpv。该设置可能会对时间戳异常的视频触发音频重采样/速度调整，导致音调听起来偏低。

Question 5

如何修复 yt-dlp 中的 'nsig extraction failed' 和 'Sign in to confirm you’re not a bot' 错误？

Accepted Answer

1. 将 yt-dlp 更新到最新的 nightly 版本：`yt-dlp -U` 或 `pip install -U yt-dlp`。
2. 如果仍然遇到“请登录以确认您不是机器人”的错误，请传递浏览器 cookies 以绕过 YouTube 的机器人检测。使用 `--cookies-from-browser BROWSER`（例如 `--cookies-from-browser chrome`）或通过 `--cookies COOKIES_FILE` 导出 cookies 文件。详细步骤请参见：https://github.com/yt-dlp/yt-dlp/wiki/Extractors#exporting-youtube-cookies
3. “nsig extraction failed”警告通常在更新后消失；如果没有，这是一个已知的临时问题——请关注链接的 GitHub issues 以获取更新。

yt-dlp

核心功能

避坑指南

适用场景

标签

快速上手

相似推荐