universal-media-downloader

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Universal Media Downloader（通用视频/播客下载）

Universal Media Downloader (General Video/Podcast Download)

适用范围

Scope of Application

优先覆盖（通常可直接用）

抖音：
```
douyin.com
```
、
```
v.douyin.com
```
等分享/视频链接
B站：
```
bilibili.com
```
、
```
b23.tv
```
等
YouTube：
```
youtube.com
```
、
```
youtu.be
```
以及其它 yt-dlp 支持的网站（数量很多）

播客平台

小宇宙（单集/节目页）：多数情况下可直接下载音频（yt-dlp 通常能用）
其它播客平台：如果页面可解析出音频直链，通常也能下载

合规提示：仅用于下载你有权保存的内容（例如你自己上传/拥有版权/获得授权/平台允许离线的内容）。遇到 DRM/加密或平台限制时，不要尝试绕过。

Prioritized Coverage (Usually Directly Usable)

Douyin: Sharing/video links like
```
douyin.com
```
,
```
v.douyin.com
```
, etc.
Bilibili: Links like
```
bilibili.com
```
,
```
b23.tv
```
, etc.
YouTube:
```
youtube.com
```
,
```
youtu.be
```
And other websites supported by yt-dlp (a large number)

Podcast Platforms

Xiaoyuzhou (Single Episode/Program Page): Audio can usually be downloaded directly in most cases (yt-dlp is usually applicable)
Other podcast platforms: If the page can parse out direct audio links, downloads are usually possible

Compliance Note: Only use to download content you are authorized to save (e.g., content you uploaded/own copyright for/obtained authorization for/platform allows offline access to). Do not attempt to bypass when encountering DRM/encryption or platform restrictions.

快速开始

Quick Start

1）下载视频（默认）

1) Download Video (Default)

命令：

python scripts/download_media.py "<URL>"

默认保存目录：
- 技能目录下的
```
downloads/
```
  文件夹（自包含）
- 可通过
```
--out-dir
```
  参数自定义输出路径

Command:

python scripts/download_media.py "<URL>"

Default save directory:
- The
```
downloads/
```
  folder under the skill directory (self-contained)
- Custom output path can be set via the
```
--out-dir
```
  parameter

2）只下载音频（适合播客 / 只想要 MP3）

2) Download Audio Only (Suitable for Podcasts / Only Want MP3)

命令：

python scripts/download_media.py --audio-only --audio-format mp3 "<URL>"

Command:

python scripts/download_media.py --audio-only --audio-format mp3 "<URL>"

3）遇到 403 / 需要登录 / 风控拦截：用 cookies 重试

3) Encounter 403 / Need Login / Risk Control Block: Retry with Cookies

让用户提供浏览器导出的 Netscape 格式
```
cookies.txt
```

然后重试：

python scripts/download_media.py --cookies "/path/to/cookies.txt" "<URL>"

Ask users to provide Netscape format
```
cookies.txt
```
exported from the browser

Then retry:

python scripts/download_media.py --cookies "/path/to/cookies.txt" "<URL>"

4）需要代理（可选）

4) Proxy Required (Optional)

例如：
- ```
--proxy "socks5://127.0.0.1:7890"
```

Example:
- ```
--proxy "socks5://127.0.0.1:7890"
```

5）指定下载路径

5) Specify Download Path

用户可通过自然语言指定保存位置，AI 应自动转换为
```
--out-dir
```
参数
示例：
- 用户说"下载到桌面" →
```
--out-dir ~/Desktop
```
- 用户说"保存到 Videos/bilibili" →
```
--out-dir "~/Videos/bilibili"
```
- 用户说"下载到这个文件夹"（指定某路径）→ 使用用户指定的绝对路径
注意：确保目标目录存在，如不存在可自动创建

Users can specify the save location via natural language, and the AI should automatically convert it to the
```
--out-dir
```
parameter
Examples:
- User says "Download to desktop" →
```
--out-dir ~/Desktop
```
- User says "Save to Videos/bilibili" →
```
--out-dir "~/Videos/bilibili"
```
- User says "Download to this folder" (specify a path) → Use the absolute path specified by the user
Note: Ensure the target directory exists; if not, it can be created automatically

平台差异与限制（重要）

Platform Differences and Restrictions (Important)

YouTube/B站/抖音：
- 常见失败原因：年龄限制、地区限制、频繁请求触发风控、需要登录
- 处理方式：cookies、代理、或降低并发/等待后重试
- YouTube 额外提示：若出现 Signature solving failed / JS challenge 警告，可按 yt-dlp 的 EJS 指引启用挑战求解组件（例如加
```
--remote-components ejs:github
```
  ），或让用户提供 cookies
Spotify：
- Spotify 上的内容可能存在 DRM、账号权限/订阅限制，且“下载”可能违反平台条款。
- 本 skill 不保证 Spotify 链接一定可下载。
- 可行替代：
  - 使用官方离线功能（若平台提供）
  - 提供该播客的 RSS/音频直链（如果你拥有/可获得），再用本脚本下载

YouTube/Bilibili/Douyin:
- Common failure reasons: Age restrictions, regional restrictions, frequent requests triggering risk control, need for login
- Handling methods: Use cookies, proxy, or reduce concurrency/retry after waiting
- Additional YouTube note: If a Signature solving failed / JS challenge warning appears, follow yt-dlp's EJS guidelines to enable the challenge-solving component (e.g., add
```
--remote-components ejs:github
```
  ), or ask the user to provide cookies
Spotify:
- Content on Spotify may have DRM, account permission/subscription restrictions, and "downloading" may violate platform terms.
- This skill does not guarantee that Spotify links can be downloaded for sure.
- Viable alternatives:
  - Use official offline functions (if provided by the platform)
  - Provide the RSS/audio direct link of the podcast (if you own/obtain it), then use this script to download

Bundled scripts

```
scripts/download_media.py
```
- 基于
```
yt-dlp
```
  的通用下载器
- 输出：成功时最后一行
```
SAVED_FILEPATH=...
```
- AI 使用指引：当用户指定保存路径时，自动使用
```
--out-dir
```
  参数
- 参数：
  - ```
  url
```
  （必填）
- ```
--audio-only
```
    /
```
--audio-format
```
  - ```
  --subtitles
```
  （可选，自动下载字幕）
- ```
--sub-lang
```
    （可选，字幕语言，默认 all）
  - ```
  --cookies
```
  （可选）
- ```
--proxy
```
    （可选）
  - ```
  --out-dir
```
  （可选，自定义输出目录）

```
scripts/download_media.py
```
- General downloader based on
```
yt-dlp
```
- Output: Last line
```
SAVED_FILEPATH=...
```
  when successful
- AI Usage Guide: When users specify a save path, automatically use the
```
--out-dir
```
  parameter
- Parameters:
  - ```
  url
```
  (required)
- ```
--audio-only
```
    /
```
--audio-format
```
  - ```
  --subtitles
```
  (optional, automatically downloads subtitles)
- ```
--sub-lang
```
    (optional, subtitle language, default is all)
  - ```
  --cookies
```
  (optional)
- ```
--proxy
```
    (optional)
  - ```
  --out-dir
```
  (optional, custom output directory)

依赖

Dependencies

系统依赖

System Dependencies

依赖	安装方式
`yt-dlp`	`pip install yt-dlp`
`ffmpeg` （可选，用于字幕提取和音频转换）	macOS: `brew install ffmpeg` <br>Linux: `sudo apt-get install ffmpeg`

Dependency	Installation Method
`yt-dlp`	`pip install yt-dlp`
`ffmpeg` (optional, used for subtitle extraction and audio conversion)	macOS: `brew install ffmpeg` <br>Linux: `sudo apt-get install ffmpeg`

Python 包

Python Packages

无需额外 Python 依赖，

yt-dlp

已包含所需库。

No additional Python dependencies required;

yt-dlp

already includes the necessary libraries.