reel-subs — 릴 자막 및 애니메이션
편집이 완료된 토킹헷 컷(CapCut / Premiere / 폰에서 내보내기)을 가져와 구문별 자막과 깔끔한 모션 그래픽이 포함된 릴로 만듭니다. 모든 작업은 사용자 컴퓨터에서 로컬로 실행됩니다.
작동 방식: 음성 → 시간 정보가 포함된 단어(sherpa-onnx, 오프라인) → 사용자가 edit.json 작성(자막 + 그래픽 항목) → Remotion이 투명 그래픽 레이어만 렌더링 → ffmpeg가 원본 위에 원본의 색상 태그를 유지한 채 합성합니다. Remotion으로 전체 영상을 렌더링하지 마세요: 그러면 색상 매트릭스가 달라져 피부 톤이 변합니다.
SKILL_DIR 아래 = 이 파일이 있는 폴더. ENGINE = ~/.reel-subs/engine
(Windows의 경우 %USERPROFILE%\.reel-subs\engine; $REELS_HOME/engine 환경 변수가 설정된 경우 해당 경로).
모든 스크립트는 일반 Node 스크립트입니다 — node로 실행하며 macOS, Windows, Linux에서 동일하게 작동합니다.
사용자의 언어로 대화하세요. 이 파일은 영어로 작성되어 있지만, 사용자가 작성하는 언어(보통 러시아어)로 진행 상황, 질문, 오류, 최종 요약을 답변하세요. 명령어, 경로, JSON 키는 그대로 유지합니다.
먼저 사용자 선호도를 읽으세요. ~/.reel-subs/preferences.md 파일이 있으면(또는 $REELS_HOME/preferences.md), 1단계 전에 읽고 따르세요: 이 파일에는 이전 세션에서 사용자가 요청한 내용이 저장되어 있으며 이 파일의 기본값을 재정의합니다. 아래 "사용자 취향 학습" 참조.
0. 설정 (처음 사용 시, 또는 doctor가 NOT READY를 출력할 때)
node SKILL_DIR/scripts/setup.mjs # 러시아어 음성 모델 (기본값)
node SKILL_DIR/scripts/setup.mjs --lang multi # 영어 + 24개 유럽어
Node.js 18+만 있으면 됩니다. node가 없으면 nodejs.org에서 LTS를 설치하라고 알리고 중단하세요(macOS: brew install node도 가능; Windows: winget install OpenJS.NodeJS.LTS).
설치는 ENGINE 경로에 엔진을 복사하고, npm install(Remotion, ffmpeg/ffprobe 바이너리, sherpa-onnx)을 실행하며, 음성 모델(~170 MB ru / ~490 MB multi)과 헤드리스 Chrome을 다운로드합니다. 멱등성(idempotent)을 보장합니다. 처음에는 2-5분 정도 걸립니다 — 한 줄로 알려주세요. READY로 종료됩니다.
✗ headless browser가 출력되면: Remotion의 Chrome 다운로드가 네트워크에서 차단되었고 설치된 Chrome/Edge가 없는 경우입니다 → 사용자에게 Google Chrome을 설치한 후 다시 실행하도록 요청하세요.
1. 준비
node ENGINE/scripts/prepare.mjs "<video>" [--lang ru|multi] [--audio clean_voice.wav]
--lang:ru(GigaAM, 러시아어에 최적) 또는multi(영어, 독일어, 스페인어, 프랑스어, 우크라이나어 등). 영상에서 사용된 언어에 따라 선택하며, 명확하지 않은 경우에만 질문하세요. 누락된 모델은 자동으로 다운로드됩니다.--audio: 사용자가 깨끗한 음성 트랙(Auphonic, Adobe Podcast 등)을 가지고 있으면 사용하세요 — 인식률이 좋아지며, 렌더링 시 최종 영상에 적용됩니다.- 영상 옆에
<video name>.reels/폴더를 생성합니다:transcript.txt,words.json,edit.json(초안). - HDR 영상이면 설명과 함께 중단됩니다(HDR에 오버레이하면 색상이 변함) — 사용자에게 전달하세요.
2. 영상 이해하기
transcript.txt(시간 코드가 포함된 구문)를 읽고words.json에서 정확한 단어 시간을 훑어봅니다.- 프레임을 확인합니다:
node ENGINE/scripts/look.mjs "<video>" --every 1→ 시트 이미지를 엽니다. 얼굴 위치(위/중간), 손 제스처 위치, 화면/제품이 표시된 위치, 컷 편집 위치를 확인하세요. 긴 영상의 경우 부분적으로 시트를 만듭니다(--from 0 --to 30).
3. 자막 수정 (edit.json → captions)
초안 페이지는 이미 구문별로 나뉘어 있습니다(~2초, 최대 32자). 당신의 임무:
- 인식 오류 수정: 제품명, 영어 용어, 숫자(
четыре бакса→$4), 브랜드 철자. 인식에는 구두점이 없습니다 — 읽는 데 도움이 되는 것만 추가하며, 대부분 추가하지 않습니다. - 화자의 실제 단어와 언어를 유지하세요. 요청받지 않는 한 번역하지 마세요.
- 각 페이지가 하나의 자연스러운 구문이 되도록 병합/분할하세요.
startMs/endMs가words.json과 일치하도록 유지하세요. - 자막 텍스트 내 마크업:
*word*→ 강조 색상(드물게, 핵심 단어에만),~word~→ 빨간색(화자가 농담하는 말실수). - 확실하지 않은 단어는 최종 메시지에 목록으로 남기고 조용히 추측하지 마세요.
4. 그래픽 계획 (edit.json → items)
전체 필드 참조와 예시: SKILL_DIR/reference/edit-schema.md — 아이템을 작성하기 전에 읽으세요.
- hook — 처음 2-4초, 첫 번째 컷 또는 농구까지: 영상의 핵심을 화자의 언어로 한 줄로 짧게. hook이 표시되는 동안 자막은 자동으로 숨겨집니다.
- card — 핵심 포인트:
label(작은 대문자) +title및/또는 설명하는 단어(at)에 나타나는chips, 결과 칩의 경우on: true, 무언가를 지우는 경우strikeAt. - big — 화자가 강조하는 숫자 또는 한 단어 ("$1", "5000").
- terminal — 코드, 에이전트, 명령어에 대해 이야기할 때만.
- punch — 농담/자조:
a는 취소선,b는 크게 표시됩니다. 자막은 자동으로 숨겨집니다. - pop — 손 제스처 옆에 스냅인 되는 작은 HUD 위젯 ("그리고 이 애니메이션들은…"). 단어보다 약 0.3초 전에 배치하세요: 인식된 타이밍이 지연됩니다.
- badge — 왼쪽 상단에 지속적으로 표시되는 태그(에피소드 번호 등), 사용자가 원하는 경우에만.
규칙:
- 절대 얼굴을 가리지 마세요. 카드는 기본적으로 상단 1/3 지점(
top: 260)에 배치됩니다. 얼굴이 프레임 상단 절반에 있으면top: 1110(하단)을 사용하세요. 또한 화자가 가리키는 것을 가리지 마세요. - 모든 것은 안전 영역 안에 유지됩니다(카드는 840px 너비, 중앙 정렬) — 가장자리로 이동하지 마세요.
- 밀도: 평균 5-10초당 하나의 그래픽, 단어에 맞춰 타이밍 설정. 말한 내용을 반복하는 상자형 자막 금지, 명백한 설명 금지, 튀거나 유치한 움직임 금지.
- 제품/프로젝트의 첫 언급: 카드에 몇 단어로 설명하세요 — 시청자는 처음 보는 사람입니다.
- 시간은 원본 영상의 초 단위입니다. 아이템은 자막과 겹칠 수 있습니다. hook/punch는 자막을 숨깁니다.
- 사실을 지어내지 마세요: 칩과 카드는 화자가 말한 내용을 정확히 표시합니다.
5. 미리보기 — 항상 전체 렌더링 전에 확인
node ENGINE/scripts/preview.mjs "<work>/edit.json" # 모든 아이템 내부의 한 프레임
node ENGINE/scripts/preview.mjs "<work>/edit.json" --at 1.2,7,15
previews/sheet.jpg(그리고 필요한 경우 단일 at_<t>.jpg)를 엽니다. 확인할 사항: 얼굴이 명확하게 보이는지, 텍스트가 잘 맞는지, 가장자리에 닿는 것이 없는지, 자막을 읽을 수 있는지. edit.json을 수정하고 다시 미리보기하세요. 실행당 ~10-30초.
6. 렌더링
node ENGINE/scripts/render.mjs "<work>/edit.json" [--out file.mp4]
영상 1분당 ~1-4분. 출력 파일은 기본적으로 원본 옆에 <video name>_final.mp4로 저장됩니다. 출력 프레임 수와 원본 프레임 수를 출력하며, 불일치 시 MISMATCH라고 알립니다.
그런 다음 사용자에게: 출력 경로, 추가한 내용에 대한 2-3줄 요약, 의심스러운 단어를 알려주세요.
수정
edit.json 수정 → 변경된 부분 미리보기 → 다시 렌더링. 사용자가 자막을 승인한 후에는 prepare.mjs --force를 다시 실행하지 마세요(자막이 초기화됩니다). 큰 변경 전에는 edit.json을 복사하세요.
사용자 취향 학습
이 스킬은 사용할수록 더 나아져야 합니다. 사용자의 메모는 ~/.reel-subs/preferences.md($REELS_HOME/preferences.md가 설정된 경우)에 저장됩니다 — 스킬 폴더와 ENGINE 외부에 있어 스킬 업데이트나 재설정 시 절대 지워지지 않습니다.
저장 제안 시점:
- 사용자가 같은 종류의 것을 두 번 수정하는 경우(글꼴, 색상, 자막 크기나 위치, 그래픽 양, 후크 문구, 강조할 단어 등).
- 사용자가 «запомни», «в следующий раз делай так», «мне так больше нравится»와 같이 말하는 경우.
- 수정이 포함된 세션 종료 시: 수정 사항을 2-4줄로 요약하고 다음에 저장할지 한 번 묻습니다.
방법:
- 항상 먼저 물어보고, 정확히 무엇을 쓸지 보여주고, 승인 후에만 저장하세요. 절대 혼자 저장하지 마세요.
- 기록이 아닌 규칙을 저장하세요: «자막 크기 크게: captionSize 60», «후크에 이모지 없음», «10초에 플래시 하나 이하». 짧은 제목(Style, Captions, Graphics, Wording)으로 그룹화하세요. 기존 규칙과 모순되는 규칙을 추가하는 대신 업데이트하거나 제거하세요.
edit.json→style이 지원하는 스타일 값은 정확한 값으로 저장하여 새edit.json에 복사할 수 있도록 하세요.- 변경 사항이 코드 변경을 필요로 하는 경우(새 글꼴, 새 애니메이션, 다른 카드 모양),
ENGINE/src/에서 수정하고preferences.md의 Engine changes 섹션에 기록하세요: 어떤 파일, 무엇이 변경되었는지, 이유. setup은 엔진을 다시 복사하고 편집된 파일을 덮어씁니다(새 파일은 유지됨). 따라서 setup 실행 후 이 목록을 확인하고 누락된 부분을 다시 적용하세요. - 사용자는
preferences.md를 직접 편집하거나 변경할 내용을 말로 알려줄 수도 있습니다.
커스터마이징
- 색상 / 크기:
edit.json→style(accent,captionSize,captionTop,font). - 새로운 그래픽 종류:
ENGINE/src/components/에 컴포넌트 추가,src/types.ts에 타입 추가,src/Overlay.tsx에 case 추가 — 다음 미리보기 시 번들이 자동으로 재빌드됩니다. 레이어를 투명하게 유지하세요(Remotion 내부에 배경이나 비디오 없음). npm run studio를ENGINE내부에서 실행하면 Remotion Studio가 열려 실시간 조정이 가능합니다.
문제 해결
doctor:node ENGINE/scripts/doctor.mjs— 모든 의존성에 대해 ✓/✗를 출력합니다.- 가변 프레임 속도 경고 → 사용자에게 고정 30 또는 60 fps로 내보내도록 요청하세요.
- 9:16 비율이 아닌 경우 → 그래픽은 수직 영상용으로 설계되었습니다. 비율에 맞게 조정되지만, 사용자에게 알리세요.
- Windows: 동일한 명령어를 사용하며, 공백이 있는 경로는 따옴표로 감싸세요. PowerShell과 cmd 모두 작동합니다.
- 어떤 것도 업로드되지 않습니다: 모델과 Chrome은 한 번 다운로드되면 이후에는 완전히 오프라인으로 실행됩니다.