가라오케 자막
파이프라인: 비디오 → 16kHz 오디오 → DashScope ASR(단어 타임스탬프 포함) → LLM이 용어를 선택하고 중국어 주석 작성 → ASS 가라오케 자막 → ffmpeg 및 libass로 인코딩.
모든 작업은 하나의 비대화형 CLI인 scripts/pipeline.py를 통해 수행됩니다. 이 파일의 경로는 스킬 디렉터리를 기준으로 합니다. 모든 명령은 어떤 디렉터리에서든 스킬 경로를 앞에 추가하여 실행하세요. 예: python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor
첫 실행 전
python3 scripts/pipeline.py doctor를 실행하세요. 종료 코드 0이면 준비 완료입니다. 키가 설정되면,DASHSCOPE_BASE가 해당 키의 리전과 일치하는지 확인하기 위해 무료 요청을 한 번 보냅니다. 아무것도 업로드되거나 청구되지 않습니다. 해당 요청을 건너뛰려면--offline을 추가하세요.- 종료 코드 3이면
bash scripts/install.sh를 실행하고 출력되는 각FAIL행을 수정하세요. 스크립트에서 sudo에 비밀번호가 필요하다고 하거나 API 키가 없다고 하면 중단하고 사용자에게 물어보세요. 사용자에게 키를 채팅에 붙여넣도록 요청하지 말고,.env파일에 넣도록 하세요(.env.example참조). - 설정 세부 사항:
references/prerequisites.md를 참조하세요.
사용자와 확인
- 비디오: 로컬 파일 또는 URL. 사용자가 해당 파일을 처리할 권한이 있어야 합니다.
- 주석: 켜짐(기본값) 또는 꺼짐(
--no-annotate). - 결과 저장 위치: 기본값은 출력 파일 경로를 반환합니다.
사용자가 변경을 요청하지 않는 한 시각적 스타일을 그대로 유지하세요. 스타일 값: references/ass-style.md.
실행
하나의 명령으로 모든 것을 실행하고 중단 후 재개합니다:
python3 scripts/pipeline.py all "<url-or-file>" --work ./job [--no-annotate]
또는 단계를 하나씩 실행합니다. 각 단계는 작업 디렉터리에 고정된 파일 이름을 쓰고, 이미 출력이 존재하는 작업은 건너뜁니다. 단계를 다시 실행하려면 --force를 추가하세요. 모든 하위 명령에는 --help가 있습니다.
| 단계 | 생성 파일 | 유료 API |
|---|---|---|
fetch <url-or-file> | src.mp4 | 아니오 |
transcribe [--audio-url URL] | audio.mp3, asr_task.json, transcription.json | 예 |
annotate | annotations.json | 예 |
ass [--no-pop] [--no-annotate] | subs.ass | 아니오 |
render [--segment 1200] [--out FILE] | karaoke.mp4 | 아니오 |
ASR API는 URL에서 오디오를 읽습니다. 기본적으로 transcribe는 job/audio.mp3를 DashScope의 무료 임시 저장소에 업로드합니다. 이 저장소는 파일을 48시간 동안 보관하며, 이 계정의 ASR 모델만 읽을 수 있습니다. 별도의 버킷이나 추가 설정이 필요하지 않습니다. 사용자가 자신의 저장소를 선호하는 경우, .env의 AUDIO_URL_CMD가 파일을 업로드하고 URL을 출력하거나, --audio-url URL을 전달할 수 있습니다.
진행 상황은 stderr로 출력됩니다. 각 단계는 stdout에 출력 파일의 경로를 출력합니다.
종료 코드
| 코드 | 의미 | 조치 |
|---|---|---|
| 0 | 완료 | 계속 진행합니다. |
| 2 | 사용법 오류 | 하위 명령의 --help를 읽으세요. |
| 3 | 환경이 준비되지 않음 | next: 행의 지침을 따르거나 doctor를 실행하세요. 사용자에게 키나 sudo를 요청하거나 리전 설정을 수정하도록 요청하세요. |
| 4 | 원격 서비스 실패 | next: 행의 지침을 따르세요. 동일한 명령을 다시 실행하면 완료된 작업은 유지됩니다. |
| 5 | 이전 단계의 입력 누락 | next: 행에 지정된 단계를 실행하세요. |
| 1 | 예상치 못한 실패 | 오류 위에 있는 도구 출력을 읽으세요. |
장시간 작업
전사(transcription) 및 렌더링(rendering)은 셸 도구가 허용하는 시간보다 오래 걸릴 수 있습니다. 명령을 로그 파일과 함께 백그라운드에서 실행하세요. 예: nohup python3 scripts/pipeline.py all "<src>" --work ./job > job.log 2>&1 &, 그런 다음 로그가 끝날 때까지 읽으세요. 프로세스가 종료되면 동일한 명령을 다시 실행하세요. 전사는 저장된 ASR 작업을 재개하여 추가 비용을 지불하지 않으며, 렌더링은 완료된 세그먼트를 재사용합니다.
전달 전 확인
출력의 중간에서 한 프레임을 추출하고(ffmpeg -ss <seconds> -i job/karaoke.mp4 -frames:v 1 check.jpg), 이미지를 볼 수 있다면 확인하세요. 원본에 이미 하드코딩된 자막이 있는 경우, 사용자에게 알리고 두 가지 옵션을 제시하세요: 블러 밴드로 덮거나, 새 자막을 상단으로 이동합니다.
규칙
DASHSCOPE_API_KEY를 절대 출력, 로그, 커밋하지 마세요.doctor는 설정 여부만 보고합니다.transcribe와annotate는 사용자 계정에 비용이 발생합니다. 사용자가 동의하지 않는 한 이들에--force를 사용하지 마세요.- 주석은 간체 중국어만 지원합니다. 중국어를 읽지 못하는 시청자를 위해
--no-annotate를 사용하세요. - ASR은 이름과 전문 용어를 잘못 인식하거나 소문자 텍스트를 반환할 수 있습니다. 비디오를 공유하기 전에 사용자에게 자막을 검토하라고 알리세요.