zaddy99999/captions

captions은(는) 무엇을 하나요?

로컬 단어 수준 전사, 숏폼 자막 스타일링 및 굽기.

스크립트는 scripts/ 디렉토리에 있습니다:

스크립트	기능
transcribe.py	word_timestamps=True 옵션으로 faster-whisper 실행하여 words.json 생성 (캐시됨)
make-captions.mjs	words.json을 ASS(스타일 적용, 활성 단어 강조) 및 SRT로 변환
burn.mjs	libass(ass / subtitles 필터)를 사용하여 ASS/SRT 굽기
snap-to-words.mjs	컷 포인트를 단어 사이의 가장 가까운 간격으로 이동

워크플로우

1. 전사 (소스당 한 번; 결과는 캐시됨):

   pip install faster-whisper            # 한 번만 실행
   python3 scripts/transcribe.py --input clip.mp4 --out edit/clip.words.json --model small --language en
   

   첫 번째 실행 시 Hugging Face에서 모델을 다운로드합니다. 차단된 경우 스크립트는 트레이스백 대신 종료 코드 4와 JSON fix 메시지를 출력하며, 가짜 전사본을 절대 쓰지 않습니다. 오프라인 작업을 위해 --model을 로컬 CTranslate2 모델 폴더로 지정할 수 있습니다.
2. 자막 생성:

   node scripts/make-captions.mjs --words edit/clip.words.json --out-ass edit/clip.ass --out-srt edit/clip.srt
   

   스타일은 브랜드 팩(captions 블록: 크기, 여백, 외곽선, 강조; colors.accent는 활성 단어 색상)에서 가져옵니다.
3. 굽기 (비주얼 작업의 마지막 단계):

   node scripts/burn.mjs --input edit/clip-hook.mp4 --subs edit/clip.ass --out edit/clip-captioned.mp4
   

   자막 폰트가 설치된 폰트가 아닌 파일인 경우 --fonts-dir를 사용하세요.
4. 검증 render-qc 증명 시트로 확인: 가독성, 안전 영역 내부, 훅 플레이트 위로 올라가지 않음.

규칙

• 단어 내부를 절대 자르지 마십시오. 음성을 분할하기 전에 컷을 단어 간격으로 스냅합니다: node scripts/snap-to-words.mjs --words edit/clip.words.json --markers edit/cuts.json --out edit/cuts.json
• 자막은 마지막에 적용: 컷, 오버레이 및 색상 적용 후. 트랜스크립트 작성 후 클립을 자른 경우 make-captions.mjs에 --offset -<잘라낸 초>를 전달합니다.
• 숏폼의 경우 청크당 1~3단어(maxWords, maxChars). 청크는 구두점과 일시 정지에서 나뉩니다.
• 자막을 하단 약 15%(플랫폼 UI) 밖에, 훅 플레이트에서 멀리 유지: captions.marginV 조정.
• 전사본은 캐시됩니다: 오디오가 변경된 경우에만 --force로 다시 실행합니다.
• 단어를 오디오와 대조하여 샘플 점검; whisper는 이름이나 전문 용어를 잘못 들을 수 있습니다. 필요한 경우 words.json을 수동으로 수정하세요.

ffmpeg libass 없는 경우

burn.mjs에서 ass 필터가 없다고 보고하면 ffmpeg 빌드에 libass가 없는 것입니다. 전체 빌드를 설치하거나(대부분의 패키지 관리자가 제공함), SRT를 별도의 자막 트랙으로 업로드하여 굽지 않고 사용하세요.