Communitygithub.com

가사 비디오

오디오 파일, 커버 이미지, (선택 사항) 일반 텍스트 가사를 입력하면 SRT 파일 없이도 자동으로 자막 타이밍을 생성하여 완성된 가사 비디오를 만듭니다. 오프라인 음성 인식과 오타에 강한 퍼지 정렬을 사용합니다.

가사 비디오란 무엇인가요?

이 스킬은 사용자가 제공한 오디오, 커버 이미지, 그리고 선택적인 가사 텍스트를 바탕으로 완성된 MP4 가사 비디오를 생성합니다. 사용자는 SRT 자막 파일을 제공할 필요가 없으며, `auto_srt.py` 스크립트가 오디오를 분석하여 Vosk 오프라인 음성 인식 엔진으로 음성을 텍스트로 변환한 후, 사용자가 제공한 가사와 퍼지 매칭(fuzzy matching)으로 정렬하여 SRT 파일을 자동 생성합니다. 두 가지 비주얼 스타일을 지원합니다: Spotify 스타일(흐릿한 커버 배경, 앨범 카드, 진행 막대)과 시네마틱 스타일(전체 화면 배경, 2.35:1 레터박스, 힌디어 폰트 Kalam, 단어별 하이라이트). 오타는 노멀라이제이션과 퍼지 비율 매칭을 통해 처리되며, 일치하지 않는 단어는 이웃 단어 사이에 보간됩니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 에이전트 환경에서 사용자를 대신하여 명령어를 실행하고, 결과물을 확인한 후 전달합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CyberGaurav404/lyric-video-skill/tree/HEAD

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

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

문서

가사 비디오 스킬

사용자가 제공하는 입력: 오디오 파일, 커버 이미지, 가사(일반 텍스트, 선택 사항). 당신이 제공하는 결과: 완성된 .mp4 파일 하나. 사용자는 SRT 파일을 제공할 필요가 전혀 없습니다. auto_srt.py가 오디오로부터 SRT를 자동 생성합니다.

실행 방법

pip install pillow imageio-ffmpeg vosk          # ffmpeg는 imageio-ffmpeg에 포함되어 있습니다

python scripts/make_video.py \
    --audio song.mp3 --cover cover.png --lyrics lyrics.txt \
    --title "노래 제목" --artist "가수 이름" \
    --style spotify --out lyric_video.mp4

이 단일 명령어가 하는 일: 음성 인식 → 사용자 가사 정렬 → SRT 파일 작성 → 비디오를 청크 단위로 렌더링 → 연결(concatenate) → lyric_video.mp4 파일 생성.

  • --style spotify (기본값) — 흐릿한 커버 배경, 앨범 카드, 진행 막대, 부드럽게 스크롤되는 가사.
  • --style cinematic — 전체 화면 배경 (--bg plate.png 옵션 전달, 또는 자동 생성됨), 2.35:1 레터박스, Kalam 폰트, 단어별 하이라이트.
  • --start 9.6 --duration 20 — 티저 클립.
  • 커버 이미지가 없으면? 제목으로부터 생성됩니다. 가사가 없으면? ASR(음성 인식) 텍스트가 사용됩니다.

입력과 누락 시 처리 방법

입력설명누락 시
오디오mp3 / m4a / wav필수 — 사용자에게 요청하세요
커버 이미지정사각형, 1000×1000 이상절차적으로 생성됨; 또는 Figma에서 직접 제작 (generate_image, PROMPTS.md 참고)
가사 텍스트일반 텍스트, 한 줄에 한 줄의 가사ASR 텍스트 사용, 타이밍은 자동 생성
제목 / 가수 이름텍스트커버 이미지에서 추론하거나 일반 텍스트로 남김
언어--lang hi (기본값) 또는 en가사 스크립트에서 선택

오타는 예상되며 처리됩니다: 양쪽 문자열이 정규화(구두점, nukta, 대소문자)되고 단어는 퍼지 비율로 매칭되므로 "कोलम्बस" 대 "कोलंबस" 또는 "आईंस्टीन" 대 "आइंस्टाइन"도 정렬됩니다. 매칭되지 않는 단어는 인접 단어 사이에 보간됩니다.

파이프라인 (스크립트가 수행하는 작업)

  1. auto_srt.py — 오디오를 16kHz PCM으로 디코딩하고, Vosk를 실행(오프라인, 약 40~80MB 모델 한 번 다운로드)하며, 선택적으로 사용자의 가사 줄을 문법(grammar)으로 사용하여 디코딩을 제약하고, difflib + 퍼지 매칭으로 정렬한 후 각 가사 줄당 하나의 SRT 큐(cue)를 작성합니다.
  2. spotify_lyrics.py / motivational_render.py — Pillow로 프레임을 렌더링하고, 원시 프레임을 ffmpeg로 파이프합니다.
  3. make_video.py — 렌더링을 청크 단위로 처리(기본 45초 청크, 메모리 2GB 미만 유지), ffmpeg -f concat -c copy로 연결합니다.

품질 기준

  • 연속적인 움직임, 절대 끊기지 않음: 카메라/스크롤을 프레임별로 보간합니다.
  • 활성 라인은 더 크고 밝게; 주변 라인은 단계별로 작아지고 어두워집니다.
  • 긴 줄은 안전한 너비로 자동 축소; 텍스트가 프레임 가장자리에서 잘리지 않도록 합니다.
  • 스크립트에 맞는 올바른 폰트: 데바나가리(Devanagari) 줄은 데바나가리 폰트(assets/fonts/에 포함됨)가 필요하고, 라틴(Latin) 줄은 라틴 폰트가 필요합니다. 절대 하나의 문자열에 섞지 마십시오.
  • 한 프레임에 하나의 아이디어: 배경이 움직이거나 텍스트가 움직여야 하며, 둘 다 동시에 움직이면 안 됩니다.

전달 전 확인사항

ffmpeg -ss 12 -i out.mp4 -frames:v 1 check.jpg   # 2~3 지점 확인

확인할 사항: 잘린 줄 없음, 하나의 활성 라인, 토분(상자) 없음(글꼴 문제), 진행 시간 정확, 오디오 동기화, 막대/그레이드 일관성.

문제 해결

증상원인해결 방법
텍스트 대신 상자(□) 표시스크립트에 맞지 않는 폰트font_for(text, …) 사용; 데바나가리 폰트는 assets/fonts/에 있음
mkl_malloc: failed to allocate memory2GB RAM + 큰 모델/오디오여기서 사용하는 Vosk는 이 문제를 피함; whisper를 사용하는 경우 8~10초로 청크 분할
ffmpeg Cannot allocate memory너무 많은 프레임이 처리 중--chunk 40, -threads 2, rc-lookahead=4 옵션 사용
시간이 지남에 따라 가사가 어긋남긴 악기 간주 구간에서 정렬 실패--lyrics 옵션 전달; 텍스트 한 줄에 가사 한 줄 유지
배경이 튀어 오름사전 렌더링된 키프레임이 교체되고 혼합되지 않음포함된 렌더러는 혼합/보간 처리함

관련 스킬