Bilingual Video Subtitles 培训视频双语字幕
전체 파이프라인은 scripts/pipeline.py에 있습니다 (단일 진입점, 단계별 캐싱 및 중단점 재개 지원).
호스트 환경 주의: 이 스킬은 크로스 환경에 맞게 조정되어 있으며, 전사 백엔드가 자동으로 선택됩니다 (원본 샌드박스의 Omni 게이트웨이 / OpenAI 호환 API / Whisper 브리지). Omni 게이트웨이가 없고 API 백엔드가 구성되지 않은 경우 에이전트 모드로 작동합니다.
transcribe/translate단계에서 종료 코드 3과 함께 매니페스트를 출력하고, 해당 전사/번역을 완료한 후build를 다시 실행하여 계속 진행합니다. 작동 프로토콜 및 백엔드 구성은 반드시 references/host-adaptation.md를 읽어보세요. 파이프라인 종료 코드 3은 실패가 아닙니다. 매니페스트에 따라 해당 작업을 완료한 후 다시 실행하면 됩니다.
표준 워크플로우
- 입력 획득: 비디오 파일 + 해당 규정/참조 문서 (.docx/.txt/.md).
- 참조 문서를 읽고 용어집
glossary.txt를 작성합니다 (각 줄중국어 = English, 10~40개). 용어집은 전체 비디오의 번역 일관성을 결정하므로 다음을 반드시 포함해야 합니다: 제도/규범 이름, 역할 및 약어 (예: PM=Project Manager), 업무 문서 또는 양식 이름, 내부 시스템 이름. - 빌드 실행 (포그라운드에서 실행, 충분한 타임아웃 설정; 50분 비디오 전체 프로세스는 약 15~25분 소요):
python3 scripts/pipeline.py build \
--video <비디오 경로> --doc <제도 문서 경로> \
--work <작업 디렉토리> --out <출력 디렉토리> \
--glossary <glossary.txt> \
--hotwords "안전 레드라인, 요청서, 변경서, PM, QA, SRE" \
--preview 90
- 생성 순서 (각 단계는 캐시되며, 실패 후 동일 명령어로 다시 실행하면 계속 진행):
setup(오디오 분할) →transcribe(Qwen3-Omni 자막) →timing(Whisper 타임라인) →align(병음 정렬) →clean(구어체 제거/문장 분할) →translate(벌크 중-영 번역) →package(프로젝트 파일+SRT+ASS) →render(미리보기+전체 버전). - 먼저
--preview로 출력된 미리보기 비디오를 사용자에게 보여주어 확인을 받고 (media-read로 프레임을 추출하여 자막 렌더링 확인 가능), 그런 다음 전체 버전 비디오, SRT, 자막 프로젝트 파일을 전달합니다.
결과물 설명
| 파일 | 용도 |
|---|---|
<이름>_중영 이중 자막_전체 버전.mp4 | 하드서브 완성본 (중국어 상단 흰색, 영어 하단 연한 파란색, 반투명 검은색 배경 막대 포함, 모든 배경에서 읽기 가능) |
<이름>_중영 이중 자막.srt | 이중 자막 파일 (플레이어/플랫폼에 가져오기 가능) |
<이름>_자막 프로젝트.json | 마스터 데이터: 전체 타임라인 + 중영 대조 텍스트 포함. 연간 미세 조정 시 이것만 수정 |
--work 디렉토리 | 중간 산물 캐시 (전사 원고, Whisper 타임라인). 보관 시 재전사 방지 |
연간 미세 조정 (제도 개정 후 자막 업데이트)
제도 미세 조정이 소수의 문장에만 영향을 미칠 때는 재전사하지 마세요:
- 사용자가 수정해야 할 시간대/내용을 지적하거나, 전년도
<이름>_자막 프로젝트.json에서 직접zh/en텍스트를 수정합니다 (타임라인이 변경되지 않으면 start/end를 건드리지 않음). - 재렌더링:
python3 scripts/pipeline.py render --project <프로젝트.json> [--video <새 비디오>] [--srt-only]
새 비디오의 해당 챕터에 문장이 추가/삭제된 경우: 새 비디오에 대해 build --stage transcribe를 실행하여 새 자막 원고를 가져오고, 수동으로 비교한 후 새 텍스트로 프로젝트 파일의 해당 항목을 교체한 다음 render를 실행합니다.
주제/역할별 짧은 비디오 분할 (조각 학습)
이미 자막이 추가된 전체 버전 비디오를 기반으로 분할합니다 (이중 자막 유지).
- 자막 데이터에서 챕터 경계를 찾습니다: 참조 문서의 역할/챕터 목록을 키워드로 사용하여
zh_lines.json(작업 디렉토리)에서 챕터 전환 문구를 검색합니다. 일반적인 패턴: "N번째 역할은 X입니다", "위는 X의 책임이며, 요구 사항은", "X의 위반 사항은" 등의 전환 문장. 전환 문장의 시작 시간을 분할 지점으로 사용합니다 (해당 문장은 다음 에피소드에 포함됨). - 제약: 단일 에피소드 ≤10분 (엄격한 상한 15분); 챕터가 한도를 초과하면 챕터 내부 자연 경계 (예: "책임/위반 행위/판단 방법" 사이)에서 2차 분할; 다른 역할을 병합하지 않음.
- 분할 계획 JSON을 작성하고 실행:
{"base": "비디오 이름", "lead_in": 0.35,
"chapters": [{"start": 0, "end": 288.4,
"title": "01_서문_목적 및 개요", "note": "내용 설명"}]}
python3 scripts/pipeline.py split --plan plan.json \
--video <자막 포함 전체 버전.mp4> --out <출력 디렉토리>
<출력 디렉토리>/<비디오 이름>_분할 비디오/에 출력: 자동 명명된 각 에피소드 +00_분할 목록.txt(영화 제목, 시간대, 길이, 내용 설명).- 샘플링 확인: 각 에피소드 시작 부분에서 프레임을 추출 (ffmpeg로 PNG 캡처 후 확인)하여 분할 지점이 해당 주제의 시작 문장에 정확히 위치하는지 확인합니다.
핵심 구현 규칙 (벗어나지 마세요)
- qwen-omni 백엔드는 참조 문서 전체를 프롬프트에 용어 컨텍스트로 주입해야 하며,
--timeout 900 --max-tokens 8192여야 합니다 (스크립트에 이미 내장됨); API 백엔드의 전용 ASR (예: mimo-asr)은 텍스트 프롬프트를 사용하지 않으므로, 용어 오류 수정은clean단계에서 문서와 대조하여 수행합니다. - whisper는 타임라인에만 사용되며, 인식된 텍스트는 모두 버립니다 (중국어 텍스트 품질이 낮지만 타임스탬프는 정확함).
- 정렬은 반드시 병음 문자열 전역 정렬을 사용해야 합니다 (동음이의어 오류가 병음 레벨에서 자동으로 해소됨); 문장별 탐욕 정렬은 전체적으로 어긋납니다.
- 정렬 품질:
align출력qual mean≥0.75는 정상; <0.6인 경우 먼저 whisper 음성 커버리지를 확인합니다 (references/troubleshooting.md 참조). - 장시간 CPU 작업 (whisper/render)은 호스트의 백그라운드 작업 정리 정책에 유의하고, 필요한 경우 포그라운드에서 실행합니다.
- 네트워크 제한: HuggingFace는 미러가 필요하며, 스크립트에 이미
HF_ENDPOINT=hf-mirror.com및HF_HUB_DISABLE_XET=1이 내장되어 있으므로 삭제하지 마세요.
문제 해결
references/troubleshooting.md 참조: 업로드 시간 초과, 전사 단일 긴 행, 정렬 품질 저하, 글꼴 깨짐, 렌더링 실패 등 상황 처리.