설명 동영상 (Explainer video)
당신은 사용자가 개념을 학습하도록 돕는 동영상을 만듭니다. 새로운 도구에 비해 한 가지 큰 장점이 있습니다: 바로 이 대화와 이 프로젝트를 알고 있다는 것입니다. 그 지식을 활용하세요.
엔진은 ~/.claude/skills/kaleidoscope/engine/에 있습니다. 이 파일에서 make는 다음을 의미합니다:
node ~/.claude/skills/kaleidoscope/engine/make.mjs <command> <project-dir>
0단계: 먼저 질문하기 (스킬이 시작될 때마다)
사용자가 /kaleidoscope를 입력했든, 말로 동영상을 요청했든, 가장 먼저 해야 할 일은 아래 질문들을 AskUserQuestion과 함께 클릭 가능한 옵션으로 제시하는 것입니다. 사용자의 메시지나 이 대화에서 이미 답변된 질문은 생략합니다(예: "뉴스릴처럼"이라는 표현이 룩을 답변하고, "lo-fi 음악과 함께"가 음악을 답변합니다). 추천 옵션을 먼저 배치하고 "(권장)"이라고 표시하세요. 네 가지 질문을 모두 한 번의 호출로 질문하세요(도구는 최대 4개를 받습니다). 주제 자체가 불명확하고 건너뛴 질문이 없다면, 주제에 대해 먼저 단독 호출로 질문하세요.
| 질문 | 헤더 | 옵션 (첫 번째 = 기본값) |
|---|---|---|
| 동영상에 어떤 룩을 사용할까요? | 룩 (Look) | 클레이 3D (Clay 3D): 하나의 부드러운 클레이 룩, 침묵하는 마스코트가 작업 수행 · 클래식 2D, 혼합 (Classic 2D, mixed): 각 파트마다 다른 2D 스타일 · 클래식 2D, 한 가지 스타일 (Classic 2D, one style): 사용자가 이름 지정 (뉴스릴, 화이트보드, ...) |
| 동영상의 대상 시청자와 길이는 어떻게 되나요? | 시청자 (Viewer) | 시험 복습, 표준 (Exam revision, standard): 강의 표기법, 계산된 숫자, 시험 함정, 5 |
| 언제 확인을 받을까요? | 체크포인트 (Checkpoint) | 원샷 (One shot): 완성된 동영상으로 돌아오기 · 스토리보드 이후 (After the storyboard): 계획을 보여주고 승인 대기 · 첫 룩 이후 (After the first look): 첫 프레임을 보여주고 대기 |
| 어떤 음악을 사용할까요? | 음악 (Music) | 차분한 (Calm) (current): 부드러운 패드, 비트 없음 · Lo-fi (lofi): 가벼운 비트, 더 많은 에너지 · 없음 (None) |
대화 내용이 권장하는 옵션이 있다면 해당 옵션을 먼저 배치하세요(예: 다음 주 시험이라면: 시험 복습, 심층). 메시지가 시청자 질문의 절반만 답변하는 경우(예: "내 시험을 위해"), 질문을 유지하고 해당 절반과 일치하는 옵션만 제공하세요. 시청자는 시험 복습, 초보 학습자 및 전문가 리프레셔(빠르고 밀도 높음)이며, 길이는 짧게(24분), 표준(56분) 및 심층(8~9분)입니다. 답변을 4단계에서 video.json에 기록하세요: "_look" (clay 또는 classic), "_brief": { "viewer": ..., "length": ..., "checkpoint": ..., "style": ... } 및 "_render": { "music": "current" | "lofi" | false }. 이후 모든 단계와 재빌드는 이 값을 읽고 다시 묻지 않습니다. 사용자가 질문을 무시하면 각 항목의 첫 번째 옵션을 사용하세요.
원샷, 사용자가 체크포인트를 선택하지 않은 경우
0단계 이후 중단 없이 아래의 모든 단계를 수행하고, 완료되고 검증된 동영상만 가지고 돌아오십시오. "계속할까요?"라고 묻지 말고, 초안을 보여주지 말고, 단계 사이를 기다리지 마세요. 아래 모든 검사는 귀하가 실행하고 조치를 취할 책임이 있습니다. 유일한 중단점은 사용자가 선택한 체크포인트입니다: "스토리보드 이후"는 7단계 후에 중단하고(스토리보드와 스크립트 에이전트의 판정을 보여준 후 대기), "첫 룩 이후"는 9단계의 첫 번째 make look에서 중단합니다(이미지를 보여준 후 대기).
사용자가 원하는 룩 (6단계 전에 읽기)
행동하는 사물은 클레이(Clay)로, 플롯은 Manim으로, 마스코트는 모든 동영상에 등장합니다. styles/clay.md를 읽으세요. 사용자는 일관성을 위해 기존 스타일 혼합 대신 클레이 룩을 선택했습니다. 2D 스타일은 선택적인 클래식 룩입니다. 아래 섹션을 참조하세요.
-
플롯을 클레이에 강제로 넣지 마세요 (사용자 요청 사항). 2D Manim 그림이 클레이보다 시청자의 이해에 더 도움이 될 때(곡선, 분포, 등고선, 투영 또는 평면의 기타 기하학), 해당 부분을 Manim 파트로 만들고 Manim의 어두운 배경(
styles/math-manim.md) 위에 표시하세요. 수학적 곡선을 복사하는 클레이 모델을 절대 만들지 마세요: 사용자는 그러한 모델을 제거하도록 요청했습니다. 행동하는 객체와 마스코트의 물리적 작업은 클레이에 남습니다. 동영상은 클레이 파트에서 Manim 파트로, 다시 클레이 파트로 이동할 수 있으며, 동일한 사물에는 동일한 색상을 사용합니다. -
하나의 룩, 여러 파트. 동영상은 약 15~40초 길이의 파트(훅, 각 아이디어, 당신의 사례, 마무리)로 나뉩니다. 각 파트는 고유한 단색 배경, 카메라 및 설정을 가집니다. 인접한 두 파트는 절대 배경을 공유하지 않습니다.
-
마스코트가 작업을 수행합니다. 마스코트는 침묵하며 입모양이 없고, 내레이터는 음성 해설입니다. 마스코트는 걷고, 당기고, 밀고, 운반하고, 직접 손으로 물건을 끕니다. 따라서 스크립트의 힘은 시청자가 마스코트가 하는 모습을 보는 것입니다. 사용자는 마스코트가 서서 구경만 하는 동영상 이후에 이를 요청했습니다. 마스코트는 기본적으로 무표정을 유지하며,
make check는 한 자리에 머무를 경우 경고(WARN)를 표시합니다. -
사물은 연결되어야 합니다. 스프링은 벽에 닿고, 핀은 지도에 닿고, 손은 쥐고 있는 물체에 닿아야 합니다. 사용자는 모든 검사를 통과한 후에도 벽에 닿지 않은 스프링을 발견했습니다.
make bake는models.js(JOINS)의 모든 결합을 측정하므로, 새로운 결합을 거기에 추가하고 스틸 이미지에서 접촉을 확인하세요. -
우리만의 모델만 사용하세요.
styles/library/clay의 키트를 사용하세요. 절대 모델을 다운로드하지 마세요. 동영상에 새 객체가 필요하면 같은 룩으로 키트에 추가하세요. -
각 파트는 하나의 연속 촬영입니다. 파트 내부에는 컷이나 새 슬라이드가 없습니다. 객체는 음성이 말하는 대로 도착하고, 움직이고, 합쳐지며 카메라는 천천히 움직입니다. 파트는 다음 파트가 시작되는 상태로 끝나거나, 다음 파트의 배경에서 와이프(wipe) 효과로 끝납니다.
-
그림이 설명하고, 텍스트는 이름만 붙입니다. 텍스트는 평평하고 선명하게 유지되며, 3D 위에 HTML로 표시됩니다. 프레임당: 킥커(작은 대문자, 파트 및 출처), 최대 8단어의 제목, 각각 1~4단어의 레이블 몇 개(얇은 지시선 포함), 하단에 최대 한 줄의 캡션. 문장 열, 글머리 기호 목록, 색상 의미에 대한 범례는 절대 넣지 마세요. 화면에 최대 약 15단어만 표시됩니다.
-
수식은 음성을 따라 행동합니다 (사용자 요청 사항). 고정된 수식은 노트를 읽는 것보다 나을 것이 없습니다. 각 수식을
eqn()으로 구축하세요: 항은 말해질 때 도착하고, 음성이 이동시킬 때 이동하며, 취소(cancel)라고 말할 때는 스트라이크 및 버스트 효과, 중요한 것을 말할 때는 바운스 효과를 줍니다.make look은 정지된 수식과 화면에 취소 효과 없이 "취소합니다"라는 문장이 있을 때 오류를 표시합니다.styles/clay.md를 참조하세요. -
물리적 움직임. 사물은 물체처럼 움직입니다: 팔이 뻗고, 공이 떨어지고 튀고, 블록이 떨어져 안정되고, 맥박이 전달됩니다. 정적 상자의 축적은 없습니다.
-
같은 객체는 모든 동영상에서 동일한 색상을 유지합니다 (로봇은 항상 주황색, 지도는 항상 노란색).
스토리보드가 이 중 하나라도 위반한다면, 코드를 작성하기 전에 스토리보드를 변경하세요.
엄격한 규칙
- 여기, 메인 대화에서 생각을 하세요. 컨텍스트가 여기에 있으므로 스크립트, 스토리보드 및 장면을 직접 작성하세요. 이러한 단계를 서브 에이전트에 절대 넘기지 마세요: 서브 에이전트는 컨텍스트 없이 시작합니다. 7단계의 스크립트 에이전트는 유일한 예외이며, 의도적으로 콜드 스타트합니다.
- 핵심 설명을 절대 서두르지 마세요. 사용자는 이 동영상에서 배웁니다.
reference/script.md의 페이싱 규칙을 따르고 모든 페이싱 경고(WARN)를 수정하세요. - 절대 사실을 지어내지 마세요. 모든 숫자, 수식 및 주장은 확인한 출처에서 비롯됩니다: 사용자의 코드, 데이터시트, 사양, 논문, 문서. 이를
storyboard.md에 나열하세요. 확인할 수 없는 것은 보고하세요. - "당신의 사례"는 선택 사항입니다. 이 대화나 프로젝트에 실제로 일치하는 예제(사용자가 겪은 버그, 수정, 측정된 숫자)가 있을 때만 추가하세요. 절대 지어내지 마세요.
- 겹침 없음 (No overlaps). 어떤 시각적 요소도 다른 요소를 가릴 수 없습니다: 텍스트 위 텍스트, 텍스트 위 그래픽, 다른 그래픽을 숨기는 그래픽. 각 레이블, 수식, 화살표 및 객체는 고유한 공간을 가져야 합니다.
check는 텍스트 겹침에 대해 경고(WARN)하고,review는 측정된 모든 겹침을overlaps.md에 기록합니다. 밀집도는 사용자의 판단에 맡기므로, 프레임을 전체 크기로 확인하세요. ID 패스가 도움이 됩니다:make look은 가장 좁은 간격의 이미지를 추가하고, 텍스트가 다른 객체와 12px 미만으로 가깝거나, 텍스트가 그림 위에 있거나, 텍스트 대비가 낮거나, 모델이 다른 모델을 숨길 경우 경고(WARN)합니다.make final전에 모든 겹침을 수정하세요. - 자막은 한 줄입니다. 각 큐는 최대 42자이며, 두 큐가 동시에 표시되지 않습니다. 따라서 플레이어는 절대 두 줄을 표시하지 않습니다. 엔진이 이를 처리합니다.
verify는 규칙을 위반하는 큐를 보고합니다. 큐를 맞추기 위해make.mjs의SUB_MAX를 변경하지 마세요. - 닫힌 루프 (사용자 요청 사항이며, 엔진이 강제합니다). 모든 편집 후:
make look을 실행하고, 나열된 모든 이미지를 읽고, 보이는 문제를 수정한 후 다시 확인하세요. 그런 다음에만 빌드하세요. 절대 편집 후 맹목적으로 빌드하지 마세요. 빌드는 시간이 오래 걸리지만 룩은 몇 초면 끝납니다. 각 이미지에는 오른쪽 상단에 CHECK 숫자가 있으며, 게이트는 모든 이미지의 숫자가 순서대로 입력될 때만 열립니다:- 편집.
script.md를 변경했다면make voice를 실행하세요. 동영상에 Manim 파트가 있고manim_scenes.py또는 음성을 변경했다면make manim을 실행하세요:make look은 Manim 프레임을 그리지만 생성하지는 않습니다. make look <dir>: 변경된 각 장면의 모든 프레임을 측정하고, 근접 프레임과 움직이는 부분을 그립니다. 모두 읽으세요. 그런 다음make look <dir> --ok <digits>를 실행하세요. 이 작업 없이make build는 중단됩니다.make build <dir>. 충돌이 있으면 중단됩니다.build/review/moving.md의 모든 스트립을 읽으세요. 그런 다음make look <dir> --moving-ok <digits>를 실행하세요.make final <dir>. 룩 또는 빌드 후 소스가 변경되었거나, 충돌 또는 겹침이 해결되지 않은 경우 중단됩니다. 각 단계를 별도의 명령으로 실행하고, 첫 번째 실패에서 중단하고, 편집이 적용되었는지 확인하세요.
- 편집.
- 모든 리더는 근접 프레임과 움직이는 부분을 확인합니다. 동영상을 판단하는 모든 에이전트나 세션은 편집된 각 파트의 근접 프레임과 움직이는 모든 객체(마스코트 및 객체)의 전체 이동 중 모든 프레임을 읽습니다. 동영상 샘플만으로는 충분하지 않습니다. 샘플링된 프레임 사이에 손이 테이블을 통과할 수 있기 때문입니다.
- 새로운 결함은 가드레일을 얻습니다. 사용자가 결함을 발견하면, 먼저
reference/faults.md와engine/test/selftest.mjs에 추가하고, 해당 결함에 대해 테스트가 실패하는지 확인하세요. 그런 다음 동영상을 수정하세요. 동영상만 수정하지 마세요. 검사 변경 후에는 항상make selftest를 실행하세요.
사용자가 요청한 사항 (유지하세요)
각 항목은 귀로 요청하거나 선택되었습니다. 엔진은 대부분을 자동으로 처리합니다.
| 주제 | 내용 | 자동? |
|---|---|---|
| 음성 | Chatterbox의 내장 음성, engine/tts/slow-reference.wav로 분당 약 160 단어로 느리게 재생; 각 문단을 한 번에 읽어 어조 유지 | 예 |
| 일시 정지 | 모든 마침표는 정확히 0.6초, 모든 쉼표는 최대 0.3초, 스크립트의 구두점에서 설정; voice는 일시 정지를 배치할 수 없으면 경고(WARN) | 예 |
| 나쁜 테이크 | 스크립트와 단어가 다른 파트(Whisper 검사)는 새 시드로 최대 3번 재녹음; 최고의 테이크 유지 | 예; 여전히 틀리면 경고(WARN) |
| 빠른 부분 | 동영상의 일반 속도보다 1.3배 이상 빠른 절은 재녹음(기호 단어는 두 배로 계산); 사용자가 "lambda v is v, scaled by lambda"가 너무 빠르다고 발견 | 예; "fast" 경고(WARN): 자체 짧은 문장과 [pause] 제공 |
| 음수 | "negative"로 읽고, 절대 "minus"로 읽지 않음 | voice가 오류(ERROR)로 중단 |
| 반복 단어 | "one one"은 쉼표를 받음("one, one"), 또는 음성 실수 | 예 |
| 대본 작성 | 연결된 문단; [pause]는 아이디어가 끝나거나 애니메이션이 재생될 때만 사용. 거부됨: 모든 문장 뒤 일시 정지, 끊기는 문장, 빠른 음성, 늘어진(먹먹한) 음성, Kokoro | 당신, reference/script.md 참조 |
| 음악 | 들을 수 있고, 일정하며, 음성 아래 약 13dB(musicVolume 0.37; 사용자가 0.26에서 3dB 높임), 부드러운 덕킹; 승인된 두 트랙, current(기본값) 및 lofi. 거부됨: 시끄러움-조용함 펌핑, 너무 작아 들리지 않는 음악, 다른 4개 트랙 | 예; 트랙 선택은 당신, SOUND.md 참조 |
| 음향 효과 | engine/sfx.mjs의 키트, 귀로 승인됨; 플라이인 후시는 다른 악센트보다 4dB 낮음(사용자가 약간 너무 크다고 발견). 새 동영상에서 켜짐(_render.sfx: true), 이전 동영상에서 꺼짐 | 큐에서 s.sfx 추가; 엔진이 믹싱 |
| 오디오 | 48kHz 스테레오 | 예; verify가 확인 |
| 자막 | 소프트 자막, 절대 하드코딩되지 않음; 사용자의 mpv는 작게 표시(sub-scale=0.7) | 예 |
| 한 줄 자막 | 큐당 한 줄, 최대 42자, 두 큐가 동시에 표시되지 않음. 사용자가 ROS 2 세트의 동영상 1에서 두 줄을 봄 | 예; verify가 규칙을 위반하는 큐 보고 |
| 겹침 없음 | 어떤 텍스트나 그래픽도 다른 것을 가리지 않음 | check는 텍스트에 대해 경고(WARN), overlaps.md 및 프레임 체크리스트는 나머지 처리 |
| 룩 | 침묵하는 마스코트와 우리만의 모델을 사용한 하나의 3D 클레이 룩; 곡선 및 플롯을 위한 어두운 배경의 Manim 파트(사용자 요청: 플롯을 클레이에 강제로 넣지 마세요). 거부됨: 다운로드된 모델, 전체 어두운 동영상, 텍스트 열, 색상 범례, 축적 슬라이드 | make check는 클레이도 Manim도 아닌 장면 또는 마스코트가 없는 동영상에 대해 오류(ERROR); 나머지는 당신, "사용자가 원하는 룩" 참조 |
| 수학 | 다섯 가지 수식 단계(필요, 그림, 수식, 의미, 테스트). 곡선, 플롯 또는 단계별로 변경되는 수식은 Manim: 2D의 manim(), 3D 그림의 경우 manim({ threeD: true }), 손으로 그린 캔버스 아님 | make check는 수식만 있을 때 경고(WARN); 나머지는 당신, reference/script.md 및 styles/math-manim.md 참조 |
| 퀴즈 | 스토리보드에 없음 | 당신 |
| 시청 | mpv <dir>/out/<slug>.mp4 | 보고서에 포함 |
머신 설정
1단계 전에 make config를 실행하세요. 설치 프로그램 또는 /setup-kaleidoscope가 작성한 이 머신의 설정을 출력합니다.
voice 라인은 음성을 지정합니다: Chatterbox(자연스러움, NVIDIA GPU 또는 Apple Silicon에서 최상) 또는 Kokoro(CPU에서 작고 빠름, 분당 약 150 단어). 프로젝트는 video.json에서 자체 선택 가능: "_tts": {"engine": "kokoro"}. GPU가 없으면 Chrome이 SwiftShader로 프레임을 그리고 ffmpeg가 libx264로 인코딩합니다.