전문 자막 디자인은(는) 무엇을 하나요?
타임라인이 있는 단어를 세로형 동영상의 화면 자막으로 변환합니다. 상태: 구현 및 테스트 완료.
목적
단어를 읽기 쉬운 큐(cue)로 그룹화하고, 측정된 줄 너비로 배치하며, 소수의 명명된 스타일로 스타일링한 후 ASS / SRT / WebVTT로 내보내고 레이아웃 문제를 보고합니다.
지원되는 입력
- 단어 타이밍:
{"text", "start", "end"}또는{"words": [...]}형태의 JSON 목록, 시간은 초 단위. 텍스트는 로드 시 유니코드 NFC로 정규화되므로 베트남어 발음 구별 기호가 안정적으로 비교되고 렌더링됩니다. - (선택 사항) 강조할 키워드 목록과 숫자를 포함한 토큰을 강조할지 여부를 나타내는 플래그.
음성-텍스트 변환은 포함되어 있지 않습니다. 단어 타이밍은 호출자가 제공해야 합니다.
지원되는 출력
captions.ass(libass 스타일 적용, 렌더 파이프라인에서 합성됨)captions.srt,captions.vtt(일반 텍스트, 플레이어 및 플랫폼용)level(error|warning),code,message,cue인덱스가 포함된 문제 목록
실행
python3 -m uvs.captions examples/demo_caption/words.json --style bold_shorts \
--keywords "cháo,5" --out-dir out/captions
오류 수준의 문제가 하나라도 있으면 종료 코드는 1입니다. Python에서: uvs.captions.build_captions(...)
다음 write_outputs(build, out_dir).
매개변수
style:documentary_minimal,bold_shorts,cinematic,emotional_storytelling. 각 스타일은 글꼴, 크기, 두께, 색상, 윤곽선, 그림자, 하단 안전 여백(margin_v), 측면 여백, 최대 줄 수(2), 애니메이션(fade,pop,none)을 설정합니다.frame_w,frame_h: 기본값 1080x1920.SegmentConfig:max_gap(0.45초),max_duration(2.8초, 목표),hard_max_duration(3.4초, 문장 끝은 최대 이 시간까지 큐를 마칠 수 있음),min_duration(0.7초).
의존성
- Python 3.10+, Pillow.
- fontconfig (
fc-match) : 글꼴 파일을 찾는 데 사용됩니다. 없으면 Pillow의 기본 글꼴이 사용되며 너비 검사는 근사치입니다. 검증기는 이 대체를 보고하지 않으므로 fontconfig를 설치된 상태로 유지하세요. - 스타일에 지정된 글꼴 패밀리(기본값
Inter)는 libass 및 fontconfig를 위해 설치되어 있어야 합니다.
레이아웃 규칙
- 너비는 실제 글꼴 파일로 측정됩니다. 사용 가능한 너비는
frame_w - 2*margin_h - 2*outline입니다. - 두 줄 분할은 측정된 너비로 균형을 맞추며, 구두점 뒤에서 줄바꿈할 경우 약간의 보너스가 있습니다.
- 큐는 문장 끝, 긴 무음, 지속 시간 제한, 또는 다음 단어가 두 줄에 맞지 않을 때 나뉩니다.
- 강조된 키워드는 색상이 변경됩니다.
bold_shorts스타일에서는 잠시 확대(pop)되기도 합니다. 다른 단어는 애니메이션되지 않으므로 모든 단어가 동일하게 움직이지는 않습니다. - 사용자 텍스트의 ASS 오버라이드 구문(
{,},\)은 유사한 문자로 대체됩니다.
예제
examples/demo_caption/words.json은 수동으로 시간을 맞춘 베트남어 플레이스홀더입니다. 실제 내레이션과 일치하지 않습니다. 데모 실행: python3 -m uvs.render --out out/demo.
제약 사항
- 플랫폼 자막 규칙(예: 각 플랫폼의 줄 길이 또는 읽기 속도 제한)에 대해 검증되지 않았습니다.
too_fast임계값(초당 22자)은 경험적 기준입니다. - 화자 인식 스타일, 언어별 줄바꿈 사전이 없습니다(베트남어는 공백에서만 줄바꿈).
- "Documentary Minimal", "Bold Shorts", "Cinematic", "Emotional Storytelling"이 구현되었습니다. "Clean Modern", "Podcast Highlight", "Educational"은 구현되지 않았습니다.
오류 처리
- 빈 텍스트, 음수 시간, 또는 순서가 잘못된 시간은 로드 시
ValueError를 발생시킵니다. - 알 수 없는 스타일은
KeyError를 발생시킵니다. - 레이아웃 문제는 자동으로 수정되지 않고 문제로 보고됩니다:
line_overflow,too_many_lines,overlap,outside_frame,non_positive_duration,empty_cue(오류);short_cue,long_cue,orphan_word,too_fast,space_before_punctuation,missing_space_after_punctuation,double_space,not_nfc(경고). render_captioned은 오류가 있을 때 렌더링을 거부합니다.
테스트
tests/unit/test_captions.py (로딩, 레이아웃, 분할, 검증, 내보내기).
tests/render/test_pipeline.py::RenderTests는 데모를 렌더링하고 차원, 코덱, 프레임 속도,
그리고 자막 텍스트가 ASS 파일에 도달하는지 확인합니다.
통합
렌더 파이프라인(uvs/render.py)은 build_captions와 write_outputs를 호출한 다음, ASS
파일을 ffmpeg -vf ass=...로 합성합니다. 스타일 및 키워드 옵션은 파이프라인의 CLI에 직접 매핑됩니다.