explainer-short은(는) 무엇을 하나요?
짧은 세로형 설명 영상을 만듭니다. 하단 절반에 발표자, 상단 절반에 모션 그래픽, 중간에 큰 자막 칩이 배치됩니다. 클립당 하나의 아이디어만 전달합니다. 테마 토큰으로 색상, 글꼴, 둥글기, 모션을 제어하여 동일한 스크립트로 따뜻한, 단색, 고대비, 또는 재미있는 스타일을 연출할 수 있습니다.
사용 시기
- 8~30초 길이의 세로형 교육 또는 제품 설명 영상
- MP4로 내보내는 재사용 가능한 HTML/Canvas 파이프라인
- 장면 코드를 다시 작성하지 않고 시각적 테마를 전환해야 할 때
레이아웃
+---------------------------+
| 모션 / 카드 (1080) |
| |
|---------------------------| <- 이음새 부분 자막 칩
| 발표자 크롭 (960) |
| |
+---------------------------+
1080 x 1920
테마 시스템
테마는 template/themes/*.json (데모용 sample/themes/)에 위치합니다.
활성 테마는 프로젝트 폴더의 theme.json입니다.
bash template/scripts/use-theme.sh warm # 또는 mono | high-contrast | playful
# 또는 복사된 프로젝트에서:
bash scripts/use-theme.sh mono
로드된 토큰 (loadTheme 이후 CSS 변수):
| 토큰 | 역할 |
|---|---|
--ink --mute | 텍스트 |
--bg --bg-hi --bg-lo | 스테이지 배경 |
--surface --surface-2 | 카드 |
--accent --accent-2 --accent-3 | 강조 |
--chip-bg --chip-fg | 자막 칩 |
--radius-card --radius-chip --chip-size | 모양 |
--headline-weight | 제목 두께 |
--font-sans --font-mono | 글꼴 (OFL woff2, fonts/ 폴더) |
프리셋: warm (기본값), mono, high-contrast, playful.
JSON 파일을 편집하고, use-theme.sh를 다시 실행한 후, 브라우저를 새로고침하세요. 테마 자체에는 빌드 단계가 없습니다.
글꼴 교체
- 오픈 라이선스 woff2 파일을
fonts/폴더에 넣고 라이선스 파일도 함께 보관하세요. - 테마 JSON에서
fonts.sans/fonts.sans_file(및 모노) 값을 설정하세요. - 폰트 패밀리 이름이 변경되면
index.html의@font-face가 새 파일을 가리키도록 수정하세요. - 중간 프레임 스틸을 다시 렌더링하여 확인하세요.
기본 번들 폰트: Inter + JetBrains Mono (SIL OFL). 라이선스 텍스트는 fonts/ 아래에 함께 제공됩니다.
빠른 시작 (테마 데모, 발표자 영상 없음)
npm install
node scripts/render_sample.mjs warm
node scripts/render_sample.mjs mono
# 출력: sample/out/<프리셋>/<프리셋>.mp4 + 프레임 스틸
필요 사항: Node 18+, 시스템 Chrome 또는 Chromium, ffmpeg.
전체 프로젝트 파이프라인 (자체 포함)
template/을 새 프로젝트 폴더로 복사하거나 (sample/안에서 작업).main.js에서 장면을 작성하고window.render(t)를 호출하며 테마의 CSS 변수를 사용합니다.- (선택 사항) 발표자 영상: 테이크를 가져온 후
src/edit.json을 채우고python3 src/edit.py를 실행 (numpy + soundfile 필요), 그 다음python3 src/captions.py를 실행합니다. - 스킬 루트에서 (
npm install후):
PRESET=warm bash template/build.sh
# 또는 복사된 프로젝트에서:
SKILL_ROOT=/path/to/explainer-short PRESET=mono bash build.sh
# 또는 렌더러 직접 호출:
node scripts/render.mjs --dir path/to/project --preset warm --out path/to/project/out/video.mp4
out/voice.wav파일이 있으면python3 mix.py가 -14 LUFS / -1 dBTP로 음량을 정규화하고build.sh가 이를 먹싱합니다.
template/scripts/render.mjs는 템플릿과 함께 복사되므로 프로젝트에서 로컬 복사본을 유지할 수 있습니다.
디자인 규칙
- 하나의 아이디어. 하나의 대상, 하나의 약속, 영상 종료 전에 완결될 것.
- 팔 길이 거리에서 읽기 쉬울 것. 큰 글자, 높은 대비, 화면에 최소한의 단어.
- 자막 칩이 목소리 역할을 합니다. 큐는 짧게 유지하고, 마지막 단어를 잠시 멈춤.
- 테마를 사용하고 하드코딩하지 마세요. 색상, 둥글기, 칩 크기는 토큰에서 가져옵니다.
- 취향 중립 기본값. Warm이 기본값이며, 사용자가 프리셋을 선택합니다.
출시 전 검토
각 축을 0-3점으로 평가합니다. 평균이 2.3 이상일 때만 출시합니다. 독립 검토자가 주요 파일을 측정합니다.
| 축 | 확인 사항 |
|---|---|
| 정지 | 마지막 자막이 ~0.3-0.5초 유지됨. 단어 중간에 컷 없음 |
| 음량 | 약 -14 LUFS 통합 (ffmpeg loudnorm으로 측정) |
| 실제 피크 | <= -1 dBTP |
| 표지 | 마지막 프레임 또는 썸네일 오프셋이 명확한 타이틀 카드 |
| 테마 | 토큰이 적용됨. 하드코딩된 브랜드 색상 없음 |
| 명확성 | 처음 보는 사람이 오디오 없이도 요점을 이해할 수 있음 |
전체 루브릭: references/review-rubric.md. 안전 영역: references/cover.md.
파일
| 경로 | 역할 |
|---|---|
package.json | playwright-core 의존성 선언 |
template/ | 시작 프로젝트 (HTML, 테마, 글꼴, build.sh) |
template/themes/ | 프리셋 JSON |
template/theme.js | loadTheme() -> :root에 CSS 변수 설정 |
sample/ | 자체 포함 12초 테마 데모 |
scripts/render.mjs | 헤드리스 프레임 렌더 + ffmpeg 먹싱 |
scripts/render_sample.mjs | 샘플 프리셋용 편의 래퍼 |
references/ | 구조, 테마, 검토 루브릭, 표지, 마무리 |
docs/ | 검증된 실행에서 나온 미리보기 스틸 |
에이전트 체크리스트
-
npm install을 스킬 루트에서 완료 - 테마 프리셋 선택 (또는 warm 기본값 사용)
-
theme.json이 선택한 프리셋과 일치 - 장면에서 CSS 변수 사용, 하드코딩된 브랜드 색상 사용 안 함
- 샘플 또는 전체 빌드가 MP4를 생성
- ffprobe로 1080x1920 및 예상 길이 확인
- 중간 프레임 스틸이 프리셋에 맞게 브랜드 일관성 확인
- 오디오가 있을 때 음량 약 -14 LUFS, 실제 피크 <= -1 dBTP
- 검토 루브릭 평균 >= 2.3
- 프로젝트에 개인 또는 타사 브랜드 잔재 없음