explainer은(는) 무엇을 하나요?
명세 파일(spec file)은 장면(scene) 목록을 포함합니다. 스크립트는 자료를 캡처하고, 내레이션을 녹음하며, 장면별로 HyperFrames 하위 컴포지션을 빌드하고, 배포 전에 모든 것을 검증합니다.
1. 이해 설명 대상이 되는 코드 / 문서 / 앱을 읽습니다
2. 캡처 scripts/capture.py 스크린샷, 요소 박스, 녹화, 마스킹(redaction)
3. 명세 직접 explainer.json 작성 (장면 + 내레이션 + 출처 포함 주장)
4. 사실 검증 scripts/verify.py facts (게이트: 검증되지 않은 내용은 음성으로 읽히지 않음)
5. 빌드 scripts/build_explainer.py (음성, 캡션, 장면; 기본적으로 캐릭터 없음)
6. 검증 scripts/verify.py all (에셋, 빌드, 렌더, 오디오) - 통과할 때까지 반복
7. 렌더링 scripts/render.py
모든 경로는 이 패키지의 루트를 기준으로 합니다. 루트는 .claude-plugin/ 폴더가 있는 폴더로, 이 파일보다 두 단계 위에 있습니다 (심볼릭 링크를 먼저 확인하세요). 공개 HyperFrames 스킬(hyperframes, hyperframes-cli; 추가 기능을 위해 hyperframes-registry 및 media-use)이 필요합니다. 생성된 컴포지션을 직접 수정하기 전에 hyperframes를 한 번 읽어보세요.
0. 사전 점검 (항상 먼저)
python3 scripts/setup.py doctor를 실행하세요 (--json을 추가하면 파싱 가능). 이 명령어는 모든 의존성, 각각의 용도, 그리고 이 머신에 맞는 정확한 설치 명령어를 나열합니다. 필수 항목이 누락된 경우 exit 1로 종료됩니다.
- 필수 누락 (ffmpeg, Node.js 18+, HyperFrames 스킬, ElevenLabs 키 또는 설정된 음성에 해당하는
say): 각각의 용도를 한 줄로 설명하고 출력된 설치 명령어를 제안하세요. 사용자가 확인한 후에만 실행하세요. 직접 API 키를 입력하거나 요청하지 말고, 사용자에게 셸에서ELEVENLABS_API_KEY를 내보내도록(export) 안내하세요. - 선택 누락: 한 번 제안하고 각각이 무엇을 가능하게 하는지 설명하세요. Playwright는 요소 확대 상자와 전체 페이지 샷이 포함된 웹 캡처를 제공하고, tesseract(OCR)는 스크린샷의 비밀 스캔을 제공하며, ASR(mlx-whisper / openai-whisper)은 오디오 검사와 정확한 단어 타이밍을 제공합니다. 사용자가 거절하면 건너뛰고, 해당 검사는 수동
review단계가 됩니다. - HyperFrames 스킬 (
hyperframes,hyperframes-cli,hyperframes-registry,media-use): 누락된 경우npx hyperframes skills를 권장합니다. 컴포지션을 빌드하거나 편집하기 전에hyperframes(그리고 렌더링 문제가 있으면hyperframes-cli)를 읽어보세요.
설정 (첫 실행 시 또는 사용자가 변경하려는 경우)
python3 scripts/setup.py show는 활성 설정을 출력합니다. 설정이 없으면 사용자에게 인터뷰(한 번에 하나의 짧은 질문, 기본값 제공)하고 설정을 작성합니다:
| 질문 | 플래그 | 옵션 |
|---|---|---|
| 어떤 부분? | --features | explainer 단독 (캐릭터 파일 불필요), 또는 character,explainer로 프레젠터 가능 |
| 내레이션 언어 | --language | ISO 코드 (en, es, ...): 명확한 say 음성을 선택하고 ASR에 예상 언어를 알림 |
| 내레이션 음성 | --narration-voice | voice (설정된 제공자), say (무료, macOS), none (캡션만) |
| 음성 제공자 | --voice | elevenlabs (환경 변수 ELEVENLABS_API_KEY + --voice-id 필요), say, none |
| 크레딧 보호 | --max-chars, --max-seconds, --daily-credit-cap | 사용자 숫자 |
| 렌더링 | --render | local, cloud, preview |
| 크기 | --size | 1080x1920 (기본값), 1920x1080, 1080x1080 |
python3 scripts/setup.py init --features explainer --voice say --render local --yes
init은 먼저 doctor를 실행하고 동일한 설치를 제안합니다. 설정이 이미 존재하면 덮어쓰기 전에 확인합니다 (비대화형 실행 시 --force 전달). setup.py voices --lang <code>는 언어별 macOS 음성과 사용자의 ElevenLabs 음성을 나열합니다. --say-voice "<name>"으로 하나를 선택합니다. API 키를 요청, 출력 또는 작성하지 마세요.
1. 이해, 그리고 스크립팅
- 먼저 출처에서 사실을 확인하세요: 코드, PR, 문서 또는 앱을 읽으세요. 잘못된 설명은 없는 것보다 나쁩니다. 세부 사항 전에 전체적인 형태를 보여주고, 실제 사례 하나를 통해 설명하세요 (실제 이름, 실제 값 사용). 각 장면은 하나의 아이디어로 제한하세요.
- 형태 (≤
styles.explainer.max_seconds): 각각 약 6-12초의 장면 3-5개와 마무리 제목. TTS는 초당 약 2.4단어를 읽습니다: 장면의 내레이션은 약 25단어 미만으로 유지하세요.
이 비디오의 스타일 선택
이 패키지는 중립적인 기본값만 제공합니다. 주제, 대상 청중, 사용자의 브랜드나 선호도에 따라 비디오별로 스타일을 선택하고, 중요할 때(브랜드, 공개 채널, 시리즈) 질문하세요. 이전 비디오의 모양을 습관적으로 반복하지 마세요. 명세(spec)의 style 블록에 넣으세요:
| 키 | 값 |
|---|---|
| palette | background, panel, ink, muted, accent, highlight (CSS 색상; 텍스트 대비 4.5:1 이상 유지) |
| typography | font, mono (HyperFrames 번들 폰트), title_scale (0.6-1.6) |
| layout | align (left, center), radius (0-60), background_style (solid, gradient) |
| motion | motion (calm, normal, lively): 모든 움직임의 지속 시간과 이징 |
| captions | caption_style (box, outline, plain, none), caption_position (bottom, top) |
설정에 brand 키트(동일한 키)가 있으면 키별로 선택을 덮어씁니다. 프레젠터의 세트는 해당 블록에 자체 style이 없는 한 비디오의 배경을 따릅니다 (talking-clip 참조).
2. 자료 캡처
python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit" # Playwright 필요
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12 # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48 # 또는 --blur
python3 scripts/capture.py list
url은 Playwright가 설치된 경우 사용하고(--box및--full-page에 필요), 그렇지 않으면 headless Chrome을 사용합니다. Playwright 없이 초점 상자는 PNG에서 읽은 픽셀 사각형[x, y, w, h]으로 제공하세요 (기본 스케일에서 CSS 픽셀의 두 배). Playwright가 virtualenv에 있으면 해당 인터프리터로 스크립트를 실행하세요 (.venv/bin/python scripts/capture.py ...).--box는 이미지 픽셀 단위로 요소의 상자를 기록하여 장면이 바로 확대할 수 있게 합니다. 기본--scale 2`는 확대 시 텍스트를 선명하게 유지합니다.- 이야기를 전달하는 가장 작은 영역을 캡처하세요; 전체 데스크톱을 폰 프레임에 축소하면 읽을 수 없습니다. 초점 상자를 사용하여 확대하세요.
- 단일 샷 대신 프로젝트로 전체 웹사이트:
npx hyperframes capture <url>(hyperframes-cli).
3. 명세 작성
examples/explainer/explainer.json은 완전하고 작동하는 예제입니다. 명세는 자료의 루트에 두세요: 참조하는 코드 파일과 캡처는 명세 폴더 안에 있어야 합니다. 장면 유형:
| type | 필요 항목 | 표시 내용 |
|---|---|---|
screen | capture, 선택적 focus: [{"box": "#sel" 또는 [x,y,w,h], "label": "...", "at": s}] | 스크린샷, 그 후 각 상자로 카메라 이동하며 하이라이트와 레이블 표시 |
recording | capture (비디오), 선택적 focus | 화면 녹화, 음소거, 동일한 카메라 및 레이블 |
code | file, lines: "a-b" (≤ 24줄, 각 줄 ≤ ~49자), highlight: [{"lines": [a, b], "at": s}] | 카드 위의 코드, 줄이 나타나고, 핵심 줄에 밴드 표시 |
diagram | nodes: [{"id","label","sub"?,"highlight"?}], edges: [[a, b]], 선택적 flow: [ids] | 상자와 화살표가 순차적으로 구성, flow를 따라 이동하는 토큰 |
title | text, 선택적 sub, dur | 마무리 또는 구분 카드 |
모션, 모든 장면에 대해 (선택 사항; 색상과 타이밍은 스타일에서 가져오므로 비디오의 다른 모양과 마찬가지로 비디오별로 다르게 지정):
| 키 | 설명 |
|---|---|
callouts: [{"type": "circle" 또는 "arrow", "box": [x,y,w,h] 또는 "#sel", "at": s, "note": "..."}] | 손으로 그린 원 또는 화살표가 그려짐; screen/recording 장면에서는 이미지 픽셀, 그 외에는 프레임 픽셀 사용 |
kinetic: [{"text", "at", "dur", "y"?, "from"?}] | 강조를 위해 단어가 강하게 등장; 드물게 사용 (비디오당 하나 또는 두 개) |
counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?} | 정확한 값에 도달하는 카운트업 |
최상위 transition: "wipe" 또는 "fade" | 모든 컷에서 전환 (기본값 none) |
이들은 레지스트리 항목 count-up, caption-kinetic-slam, hw-callout-circle 및 hw-arrow를 따릅니다 (/hyperframes-registry 참조). style.hand_font: "Caveat"는 npx hyperframes add로 해당 필기체 폰트를 가져옵니다. 모든 비디오에 모든 기능을 사용하지 말고, 이야기에 필요한 것만 선택하세요.
내레이션이 있는 모든 장면은 claims를 포함해야 합니다: 각 기술적 진술에 대해 source(명세 기준 상대 경로, capture:<name>, https://..., doc:<name>)와 status: "supported"(출처에서 확인한 경우)를 포함합니다. "claims": []는 내레이션이 기술적 주장을 하지 않음을 의미합니다. 지원되지 않는 주장은 수정하거나 제거하며, 절대 음성으로 읽히지 않습니다.
기본적으로 캐릭터 없음. 설명 동영상은 내레이션, 캡션 및 시각 자료입니다. 사용자가 요청하거나, 가치를 더한다고 판단될 때(호스트가 있는 시리즈, 친근한 온보딩)만 프레젠터로 캐릭터를 추가하고, 그 이유와 함께 사용자에게 알리세요. 그런 다음 presenter 블록(intro / outro, 각각 {"text", "plan"?, "mood"?, "style"?, "claims"}; 계획은 talking-clip 형식을 따름)을 추가하고 --presenter로 빌드하세요. 또한 features.character가 필요합니다. 프레젠터 장면에도 캡션이 있습니다(명세가 "captions": false로 설정되지 않은 경우). examples/explainer/explainer-with-presenter.json이 예제입니다.
4-5. 사실 게이트, 그 다음 빌드
python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]
--estimate는 길이와 ElevenLabs 크레딧을 출력합니다; 사용자에게 알린 후 --confirm으로 빌드하세요. 빌더는 또한 사실 게이트를 실행하고 실패하면 중지합니다. 캡션은 ElevenLabs 정렬, ASR 또는 추정치에서 시간이 지정된 스크립트 자체의 단어를 표시합니다(대소문자, 구두점, 숫자).
6. 검증 (필수 반복)
python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4
| 단계 | 통과 조건 | 실패 시 |
|---|---|---|
| facts | 모든 내레이션 주장이 존재하는 출처와 supported 상태를 가짐 | 출처 확인; 주장 수정 또는 제거 |
| assets | 캡처와 코드가 출력 크기에서 읽기 쉬움; OCR(tesseract) / 텍스트 검사에서 이메일, 키, 토큰, 카드 번호를 찾지 못함 | 초점 상자 추가 또는 더 작은 영역 다시 캡처; capture.py redact 사용; 코드의 비밀을 플레이스홀더로 교체 |
| build | npx hyperframes check --json에 오류나 경고가 없음 (verify.ignore_rules 제외) | 명세 또는 생성된 컴포지션 수정 |
| render | 연속 이미지(시작, 모든 장면 전환, 장면 중간, 끝)를 확인: 오버플로우, 겹침, 잘림, 읽을 수 없는 텍스트 없음; 시각 자료가 내레이션과 일치 | 수정, 재빌드, 재렌더링 |
| audio | 렌더링된 오디오의 ASR이 스크립트와 일치하고 (verify.min_asr_similarity) 길이가 제한 내에 있음 | 음성 재생성 또는 단축 |
반복 루프를 실행하는 방법:
verify.py all을 실행합니다. 각 실행은 한 번의 반복입니다 (<project>/.verify/state.json에 기록됨).render는 항상 먼저review로 돌아옵니다: 나열된 연속 이미지를 열고, 모든 프레임을 확인한 다음, 본 내용을 기록합니다:python3 scripts/verify.py mark render pass --project out/explainer --note "<확인한 내용>"(또는fail, 그런 다음 수정). 마크는 해당 정확한 파일에 연결되며, 재빌드 시 무효화됩니다.- OCR이나 ASR이 설치되지 않은 경우
assets/audio도review가 됩니다: 눈이나 귀로 확인하고 보고서에 그렇게 명시하세요. - 실패한 부분을 수정하고, 재빌드 또는 재렌더링한 다음,
verify.py all을 다시 실행합니다. Exit 0 = 배포 가능. - 횟수가
verify.max_iterations(기본값 3)에 도달하면 exit 2로 종료합니다: 중지하고 여전히 실패하는 항목을 사용자에게 알리세요. 조용히 배포하지 마세요. 주요 변경 후 새로운 횟수를 시작하려면.verify/state.json을 삭제하세요.
VERIFY.md는 숫자를 보여줍니다: 스캔된 OCR 이미지 및 적중, 단어가 들리고 예상된 ASR 유사도, 제한 대비 지속 시간. 보고할 때 이를 인용하세요. 마지막 캡션이 읽기 쉽도록 장면은 자동으로 길어집니다. line_unread 경고가 남아 있으면 해당 장면에 더 많은 min_dur을 제공하세요.
스크립트를 실행할 때 사용자의 일반적인 HOME을 유지하세요: 임시 HOME은 npx, Playwright 및 whisper가 모든 것을 다시 다운로드하게 하고 gh/npx 인증을 깨뜨립니다.
숫자, 약어 또는 외국어의 오디오 불일치: 설정에서 language를 설정하고 내레이션에 해당 단어가 들려야 하는 방식으로 쓰세요 ("fifteen", "A P I"). 프로젝트의 VERIFY.md는 체크리스트 보고서입니다. 비디오를 전달할 때 그 요약을 포함하세요.
7. 렌더링
python3 scripts/render.py out/explainer --out out/explainer.mp4는 render.backend(local, cloud 또는 preview)를 사용합니다. render.max_mb는 업로드 제한에 맞게 다시 인코딩합니다. mp4 또는 wav 파일을 커밋하지 마세요.