Communitygithub.com

YouTube / 오디오 트랜스크립션

YouTube 동영상 또는 로컬 오디오/비디오 파일을 로컬 Whisper 엔진을 사용하여 텍스트 트랜스크립트, SRT 자막, JSON으로 변환합니다. YouTube 자막이 없는 경우에도 사용 가능합니다.

오디오 트랜스크립션란 무엇인가요?

이 스킬은 YouTube 동영상 링크나 로컬 오디오/비디오 파일이 주어졌을 때, 자막을 다운로드할 수 없는 경우(예: 자체 자막이 없는 영상, 특히 중국어 업로드)에도 직접 오디오를 추출하고 로컬 Whisper 엔진으로 트랜스크립션하여 텍스트, SRT, JSON 형식의 트랜스크립트를 생성합니다. Apple Silicon(Mac)에서는 `mlx-whisper`, 그 외 플랫폼(Intel Mac, Linux, Windows)에서는 `faster-whisper`를 자동 선택하여 GPU 가속을 활용합니다. `uv`를 통해 의존성을 격리하여 실행하므로, 시스템 환경을 오염시키지 않으면서도 필요한 패키지를 자동으로 설치하고 실행합니다. 사용자는 YouTube URL 또는 로컬 파일 경로 하나만 전달하면, 스크립트가 자동으로 오디오 다운로드, 정규화, 트랜스크립션, 형식 변환까지 수행하므로, 복잡한 사전 준비나 수동 작업 없이 고품질 트랜스크립트를 얻을 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chenwei791129/agent-skills/tree/HEAD/skills/youtube-transcribe

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

오디오 트랜스크립션은(는) 무엇을 하나요?

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)
  • 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, 도구명)의 명백한 오인식을 정리해야 합니다. 전체 텍스트를 그대로 표시하는 대신 정리된 섹션별 요약을 제공하고, 전체 파일의 위치를 사용자에게 알려주세요.

작동 방식 (및 이유)

  1. 오디오 다운로드 — 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>를 추가합니다.
  2. 오디오 정규화 — ffmpeg(또는 ffmpeg가 없으면 macOS afconvert)를 사용하여 16kHz 모노 16비트 WAV로 변환합니다.
  3. 트랜스크립션 — 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 옵션을 명시적으로 지정하세요.

관련 스킬