agent-caption

agent-caption — SKILL

당신은 AI 자막(캡션) 에이전트입니다. 이 레포지토리는 모든 언어(기본값: 영어)로 된 동영상 또는 오디오에 대해 정확하고 완벽한 타이밍의 자막/서브타이틀을 추가합니다. 음성 및 음악을 모두 지원하며, 힌글리시(Hinglish) / 코드 스위칭을 일급 시민으로 지원합니다. Windows, macOS, Linux에서 실행됩니다.

레포지토리: https://github.com/ahkamboh/agent-caption — 클론: git clone https://github.com/ahkamboh/agent-caption 이 파일(원본, 채팅 에이전트가 가져오기용): https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

핵심 원칙: 단어는 음성 인식에서 오지만, 타이밍은 파형에 대한 강제 정렬에서 옵니다 — 절대 원시 ASR 타임스탬프를 사용하지 않습니다. 따라서 전사에 철자 오류가 있어도 자막이 늦거나 빠르지 않습니다.

일회성 설정 (Windows / macOS / Linux)

필요 사항: Python 3.10+, ffmpeg, 약 4 GB 디스크 공간. (torch는 3.14까지 wheel을 제공합니다. whisperx가 아주 새로운 Python 버전에서 wheel을 지원하지 않으면 3.11–3.12를 사용하세요.)

python setup.py        # 크로스 플랫폼: ./.venv-whisperx 생성 및 모든 것 설치
# macOS/Linux 편의: bash setup.sh      ·      Windows 편의: setup.bat

ffmpeg: macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg. 모델(Whisper large-v3 — 기본값 — MMS_FA, whisperX)은 첫 실행 시 자동 다운로드됩니다.

가장 쉬운 경로 — 단일 명령 래퍼 (이것을 선호)

"이 동영상에 자막을 넣어줘" 같은 요청의 경우, 최상위 래퍼를 실행하기만 하면 됩니다. 이 래퍼는 전사 → 정렬 → 자동 비례 자막(모든 해상도에 맞는 올바른 크기/간격/정렬)을 포함한 렌더링(burn)을 수행하며, 사용자의 ffmpeg가 자막을 지원하지 않는 경우 libass-free 렌더러(Pillow + overlay)로 대체합니다.

python caption.py <video>                                  # 영어, clean, 비례 -> <video>.captioned.mp4
python caption.py <video> --hinglish --style tiktok        # 힌글리시 + TikTok 박스
python caption.py <video> --lang ur --pos center --size 6  # 다른 언어 / 위치 / 크기
python caption.py <video> --srt                            # .srt 파일만 생성 (렌더링 안 함)
python caption.py <video> --from-srt FILE                  # 기존 .srt 파일을 비례에 맞춰 렌더링

15가지 스타일(번들 폰트 포함): clean (기본값) bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle. 아래 개별 스크립트는 원시 전사본, 사용자 정의 렌더링, 또는 번역이 필요할 때만 사용하세요.

모델: large-v3가 기본값(최고 정확도)입니다 — 별도 플래그가 필요 없으며, setup.py가 미리 가져옵니다. 깨끗한 영어에서 속도를 원하면 --fast를 추가하세요(소형 모델). --accurate는 여전히 존재하지만 이제 불필요합니다. 힌글리시 경로는 항상 large-v3를 사용합니다.

사용자 정의 스타일 — 사용자가 설명하는 모든 모양을 만듭니다. 사용자의 말을 다음 플래그에 매핑하세요(--style을 재정의합니다):

• --font <name|path> — 번들 폰트(Poppins-Bold, Poppins-Black, Anton-Regular, BebasNeue-Regular, ArchivoBlack-Regular) 또는 모든 .ttf 경로
• --fill #hex (텍스트 색상) · --outline #hex · --box #hex|#hexAA|none (텍스트 뒤의 필)
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N (외곽선 두께)
• --size <pct> (높이) · --pos bottom|center|top

예시 — 사용자가 *"핫핑크 대문자, 어두운 둥근 박스에 크게, Anton 폰트"*라고 말하면 →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

새로운 명명된 스타일을 영구적으로 만들려면 caption.py의 STYLES 딕셔너리에 항목을 추가하세요.

정확도 — 잘못 들은 단어 제거 (무료, 토큰 불필요, 사람 검토 불필요)

강제 정렬은 타이밍을 설계상 올바르게 만듭니다. 고칠 수 없는 유일한 것은 단어가 올바르게 들렸는지 여부입니다("그들의" / "거기", 이름, 속어). 세 가지 무료 지렛대가 이를 0에 가깝게 만듭니다:

• --glossary "..." — 이름/브랜드/속어를 제공합니다(목록 또는 .txt 경로). ASR의 초기 프롬프트에 편향을 주어 고유 명사가 잘못 들리는 것을 방지합니다. 이름에 대해 가장 큰 단일 효과입니다. 한 번만 목록을 작성하면 됩니다.

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script FILE — 올바른 단어가 이미 존재하는 경우(가사, 대본), 이들을 전달합니다. 도구는 ASR을 완전히 건너뛰고 주어진 단어만 강제 정렬합니다 → 100% 콘텐츠 정확도.

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — 자막에 대한 오프라인 동음이의어/문법 검사("그들의"→"거기", "너의"→"넌"). 로컬에서 LanguageTool을 실행합니다(업로드 없음, 토큰 없음); 타이밍은 절대 건드리지 않습니다. 선택적 의존성 — python setup.py --grammar로 한 번 활성화합니다(Java/JRE 8+ 필요); 없으면 깔끔하게 건너뜁니다.

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # 모두 함께 사용
  

가성비 순서: --glossary (이름) → --script (텍스트가 있을 때) → --grammar (동음이의어). 기본 모델은 이미 large-v3입니다. 이들이 잡을 수 없는 유일한 잔여물은 사람이나 LLM이 필요합니다 — 이것이 토큰을 쓸 가치가 있는 유일한 비용이며, 전체 전사본이 아닌 표시된 단어에 대해서만입니다.

노래 — 먼저 보컬 분리 (--content)

음악의 경우, ASR 전에 보컬 스템을 분리하면 가사 전사가 훨씬 깨끗해집니다(Whisper가 배경 트랙과 싸우지 않음). 조건부입니다 — 깨끗한 음성에는 무의미/느리므로 게이트가 있습니다:

python caption.py song.mp4 --content music                 # 강제 보컬 분리 (demucs)
python caption.py clip.mp4                                  # --content auto (기본값): 음악 감지 시에만 분리
python caption.py podcast.mp4 --content speech              # 절대 분리 안 함 (또는 --no-isolate)
python caption.py song.mp4 --content music --script lyrics.txt   # 가장 깨끗한 노래: 알려진 단어, 보컬 스템에 맞춰 타이밍

auto는 빠른 음악/음성 프로브를 실행하고 음악이 감지된 경우에만 분리합니다 — 따라서 팟캐스트/인터뷰는 느려지지 않습니다. 렌더링(burn)은 항상 원본 동영상을 사용하며, 우리가 전사/정렬하는 것은 스템뿐입니다. demucs 필요(python setup.py로 설치됨); 없으면 원본 오디오로 대체됩니다.

모든 스크립트는 venv의 python으로 실행 — 여기서는 PY로 표기:

• macOS / Linux: PY = ./.venv-whisperx/bin/python
• Windows: PY = .venv-whisperx\Scripts\python

스크립트들

• transcribe.py — Whisper → 단어 수준 전사(기본값 영어; 다른 언어는 --lang xx).
• align.py — 강제 정렬을 통한 프레임 정확한 타이밍. 힌글리시/혼합용 --code-switch.
• cs_transcribe.py — 코드 스위칭에 강건한 단어 인식(세그먼트별 언어 ID).
• mms_align.py — 범용 MMS_FA 강제 정렬기(1100개 이상 언어, 모든 스크립트).
• validate_timing.py — 코드 스위치 경로에서 사용하는 타이밍 온전성 검사.
• export-subs.py — 전사 → .srt + .vtt.
• multilang-subs.py — 자막을 여러 언어로 오프라인 번역.
• grammar_fix.py — .srt 파일에 대한 오프라인 동음이의어/문법 수정(타이밍 유지); --grammar에서 사용.
• isolate_vocals.py — 노래용 Demucs 보컬 분리 + 음악 대 음성 프로브; --content에서 사용.
• qa.py — 빠른 결정론적 QA 게이트(큐 온전성 + ffprobe 출력 검사) → work/<base>.qa.json. 모든 렌더링 후 자동 실행; --strict는 손상된 출력에 대해 0이 아닌 종료 코드를 반환함.
• footprint.py — <base>.footprint.svg을 렌더링: 한 눈에 보는 자막 건강 맵(각 단어 색상 = 강제 정렬 신뢰도 + 갭 표시기 + 판정). 각 자막 후 자동 실행; 건너뛰려면 --no-footprint.
• benchmark.py — 실제 정확도 향상 측정: 이전 기본값(small)과 새 기본값(large-v3 [+ Demucs])의 기준 전사 대비 WER. PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish].
• caption.py — 올인원 스타일 자막(노래방/단어/라인; Hormozi/TikTok/네온…) → 애니메이션 captions.js.

동영상 자막 처리 (주 작업) — 기본 언어 = 영어

다른 언어의 경우 --lang <code>를 전달하세요. 힌글리시 / 혼합의 경우 --code-switch를 사용하세요.

1) 프레임 정확한 단어 타이밍

음성(대화, 팟캐스트, UGC):

PY scripts/align.py INPUT --lang en --out work/transcript.json

힌글리시 / 혼합 힌디어-영어(또는 모든 코드 스위칭 오디오):

PY scripts/align.py INPUT --code-switch --dual hi en --out work/transcript.json

다른 모든 언어(우르두어, 스페인어, 아랍어, 중국어, …):

PY scripts/align.py INPUT --lang ur --out work/transcript.json

2a) 자막 (.srt / .vtt) + 동영상에 렌더링(burn)

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i INPUT -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

.srt 파일은 YouTube에 직접 업로드하기에도 완벽합니다(선택 가능 + SEO).

2b) 스타일/애니메이션 자막 (Hormozi, TikTok, 노래방 — 숏폼)

PY scripts/caption.py INPUT --lang en --content speech --style karaoke --preset hormozi --out out/

프리셋: hormozi, beast, pill, neon, gradient, minimal, tiktok. 노래/가사에는 --content music을 사용하세요. docs/caption-styles.md 참조.

3) 자막을 모든 언어로 번역 (선택 사항)

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn INPUT]

규칙 (내장 — 재정의하지 마세요)

• 타이밍은 항상 강제 정렬이어야 하며, 절대 원시 ASR 타임스탬프를 사용하지 않습니다(앞서거나 늦어지지 않음).
• 기본 자막 언어 = 영어; 다른 언어는 --lang을 전달하세요.
• 음악/노래 → --content music; 음성/대화 → --content speech.
• 모든 스크립트는 PY(venv python)로 실행하여 whisperx/torch가 있는지 확인하세요.
• 전달 전에 몇 개의 자막을 단어 시작점에서 확인하여 동기화를 확인하세요.

언어 코드

en (기본값), hi, ur, pa, es, fr, de, pt, ar, zh, ja, ko, ru, it, tr, id, nl, pl, uk, … — Whisper는 약 99개 언어를 지원합니다. MMS_FA는 1100개 이상을 정렬합니다.