口诀讲解视频（数学说唱）

구술 설명 동영상 (수학 랩)

하나의 지식 포인트를 약 1분 길이의 설명 동영상으로 만듭니다. 기억에 잘 남는 이유는 세 가지 레이어가 겹쳐져 있고 모두 동일한 오디오 트랙을 따르기 때문입니다:

• 귀: 일정한 비트, 한 행에 한 소절, 끝까지 같은 운율로 부드럽게 이어짐
• 언어: 8–10자의 구절, 2–3번 반복, 화면 상단에 고정
• 눈: 가사가 불러지는 글자에 맞춰 그래픽이 단계별로 움직여 학생이 "왜 맞는지" 볼 수 있음

이야기 구성은 고정되어 있습니다: 문제 제시 → 함정 설정 (어리석은 방법은 혼란을 줌) → 구절 제공 → 시연 → 원리 설명 → 마무리.

역할 분담: 누가 무엇을 제공하는가

부분	담당자	설명
구절, 가사, 스토리보드	당신(AI) 이 작성, 사용자 확인	규칙은 references/lyrics.md 참조
오디오 (보컬 + 음악)	사용자 또는 고객이 직접 제공	어떤 모델, 누구의 목소리를 사용할지는 그들이 결정합니다. references/audio.md의 "고객에게 보낼 요구사항"을 그들에게 전달하세요. 이 스킬은 사용자를 대신해 플랫폼을 선택하거나 기본적으로 비용을 지불하여 생성하지 않습니다.
자막 시간	스크립트가 계산	어떤 도구로 내보낸 SRT든 사용 가능, 오타가 있어도 괜찮습니다.
배경 화면	자료 라이브러리가 자동 선택	assets/backgrounds/에 용도별로 태그가 지정되어 있습니다. 직접 추가할 수 있습니다.
그래픽, 구절, 수식, 자막	스크립트가 프레임별로 그림	당신은 이 주제에 대한 storyboard.json과 graphics.py만 작성하면 됩니다.

환경

처음 사용하기 전에 먼저 자체 점검을 실행하세요. 무엇이 부족하고 어떻게 설치하는지 항목별로 알려줍니다:

python $SKILL/scripts/check_env.py

필요한 것: Python 3.10+ (pip install pillow numpy librosa pypinyin), ffmpeg / ffprobe, 중국어 굵은 글꼴 (일반 시스템에 내장된 것은 자동으로 찾음), 배경 자료 라이브러리. 자료 라이브러리는 다음 순서로 찾습니다: 환경 변수 MATH_RAP_LIBRARY → 이 스킬의 assets/backgrounds/ → 공유 위치 ~/.math-rap-video/backgrounds/. 자료 라이브러리가 없으면 python $SKILL/scripts/install.py --library <라이브러리_압축파일.zip>을 실행하세요.

아래에서 $SKILL은 이 스킬이 있는 디렉토리(이 SKILL.md 파일이 있는 폴더)를 가리킵니다. 미리 정의된 환경 변수가 아닙니다: 명령을 실행할 때 실제 경로로 바꾸거나, 미리 설정하세요 (bash: export SKILL="/경로/math-rap-video"; PowerShell: $SKILL="C:\경로\math-rap-video"). 경로에 공백이나 한글이 있으면 따옴표를 추가하세요. 모든 스크립트는 일반 명령줄 프로그램이며 (--help 지원), 명령을 실행할 수 있는 모든 AI 또는 사람이 사용할 수 있으며 특정 도구에 의존하지 않습니다.

프로세스

1 가사와 스토리보드 작성 ──→ 2 사용자 오디오 제출 ──→ 3 prepare_audio 시간 계산 및 검증
                                        │
4 storyboard.json + graphics.py 작성 ←────┘
        │
5 확인 + 미리보기 이미지 (확인 후) ──→ 6 build_video 동영상 생성 ──→ 7 확인 및 전달

각 단계가 끝나면 결과를 간단히 사용자에게 알립니다. 1단계와 5단계는 사용자 확인 후 진행합니다.

사용자가 완성된 가사와 오디오를 가지고 올 때 (가사는 확정, 오디오는 그에 맞춰 제작됨): 가사는 한 글자도 변경하지 마세요. 그렇지 않으면 화면과 노래 가사가 일치하지 않습니다. 1단계에서는 세 가지만 수행합니다: 새 프로젝트 생성, 가사를 그대로 lyrics.md에 넣기, 마지막에 스토리보드 표 추가; check_lyrics.py의 결과는 참고용일 뿐이며 이에 따라 가사를 변경하지 않습니다. 그런 다음 3단계부터 바로 진행합니다.

1. 새 프로젝트 생성, 구절, 가사, 스토리보드 표 작성

python $SKILL/scripts/new_project.py <프로젝트_디렉토리>          # 예제(선분 세기)를 복사하여 시작점으로
python $SKILL/scripts/new_project.py <프로젝트_디렉토리> --blank  # 또는 빈 템플릿에서 시작

references/lyrics.md에 따라 lyrics.md를 작성합니다: 한 줄 = 한 소절, 각 줄 11–15자 (원리 부분은 9–11자), 끝까지 같은 운율; 구조는 Verse 1 (14줄) + Hook (2줄, 구절만 부름) + Verse 2 (8줄).

스토리보드 표는 lyrics.md 마지막의 ## 스토리보드 섹션에 작성합니다 (표: 줄 번호, 화면 동작, 어떤 글자가 트리거되는지). 이것은 사용자 확인용이며 4단계 코드 작성의 기초입니다; 스크립트는 이것을 읽지 않습니다.

작성 후 가사 검사를 실행하고, "반드시 수정"해야 할 사항은 모두 수정하고, "권장" 사항은 하나씩 검토합니다:

python $SKILL/scripts/check_lyrics.py <프로젝트_디렉토리>     # 구조, 각 줄 글자 수, 운율, 듣기 쉬운 오류

예제의 모든 숫자를 직접 검증하세요 (스크립트는 수학을 확인할 수 없습니다). 그런 다음 구절, 가사, 스토리보드 표를 사용자에게 확인받습니다.

2. 사용자 오디오 제공

확인된 가사와 references/audio.md의 "고객에게 보낼 요구사항"을 사용자에게 전달합니다. 그들은 어떤 방식으로든 오디오를 제작할 수 있습니다: AI 음악 플랫폼, 실제 랩, TTS 또는 실제 더빙 + 반주. 돌려받는 것은:

• 하나 이상의 오디오 파일 (mp3 / wav), 보컬 포함. AI 생성의 경우 2–3 버전을 제공하는 것이 좋습니다.
• 가급적 자막 파일 (SRT)도 함께 제공. 없는 경우, 어떤 음성 인식 도구를 사용하여 오디오를 인식하고 SRT로 내보냅니다.

만약 사용자가 명시적으로 당신이 노래를 생성해 주길 요청하고 ElevenLabs API 키를 제공했다면, scripts/gen_music.py를 사용할 수 있습니다 (사용법은 references/audio.md 참조). 이는 선택 사항이며, 각 버전은 사용자의 크레딧을 소모하므로 생성 전에 설명해야 합니다.

3. 오디오 처리: 시간 계산 및 이 버전 사용 가능 여부 판단

python $SKILL/scripts/prepare_audio.py <프로젝트_디렉토리> --audio 노래.mp3 --srt 인식.srt --bpm 90 --intro-bars 2

이 스크립트는 인식 결과를 가사에 글자 단위로 매핑하고 (오타나 구분점이 달라도 괜찮음), 속도와 비트를 감지하여 timing.json을 작성하고 오디오를 프로젝트 디렉토리에 복사합니다 (동영상 생성 시 여기서 읽으므로 프로젝트 디렉토리에 오디오 파일이 추가되는 것은 정상입니다). 마지막 줄에 결론을 제공합니다:

• 사용 가능: 계속 진행합니다. "매칭률 낮음" 문장이 있으면 기록해 두고, 전달 시 사용자에게 해당 문장을 들어보라고 알립니다.
• 다른 버전 권장 (종료 코드 3): 이유를 나열합니다. 일반적인 원인은 특정 문장을 빠뜨림, 보컬 진입 지연, 전체적으로 압축됨 등입니다. 다른 오디오 버전을 사용하고 억지로 사용하지 마세요.

여러 버전의 오디오가 있는 경우, 각 버전을 다른 파일로 저장한 후 비교하고, 선택한 버전을 timing.json으로 복사합니다:

python $SKILL/scripts/prepare_audio.py <프로젝트_디렉토리> --audio 생성_01.mp3 --srt 01.srt --bpm 90 --intro-bars 2 --out timing_01.json
python $SKILL/scripts/prepare_audio.py <프로젝트_디렉토리> --audio 생성_02.mp3 --srt 02.srt --bpm 90 --intro-bars 2 --out timing_02.json
cp <프로젝트_디렉토리>/timing_02.json <프로젝트_디렉토리>/timing.json

선택 방법은 references/audio.md 3절 참조. 간단히 말하면: 먼저 "다른 버전 권장" 항목을 제외한 후, 구절 두 줄의 매칭률이 가장 높은 버전을 선택하고, 마지막으로 리듬의 규칙성을 확인합니다. 두 가지가 충돌할 경우 구절 명확성이 리듬 규칙성보다 우선합니다: 시청자는 구절을 기억합니다.

기타 상황: 순수 해설 더빙, 비트가 없는 오디오는 --no-beat 추가; SRT가 없을 때의 대안은 --grid --entry <보컬_진입_시간(초)>로, 한 줄을 한 소절로 추정합니다; --intro-bars는 고객과 합의된 인트로 소절 수를 씁니다 (위 예시의 2는 고객에게 주는 기본 요구사항), 합의된 적이 없으면 쓰지 마세요. Windows PowerShell에서 cp도 사용 가능; cmd에서는 copy를 사용하세요.

오디오 변경은 이 단계만 다시 실행하면 되며, 스토리보드를 수정할 필요가 없습니다.

4. 스토리보드 및 주제 그래픽 작성

references/visuals.md를 읽은 후, 프로젝트 디렉토리의 두 파일을 수정합니다:

• storyboard.json: 구절 배너, 수식, 글자 팝업, 화살표, 배경 전환 계획
• graphics.py: 이 주제 전용 그래픽, setup(ctx) 및 draw(canvas, t, ctx) 구현

가장 중요한 규칙: 시간은 항상 가사에 대한 상대 표현식으로 작성하고, 절대 초 단위로 하드코딩하지 마십시오.

표기법	의미
L(6) / E(6)	6번째 줄의 시작 / 끝
W(9,'사') / W(9,'사',2)	9번째 줄에서 '사' 글자 (두 번째 '사')가 불려지는 시간
B, L(6)+2*B	한 박자; 6번째 줄 시작 후 2박자

이렇게 하면 화면이 실제로 가사에 맞춰지고, 고객이 오디오 버전을 변경해도 3단계만 다시 실행하면 바로 동영상을 생성할 수 있습니다.

그래픽은 가장 시간이 많이 걸리는 단계입니다. 엔진은 이미 일반적인 그림 방법(점, 선, 호, 부채꼴 각도, 직각 기호, 숫자 블록, 괄호선, 한 줄 여러 색상 수식, 전체 회전 및 평행 이동, 경로 따라 이동, 등간격 배치)을 제공하므로, 먼저 references/visuals.md 4절에서 기성품을 찾고 처음부터 만들지 마세요. 작은 부분을 작성할 때마다 이미지를 확인하고 (다음 단계 참조), 전체를 다 작성한 후에 확인하지 마세요.

실제 테스트에서 가장 흔한 두 가지 문제점은 작성 시부터 피해야 합니다:

• 그래픽이 너무 작고 얇게 그려집니다. 이것은 휴대폰에서 보기 위한 것입니다: 주요 그래픽은 화면 너비의 절반 이상을 차지해야 합니다 (너비 ≥ 800 또는 높이 ≥ 400), 한 줄의 요소는 ctx.spread(n)로 너비를 채우고, 선 너비 ≥ 9, 글꼴 크기 ≥ 44. 크기 참조는 references/visuals.md 1절 참조.
• 모든 줄마다 화면 동작이 있어야 합니다. 그래픽, 팝업 텍스트, 수식 중 적어도 하나는 화면 중앙에 있어야 하며, 어떤 줄도 배경과 자막만으로 남아서는 안 됩니다.

5. 확인 및 미리보기

python $SKILL/scripts/overlay_engine.py <프로젝트_디렉토리> check          # 필수: 스토리보드 문제 0개, 렌더링 오류 0개; "레이아웃 주의" 항목은 하나씩 확인
python $SKILL/scripts/overlay_engine.py <프로젝트_디렉토리> sheet          # 스토리보드 미리보기.jpg: 줄별 개요
python $SKILL/scripts/overlay_engine.py <프로젝트_디렉토리> sheet --pages  # 추가: 스토리보드 미리보기_p1.jpg…: 큰 이미지 페이지네이션, 텍스트가 가장자리에 닿는지 확인 (개요 이미지도 함께 업데이트됨)
python $SKILL/scripts/overlay_engine.py <프로젝트_디렉토리> frames "L(18)" "L(19)" 0.2   # 스토리보드 프레임별.jpg: 애니메이션 구간을 프레임별로 펼쳐서 보여줌

직접 이미지를 열어서 프레임별로 스토리보드 표와 대조하세요:

• 개요 이미지: 각 줄에 표시되어야 할 것들이 나타나는지, 빈 칸이 없는지 확인
• 큰 이미지 페이지네이션: 텍스트가 서로 겹치지 않는지, 구절 배너나 자막에 닿지 않는지, 그래픽이 충분히 굵고 큰지 확인
• 이동, 회전, 등장이 있는 곳은 frames를 사용하여 도중에 다른 것과 충돌하는지 확인
• check의 "레이아웃 주의"가 지적한 시점을 하나씩 살펴보세요 (배너에 닿음, 자막에 눌림, 수식과 겹침, 가장자리에 닿음, 그래픽이 너무 작음, 화면 중앙이 비어 있음, 텍스트가 서로 겹침 등을 보고함)
• check가 찾지 못하는 것: 선이나 색상 블록 위의 텍스트가 흐려서 보이지 않음, 그래픽 수량이 잘못 그려짐, 색상이 충분히 눈에 띄지 않음. 이것들은 큰 이미지를 통해서만 발견할 수 있습니다.

문제가 있으면 4단계로 돌아가 수정하고 다시 확인합니다. 문제가 없으면 개요 이미지를 사용자에게 보여주고 확인을 받은 후 동영상을 생성합니다.

6. 동영상 생성

python $SKILL/scripts/build_video.py <프로젝트_디렉토리> bg            # 배경 선택 및 연결, 각 구간에 사용된 자료 출력
python $SKILL/scripts/build_video.py <프로젝트_디렉토리> final 20 30   # 선택 사항: 먼저 10초 구간 생성하여 효과 확인
python $SKILL/scripts/build_video.py <프로젝트_디렉토리> final         # 전체 동영상, 약 6–12분 소요 (컴퓨터 성능에 따라 다름), 백그라운드 실행
python $SKILL/scripts/build_video.py <프로젝트_디렉토리> sheet         # 완성_개요.jpg
python $SKILL/scripts/make_vertical.py <프로젝트_디렉토리> --title "제목"   # 선택 사항: 세로 버전 (틱톡, 쾌수, 비디오 계정)

bg는 각 구간 중간에 주제 그래픽이 있는지 자동으로 판단하고, 있는 경우 "조용한" 구간(밝은 얼굴 특성이 없는)만 선택하여 출력 목록에 명시합니다. 미리보기를 모두 확인한 후 build_video.py <프로젝트_디렉토리> all 명령 하나로 check + bg + final + 개요 이미지를 한 번에 실행할 수도 있습니다. 세로 버전은 가로 동영상을 1080×1920 화면 중앙에 배치하고, 위쪽에 제목, 아래쪽에 작은 글씨를 추가하고 배경은 흐릿하게 확대된 이미지로 채웁니다; 그래픽을 세로로 재배치하지는 않습니다. 세로 제목에 --title을 지정하지 않으면 storyboard.json의 vertical.title 값을 읽고, 없으면 가사 파일의 제목을 사용합니다.

7. 확인 및 전달

완성_개요.jpg를 확인합니다: 배경이 충분히 어두운지, 그래픽과 텍스트가 선명한지, 배경의 밝은 얼굴이 팝업 텍스트나 설명 텍스트 뒤에 오지 않는지 (있는 경우 배경 계획에서 해당 줄에 :quiet를 추가하거나 특정 클립을 지정하고 bg와 final을 다시 실행). 그런 다음 완성.mp4를 사용자에게 전달하고 다음 사항을 설명합니다:

• 화면과 시간은 스크립트로 검증되었지만, 사운드는 사람이 들어야 합니다: 구절이 나타나고 결과 숫자가 나올 때 가사와 정확히 일치하는지 중점적으로 확인해 주세요.
• 3단계에서 매칭률이 낮았던 문장은 특별히 들어보세요.

참고 파일

파일	언제 읽는가
references/lyrics.md	구절, 가사, 스토리보드 표 작성 전
references/audio.md	사용자가 "음악/더빙에 무엇을 사용하나요?"라고 물을 때; 오디오 요구사항을 고객에게 보내야 할 때; 오디오 검수 및 선택 시
references/visuals.md	storyboard.json 및 graphics.py 작성 전 (레이아웃, 필드, 그리기 도구, 일반적인 문제 유형 그리기 방법)
references/library.md	자료 라이브러리에 클립을 추가하거나, 새 배경을 생성하거나, 배경 선택이 적절하지 않을 때
references/troubleshooting.md	어떤 단계에서 오류가 발생하거나 결과가 예상과 다를 때
references/teaching.md	사용자가 원리를 이해하거나, 다른 사람에게 가르치거나, 코드를 작성하지 않으려 할 때 (CapCut 방식)
references/compatibility.md	사용자가 "다른 AI / 다른 모델로도 가능한가요?"라고 물을 때; 스킬을 다른 사람에게 전달할 때
examples/shuxianduan/	완전한 예제: 가사, 스토리보드, 그래픽. 새 문제를 작성하기 전에 먼저 살펴보기

스크립트 목록

스크립트	역할
check_env.py	환경 자체 점검
new_project.py	새 프로젝트 디렉토리 생성
check_lyrics.py	가사 검사
prepare_audio.py	오디오 + 자막 → timing.json, 사용 가능 / 다른 버전 권장 결론 제공
overlay_engine.py	검사, 미리보기, 오버레이 레이어 렌더링
build_video.py	배경 선택, 최종 동영상 합성, 개요 이미지 생성
make_vertical.py	가로 동영상 → 세로 버전
library_tool.py	배경 자료 라이브러리 관리 (추가, 삭제, 태그 수정, 개요 이미지 생성)
gen_music.py	선택 사항: ElevenLabs로 노래 생성
install.py	이 스킬을 다른 AI 도구(Codex, Gemini CLI, opencode 등)에 설치하고 자료 라이브러리 배치
chat_pack.py	채팅 전용 AI를 위한 프롬프트 팩 생성 (가사 작성 / 화면 작성 / 검사 결과에 따른 수정)