auto-subtitle

auto-subtitle — 오디오/비디오 자동 전사 → SubtitleCue

한 줄로 자막 생성: 오디오/비디오 파일 입력 → <동일 이름>.cues.json + <동일 이름>.srt 두 개의 출력 파일 생성. 데이터 계약은 video-motion SubtitleCue와 단어 단위로 정렬됨: {start, end, text}, 초, 소수점 3자리, 한 줄 텍스트(긴 문장은 분할됨) — subtitles 배열은 바로 video-motion 타임라인에 사용 가능.

Step 1 · 미디어 파일 및 언어 확인

• mp4 / wav / flac 모두 지원 (PyAV로 직접 디코딩). 디코딩 오류 발생 → 먼저 트랜스코딩 후 입력: ffmpeg -i in.mp4 -vn -ac 1 -ar 16000 out.wav
• 언어 확인 및 --lang 전달: zh(기본값) / en 등 Whisper 언어 코드
• 순수 음악/효과음素材는 실행 불필요: VAD가 빈 출력 또는 매우 짧은 출력을 걸러냄 (이것은 기능이며 버그가 아님)
• 이미 알려진 텍스트(구술 대본 / 대사 / 원문)가 있는 경우 UTF-8로 보관 — Step 3 L2 비교의 기준선으로 사용, 기준선 표류 방지

Step 2 · 전사 실행

venv는 저장소 외부에 위치 (284MB 빌드 산출물, .gitignore에 .venv/가 이미 포함됨). 이 저장소는 빌드 산출물을 포함하지 않는 스킬 템플릿 규칙을 따르며, 템플릿에 node_modules가 없는 것과 동일한 원리입니다. 따라서 venv는 저장소 외부에 생성하여 모든 프로젝트가 한 번에 재사용:

python -m venv "$env:USERPROFILE\.cache\vibe-studio\asr-venv"
& "$env:USERPROFILE\.cache\vibe-studio\asr-venv\Scripts\python.exe" -m pip install -r skills/auto-subtitle/templates/asr/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

cd skills/auto-subtitle/templates/asr
& "$env:USERPROFILE\.cache\vibe-studio\asr-venv\Scripts\python.exe" transcribe.py <입력.mp4|wav> --outdir <출력 디렉터리>

• 기본 모델 large-v3-turbo (≈1.6GB, 최초 자동 다운로드, 중국어 품질 기준); 빠른 검증 시 --model small 추가 (≈484MB). 모델 캐시는 ~/.cache/huggingface에 저장, 한 번 다운로드하면 전역 재사용
• 모델 다운로드 실패 시 HF_ENDPOINT 설정: 기본값은 공식 직접 연결 (2026-08 기준 정상 작동 확인); 대안 예: $env:HF_ENDPOINT="https://hf-mirror.com" (참고: hub 1.x 버전에서 해당 미러는 308 리디렉션 호환성 문제가 있을 수 있으므로 공식 우선)
• stdout 한 줄 영문 요약: segments=N cues=M total_audio=... model=... lang=... out=...; exit 0 성공, 1 실패

Step 3 · 삼중 검증 (필수, 생략 불가)

L1 프로그램 수준: JSON은 json.load 가능해야 함; subtitles는 배열이며 각 항목은 정확히 start/end/text 세 필드를 가져야 함; start < end이며 항목 간 단조 감소하지 않음; 숫자는 소수점 3자리; 마지막 항목의 end ≤ ffprobe 길이 + 1초. SRT 타임스탬프 줄은 HH:MM:SS,mmm --> HH:MM:SS,mmm 형식과 일치해야 하며, 번호는 1부터 연속적.

L2 정확성: 알려진 텍스트가 있는 경우 → difflib.SequenceMatcher로 비교 (양쪽에서 구두점과 공백 제거 및 정규화 후), 전체 유사도 ≥0.85, 문장별 유사도 ≥0.70 (연속 cue에 대해 결합 창을 기준으로 max 값 사용, 분할/병합 모두 포함); 알려진 텍스트가 없는 경우 → 처음/중간/끝 세 부분을 청취하여 확인.

L2.5 타임라인 (일반 검사): 자막 창은 단어 수준 음성 창과 정렬되어야 하며, 문장 사이의 무음 구간에는 자막이 없어야 함 — 인접 cue 사이의 간격을 감사: 문장 사이에는 >1초의 실제 무음 간격이 나타나야 함 (문장 내 분할 gap=0은 정상); <0.3초의 섬광 조각이 존재해서는 안 됨; 첫 번째 cue의 start는 음성 시작점과 정렬되고, 마지막 cue의 end는 끝 무음을 삼키지 않아야 함. 스크립트 내부에서는 이미 단어 수준 타임스탬프(첫 번째 단어 start / 마지막 단어 end)를 사용하여 창을 정의하며, 이 단계는 출력물 수준 검증입니다.

L3 결론 행: 모두 통과 = ALL GREEN; 빨간 항목이 있는 경우 → 분할 수정 / VAD 매개변수 조정 후 재실행 및 재검사, 2회 연속 빨간 항목 → 중지 및 보고, 맹목적 조정 금지.

Step 4 · 전달

• 보고: cues.json 절대 경로 + cue 수 + 오디오 길이 + 모델/언어 + 삼중 검증 결과
• video-motion 연동: subtitles 배열을 video-motion 프로젝트의 src/cues.ts 파일에 있는 cues.subtitles에 직접 붙여넣어 사용 가능, 필드 변환 불필요
• 명시적으로 수행하지 않음 (향후 계획): 화자 분리, 단어 수준 타임스탬프 내보내기, 번역, TTS 음성

Step 5 · 재실행 명령어 기록

전달 보고서 끝에 전체 재실행 명령어를 첨부 (입력 경로 / --lang / --outdir / --model), 이후 세션이나 다른 사람이 정확히 재현할 수 있도록 보장; 산출물(cues.json / srt)은 출력 영역에 저장 (이 저장소의 경우 products/, 다른 저장소의 경우 프로젝트 루트 output/)되며 git에 포함되지 않음. 명령어 자체가 자산입니다.

경계 및 주의사항

• GBK 콘솔: 스크립트 print는 모두 영문; 파일 쓰기는 항상 명시적으로 encoding="utf-8" 사용, JSON은 ensure_ascii=False
• 분할 규칙: 한 항목이 20자를 초과하는 경우 구두점(。！？；，、)에서 분할, 창 내 구두점이 없으면 강제 분할하며 마지막 조각은 최소 3자 보장 (1자 조각 방지); <0.3초 조각은 이전 항목과 병합, 병합 시 20자 상한 초과 금지
• 단어 수준 타임스탬프가 자막 창의 유일한 올바른 소스입니다. 구간 수준 타임스탬프는 문장 간 무음을 삼켜 자막이 무음 구간만큼 일찍 나타나게 할 수 있습니다 (수정 완료, word_timestamps=False로 롤백하지 마세요)
• CPU int8 추론: 28초 오디오 ≈ 1분 이내 결과 출력, 긴 오디오는 비례하여 시간 예상; large-v3-turbo 첫 실행 시 다운로드 포함, 충분한 시간 초과 설정 필요
• 중국어 인식에서 숫자는 종종 아라비아 숫자로 변환됨 (예: "两百毫秒" → "200毫秒"), L2 비교 시 정상적인 차이로 인식 오류가 아님

전달 연동

최종 SRT/cues 파일은 원본 오디오 트랙 소스, 모델 버전과 함께 보관해야 함; 자막이 하드코딩된 mp4만 남기지 마세요. 비디오 전달 시 media-qc를 사용하여 자막 창이 실제 길이와 일치하는지 확인하고, 정확성은 여전히 알려진 대본 또는 청취를 통해 확인합니다. 기본 모델 다운로드 및 로컬 추론은 수동 음성 더빙을 대체하지 않습니다.