ytdl

🇺🇸 English | 🇯🇵 日本語 | 🇨🇳 简体中文 | 🇪🇸 Español | 🇮🇳 हिन्दी | 🇧🇷 Português | 🇮🇩 Bahasa Indonesia

面向开发者的通用媒体获取 CLI。支持通过 yt-dlp 下载视频网站内容、Torrent（P2P）、RTMP/RTSP 流媒体等多种来源。交互式 UI + AI 原生（Claude Code 插件）。

合规与法律声明

本项目是通用媒体获取工具。

仅适用于以下内容：

• 您拥有版权的内容
• 公共许可（如 Creative Commons）内容
• 平台明确允许下载的内容

用户有责任遵守版权法和各平台的服务条款。本项目不鼓励或支持未经许可下载受版权保护的内容。

禁止用途

• 未经许可下载受版权保护的内容
• 未经授权下载付费或订阅内容
• 再分发下载的媒体
• 规避 DRM 或技术保护措施

允许用途

• 备份您自己上传的内容
• 离线处理您拥有权利的媒体
• 归档 Creative Commons / 公共领域内容
• 拥有适当权利的教育和研究目的

安装

npm install -g @kanketsu/ytdl

需要 yt-dlp 和 ffmpeg。首次运行时，如果未安装，ytdl 会提供自动安装。手动安装：

brew install yt-dlp ffmpeg

语言设置

默认 UI 语言为日语。切换为中文：

# 环境变量
YTDL_LANG=zh-Hans ytdl

# CLI 参数
ytdl --lang zh-Hans "URL"

使用方法

交互模式

不带参数运行 — 逐步选择：

ytdl

命令模式

# 视频网站（yt-dlp，支持 1000+ 网站）
ytdl "https://example.com/watch?v=VIDEO_ID"        # 最高画质 + 缩略图 + 字幕 + 描述
ytdl -a "https://example.com/watch?v=VIDEO_ID"     # 仅音频 (m4a)
ytdl -q 720 "https://example.com/watch?v=VIDEO_ID" # 720p
ytdl -p "https://example.com/playlist?list=..."     # 播放列表
ytdl -i "https://example.com/watch?v=VIDEO_ID"     # 仅信息（不下载）

# Torrent / P2P
ytdl "magnet:?xt=urn:btih:..."                            # 磁力链接（自动检测）
ytdl "https://example.com/file.torrent"                   # .torrent URL（自动检测）

# RTMP / RTSP 流媒体
ytdl "rtmp://live.example.com/stream/key"                 # RTMP 直播
ytdl "rtsp://camera.example.com/feed"                     # RTSP 摄像头
ytdl --duration 60 "rtmp://..."                           # 录制 60 秒

# 网站分析（当 yt-dlp 无法获取时）
ytdl --analyze "https://example.com/page-with-video"      # 强制网站分析模式

# 强制指定后端
ytdl --via torrent "magnet:?xt=..."
ytdl --via stream "rtmp://..."
ytdl --via ytdlp "https://..."

# 直接传递 yt-dlp 选项
ytdl "URL" -- --limit-rate 1M

选项

| 参数 | 说明 | 默认值 | |------|------|--------| | -a | 仅音频（m4a） | off | | -q <分辨率> | 画质（360/480/720/1080/1440/2160） | 最高 | | -o <目录> | 输出目录 | ~/Downloads | | -p | 播放列表模式 | off | | -b <浏览器> | Cookie 浏览器 | off | | -n | 不使用 Cookie（默认） | on | | -i | 仅信息 | off | | -t | 下载后转录 | off | | --backend <b> | 转录后端 (local/api) | local | | --manuscript <path> | 原稿文件路径（提高准确度） | - | | --lang <code> | 语言（ja/en/zh-Hans/es/hi/pt/id） | ja | | --via <backend> | 指定后端（ytdlp/torrent/stream/analyzer） | 自动 | | --analyze | 强制网站分析模式 | off | | --duration <秒> | 流媒体录制时长（秒） | 直到停止 | | -- | 传递给 yt-dlp | - |

默认不使用浏览器 Cookie。对于受限内容（年龄限制、会员专属等），请使用 -b <浏览器>。

架构

ytdl 根据 URL 类型自动选择合适的后端：

ytdl CLI
  │
  ├── magnet: / .torrent  → Torrent 后端（webtorrent P2P）
  ├── rtmp:// / rtsp://   → 流媒体后端（ffmpeg spawn）
  ├── --analyze 标志      → 网站分析后端（Chrome CDP）
  └── http(s)://          → yt-dlp 后端（1000+ 网站）
                               └── 失败时 → 网站分析兜底

yt-dlp 后端封装 bin/ytdl.sh（与 v1 相同）。新后端完全在 lib/backends/ 中实现。

输出结构

~/Downloads/
  └── 频道名/
      └── 标题/
          ├── 标题.mp4
          ├── 标题.jpg           # 缩略图
          ├── 标题.zh-Hans.srt   # 字幕
          ├── 标题.description.txt   # 描述
          └── ytdl_20250226_1234.log # 日志

Claude Code 插件

将 ytdl 作为 Claude Code 技能使用。Claude 会通过 AskUserQuestion 交互式确认下载内容。支持视频网站、磁力链接、RTMP/RTSP 流媒体和网站分析。

安装

/plugin marketplace add kanketsu-jp/ytdl
/plugin install ytdl@kanketsu-ytdl

使用方法

在 Claude Code 对话中粘贴任意媒体 URL 或说"下载这个"。技能会自动激活：

1. 检查 ytdl 是否已安装（未安装则提示安装）
2. 检测 URL 类型并选择合适的后端
3. 获取媒体信息（如适用）
4. 询问您的需求（视频/音频、画质、保存位置）
5. 执行下载

AI 功能

通用 URL 检测

直接粘贴任意 URL，ytdl 会自动路由到正确的后端：

• 视频网站（支持 1000+ 站点） → yt-dlp
• magnet: 链接 → Torrent（webtorrent）
• rtmp://、rtsp:// → 流媒体抓取（ffmpeg）
• 包含嵌入视频的页面 → 网站分析

页面URL分析

无需自己查找视频的直接URL。只需粘贴包含视频的网页URL，AI 会：

1. 分析页面以查找嵌入的视频
2. 展示找到的视频（如有多个，可供选择）
3. 下载选定的视频

适用于 Claude Code。

示例：

保存 https://example.com/blog/my-post 中的视频

批量下载

一次粘贴多个URL。AI 只问一次偏好设置（视频/音频、画质），然后应用到所有下载。

示例：

下载这些：
https://example.com/watch?v=aaa
https://example.com/watch?v=bbb
magnet:?xt=urn:btih:ccc

免责声明

本软件仅供合法使用。作者不对任何滥用行为负责。

许可证

MIT