Explainer Short (아이디어 → 완성된 동영상)
요청당 하나의 완성된 동영상을 아래 7단계를 순서대로, 한 번씩 수행하여 제작합니다. 모든 단계에는 명령어, 출력, 중단 조건이 있습니다. 추가 단계를 임의로 만들지 마십시오.
경로: SKILL = 이 파일이 있는 폴더. STUDIO = 동영상 작업 공간
(기본값: 현재 프로젝트의 ./explainer-studio; 이미 존재하면 재사용). SLUG = 동영상의 케밥-케이스 ID
(예: how-https-works).
하드 제한 (실행 시간과 비용을 낮게 유지)
- 사용자에게 최대 한 개의 질문만 하며, 주제가 전혀 없을 때만 질문합니다. 그 외에는 아래 기본값을 사용하여 (길이, 형식, 브랜드) 스스로 결정하고 최종 응답에 선택 사항을 명시하십시오.
check.sh→ 수정 →check.sh는 최대 2회 수정 라운드까지만 진행합니다. 그 후 렌더링하고, 남은 문제가 있으면 응답에 나열하십시오.- 음성 재생성은 최대 2회까지만 허용합니다(길이 또는 잘못 발음된 단어의 경우에만).
src/kit/은 편집하지 마십시오(아이콘 추가 제외). 다른 패키지나 도구를 설치하지 마십시오.template/src/videos/example/을 한 번 읽으십시오(참조 구현입니다). 키트 소스는 읽지 마십시오.references/kit-api.md가 키트를 문서화합니다.
"쇼츠", "릴", "설명 쇼츠" = 세로 FORMAT을 의미하며, 길이 모드를 의미하지 않습니다. "쇼츠" 길이 모드는 사용자가 빠른/매우 짧은/1분 미만 동영상 또는 초 단위 시간을 요청할 때만 사용하십시오.
기본값: 길이 95–120초(300–370단어; "쇼츠" = 55–70초, "전체" = 참조 길이 160–175초 —
references/script-guide.md 참조), 음성 am_michael 속도 1.18, 브랜드 = 사용자의 이름/채널(알고 있는 경우), 아니면 "YourBrand".
스타일 규칙은 23개의 참조 동영상을 측정하여 도출되었습니다. 증거는 references/style-evidence/에 있습니다(인간만 확인 — 읽을 필요 없음).
1단계 — 설정 (머신당 한 번, 처음 ~3분, 이후 ~2초)
bash SKILL/scripts/setup.sh STUDIO
중단 조건: 마지막 줄이 READY: …입니다. MISSING TOOLS가 출력되면, 사용자에게 정확히 무엇을 설치해야 하는지 알리고 중단하십시오.
(음성 모델 파일이 이미 어딘가에 존재하는 경우 먼저 KOKORO_MODELS=<dir>을 설정하여 340MB 다운로드를 건너뛰십시오.)
2단계 — 계획 (아직 코드 없음)
references/script-guide.md를 읽으십시오. 그런 다음 STUDIO/src/videos/SLUG/plan.md를 작성하십시오(≤ 25줄, 3단계에서 폴더를 만든 후):
- 제목 (How X works · X vs Y · Interview: … · System design: how does X 형식 중 하나).
- 실행 예제: 처음부터 끝까지 사용되는 구체적인 사람 이름 + 제품/입력/값.
- 비트(섹션) : id가 있는 6–9개, 각각 = 하나의 아이디어.
- 스테이지:
references/visual-guide.md를 읽고, 섹션당 한 줄을 작성하십시오:section → added / moved / focus (spotlight ids) / leaves(해당 문서의 "Planning stages" 참조). 3–4개의 악센트를 선택하고 각각을 하나의 요소에 바인딩하십시오.
3단계 — 스크립트
bash SKILL/scripts/new_video.sh STUDIO SLUG
STUDIO/src/videos/SLUG/script.json을 작성하십시오(형식: 예제의 script.json 참조). 문제를 일으키는 규칙:
sections[].id는 고유하고 단순해야 함(hook,scenario,mechanism, …). 마지막 섹션은 CTA입니다.- 숫자/기호는 표시하고 싶은 대로 작성하고,
pronounce에서 발음되는 방식으로 매핑하십시오 ("429": "four twenty nine","API": "A P I","SQL": "sequel","k8s": "kubernetes"). - 문장은 18단어 이하.
. ! ?만 문장을 끝냅니다(각 문장은 개별적으로 합성됨). 다음 단계로 넘어가기 전에script-guide.md끝에 있는 규칙 목록을 기준으로 자체 점검하십시오.
4단계 — 음성
bash SKILL/scripts/voice.sh STUDIO SLUG
각 섹션의 시작/종료 및 Done: <sec>s, <words> words, <wpm> wpm을 출력합니다. 중단 조건: 지속 시간이
대상 ±15% 이내여야 함. 너무 길면 문장을 자르고(속도 조절 아님) 한 번 더 실행하십시오.
5단계 — 시각 자료
references/kit-api.md와 예제(STUDIO/src/videos/example/Video.tsx + stages/*.tsx)를 읽으십시오.
STUDIO/src/videos/SLUG/Video.tsx + stages/에 스테이지당 하나의 파일을 작성하십시오. 절대 타협할 수 없는 사항:
- 모든 요소의
at은cue(section, word)또는sec(section).from에서 가져와야 함 — 절대 하드코딩된 초 단위 사용 금지. - 하나의 연속 캔버스: 요소는 지속되고, 이동하고, 흐려지고, 재사용됩니다. 스테이지 사이를 제외하고 전체 화면 클리어 금지.
- 내레이션의 최소 ~3초마다 시각적으로 변화하는 것이 있어야 함(새 요소, 강조, 상태 변경, 이동).
- 초점 =
<Canvas focus>에 스포트라이트 계획 적용(나머지는 흐리게) — 스타일의 주요 장치. - 자막 없음. 캡션(
Takeaway)은 7단어 이하, 동영상당 2–6개. - 콘텐츠를 안전 영역(x 60–1020, y 280–1480; 제목 ≈150; 캡션은 다이어그램 바로 아래)에 유지.
- 너비를 채울 것: 메인 패널 w 960(또는 2 × 465). 26px보다 작은 요소 금지.
6단계 — 확인 (최대 2회 수정 라운드)
check.sh와 render.sh는 로컬 서버 + 헤드리스 Chrome을 시작합니다. 샌드박스 에이전트에서는 두 명령어를
샌드박스 외부에서 실행하십시오. 환경이 전혀 실행할 수 없는 경우(No available ports found, Chrome이 시작되지 않음,
샌드박스 해제 호출 거부): 5단계 후 중단하고, 사용자에게 check.sh와 render.sh를 직접 실행하라고 알리십시오
(두 명령어 전체를 제공). 대안을 시도하지 마십시오.
bash SKILL/scripts/check.sh STUDIO SLUG # 선택적 3번째 인수: "12.5,30,41" = 추가로 검사할 초
모든 cue()를 음성 타이밍과 대조(즉시), 타입체크, 섹션당 ~3프레임 + 엔드 카드 렌더링, out/SLUG/check/sheet.jpg
(+ NN.jpg 단일 프레임)을 작성합니다. 시트 이미지(및 전체 크기의 2–3개 단일 프레임)를 살펴보십시오. 실패한 부분만 수정:
| 검사 | 실패 조건 |
|---|---|
| overlap | 텍스트/박스가 충돌하거나 화면 가장자리에 잘림 |
| scale | 다이어그램이 너비의 < 80%를 사용하거나 바쁜 섹션에서 y 900–1400이 비어 있음; 540px 너비 프레임에서 눈을 찡그려야 하는 텍스트 |
| readability | ~28px보다 작은 레이블, 또는 복잡한 영역 위의 텍스트 |
| sync | 해당 단어보다 먼저 나타나는 요소, 또는 내레이션이 무언가에 대해 말하는 동안 빈/오래된 캔버스를 보여주는 프레임 |
| continuity | 이야기가 계속될 때 이전 스테이지와 관련 없어 보이는 스테이지(모든 것이 대체됨) |
| focus | 현재 말하고 있는 것이 강조되지 않음(초점 / 호박색 / 다른 것 흐리게) |
| density | 9개 이상의 가시 요소 또는 2줄 이상의 테이크어웨이 텍스트가 있는 프레임 |
타입 오류 / cue not found 오류는 수정 방법(유효한 단어 목록)을 출력합니다. 수정하고 재실행하십시오.
7단계 — 렌더링 + 전달
bash SKILL/scripts/render.sh STUDIO SLUG
(헤드리스 Chrome이 샌드박스에 의해 차단된 경우, 이 명령어를 샌드박스 외부에서 재실행하십시오.)
그런 다음 STUDIO/out/SLUG/upload.md를 작성하십시오: 제목(= 동영상 제목, ≤ 60자, 끝에 1개 이모지 허용),
2문장 설명, 5개의 해시태그, 그리고 "확인할 사실" 목록(기억에서 언급한 모든 숫자/주장).
최종 응답(짧게): MP4 경로, 지속 시간, SRT/커버/upload.md 경로, 당신이 선택한 사항 (형식, 길이, 실행 예제), 그리고 남은 알려진 문제. 그 후 중단.
문제 해결
| 증상 | 해결책 |
|---|---|
cue not found: "x" #1 in section "y". Words: … | 출력된 목록의 단어를 사용하거나 올바른 섹션 사용 |
| 단어가 잘못 발음됨 | pronounce에 추가하고 4단계 재실행 |
Cannot find module './timing.json' | 이 SLUG에 대해 4단계를 실행하지 않음 |
composition SLUG not found | voice.sh 실행(비디오 등록) |
Chrome / SIGABRT / ENOTFOUND remotion.media / No available ports found | 샌드박스가 브라우저/포트 차단: 명령어를 샌드박스 해제 상태로 실행(6단계 참조) |
failed to canonicalize path …/voice/.venv/bin/python3 또는 기타 uv/venv 오류 | STUDIO/voice/.venv를 삭제하고 setup.sh 재실행 |
| 프레임에 텍스트가 패널을 넘쳐 흐름 | <El>에 더 큰 h, 더 적은 줄, 또는 더 작은 글꼴(≥ 26px) 지정 |
| 동영상이 너무 길거나 짧음 | 스크립트 편집(속도 1.18에서 초당 약 3.1단어), 4단계 재실행 |