Video Subtitle Download & Translate
영상 URL에서 한국어 자막을 확보한다. 한국어 자막이 있으면 바로 다운로드, 없으면 영어 자막을 받아 번역한다.
사전 조건
yt-dlp가 필요하다. 먼저 존재 여부를 확인한다:
command -v yt-dlp없으면 설치를 안내한다:
# macOS
brew install yt-dlp
# pip
pip install yt-dlp실행 절차
1. URL 수신 및 자막 다운로드
사용자로부터 영상 URL을 받는다. scripts/fetch-subs.sh로 자막 조회와 우선순위 다운로드를 한 번에 수행:
bash "${CLAUDE_PLUGIN_ROOT}/skills/video-subtitle-dl/scripts/fetch-subs.sh" "<URL>"인증이 필요한 경우 추가 옵션 전달:
bash "${CLAUDE_PLUGIN_ROOT}/skills/video-subtitle-dl/scripts/fetch-subs.sh" "<URL>" --cookies-from-browser chromeCLAUDE_PLUGIN_ROOT가 없는 환경에서는 스킬 디렉토리의 절대 경로를 직접 사용한다.
스크립트 출력의 RESULT: 라인으로 다음 단계를 판단한다:
ko_manual/ko_auto→ Step 4 (포맷 변환 및 저장)en_manual_needs_translation/en_auto_needs_translation→ Step 3 (번역)none→ Step 5 (자막 없음)
스크립트 실행 불가 시 수동 절차:
자막 목록 확인: yt-dlp --list-subs --skip-download "<URL>"
우선순위: ko 수동 > ko 자동 > en 수동 > en 자동
| 순위 | 조건 | 액션 | 다음 단계 |
|---|---|---|---|
| 1 | 한국어 수동 자막 있음 | --write-subs --sub-langs ko --convert-subs srt | → Step 4 (포맷 변환) |
| 2 | 한국어 자동 자막 있음 | --write-auto-subs --sub-langs ko --convert-subs srt | → Step 4 (포맷 변환) |
| 3 | 영어 수동 자막 있음 | --write-subs --sub-langs en | → Step 3 (번역) |
| 4 | 영어 자동 자막 있음 | --write-auto-subs --sub-langs en | → Step 3 (번역) |
| 5 | 둘 다 없음 | — | → Step 5 (자막 없음) |
2. 다운로드 실패 시
yt-dlp가 실패하면 인증 옵션을 안내한다. 상세는 references/yt-dlp-options.md 참조.
사용자에게 선택지 제시:
- 브라우저 쿠키 사용 —
--cookies-from-browser chrome - 쿠키 파일 지정 —
--cookies cookies.txt - 계정 로그인 —
--username/--password
사용자가 선택하면 해당 옵션을 추가하여 재시도.
3. 번역 (영어 → 한국어)
한국어 자막을 직접 받은 경우 이 단계를 건너뛴다.
다운로드된 영어 자막 파일을 읽고 한국어로 번역한다. 상세 규칙은 references/translation-guide.md 참조.
핵심 규칙:
- 타임코드는 절대 수정하지 않는다. 텍스트만 번역.
- 기술 용어, 고유명사, 브랜드명은 원문 유지.
- 자연스러운 구어체로 번역. 직역 금지.
번역 절차:
- 원본 자막 파일을 Read로 읽는다
- 500 cue 이하: 한 번에 번역
- 500 cue 초과: 200-300 cue 단위로 청크 분할하여 번역
- 번역된 내용을 새 파일로 저장
4. 포맷 변환 및 저장
파일명 규칙:
- 원본(영어):
{영상제목}.en.{vtt|srt}— 스크립트가vtt/srt/best순으로 받으므로 포맷이 다를 수 있다.ls *.srt *.vtt로 실제 파일명 확인. - 번역본:
{영상제목}.ko.srt(예:codex-for-software-engineers.ko.srt) - 한국어 자막 직접 다운로드:
{영상제목}.ko.srt— Step 1에서--convert-subs srt로 이미 SRT이므로 추가 변환 불필요. - 영상 제목은
yt-dlp가 생성한 파일명 기반. 특수문자 제거, 공백은 하이픈.
SRT 변환 (번역 경로만 해당): 영어 자막을 번역한 경우, references/translation-guide.md의 "VTT → SRT 변환 규칙"에 따라 변환.
저장 위치: 현재 작업 디렉토리 ($PWD)
5. 완료 / 자막 없음
자막을 확보한 경우:
- 저장된 파일 경로 (원본 + 번역본, 또는 한국어 자막만)
- 자막 cue 수
자막이 없는 경우:
- "이 영상에는 사용 가능한 자막(한국어/영어)이 없습니다." 출력 후 종료
Gotchas
- 자동 생성 자막(auto-sub)은 타임코드가 1-2초 단위로 과도하게 쪼개져 있다. 번역 시 인접 cue를 문맥 단위로 묶어 읽어야 자연스러운 번역이 된다.
- VTT→SRT 변환 후
<c>,<font>등 VTT 전용 태그가 잔존할 수 있다. 변환 후grep '<[a-z]' *.srt로 확인하고 VTT 전용 태그는 제거.<b>,<i>는 SRT에서도 지원하므로 유지. - 연령 제한/멤버십 전용 영상은
--cookies-from-browser로도 실패할 수 있다. 이 경우 브라우저에서 수동 export한 cookies.txt 파일이 더 안정적. %(title)s에/,?,"등 파일시스템 금지 문자가 포함되면 yt-dlp가 자동 치환하지만, 후속 파일 참조 시 실제 생성된 파일명을ls *.srt *.vtt로 확인할 것.- 일부 플랫폼(Vimeo, Naver TV 등)은 자막 포맷이 비표준이라
--convert-subs srt가 실패할 수 있다. 이때는 원본 포맷 그대로 저장 후 수동 변환.