비디오를 중국어 더빙으로 변환

번들로 제공되는 Python 파이프라인을 사용하여 완전한 중국어 더빙 비디오를 생성합니다. 사용자가 URL을 제공하고 완성된 결과물을 요청했을 때 단순히 제안만 하지 말고, 터미널 실행이 가능하고 사용자가 필요한 네트워크/다운로드 작업을 승인했다면 파이프라인을 실행하십시오.

Python 3.10+, FFmpeg/ffprobe, URL 다운로드를 위한 네트워크 액세스, 로컬 faster-whisper 모델이 필요합니다. 온라인 번역 및 음성 합성은 선택 사항입니다. 유료 음성 API 없이 자연스러운 만다린어가 필요할 때는 로컬 CosyVoice 백엔드를 사용하십시오.

<skill-root>는 이 SKILL.md 파일이 포함된 디렉토리로 확인하십시오. 호출자의 현재 작업 디렉토리가 스킬 디렉토리라고 가정하지 마십시오. macOS/Linux에서는 <skill-root>/.venv/bin/python을, Windows에서는 <skill-root>/.venv\Scripts\python.exe를 해당 가상 환경이 존재할 때 선호하며, 그렇지 않으면 활성 Python 인터프리터를 사용하십시오. 아래 명령어는 현재 디렉토리가 <skill-root>로 변경되었음을 가정합니다.

빠른 시작

사전 요구 사항 확인:
```
python3 scripts/check_environment.py
```
FFmpeg 및 Python 종속성을 설치합니다. macOS, Windows, Linux 명령어는 README.md를 참조하십시오.
유료 API 없이 자연스러운 번역을 위해 이미 설치된 Ollama 모델을 --translation-provider ollama --ollama-model MODEL과 함께 사용하십시오. 파이프라인은 로컬에서 두 번에 걸쳐 번역을 실행하고 모든 세그먼트 ID를 검증합니다. 전달하기 전에 기술 용어와 타이밍을 검토하십시오. 로컬 모델을 사용할 수 없는 경우, 온라인 초안으로만 --translation-provider google을 사용하고 허가를 받은 후 타임스탬프가 있는 세그먼트를 수동으로 다듬거나 검토된 JSON을 --segments-file을 통해 전달하십시오. OPENAI_API_KEY 또는 DEEPSEEK_API_KEY는 명시적으로 허용된 경우에만 사용하고, 허용되지 않은 API로 전환하지 마십시오.
비디오 URL(Bilibili, YouTube 또는 yt-dlp가 지원하는 모든 사이트) 변환:
```
python3 scripts/translate_video.py "https://www.youtube.com/watch?v=VIDEO_ID" \
  --translation-provider ollama --ollama-model MODEL --output-dir ./output
```
Bilibili URL에는 ?p=2와 같은 부분 매개변수가 포함될 수 있습니다. 전체 대상 URL을 전달하십시오.

또는 로컬 비디오 처리:

python3 scripts/translate_video.py ./input.mp4 \
  --translation-provider ollama --ollama-model MODEL --output-dir ./output

기본값 및 옵션

소스 언어 기본값은 영어(--source-language en)입니다. 자동 감지를 위해 auto를 사용하십시오.
중국어 음성 기본값은 zh-CN-XiaoxiaoNeural입니다. 젊은 남성 음성은 --voice zh-CN-YunxiNeural을, 남성 내레이션 음성은 --voice zh-CN-YunyangNeural을 사용하십시오.
호출당 요금이 없는 자연스러운 음성을 위해, 명시적으로 승인된 참조 클립과 정확한 대본이 있을 때 zero-shot 모드의 로컬 설치 Fun-CosyVoice3-0.5B를 선호하십시오. 그렇지 않으면 내장 스피커(예: 中文女)와 함께 CosyVoice-300M-SFT를 사용하십시오. 허가 없이 음성을 복제하지 마십시오. 모델은 모든 세그먼트에 대해 한 번 로드되고, PCM16 WAV 클립을 작성하며, 진행 상황을 체크포인트합니다. 플래그는 README.md를 참조하십시오.
Edge TTS에 연결할 수 없는 경우 DASHSCOPE_API_KEY를 설정하고 --tts-provider dashscope --voice Cherry를 사용하여 Qwen3 TTS를 이용하십시오. 번역된 대본 텍스트가 DashScope로 전송됩니다.
번역 기본값은 auto이며, 명시적으로 구성된 로컬 OLLAMA_MODEL만 사용하고 그렇지 않으면 번역 전에 중지합니다. 외부 번역기로 대본이 전송되기 전에 --translation-provider openai 또는 google을 명시적으로 선택하십시오. Ollama는 로컬 서비스와 설치된 모델이 필요합니다. 스킬은 자동으로 모델을 다운로드하지 않습니다. 파일 이름이 주제를 명확하게 식별하지 못하는 경우 --translation-context "video topic and key terms"를 사용하십시오. 그렇지 않으면 제목 또는 파일 이름이 사용됩니다.
--audio-mode replace는 소스 오디오를 중국어 음성으로 대체합니다(기본값, 안정적). --audio-mode mix는 중국어 음성 아래에 원본 트랙을 낮은 볼륨으로 유지합니다. --audio-mode background는 선택적 Demucs로 원본 보컬을 분리한 다음, 남은 배경과 중국어 음성을 혼합합니다. Demucs를 사용할 수 없거나 실패하면 스크립트는 문제를 보고하고 안전하게 대체 오디오로 폴백합니다.
--subtitle-mode soft는 MP4에 선택 가능한 중국어 자막을 포함하고 외부 SRT도 작성합니다(기본값). 먼저 소스 프레임을 검사하십시오. 자막이 이미 화면에 박혀 있는 경우 중복 텍스트를 피하기 위해 soft를 유지하십시오. burn은 자막을 화면에 박고 subtitles/libass 필터와 사용 가능한 중국어 글꼴이 있는 FFmpeg 빌드가 필요합니다. none은 MP4에서 자막을 생략하지만 검토를 위해 SRT 사이드카 파일은 계속 작성합니다.
ASR 조정: --model small(균형 잡힌 기본값), --model medium 또는 --model large-v3. 더 큰 모델은 더 많은 메모리가 필요하고 시간이 더 오래 걸립니다. 첫 실행은 선택한 모델을 다운로드합니다.
로그인 상태이고 사이트에서 자체 브라우저 세션이 필요한 경우에만 --cookies-from-browser chrome을 사용하십시오. 이는 로컬 브라우저 쿠키를 읽습니다. 기본적으로 활성화되지 않습니다.
--keep-intermediates를 사용하여 문제 해결을 위해 다운로드한 소스 오디오, WAV 파일 및 생성된 음성 클립을 보관합니다.
--segments-file path/to/translated.segments.json을 사용하여 TTS 실패 후 인식 및 번역을 반복하지 않고 검토된 번역을 재사용합니다.
--reuse-tts-dir path/to/tts_segments를 사용하여 기존 생성 클립 세트로 타이밍을 조정하고 음성 서비스를 다시 호출하지 않고 렌더링합니다.

필수 출력 확인

스크립트는 MP4가 존재하고, 비어 있지 않고, 비디오 스트림과 오디오 스트림이 있으며, 입력과 지속 시간이 가까운지 확인해야 합니다. 최종 MP4 옆에 SRT, 번역된 세그먼트 JSON 및 처리 보고서를 생성합니다. 실패한 단계는 파이프라인을 중지하고 출력이 완료된 것처럼 가장하는 대신 유용한 오류를 제공해야 합니다.

전달하기 전에 번역된 JSON/SRT에서 잘못 전사된 이름과 용어, 부자연스러운 단어 그대로의 표현, 속도가 빨라지거나 잘린 세그먼트를 검사하십시오. 렌더링된 프레임도 검사하십시오. 누락된 글리프 상자, 화면 밖 자막, 중복된 박힌 자막을 거부하십시오. CosyVoice의 경우, 긴 비디오를 렌더링하기 전에 짧은 샘플을 청취하십시오. 소수점, 코드 이름 및 영어 용어의 실제 발음을 확인하십시오(서면 텍스트만 확인하지 마십시오). 검토된 세그먼트는 spoken_text를 추가하여 숫자나 파일 이름을 자연스럽게 발음할 수 있지만 zh_text는 정확한 자막으로 유지됩니다. 그 의미는 일치해야 합니다. 잘린 음성이나 눈에 띄는 속도 향상을 배송하지 마십시오.

워크플로우

URL과 로컬 파일을 확인합니다. URL의 경우 yt-dlp(--no-playlist)를 사용하여 요청된 비디오만 다운로드합니다. Bilibili 페이지가 412를 반환하면 비디오가 명시적으로 다운로드 가능으로 표시된 경우에만 Bilibili의 공개 API를 사용할 수 있습니다. 요청된 ?p= 부분을 유지하십시오. DRM, 페이월 또는 계정 제한을 우회하지 마십시오.
ffprobe를 사용하여 스트림과 지속 시간을 검사합니다. 모노 16kHz PCM 오디오를 추출합니다.
faster-whisper로 전사하고 소스 타임스탬프를 유지합니다. 음성이 감지되지 않으면 명확하게 실패합니다.
주제 및 인접 음성 컨텍스트를 사용하여 번역한 다음 간결하고 관용적인 만다린어로 다듬습니다. ID, 순서, 의미, 숫자, 이름 및 기술 용어를 유지합니다. 비디오 주제와 비교하여 소스 인식 오류를 확인합니다.
선택한 음성 서비스를 통해 각 중국어 음성 세그먼트를 생성합니다. 타임스탬프 창에 보수적으로 맞춥니다. 세그먼트에 공격적인 속도 향상 또는 잘라내기가 필요한 경우 보고서에 경고합니다.
전체 길이의 중국어 음성 트랙을 만듭니다. 요청된 오디오 모드를 적용합니다. 선택적 Demucs 분리는 개선 사항이지 필수 종속성이 아닙니다.
중국어 SRT 및 번역된 JSON을 작성합니다. 요청에 따라 자막을 먹싱하거나 박고, 널리 호환되는 H.264/AAC MP4로 내보내고 결과를 확인합니다.
정확한 출력 경로, 선택한 설정, 경고 및 남은 검토 필요 사항을 보고합니다.

예시

# YouTube URL; API 번역; 중국 여성 음성; 추출된 배경 위에 음성 해설
OPENAI_API_KEY="$OPENAI_API_KEY" python3 scripts/translate_video.py "https://youtu.be/VIDEO_ID" \
  --translation-provider openai --audio-mode background --subtitle-mode soft --output-dir ./output

# Bilibili 파트 2; 자연스러운 번역을 위해 구성된 LLM 키 사용
python3 scripts/translate_video.py "https://www.bilibili.com/video/BV1NAuq6uE8t/?p=2" \
  --translation-provider openai --translation-context "规范驱动开发 SDD 与智能体编程" \
  --voice zh-CN-YunyangNeural --audio-mode mix --output-dir ./output

# 중국어 자막을 화면에 박기
python3 scripts/translate_video.py ./input.mp4 --subtitle-mode burn --output-dir ./output

# 유료 API 없이 CosyVoice3 및 승인된 참조를 사용한 완전 로컬 음성
python3 scripts/translate_video.py ./input.mp4 --segments-file ./reviewed.segments.json \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/Fun-CosyVoice3-0.5B \
  --cosyvoice-mode zero-shot --cosyvoice-prompt-audio ./reference.wav \
  --cosyvoice-prompt-text-file ./reference.txt --subtitle-mode burn --output-dir ./output

# 로컬 전사, Ollama 번역 및 CosyVoice 내레이션
python3 scripts/translate_video.py ./input.mp4 --translation-provider ollama --ollama-model MODEL \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/CosyVoice-300M-SFT \
  --cosyvoice-mode sft --output-dir ./output

안전 및 권리

소유하거나, 각색할 수 있는 라이선스가 있거나, 다운로드 및 변환이 허용된 비디오만 처리하십시오. 소스 플랫폼의 이용 약관 및 저작권을 존중하십시오. DRM 또는 기술적 접근 제어를 우회하지 마십시오. --cookies-from-browser는 옵트인이며 사용자 자신의 인증된 세션만 사용해야 합니다. 해당 권리를 확인하지 않고 더빙된 2차 저작물을 게시하지 마십시오.

이 프로젝트는 학습, 연구 및 기술 교류를 위한 것입니다. 불법 활동, 무단 음성 복제, 사기, 사칭 또는 오해의 소지가 있는 콘텐츠에 사용하지 마십시오. README.md의 면책 조항을 참조하십시오. 사용자는 관련 법률에 따라 생성된 콘텐츠의 사용 및 배포에 대한 책임이 있습니다.

영상-중국어-더빙