Communitygithub.com

zgyk4167/노래방 자막

영어 비디오에 단어별 노래방 스타일 자막을 자동 생성합니다. 각 단어가 발화될 때 흰색에서 초록색으로 변하고 잠시 커지며, 중국어 학습자를 위한 파란색 간체 중국어 주석을 선택적으로 추가할 수 있습니다.

노래방 자막란 무엇인가요?

이 스킬은 사용자가 제공한 영어 비디오 파일 또는 URL(YouTube, X 등 yt-dlp가 지원하는 모든 사이트)을 받아 단어 단위로 동기화된 노래방 스타일 자막을 생성합니다. 파이프라인은 비디오에서 16kHz 오디오를 추출하고, DashScope ASR을 사용하여 단어 타임스탬프가 포함된 전사를 수행한 후, LLM이 어려운 단어, 구동사, 숙어 및 기술 용어를 식별하여 CET-6 수준의 중국어 학습자에게 적합한 간체 중국어 주석을 생성합니다. 최종적으로 ASS 자막 파일을 생성하고 ffmpeg와 libass를 사용하여 비디오에 자막을 입힙니다. Alibaba Cloud Model Studio(DashScope) API 키가 필요하며 별도의 스토리지 버킷은 필요하지 않습니다. 시각적 스타일은 기본 설정을 유지하며, 사용자가 요청할 경우 변경할 수 있습니다. 또한, 배경에서 장시간 실행되는 작업을 지원하고 중단 시 이어서 재개할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add zgyk4167/karaoke-subtitles

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

가라오케 자막

파이프라인: 비디오 → 16kHz 오디오 → DashScope ASR(단어 타임스탬프 포함) → LLM이 용어를 선택하고 중국어 주석 작성 → ASS 가라오케 자막 → ffmpeg 및 libass로 인코딩.

모든 작업은 하나의 비대화형 CLI인 scripts/pipeline.py를 통해 수행됩니다. 이 파일의 경로는 스킬 디렉터리를 기준으로 합니다. 모든 명령은 어떤 디렉터리에서든 스킬 경로를 앞에 추가하여 실행하세요. 예: python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor

첫 실행 전

  1. python3 scripts/pipeline.py doctor를 실행하세요. 종료 코드 0이면 준비 완료입니다. 키가 설정되면, DASHSCOPE_BASE가 해당 키의 리전과 일치하는지 확인하기 위해 무료 요청을 한 번 보냅니다. 아무것도 업로드되거나 청구되지 않습니다. 해당 요청을 건너뛰려면 --offline을 추가하세요.
  2. 종료 코드 3이면 bash scripts/install.sh를 실행하고 출력되는 각 FAIL 행을 수정하세요. 스크립트에서 sudo에 비밀번호가 필요하다고 하거나 API 키가 없다고 하면 중단하고 사용자에게 물어보세요. 사용자에게 키를 채팅에 붙여넣도록 요청하지 말고, .env 파일에 넣도록 하세요(.env.example 참조).
  3. 설정 세부 사항: 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예
annotateannotations.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은 이름과 전문 용어를 잘못 인식하거나 소문자 텍스트를 반환할 수 있습니다. 비디오를 공유하기 전에 사용자에게 자막을 검토하라고 알리세요.

관련 스킬