자동 자막 (음성→자막)
오디오/비디오에서 사람의 음성을 인식하여 자막을 생성합니다. 공유 스크립트 skills/shared/scripts/asr.py(faster-whisper 래퍼) 기반으로,
매개변수가 결정적이며 재현 가능하고, 중국어 친화적인 문장 분할을 지원합니다. 선택적으로 자막을 비디오에 하드코딩할 수 있습니다 (skills/shared/scripts/video_ops.py / ffmpeg subtitles 필터 재사용).
"음성 → 자막 파일 (+ 선택적 하드코딩)"만 수행합니다. 일반 비디오 편집은 video-editing을, 순수 노이즈 제거는 audio-denoise를, 긴 비디오의 지능적 분할+자막 하드코딩은 clipify를 참조하세요.
입력
| 필드 | 필수 | 설명 |
|---|---|---|
| input_file | 예 | 오디오 또는 비디오 파일 경로 (비디오는 자동으로 오디오 트랙 추출) |
| format | 아니오 | srt(기본값) / ass / txt / json |
| language | 아니오 | auto(기본값) 또는 zh/en 등 ISO 639-1 코드 |
| model | 아니오 | tiny/base(기본값)/small/medium/large-v3, 클수록 정확하지만 느림 |
| burn | 아니오 | 자막을 비디오에 하드코딩할지 여부 (비디오 입력 필요) |
지원 포맷: mp3/wav/m4a/aac/flac 등 오디오; mp4/mkv/mov/webm 등 비디오.
출력
- 자막 파일은
outputs/주제명/디렉토리에 저장됨 (SRT/ASS/TXT/JSON) - 하드코딩 시: 하드 자막이 포함된 비디오 (
*-sub.mp4) - 보고: 인식된 언어, 자막 수, 사용 모델, 출력 경로
사전 조건
- 첫 실행 시 HuggingFace에서 모델을 다운로드하므로, 외부 프록시가 필요합니다. 스크립트는
EASEL_PROXY또는http(s)_proxy환경 변수를 프록시로 사용합니다; 둘 다 설정되지 않으면 직접 연결합니다.export https_proxy=... http_proxy=...로 미리 지정할 수도 있습니다. - CPU 환경에서는 기본
--device cpu --compute-type int8을 사용하면 됩니다.
실행 단계
스크립트 경로 (프로젝트 루트 기준): skills/shared/scripts/asr.py, skills/shared/scripts/video_ops.py.
1. 자막 파일 생성
# 비디오 → SRT (자동 오디오 트랙 추출 + 언어 자동 감지)
python skills/shared/scripts/asr.py transcribe \
-i input.mp4 -o outputs/주제명/input.srt --language zh
# 비디오 → ASS (스타일 포함, **글꼴 크기/여백이 비디오 가로/세로 화면에 자동 적응**): 비디오 입력 시 자동으로 너비/높이 감지
python skills/shared/scripts/asr.py transcribe \
-i input.mp4 -o outputs/주제명/input.ass --format ass --model small
# 순수 오디오 → ASS: 해상도 감지 불가, 기본 세로 화면 1080x1920; 가로 화면은 --res 1920x1080 추가
python skills/shared/scripts/asr.py transcribe \
-i voice.mp3 -o outputs/주제명/voice.ass --format ass --res 1920x1080
- ASS 스타일은 대상 비디오의 너비/높이에 자동 적응: 글꼴 크기는 짧은 변(min(w,h)*0.05, 세로/가로 화면 모두 적절, 가로 화면에서 너무 크지 않음),
하단 여백은 높이 기준, 좌우 여백은 너비 기준,
PlayRes=실제 너비/높이. 비디오 입력은 자동 감지; 순수 오디오는--res 너비x높이로 지정. 스타일이 있는 하드 자막에는 이 ASS 파일 우선 사용 (다음 절 참조), 원시 SRT + 수동 force_style보다 편리하고 자동 적응됨. - 중국어 기본값은 행당 ~18자, 초과 시 자동 줄바꿈/분할;
--max-line-chars로 조정 가능. -o를 지정하지 않으면 입력 파일 이름으로 프로젝트 디렉토리를 생성, 예:talk.mp4는outputs/talk/talk.srt로 출력; 기존 프로젝트가 있으면 명시적으로-o outputs/주제명/<파일명>.<포맷>지정.- 사용 가능한 모델/언어 확인:
python skills/shared/scripts/asr.py info.
2. (선택) 자막을 비디오에 하드코딩
사용자가 "하드 자막/비디오에 자막 넣기"를 요청하면, ffmpeg의 subtitles(SRT) 또는 ass(ASS) 필터 사용:
# SRT 하드코딩 (스타일 커스터마이징 가능)
ffmpeg -y -i input.mp4 \
-vf "subtitles=outputs/주제명/input.srt:force_style='FontName=Noto Sans CJK SC,FontSize=20,PrimaryColour=&H00FFFFFF,OutlineColour=&H80000000,BorderStyle=1,Outline=2'" \
-c:a copy outputs/주제명/input-sub.mp4
# ASS 하드코딩 (스타일은 ASS 파일에 내장, 충실도 높음)
ffmpeg -y -i input.mp4 \
-vf "ass=outputs/주제명/input.ass" \
-c:a copy outputs/주제명/input-sub.mp4
- 경로에 특수 문자가 포함된 경우,
subtitles=값을 작은따옴표로 감싸고 콜론을 이스케이프 처리합니다. - 소프트 자막(끄기 가능)이 필요하면 하드코딩 대신:
ffmpeg -i in.mp4 -i sub.srt -c copy -c:s mov_text out.mp4.
3. 산출물 및 보고
- 자막 파일, 하드코딩된 비디오는 모두
outputs/주제명/에 저장됩니다. - 사용자에게 보고: 인식된 언어, 자막 수, 모델, 파일 경로;
--model/--max-line-chars를 변경하여 재실행 가능함을 알림.
규칙
- 비디오는 먼저 오디오 트랙을 추출 — 스크립트가 자동으로 ffmpeg를 사용하여 16kHz 모노 wav 추출, 원본 비디오는 변경하지 않음.
- 중국어 친화적 문장 분할 — 구두점/길이에 따라 줄바꿈, 한 줄이 너무 길지 않도록 함.
- 원본 파일 절대 삭제하지 않음 — 새 파일만
outputs/에 생성. - 모델 선택 — 속도 우선은
base, 정확도 우선은small/medium; CPU는 int8 사용. - 하드코딩에는 비디오 입력 필요 — 순수 오디오는 하드코딩 불가, 자막 파일만 출력.
- 프로필 의존성 없음 — 전사에 계정 프로필이 필요하지 않음.
참고 자료
- SYSTRAN/faster-whisper — CTranslate2 가속 Whisper 추론
- openai/whisper — 원본 Whisper 모델 및 ASR 방법
- FFmpeg
subtitles/ass필터 (자막 하드코딩)