오디오 트랜스크립션은(는) 무엇을 하나요?
YouTube 동영상 또는 로컬 오디오/비디오 파일을 YouTube에서 제공하는 자막에 의존하지 않고 트랜스크립트로 변환합니다. 많은 동영상(특히 재업로드된 영상 및 일부 중국어 영상)에는 자막이 없거나 자동 생성 자막도 없는 경우가 있어, yt-dlp --write-subs로 자막을 다운로드해도 아무것도 얻지 못합니다. 이 스킬은 오디오를 다운로드한 뒤 플랫폼에 맞춰 선택된 Whisper 엔진으로 로컬에서 트랜스크립션하여 이 문제를 해결합니다.
언제 사용하나요?
- 사용자가 YouTube URL을 제공하고 字幕 / 逐字稿 / 트랜스크립트 / 자막을 요청할 때
yt-dlp --list-subs명령 결과has no subtitles/has no automatic captions라고 나올 때- 사용자가 로컬
.m4a/.mp3/.mp4등의 파일을 트랜스크립션하고 싶을 때
사전 요구 사항
uv설치 (yt-dlp 및 트랜스크립션 스크립트를 전역 환경 오염 없이 실행하는 데 사용). 스크립트가 자동으로 Whisper 엔진을 선택하고uv가 해당 플랫폼에 필요한 엔진만 설치합니다.- Apple Silicon Mac →
mlx-whisper(MLX/Metal, GPU 가속) - Intel Mac / Linux / Windows →
faster-whisper(CTranslate2, CPU 또는 NVIDIA CUDA)
- Apple Silicon Mac →
- JavaScript 런타임 (
node,bun,deno)이 PATH에 있어야 함. 최신 yt-dlp는 YouTube 추출을 위해 JS 런타임이 필요하며, 스크립트는 사용 가능한 런타임을 자동 감지합니다. - ffmpeg 권장하지만 필수는 아님: 없을 경우 스크립트는 macOS 내장
afconvert로 대체합니다 (비-macOS 환경에서는 ffmpeg 설치 필요).
사용법
전체 파이프라인은 하나의 자체 포함 스크립트로 구성되어 있습니다. uv run으로 실행하면 의존성이 자동으로 준비됩니다:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py \
"https://www.youtube.com/watch?v=VIDEO_ID" \
--output-dir /tmp/whisper_out
자주 사용하는 옵션:
--language zh— 언어를 자동 감지 대신 강제 지정 (더 빠르며, 이중 언어 인트로에서 오감지 방지)--model mlx-community/whisper-large-v3-turbo— 기본값; Apple Silicon에서 속도와 품질의 균형이 좋음. 최고 품질을 원하면mlx-community/whisper-large-v3로, 속도를 원하면 더 작은 모델로 교체 가능--output-name my-video— 출력 파일의 기본 이름 (기본값: 비디오 ID)--formats txt,srt— 생성할 출력 형식 선택 (기본값:txt,srt,json)
로컬 파일도 동일한 방식으로 작동합니다 — URL 대신 파일 경로를 전달하면 됩니다:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py /path/to/talk.m4a --language en
첫 번째 실행 시 Whisper 모델(turbo의 경우 약 1.6GB)이 Hugging Face 캐시에 다운로드되며, 이후 실행에서는 재사용됩니다.
출력 파일
--output-dir 디렉토리(기본값: 현재 디렉토리)에 비디오 ID(또는 --output-name 값)로 이름이 지정된 파일이 생성됩니다:
<name>.txt— 일반 텍스트 트랜스크립트 (한 덩어리)<name>.srt— 타임스탬프가 포함된 자막<name>.json— 세그먼트별 타임스탬프 및 감지된 언어를 포함한 전체 결과
트랜스크립션 후 처리
원시 Whisper 출력은 음성 언어를 그대로 반영합니다. 오디오가 중국어(만다린)인 경우 Whisper는 간체 중국어를 출력합니다. 사용자의 글로벌 규칙에 따라, 채팅에 트랜스크립트를 표시할 때는 **정체 중국어(번체)**로 변환하고 고유명사/기술 용어(모델명, CVE ID, 도구명)의 명백한 오인식을 정리해야 합니다. 전체 텍스트를 그대로 표시하는 대신 정리된 섹션별 요약을 제공하고, 전체 파일의 위치를 사용자에게 알려주세요.
작동 방식 (및 이유)
- 오디오 다운로드 —
yt-dlp -f "bestaudio[ext=m4a]/bestaudio". 포맷 140(128kbps m4a)은 YouTube의 플레이어 JS "n" 챌린지를 해결하지 않고 다운로드되므로,--remote-components ejs:github는 사용하지 않습니다 (원격 코드를 가져와 실행하며 일반적으로 샌드박스에서 차단됨). 스크립트는yt-dlp가 설치되지 않은 경우uvx를 접두사로 추가하고, 존재하는 JS 런타임에 맞게--js-runtimes <node|bun|deno>를 추가합니다. - 오디오 정규화 — ffmpeg(또는 ffmpeg가 없으면 macOS
afconvert)를 사용하여 16kHz 모노 16비트 WAV로 변환합니다. - 트랜스크립션 — WAV를 numpy float32 배열로 읽어 엔진에 직접 전달합니다 (Apple Silicon에서는
mlx_whisper.transcribe(...), 그 외에서는faster_whisper.WhisperModel.transcribe(...)). 두 엔진 모두 동일한 정규화된 결과 구조(text,language,segments)를 생성합니다. 디코딩된 배열을 Whisper에 전달하면 내부적으로 ffmpeg를 호출하지 않기 때문에, ffmpeg가 없는 시스템에서 흔히 발생하는FileNotFoundError: ffmpeg오류를 방지할 수 있습니다.
문제 해결
has no subtitles이지만 텍스트가 필요한 경우 — 바로 이 스킬이 해결하는 상황입니다. 오디오 트랜스크립션을 진행하세요.FileNotFoundError: ffmpeg— 이 스크립트를 사용한다면 발생하지 않아야 하지만(먼저 변환을 수행), m4a 파일을 직접 Whisper 엔진에 전달하는 경우 먼저 WAV로 변환하세요.- Apple Silicon 이외의 환경에서 변환 실패 —
afconvert는 macOS 전용이므로,ffmpeg를 설치하세요 (Linux/Windows는 내장 대체 기능이 없습니다). - yt-dlp가 JS 챌린지 / "Only images are available" 경고 —
node/bun/deno가 PATH에 있는지 확인하세요. 스크립트는 추출을 위해 이 중 하나가 필요합니다. 이를 해결하기 위해--remote-components ejs:github를 사용하지 마십시오. - 출력이 깨지거나 잘못된 언어 —
--language옵션을 명시적으로 지정하세요.