rad-migrate

한 번의 명령으로 YouTube 채널을 Rad TV로 옮기세요.

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

그게 전부입니다. rad-migrate는 채널을 HD로 다운로드하고 모든 동영상을 제목, 설명, 썸네일, 원본 게시 날짜와 함께 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

언제든 중단할 수 있습니다. 다시 실행하면 중단한 지점부터 정확히 이어서 진행합니다.

자신이 소유한 콘텐츠를 옮기는 크리에이터를 위해 만들어졌습니다. 소유권 참조.

목차

• 설치 · 첫 실행 · 쿠키가 필요한가요?

• 명령어 · 무엇을 옮길지 선택하기 · 결과물

• 재개 및 두 번 실행 · 알려진 제한

• 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는 PATH에 Node 20+ (22 권장)와 ffmpeg가 필요합니다.

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

Node는 선택 사항도 빌드 도구도 아닙니다 — YouTube는 HD 스트림 URL을 넘겨주기 위해 JavaScript 런타임을 요구하며, 없으면 다운로드가 실패하는 대신 조용히 저화질로 떨어집니다. 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로 제한하며, 이 검사는 파일 하나씩 낭비하는 대신 5초 만에 문제를 잡아냅니다.

3. 무엇이 옮겨질지 확인합니다.

rad-migrate plan @yourchannel

아무것도 다운로드하거나 게시하지 않습니다. 동영상, 이미 Rad에 있는 항목, 필터로 제외된 항목을 보여줍니다.

4. 먼저 동영상 하나를 마이그레이션한 다음 나머지를 진행합니다.

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

--limit 1 실행은 몇 시간을 투자하기 전에 자격 증명, 채널, 업로드 경로, 트랜스코딩을 검증합니다.

쿠키가 필요한가요? 아마 아닐 겁니다.

이 분야의 대부분 도구는 cookies.txt를 내보내라고 안내하는 것으로 시작합니다. rad-migrate는 그렇게 하지 않습니다. 보통 필요하지 않기 때문입니다 — 그리고 필요할 때도 쿠키는 첫 번째 수단이 아니라 마지막 수단입니다.

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

수동 내보내기 없이 브라우저에서 직접 쿠키를 읽습니다. Firefox를 선호하세요. Chrome 127부터 Windows는 쿠키 암호화 키를 Chrome 프로세스에 바인딩하므로 외부 도구가 Chrome, Edge, Brave 쿠키를 읽을 수 없습니다. rad-migrate는 이를 감지하고 복호화 오류로 실패하는 대신 그 사실을 알려줍니다.

알아두면 좋은 점: 이것은 쉬운 단계가 아니라 위험한 단계입니다. 로그인된 자신의 세션으로 대량 다운로드하는 것은 YouTube의 남용 감지 시스템이 찾는 패턴입니다 — 그리고 자신의 채널을 마이그레이션하는 크리에이터의 경우, 그 세션은 채널이 있는 계정에 속합니다. 위의 토큰 방식은 계정에 전혀 접촉하지 않습니다.

3. 쿠키 파일 — 브라우저 추출이 작동할 수 없는 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에서는 HD로 얻을 수 없는 동영상은 표준 화질로 저장되는 대신 실패로 처리됩니다 — 그리고 완료된 모든 다운로드는 요청된 것이 아니라 실제로 디스크에 저장된 것을 확인하기 위해 프로브됩니다. 실패는 완료로 기록되지 않으므로 다음 실행에서 더 건강한 세션으로 재시도합니다. 보통 그것으로 충분합니다.

어떤 해상도로든 동영상을 원한다면 --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

Rad가 처리를 확인하면 각 폴더를 삭제하려면 --cleanup을 추가하세요 — 채널 하나가 수십 기가바이트에 달할 수 있습니다.

재개 및 두 번 실행

중단해도 안전하고, 다시 실행해도 안전합니다. 상태는 한 번에 한 동영상씩 진행되며 즉시 기록되므로, 충돌이나 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를 반환하고 백그라운드에서 실행됩니다 — 채널은 몇 시간이 걸릴 수 있으므로 어떤 도구 호출도 차단되지 않습니다. 에이전트는 CLI와 동일한 저널을 읽는 migration_status를 폴링하므로, 사용자와 에이전트가 같은 실행을 지켜봅니다.

Claude Code

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

그런 다음 /rad-migrate @yourchannel.

스크립팅

--json은 단일 파싱 가능한 결과를 stdout에 출력하고 NDJSON 진행 이벤트를 stderr로 스트리밍하므로 둘이 섞이지 않습니다:

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

컨테이너에서는 브라우저 쿠키 추출이 작동할 수 없으므로, 필요하면 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 호출을 줄입니다. 지속되면 기다리세요 — 제한은 세션별이며 풀립니다.

Windows에서 Chrome 쿠키를 읽을 수 없습니다. 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