rad-migrate

用一条命令把你的 YouTube 频道迁移到 Rad TV。

export RAD_API_KEY=rad_...
rad-migrate @yourchannel

就这么简单。rad-migrate 以高清格式下载你的频道，并将每个视频连同标题、描述、缩略图和原始发布日期一起发布到 Rad TV，然后按原始上传顺序构建播放列表。

rad-migrate 0.1.0
  ✓ node 22.22 · ffmpeg 8.1 · yt-dlp 2026.08 · Rad auth ok
  ✓ quality probe  1080p available (no cookies)
  → channel: Your Channel  ·  47 videos
  → 12 already on Rad · 3 vertical, skipped · 32 to migrate
  [ 7/32] Inside Barolo Grill    uploading 412.8 MB

随时可以停止。再次运行它会从上次中断的地方继续。

专为迁移自己内容的创作者打造。 参见所有权。

目录

• 安装 · 首次运行 · 需要 cookies 吗？

• 命令 · 选择要迁移的内容 · 最终得到什么

• 断点续传 · 已知限制

• 从 AI 代理使用 · Docker · 配置

• 故障排查 · 所有权

Related MCP server: @kirbah/mcp-youtube

安装

无需构建任何东西。rad-migrate 是一个 Python 包——安装后即可运行。

# Not yet on PyPI. For now, install from source:
uv tool install git+https://github.com/little-core-labs/rad-migrate

# or with pipx
pipx install git+https://github.com/little-core-labs/rad-migrate

uvx rad-migrate @yourchannel     # run without installing
uv tool install rad-migrate      # or install it
pipx install rad-migrate

pip 无法替你安装的两样东西

rad-migrate 需要 Node 20+（推荐 22）和 ffmpeg 位于你的 PATH 中。

# macOS
brew install node ffmpeg
# Windows
winget install OpenJS.NodeJS.LTS Gyan.FFmpeg
# Debian/Ubuntu
sudo apt install nodejs ffmpeg

Node 不是可选项，也不是构建工具——YouTube 要求有 JavaScript 运行时才会交出高清流 URL，没有它，下载会静默降级到低画质而不是报错。ffmpeg 用于合并 YouTube 分离的视频流和音频流。

如果你不想安装这些东西，使用 Docker 镜像——它自带完整工具链。

首次运行

四步。前三步花几秒钟，能省下几小时。

1. 检查机器环境。

rad-migrate doctor

验证 Node、ffmpeg、yt-dlp、磁盘空间以及你的 Rad 凭据。

2. 检查你实际能获得什么画质。

rad-migrate doctor @yourchannel
# ✓ quality probe   1080p available (no cookies)

这会探测一个真实视频。这是长时间运行前最有用的一件事——降级的 YouTube 会话会把所有内容限制在 360p，这一步能在五秒内发现问题，而不是一个接一个地浪费文件。

3. 查看将要迁移的内容。

rad-migrate plan @yourchannel

不下载也不发布任何内容。显示视频列表、Rad 上已有的内容，以及你的过滤器排除了什么。

4. 先迁移一个视频，再迁移其余部分。

rad-migrate @yourchannel --limit 1     # one full round trip
rad-migrate @yourchannel               # everything

--limit 1 运行能验证你的凭据、频道、上传路径和转码，然后你才投入数小时。

需要 cookies 吗？大概率不需要。

这个领域的大多数工具一上来就让你导出 cookies.txt。rad-migrate 不这样做，因为通常没必要——而且即使需要，cookies 也是最后的手段，而不是首选。

rad-migrate doctor @yourchannel 会告诉你答案。如果它报告 1080p，那就完成了——不需要账号、不需要设置、不需要配置任何东西。

如果它报告有上限，rad-migrate 会按以下顺序指出修复它的那条命令：

1. 来源证明令牌——不涉及任何 Google 账号。

rad-migrate setup-potoken

YouTube 越来越要求"来源证明"令牌，现在它绑定到每个单独的视频 id，因此无法再手动提取令牌。这会安装一个生成令牌的提供程序：一个自包含的二进制文件，通过 GitHub 为固定版本发布的 SHA-256 校验和进行验证。不需要 Node、npm、Docker，也不需要登录。它会显示将要下载的内容，并在执行前征求你的同意。使用 rad-migrate setup-potoken --remove 移除它。

2. 你的浏览器会话——仅当上述方法不够时。

rad-migrate @yourchannel --cookies-from-browser firefox

直接从浏览器读取 cookies；无需手动导出。优先使用 Firefox。 自 Chrome 127 起，Windows 将 cookie 加密密钥绑定到 Chrome 进程，因此没有外部工具能在 Windows 上读取 Chrome、Edge 或 Brave 的 cookies。rad-migrate 会检测到这一点并明确告知，而不是抛出解密错误。

值得了解：这是有风险的一级，而不是简单的一级。针对你自己已登录的会话进行批量下载，正是 YouTube 滥用检测系统所寻找的模式——而对于迁移自己频道的创作者来说，该会话属于频道所在的账号。上面的令牌方案完全不涉及任何账号。

3. 一个 cookie 文件——适用于 Docker 和无头机器，因为浏览器提取在那里无法工作：

rad-migrate @yourchannel --cookies-file cookies.txt

命令

rad-migrate @yourchannel          # migrate (shorthand for `rad-migrate run`)
rad-migrate plan @yourchannel     # show what would happen, change nothing
rad-migrate doctor @yourchannel   # check the machine and the quality
rad-migrate status                # progress from previous runs
rad-migrate retry @yourchannel    # retry only what failed
rad-migrate setup-potoken         # install the HD token provider
rad-migrate mcp                   # run as an MCP server for AI agents

@handle、handle、完整 URL 或 UC… 频道 id 均可使用。

每个命令都支持 --help。

选择要迁移的内容

rad-migrate @yourchannel \
  --newest 50 \                # the 50 most recent
  --since 2024-01-01 \         # nothing older
  --landscape-only \           # skip vertical videos (Shorts)
  --min-duration 60 \          # skip anything under a minute
  --playlist "My Channel"      # build a playlist in upload order

画质是经过验证的，而非假设的

在默认的 hd-strict 模式下，无法获得高清的视频会被判定为失败，而不是以标清保存——而且每个完成的下载都会被探测，以确认实际落盘的内容，而不是请求的内容。失败永远不会被记录为已完成，因此下次运行会在更健康的会话上重试。通常这样就够了。

如果你宁愿以任何分辨率获得视频，请传入 --allow-sd。

最终得到什么

在 Rad 上： 每个视频对应一个内容条目，包含原始标题、描述、缩略图和发布日期，如果你要求了，还会有一个按上传顺序排列的播放列表。竖屏视频以竖屏形式发布。视频只有在 Rad 确认转码完成后才会被标记为完成——而不仅仅是上传成功。

在磁盘上，位于 --workdir 下（默认 ./rad-migrate-work）：

rad-migrate-work/
├── state.db                    resume journal
└── media/
    └── <channel-id>/
        └── 2024-03-15 - Video Title [dQw4w9WgXcQ]/
            ├── video.mp4       the download
            ├── video.info.json full yt-dlp metadata
            ├── video.webp      original thumbnail
            └── thumbnail.jpg   converted for upload

添加 --cleanup 可在 Rad 确认处理后删除每个文件夹——一个频道很容易达到几十 GB。

断点续传与重复运行

可以安全中断，也可以安全重新运行。状态一次只推进一个视频，并且立即写入，因此崩溃或 Ctrl-C 最多只会丢失正在传输的那个视频。

重新运行是幂等的，因为 rad-migrate 会向 Rad 查询频道上已有的内容，而不是信任本地文件。因此，在另一台机器上、完全没有本地状态的第二次运行，也不会重复发布同一个视频。

state.db 是缓存，不是事实来源。删除它后，下次运行会重新扫描；仍然不会重复发布。

已知限制

这些都来自 Rad API 的当前状态，并在 docs/rad-api-notes.md 中有详细记录——包括建议的修复方案。

从 AI 代理使用

MCP 服务器

适用于 Claude Desktop、OpenClaw、Hermes 以及任何支持 MCP 的工具：

{
  "mcpServers": {
    "rad-migrate": {
      "command": "rad-migrate",
      "args": ["mcp"],
      "env": { "RAD_API_KEY": "rad_..." }
    }
  }
}

工具：check_environment、plan_migration、start_migration、migration_status、cancel_migration、retry_failed、install_potoken_provider。

start_migration 会立即返回一个任务 id 并在后台运行——一个频道可能需要数小时，因此任何工具调用都不会阻塞。代理轮询 migration_status，它读取与 CLI 相同的日志，因此你和代理看到的是同一次运行。

Claude Code

/plugin marketplace add little-core-labs/rad-migrate
/plugin install rad-migrate

然后 /rad-migrate @yourchannel。

脚本化

--json 将单个可解析结果输出到 stdout，并在 stderr 上流式输出 NDJSON 进度事件，因此两者永远不会交错：

rad-migrate plan @yourchannel --json | jq '.to_migrate'

Docker

自带 Node、ffmpeg 和 yt-dlp，因此无需安装任何东西。

docker run --rm \
  -e RAD_API_KEY \
  -v "$PWD/work:/work" \
  ghcr.io/little-core-labs/rad-migrate @yourchannel --workdir /work

浏览器 cookie 提取在容器中无法工作，因此如果需要，请挂载一个 cookies.txt 并使用 --cookies-file。

配置

命令行标志优先于环境变量，环境变量优先于 .env，.env 优先于默认值。复制 .env.example 为 .env 即可开始。

你的 API 密钥永远不会写入状态、日志或 --json 输出。rad-migrate 打印的所有内容都会先经过脱敏过滤器，并且有一个测试来断言这一点。参见 SECURITY.md。

故障排查

所有内容都以 360p 下载。 运行 rad-migrate doctor @yourchannel。几乎总是缺少 JS 运行时（安装 Node 22+）或会话降级（rad-migrate setup-potoken）。

"请登录以确认你不是机器人"。 YouTube 正在限流。rad-migrate 会自动退避并减少每个视频的 API 调用。如果持续出现，请等待——限流是按会话的，会自动解除。

Chrome cookies 在 Windows 上无法读取。 自 Chrome 127 起，这是设计使然。请使用 Firefox 或 --cookies-file。

Rad 上的转码失败。 上传成功了；转换没有。使用 rad-migrate retry @yourchannel 重试。视频只有在 Rad 确认处理后才会被报告为完成，因此这里的失败是可见的，而不是静默的。

速度很慢。 这是故意的。YouTube 会按会话限制提取 API 的速率，因此 rad-migrate 会控制节奏以跑完整个频道，而不是冲刺到被封禁。

更多详情：skills/rad-migrate/references/troubleshooting.md。

所有权

这个工具是为创作者将自己的作品迁移到他们选择的平台而存在的。下载他人的视频并重新发布，既是版权问题，也是 YouTube 服务条款问题，这不是本工具的用途。

如果你想要自己的原始文件，且完全不涉及机器人检测，Google Takeout 可以导出 YouTube 为你频道保存的源文件。它更慢、更手动，但这是完全合规的路径。

贡献

参见 CONTRIBUTING.md。

git clone https://github.com/little-core-labs/rad-migrate && cd rad-migrate
uv sync --dev
uv run pytest

源和目标由 source/base.py 和 dest/base.py 中的协议支撑——欢迎新增。

许可证

MIT