비디오 자막 변환
번들된 whisper.cpp 서비스를 사용하여 로컬에서 비디오/오디오 파일을 텍스트로 변환합니다. 외부 프로젝트나 클라우드 API가 필요 없습니다. 단어 수준 타임스탬프를 반환합니다 (동기화된 오버레이/캡션에 필요).
사용 시점
- "이 클립/비디오/오디오를 자막으로 변환해줘", "타임스탬프가 포함된 자막을 가져와줘".
/produce-video의 하위 단계로 사용.
실행 방법
모든 작업은 번들된 실행기(runner)에 의해 처리되며, 사용자에게 Docker를 직접 관리하도록 요청하지 마세요:
node scripts/transcribe.mjs <비디오-또는-오디오-파일-경로> [--out <디렉토리>] [--port 9111] [--language ko] [--no-word-ts] [--task transcribe|translate]
node scripts/transcribe.mjs --stop # 실행 중인 컨테이너를 중지합니다
실행기는 다음을 수행합니다:
- Docker 데몬에 접근 가능한지 확인합니다 (접근 불가 시 안내와 함께 오류 출력).
assets/whisper-service/에서transcribe-video-whisper이미지가 없으면 빌드합니다 (첫 빌드는 느립니다: whisper.cpp를 컴파일하고ggml-base.en.bin모델을 포함).transcribe-video-whisper컨테이너를 시작합니다 (호스트 포트 9111 → 컨테이너 포트 9001); 이미 실행 중이면 재사용하고, 중지된 상태면docker start로 시작합니다.GET /healthz가 정상 응답을 반환할 때까지 기다립니다.- 로컬 ffmpeg를 사용하여 입력 파일에서 16kHz 모노 WAV를 추출한 후 (whisper.cpp는 WAV만 디코딩),
word_ts=true와 함께/transcribe로 POST 요청을 보냅니다. transcript.txt,transcript.srt,transcript.words.json을--out디렉토리에 기록하고 (기본값: 입력 파일의 디렉토리), 표준 출력에 JSON 결과 줄을 출력합니다.
출력 파일
transcript.txt— 일반 텍스트.transcript.srt— 자막 텍스트.transcript.words.json—[{ "word", "start", "end" }]형식, 초 단위, 시간순 정렬. 오버레이/캡션 동기화의 소스입니다.
표준 출력 결과 줄 (프로그래매틱 호출자, 예: /produce-video용):
{ "ok": true, "outDir": "...", "wordCount": 38, "segmentCount": 2, "files": { "txt": "transcript.txt", "srt": "transcript.srt", "words": "transcript.words.json" } }
요구 사항
- Docker가 필수입니다 — Whisper 서비스는 컨테이너에서 실행되므로 Docker Desktop이 설치되어 있고 실행 중이어야 합니다. 실행기는 이를 먼저 확인하고 Docker가 없거나 데몬이 중지된 경우 설치/시작 안내와 함께 오류를 출력합니다; Docker 외 대체 방법은 없습니다.
- ffmpeg가 필수입니다 (Whisper용 16kHz 모노 WAV 추출에 사용) — 실행기는 ffmpeg를 먼저 확인하고 PATH에 없으면 오류를 출력합니다.
- Node ≥ 22.
참고 사항
- 컨테이너는
--restart unless-stopped로 계속 실행 상태를 유지하여 재사용을 지원합니다.--stop으로 중지할 수 있습니다. - 단어 타임스탬프가 요청되었으나 반환되지 않으면 실행기는 오류를 출력합니다 (오버레이 동기화가 이에 의존함).
- Docker 생애 주기, API 구조, 벤더링 출처에 대해서는
references/를 참조하세요.