어떤 분들은 이미 AI 자동 번역 자막 도구가 많다면서, 이게 왜 필요하냐고 하실 수도 있어요.
맞아요, 온라인 영상 번역 도구는 정말 많고 저도 많이 써봤어요. 그런데 항상 정확도가 아쉽거나 퀄리티가 떨어졌고, 가끔은 오류가 마구 튀어나오기도 했죠.
게다가 저는 트위터나 위챗 채널에서 해외 영상을 자주 공유하는 편이라, 이 도구들을 직접 만들어보기로 했습니다. 사실 이걸로 해외 영상을 국내 플랫폼으로 가져오는 데도 쓸 수 있어요, ㅎㅎ.
이 도구를 반년 정도 써보면서 여러 번 수정했고, 이제 꽤 쓸만해졌어요. 정리해서 오픈소스로 공개합니다.
설치하고 나면, "이 링크를 한국어 자막 영상으로 번역해줘"라고 한 마디만 하면 됩니다. 그러면 다운로드, 음성 텍스트 변환, 번역, 다듬기, 자막 입히기, 대본 생성까지 모든 걸 자동으로 처리해주는 완벽한 원스톱 솔루션이에요.
음성 텍스트 변환은 내 컴퓨터에서 완전히 로컬로 실행되므로 API 비용이 전혀 들지 않아요. 번역은 이미 설치한 AI를 그대로 사용합니다. 게다가 영어뿐만 아니라 일본어, 한국어, 프랑스어 등 다른 외국어 영상도 한국어 자막으로 변환할 수 있어요.
본질적으로 몇 개의 스크립트와 설명서일 뿐입니다. Claude Code에만 국한되지 않고 OpenClaw, Gemini, Codex 등 모든 도구에서 사용할 수 있어요. 차이점은 각 도구가 "스킬"을 설치하는 방식뿐이에요.
아래에서는 설치부터 첫 번째 영상을 실행하는 방법까지 단계별로 설명합니다.
이 도구로 정확히 무엇을 할 수 있나요?
영상 링크(YouTube, Bilibili, Douyin 모두 가능) 또는 로컬 영상 파일을 주면, 다음 다섯 단계를 한 번에 수행합니다:
다운로드 → 음성 텍스트 변환 → 번역 → 다듬기 → 자막 입히기
...그리고 최종적으로 대본을 출력합니다.
자세히 설명하면:
- 영상을 다운로드합니다 (또는 로컬 파일을 직접 사용).
- 오디오를 추출하고 Whisper를 사용하여 정확한 타임스탬프가 있는 원본 자막으로 변환합니다.
- 원본 텍스트를 한국어로 번역하고 한국어 시청 습관에 맞게 다듬습니다.
- 영상에 자막을 입혀 한국어 자막이 포함된 영상을 출력합니다.
- 동시에 Markdown 형식의 대본을 생성하여 보관하거나 아티클로 전환하기 쉽게 합니다.
언어는 중요하지 않습니다. 영어, 일본어, 한국어, 프랑스어, 스페인어 등 Whisper가 이해할 수 있는 언어라면 모두 한국어 자막으로 변환됩니다. 원본 언어를 자동으로 감지하여 번역합니다. 한국어 영상의 경우 번역 단계 없이 음성 텍스트 변환과 대본 생성만 수행합니다.
두 가지 자막 옵션이 있습니다. 하나는 화면을 깔끔하게 하는 한국어 단독 자막이고, 다른 하나는 이중 언어(한국어/영어) 자막으로, 큰 한국어 텍스트와 작은 영어 텍스트가 함께 표시되어 듣기 연습을 원하는 분들에게 적합합니다.
어떤 명령어도 외울 필요 없습니다. 그냥 자연어로 말하면 됩니다: "이중 자막으로 해줘", "워터마크 없이", "빠른 모드 사용해" 등 모든 것을 이해합니다.
간단히 말해, 예전에는 서너 가지 소프트웨어와 한두 시간의 작업이 필요했던 파이프라인을 단 한 문장으로 압축한 것입니다.
기존 도구와 어떻게 다른가요?
시중에는 많은 자막 도구가 있습니다. 제가 중요하게 생각하는 세 가지가 있으며, 이 도구는 바로 이것들을 위해 만들어졌습니다.
첫째: 로컬, 무료, 오프라인. 음성 텍스트 변환은 OpenAI의 오픈소스 Whisper 모델을 사용합니다. Apple Silicon Mac에서는 자동으로 GPU 가속을 사용합니다. 전체 음성 텍스트 변환 과정이 컴퓨터에서 이루어지므로 업로드나 비용이 없습니다. 번역은 이미 설치된 AI를 재사용하므로 별도의 번역 API가 필요 없습니다.
둘째: 정확한 타임스탬프. 많은 도구에서 자막이 화자보다 앞서 나가거나 문장이 어색하게 끊깁니다. 이 도구는 각 단어가 발화되는 시점에 정확한 타임스탬프를 제공하고 "문장 + 숨 쉬는 pause"를 기준으로 자막을 나누므로 화자가 한 생각을 마칠 때 정확히 자막이 전환됩니다.
셋째: 사람을 위한 자막, 단순한 기계 번역이 아님. 잘못 들은 고유 명사를 자동으로 수정하고(Claude는 종종 "cloud"로, MCP는 "NCP"로 잘못 들림), 의미 단위로 문장을 나누고, 줄당 12자를 넘지 않도록 하며, 기술 용어는 영어를 유지합니다. 이중 언어 모드에서는 한국어는 크게, 영어는 작게 표시되어 동일한 크기로 두 줄이 겹쳐 있는 것이 아니라 명확하게 구분됩니다.
이것들은 수백 개의 영상을 통해 다듬은 제가 직접 정리한 세부 사항들로, 모두 규칙에 포함되어 있습니다.
결과물은 어떤가요?
a16z가 최근 공개한 전 OpenAI CTO Mira Murati의 인터뷰를 시험해 보겠습니다. 도구에 이중 언어 자막을 요청했습니다.
그녀의 원래 말 중에 비유가 하나 있었습니다:
It's more like a tandem bike where both people are pedaling.
기계 번역은 어색한 직역을 내놓을 수 있습니다. 이 도구는 다음과 같이 번역합니다: "오히려 두 사람이 함께 페달을 밟는 2인용 자전거에 가깝습니다."
자연스럽고 매끄럽습니다. 고유 명사도 잘 처리됩니다. "Thinking Machines" 같은 회사 이름은 억지로 번역하지 않고 영어 그대로 유지됩니다.
"링크 + 이 영상 번역해줘"라고 보내기만 하면, 먼저 한국어 단독 자막과 이중 자막 중 어떤 것을 원하는지 물어봅니다. 저는 보통 한국어로 번역하기 때문에 이 두 가지를 기본 옵션으로 남겨두었지만, 실제로는 어떤 언어로든 번역할 수 있습니다.
자막이 입혀진 영상 외에도 원본과 한국어 텍스트가 나란히 표시된 대본도 생성됩니다.
전체 단락은 다음과 같습니다:
It's more like building a system that doesn't just run off on its own and leave civilization behind, but is more like a tandem bike where both people are pedaling. On the uphill, maybe the stronger person pedals harder, but both people's hands are on the handlebars.
가장 실용적인 점은 언어에 구애받지 않는다는 것입니다. 동일한 인터뷰를 한국어, 일본어, 한국어, 아랍어, 프랑스어 등으로 이중 언어 자막으로 번역할 수 있으며, 번역문은 위에, 영어는 아래에 위치하여 우선순위가 명확합니다. 오른쪽에서 왼쪽으로 쓰는 아랍어도 깔끔하게 정렬됩니다:
10분 짜리 영상은 문제없고, 90분이 넘는 긴 영상도 쉽게 처리됩니다.
사실 세 가지 스킬입니다
리포지토리를 열면 세 개의 폴더가 보이며, 각각 작업의 일부를 관리합니다. 개별적으로 사용하거나 연결하여 사용할 수 있습니다:
- xiaohu-video-md: 총지휘관. 다운로드, 음성 텍스트 변환, 번역 호출, 자막 입히기, 대본 출력을 담당합니다.
- xiaohu-subtitle-polish: 자막 번역 및 다듬기 전문. 오류 수정, 번역, 문장 나누기, 시간 정렬, 이중 언어 형식 지정을 처리합니다.
- xiaohu-video-download: 순수 다운로드 도구. 영상, 오디오 또는 전체 재생 목록을 다운로드하고 로컬 영상에 자막을 입힐 수도 있습니다.
영상을 번역할 때 xiaohu-video-md가 오케스트레이터 역할을 하며 번역 단계에서 xiaohu-subtitle-polish를 호출합니다. 이 부분은 신경 쓰지 않아도 됩니다. 그냥 이 세 가지 부분이 있다는 것만 알면 됩니다.
단계별 설치
이 도구는 현재 Mac에 최적화되어 있으며 Apple Silicon에서 가장 부드럽게 실행됩니다. 두 가지 설치 방법이 있습니다: 간편하게 하려면 아래 텍스트를 AI에 붙여넣기만 하면 되고, 무슨 일이 일어나는지 알고 싶거나 오류가 두렵다면 수동 단계를 따르세요.
간편 버전: AI에 이 내용을 전달하세요
AI 코딩 도구(Claude Code, Codex, OpenClaw)를 열고 다음 내용을 정확히 복사하여 붙여넣으세요. 그러면 시스템을 확인하고, 종속 항목을 설치하고, 리포지토리를 클론하고, 설치 스크립트를 실행하며 필요할 때 질문을 할 것입니다:
이 영상 번역 도구를 설치하는 것을 도와주세요: https://github.com/xiaohuailabs/xiaohu-video-translate 다음 순서대로 진행하세요: 1. 내 시스템 확인: Mac인지 Windows인지; Mac이면 Apple Silicon(M 시리즈)인지 확인. 2. 종속 항목 설치: yt-dlp, ffmpeg, whisper-cpp (Mac은 brew install, Windows는 WSL 또는 winget 사용). 음성 텍스트 변환 엔진: Apple Silicon은 mlx-whisper 설치, 그 외는 faster-whisper 설치. 3. git clone으로 이 리포지토리를 복제하고 디렉토리로 이동한 후 bash install.sh를 실행하여 세 가지 스킬을 내 스킬 디렉토리에 설치. 4. 설치가 완료되면 xiaohu-video-md 스킬에서 config.json을 찾습니다(Claude Code의 경우 ~/.claude/skills/에 있음). 완성된 파일을 저장할 위치를 물어보고 output_dir을 전체 경로로 변경하도록 도와주세요. 5. 마지막으로 모든 종속 항목이 설치되었는지 확인하고 사용을 시작해도 되는지 알려주세요.
각 단계에서 수행한 작업을 간략히 설명하고, 종속 항목 설치에 실패하면 멈추고 저에게 물어보세요. 계속 진행하지 마세요.
기본적으로 아래 세 단계를 대신 실행합니다. 직접 하거나 문제를 해결하려면 수동 버전을 따르세요.
1단계: 기본 도구 설치
먼저 Homebrew가 설치되어 있는지 확인하세요. 그런 다음 이 명령어를 실행하여 세 가지 도구를 설치합니다:
brew install yt-dlp ffmpeg whisper-cpp
다음으로 음성 텍스트 변환 엔진을 설치합니다. Apple Silicon Mac의 경우 GPU 가속을 위해 다음을 사용합니다(--break-system-packages 플래그는 최신 시스템 제한을 우회하기 위한 것이며 시스템에 해를 끼치지 않습니다):
pip3 install --break-system-packages mlx-whisper
Apple Silicon이 아닌 경우 일반 버전을 사용합니다:
pip3 install --break-system-packages faster-whisper
2단계: Claude에 스킬 설치
리포지토리를 클론하고 설치 스크립트를 실행합니다:
git clone https://github.com/xiaohuailabs/xiaohu-video-translate.git cd xiaohu-video-translate bash install.sh
이 스크립트는 세 가지 스킬을 Claude의 스킬 디렉토리에 복사하고, 설정 파일을 생성하며, 종속 항목을 확인합니다. 모든 항목에 [OK]가 표시되면 준비 완료입니다. [Missing]이 표시되면 프롬프트에 따라 수정하세요. (여기서 경로는 Claude Code를 예로 들었습니다. 다른 도구의 경우 디렉토리만 변경하면 됩니다).
3단계: 결과물 저장 위치 지정
~/.claude/skills/xiaohu-video-md/config.json을 열고 output_dir을 원하는 폴더 경로(예: /Users/yourname/Documents/VideoTranslation)로 변경합니다.
임시 파일은 tmp/에, 대본은 data/에, 완성된 영상은 기본적으로 다운로드 폴더에 저장됩니다.
음성 텍스트 변환 모델을 수동으로 다운로드할 필요는 없습니다. 처음 실행할 때
mlx-whisper가 자동으로 다운로드하며(약 1.5GB), 이후에는 재사용합니다.
완료되면 AI 도구를 다시 시작하면 사용할 준비가 됩니다.
Windows 사용자 참고 사항
위 내용은 Mac용입니다. Windows에서도 실행할 수 있지만 몇 가지 차이점이 있습니다.
가장 쉬운 방법은 WSL(Windows Subsystem for Linux)을 사용하는 것입니다. 설치 후 다음을 설치하면 스크립트가 그대로 실행됩니다:
sudo apt install ffmpeg pip3 install yt-dlp faster-whisper
WSL을 사용하고 싶지 않다면:
- faster-whisper를 엔진으로 사용하세요.
- Git Bash를 사용하여 설치 스크립트를 실행하거나 수동으로 폴더를 복사하세요.
- 자막 글꼴을 변경하세요. 기본값은 Mac의 PingFang SC입니다. 명령어에서 Microsoft YaHei로 변경하여 텍스트가 상자로 표시되지 않도록 하세요.
사용 방법
설치가 완료되면 한 마디만 하면 됩니다. 다음과 같이 말할 수 있습니다:
- "이 링크를 한국어 자막 영상으로 번역해줘 + [링크]"
- "이 영상 번역해줘, 이중 자막으로 해줘 + [링크]"
- "이 영상을 텍스트로 바꿔줘 + [링크]" (Markdown만 생성)
- "이 로컬 영상에 한국어 자막 추가해줘 + [경로]"
- "이 영상 다운로드해줘 + [링크]"
- "음성 텍스트 변환은 빠른 모드 사용해"
- "번역할 때 워터마크 없이"
주의해야 할 몇 가지 함정
YouTube 가끔 다운로드 실패 (403 오류). YouTube의 리스크 관리가 강화되었습니다. 스크립트는 브라우저에서 쿠키를 읽어 재시도합니다. 그래도 실패하면 프록시를 사용하세요.
자막이 상자로 표시됨. 글꼴 인덱싱 문제입니다. 시스템에서 사용 가능한 글꼴(예: Mac의 PingFang SC)을 사용하고 있는지 확인하세요.
Douyin은 일회성 로그인이 필요합니다. douyin_login.py 스크립트를 실행하고 QR 코드를 스캔하세요. 이 로그인 정보는 컴퓨터에만 남습니다.
가져다 쓰세요
리포지토리 주소:
github.com/xiaohuailabs/xiaohu-video-translate
코드는 MIT 라이선스입니다. 워터마크, 스타일, 글꼴 크기를 자유롭게 변경할 수 있습니다. 한 가지 주의할 점: 설정 파일이나 Douyin 로그인 정보를 공개 리포지토리에 업로드하지 마세요.
이것은 제가 매일 사용하는 도구이지 장난감이 아닙니다. 유용하게 사용하셨다면 별표를 눌러주세요. 문제가 있으면 이슈를 열어주세요.
다음에는 제 아티클 일러스트레이션 스킬을 오픈소스로 공개할 예정입니다. 개인 IP 이미지를 사용하여 아티클용 일러스트레이션을 생성하는 기능으로, 이 글에 사용된 것과 같습니다.
