VideoCaptioner CLI

AI 기반 영상 자막 생성: 음성 인식 → 자막 최적화 → 번역 → 예쁜 스타일로 영상에 자막 입히기.

사용 시기

사용자가 동영상에 자막을 추가하려는 경우
사용자가 오디오/비디오를 텍스트로 변환하려는 경우
사용자가 자막을 다른 언어로 번역하려는 경우
사용자가 자막 모양을 사용자 정의하려는 경우 (색상, 글꼴, 둥근 배경)
사용자가 온라인 동영상을 다운로드하여 자막을 추가하려는 경우

시작하기 전에

명령어를 실행하기 전에 항상 videocaptioner <command> --help를 먼저 실행하여 최신 옵션과 기본값을 확인하세요. 아래 예제는 일반적인 패턴을 보여주지만, --help가 공식적인 기준입니다.

설치: pip install videocaptioner
비디오 합성에 FFmpeg 필요 (macOS: brew install ffmpeg)
무료 (API 키 불필요): 음성 인식 (bijian/jianying), 번역 (Bing/Google)
LLM API 키 필요: 자막 최적화, 자막 재분할, LLM 번역. OPENAI_API_KEY 환경 변수 또는 --api-key 플래그로 설정

일반적인 시나리오

1. 중국어 동영상에 영어 자막 추가 (한 번의 명령어, 모두 무료)

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --subtitle-mode hard --quality high -o output.mp4

2. 동영상을 SRT로 변환 (무료)

videocaptioner transcribe video.mp4 --asr bijian -o output.srt

# JSON 형식으로 디렉토리에 출력
videocaptioner transcribe video.mp4 --asr bijian --format json -o ./subtitles/

3. 기존 자막 번역

# 무료 Bing → 영어, 원문 위에 번역 출력 (이중 언어)
videocaptioner subtitle input.srt --translator bing --target-language en --layout target-above -o translated.srt

# 무료 Google → 일본어, 번역만 출력 (원문 제외)
videocaptioner subtitle input.srt --translator google --target-language ja --no-optimize --layout target-only -o output_ja.srt

# 반성 모드로 고품질 LLM 번역
videocaptioner subtitle input.srt --translator llm --target-language en --reflect \
  --api-key $OPENAI_API_KEY -o output_en.srt

4. 예쁜 스타일 자막이 포함된 전체 파이프라인

# 애니메이션 스타일 자막 (따뜻한 색상 + 주황색 윤곽선), 고품질 비디오
videocaptioner process video.mp4 --asr bijian --translator bing --target-language ja \
  --subtitle-mode hard --style anime --quality high -o output_ja.mp4

# 현대적인 둥근 배경 자막
videocaptioner process video.mp4 --asr bijian --translator google --target-language ko \
  --subtitle-mode hard --render-mode rounded -o output_ko.mp4

# 사용자 정의 색상: 빨간색 윤곽선이 있는 흰색 텍스트, 초고품질
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --subtitle-mode hard --quality ultra \
  --style-override '{"outline_color": "#ff0000", "primary_color": "#ffffff"}' -o output_en.mp4

5. 자막만, ASS 형식으로 출력 (비디오 합성 없음)

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --format ass --no-synthesize -o ./output/

6. 단계별 제어 (음성 인식 → 번역 → 합성을 별도로)

# 1단계: 음성 인식
videocaptioner transcribe video.mp4 --asr bijian -o video.srt

# 2단계: 번역 (이중 언어, 원문이 번역 위에 표시)
videocaptioner subtitle video.srt --translator bing --target-language en --layout source-above -o video_en.srt

# 3단계: 둥근 배경, 고품질로 비디오에 자막 입히기
videocaptioner synthesize video.mp4 -s video_en.srt --subtitle-mode hard \
  --render-mode rounded --quality high -o video_with_subs.mp4

7. 오디오 파일 처리 (비디오 합성 자동 건너뛰기)

videocaptioner process podcast.mp3 --asr bijian --translator bing --target-language en -o ./output/

8. 다른 언어 음성 인식 (whisper-api)

videocaptioner transcribe french_video.mp4 --asr whisper-api \
  --whisper-api-key $OPENAI_API_KEY --language fr -o french.srt

9. LLM으로만 자막 최적화 (ASR 오류 수정, 번역 없음)

videocaptioner subtitle raw_subtitle.srt --no-translate --api-key $OPENAI_API_KEY -o optimized.srt

10. 사용자 정의 글꼴로 둥근 배경 스타일

videocaptioner synthesize video.mp4 -s subtitle.srt --subtitle-mode hard \
  --style-override '{"text_color": "#ffffff", "bg_color": "#000000cc", "corner_radius": 10, "font_size": 36}' \
  --font-file ./NotoSansSC.ttf --quality high -o styled_video.mp4

명령어 참조

명령어	용도
`transcribe`	음성 → 자막. 엔진: `bijian`(무료) `jianying`(무료) `whisper-api` `whisper-cpp`
`subtitle`	자막 파일 최적화(LLM) 및/또는 번역(LLM/Bing/Google)
`synthesize`	사용자 정의 가능한 스타일로 자막을 비디오에 입히기
`process`	전체 파이프라인: 음성 인식 → 최적화 → 번역 → 합성
`download`	YouTube, Bilibili 등에서 동영상 다운로드
`config`	설정 관리 (`show` `set` `get` `path` `init`)
`style`	모든 자막 스타일 프리셋과 매개변수 나열

전체 옵션은 videocaptioner <command> --help를 실행하세요.

자막 스타일

예쁜 자막을 위한 두 가지 렌더링 모드:

ASS 모드 (기본) — 윤곽선/그림자 스타일:

프리셋: default (흰색+검은색 윤곽선), anime (따뜻한 색상+주황색 윤곽선), vertical (세로 동영상)
사용자 정의 가능 필드: font_name, font_size, primary_color, outline_color, outline_width, bold, spacing, margin_bottom

둥근 모드 — 현대적인 둥근 배경 상자:

프리셋: rounded (반투명 배경 위의 어두운 텍스트)
사용자 정의 가능 필드: font_name, font_size, text_color, bg_color (#rrggbbaa), corner_radius, padding_h, padding_v, margin_bottom

스타일 옵션은 --subtitle-mode hard에서만 작동합니다.

대상 언어

BCP 47 코드: zh-Hans zh-Hant en ja ko fr de es ru pt it ar th vi id 및 23개 추가 언어.

환경 변수

변수	용도
`OPENAI_API_KEY`	LLM API 키
`OPENAI_BASE_URL`	LLM API 기본 URL

종료 코드

0 성공 · 2 잘못된 인수 · 3 파일 없음 · 4 종속성 누락 · 5 런타임 오류

팁

스크립팅에 -q 사용 (stdout = 결과 경로만 출력)
Bing/Google 번역은 무료이며 API 키가 필요 없음
bijian/jianying 음성 인식은 무료이지만 중국어와 영어만 지원
모든 스타일 프리셋을 보려면 videocaptioner style 실행

VideoCaptioner — 자막 번인