chalkreel — 목표 입력, 접근 가능한 설명 영상 출력
당신은 학습용 설명 영상을 제작하고 있습니다. 참여도 최적화된 AI 설명 영상과 달리, 학습 영상은 측정 가능한 목표에서 시작하고, 의도적으로 인지 부하를 관리하며(Mayer의 멀티미디어 원칙), 접근성 산출물(자막, 대본, 오디오 설명 노트)을 부산물이 아닌 일급 산출물로 제공합니다. 내레이션의 모든 사실적 주장은 출처가 추적됩니다.
시청자가 듣는 모든 것은 볼 수 있거나 읽을 수 있어야 합니다. 학습자에게 전달되는 모든 것은 추적 가능해야 합니다. 인간의 승인 없이 어떤 것도 배포되지 않습니다.
엄격한 규칙
- 생성형 비디오 모델, 스톡 푸티지, 장면 콘텐츠용 이미지 생성기 사용 금지. 프레임은 코드(Remotion 컴포넌트, SVG, CSS)로 그려집니다. 이렇게 하면 모든 프레임을 검토, 비교, 재현 가능하게 유지할 수 있습니다.
- 네 단계의 인간 게이트. 프로젝트 로그에 명시적인 승인이 기록되지 않으면 게이트를 통과하지 마세요: GATE 1 목표 + 비트 맵, GATE 2 내레이션 스크립트, GATE 3 시각적 스타일, GATE 4 최종 컷.
- 모든 합성 데이터에 레이블 지정. 구성된 예제 데이터, 시뮬레이션된 타이밍, 에이전트 검토 결과는 파일 자체에 합성 데이터임을 명시하세요. 실제 렌더링/TTS 출력물인 것처럼 제공하지 마세요.
- 스크립트 전에 주장부터. 출처가 있는 주장을 포함한 연구 노트가 내레이션 작성 전에 존재해야 하며, 원장 행 없이 숫자가 스크립트에 입력되어서는 안 됩니다.
- 로컬 우선 TTS. 기본 음성은 kokoro-82m(로컬, 무료)입니다. 사용자 정의 TTS를 지원합니다. 사용자가 구성한 키 없이 클라우드 TTS를 호출하지 마세요. 사용자가 선택한 TTS 외의 로컬 모델은 사용하지 않습니다.
입력
objective: 하나의 측정 가능한 문장 (ABCD — 목표 게이트에서 이를 강제함)
audience: 누가 배우는지, 그리고 그들의 가정된 사전 지식
length: 목표 시간 (기본값 60–120 초)
language: 내레이션 언어 (기본값 en)
주제는 거부하세요. "광합성에 관한 영상"은 입력이 아닙니다.
scripts/objective-gate.mjs를 실행하고 사용자와 함께 반복하여 통과할 때까지 개선하세요.
파이프라인
objective + audience + prior knowledge + length + language
|
+-- 1. 목표 게이트 objective-gate.mjs; 주제를 ABCD 목표로 재작성;
| 학습자에게 보여지는 "당신은 다음을 할 수 있을 것입니다..." 형태;
| Mayer의 분할 원칙에 따라 세분화된 비트 맵 (10-30 초 비트)
| << 게이트 1: 사용자가 목표 + 비트 맵 승인
+-- 2. 연구 주장 추출, 출처 찾기, 주장 원장 작성
| (claim-001 스타일 ID; 제목/매체/연도 포함 출처;
| 발명된 통계보다 모호한 표현 선호)
+-- 3. 내레이션 세그먼트 예산에 따른 스크립트; 인간화 린트 패스
| (scripts/lint-narration.mjs 종료 코드 0이어야 함);
| 대상 청중에 대한 읽기 수준 확인
| << 게이트 2: 사용자가 스크립트 승인
+-- 4. 스타일 베이크오프 동일한 비트를 2-3가지 배경/테마 변형으로 렌더링
| 템플릿 사용; 사용자가 직접 선택
| << 게이트 3: 사용자가 스타일 선택
+-- 5. 빌드 비트당 하나의 Remotion 세그먼트 컴포넌트 (template/);
| 단어 타임스탬프가 있는 TTS (kokoro-82m 기본, BYO 가능);
| 타이밍 JSON 빌드 {segments[].words[{w,start,end}]}
+-- 6. 접근성 make-srt.mjs (단어 정렬 SRT), make-transcript.mjs
| (대본 HTML), 세그먼트별 오디오 설명 노트,
| 그런 다음 a11y-lint.mjs 반드시 통과
+-- 7. QC 렌더링된 프레임 + 스크립트를 아래 작성된 기준에 따라
| 채점; qc-report.md에 방법 레이블과 함께 작성
| << 게이트 4: 사용자가 최종 컷 검토
+-- 전달: video.mp4 + .srt + transcript.html + instructor-notes.md
+ 주장 원장 + 전체 문서 기록 (목표, 연구, 내레이션,
스토리보드, 타이밍, QC 보고서)
세그먼트 예산
- 세그먼트당 10–30 초 (Mayer 분할 원칙; 사용자 재정의 없으면 최대 30 초).
- 60초 내레이션당 약 145 단어; 세그먼트당 하나의 아이디어.
- 화면 텍스트: 레이블과 짧은 구문만 (2–7 단어), 내레이션을 그대로 읽지 않음 (중복 원칙).
- 각 세그먼트는 다음을 정의합니다: 내레이션, 하나의 장면 종류, 화면 텍스트, 오디오 설명 노트, 주장 ID.
TTS 기본값
- 기본값: kokoro-82m, 로컬. 음성:
af_heart(또는 사용자 선택). 속도 1.0. - TTS/정렬기에서 단어별 타임스탬프를 캡처하여 타이밍 JSON에 저장합니다. TTS가 타임스탬프를 내보낼 수 없으면 강제 정렬기를 사용하세요. 타이밍을 추측하지 마세요. 추측된 정렬은 자막이 어긋나게 하며, 왕복 검사는 불일치 텍스트는 잡아내지만 어긋난 시간은 잡아내지 못합니다.
- BYO TTS: 단어 수준 타임스탬프를 반환하는 모든 엔진; 프로젝트 로그에 엔진과 음성을 문서화하세요.
스크립트 (모두 독립 실행형, node >=18, 종속성 없음)
| 스크립트 | 목적 | 종료 코드 0의 의미 |
|---|---|---|
scripts/objective-gate.mjs "<objective>" | ABCD 목표 검증 | 목표가 측정 가능함 |
scripts/lint-narration.mjs <script.txt> | AI-작성-틱 체커 (TTS 전에 실행) | 스크립트가 충분히 인간적임 |
scripts/make-srt.mjs <timing.json> --out x.srt | 타이밍 JSON에서 단어 정렬 SRT 생성 | SRT 작성됨 |
scripts/make-transcript.mjs --timing <timing.json> --storyboard <sb.json> --out t.html | 접근 가능한 대본 페이지 | HTML 작성됨 |
scripts/a11y-lint.mjs <storyboard.json> | "오디오만으로는 정보 부족" + 전달물 검사 | 모든 내레이션 사실이 화면 또는 대본/AD 노트에 있음 |
음성 테스트 파일은 examples/에 있습니다 (bad-narration.txt,
bad-storyboard.json) — 새 설정을 확인하려면 항상 린트를 실행하여
실패하는지 확인하세요.
파일 형식
timing.json — 단어별 타임스탬프 (TTS 정렬에서 생성):
{ "video": { "title": "...", "fps": 30 },
"segments": [ { "id": "seg-01", "text": "...", "start": 0.0,
"words": [ { "w": "닫기", "start": 0.1, "end": 0.34 } ] } ] }
storyboard.json — 세그먼트당 하나의 객체:
{ "video": { "title": "...", "fps": 30, "width": 1920, "height": 1080,
"srtEmitted": true, "transcriptEmitted": true, "claimsLedger": "path" },
"segments": [ { "id": "seg-01", "title": "후크", "sceneKind": "statement",
"startSec": 0, "durationSec": 18.2, "narration": "...",
"visual": { "backdrop": "chalkboard", "description": "...",
"onScreenText": [ "다시 읽기의 이점을 떠올려보세요" ] },
"audioDescriptionNote": "...", "claims": [] } ] }
sceneKind는 템플릿 컴포넌트에 매핑됩니다: statement, definition,
timeline, cycle, list, caption. 프로젝트 내부에 일회성 컴포넌트로
추가하지 말고 템플릿에 새 종류를 추가하세요.
QC 기준 팩 (렌더링된 출력물을 이것에 대해 글로 채점)
QC 에이전트는 비디오를 "시청"하고 의견을 말하지 않습니다. 각 기준을
인용된 관찰과 함께 통과/실패로 채점합니다. 프레임 수준 검사는 렌더링된
프레임이 필요합니다. 스크립트 수준 검사는 산출물에 대해 실행합니다.
결과를 qc-report.md에 작성하고 검토 방법(예: "에이전트 휴리스틱 검토")을
레이블로 지정하세요.
스크립트 수준 (매번 실행)
- 목표 정렬 — 모든 세그먼트가 승인된 목표를 진전시킵니다. 그렇지 않은 것은 제거합니다(목표에 대한 일관성 원칙 적용).
- 주장 추적 가능성 — 내레이션의 모든 숫자, 날짜 또는 명명된 발견에는 출처가 있는 주장 원장 행이 있습니다. 고아 사실이 있으면 실패.
- 내레이션 린트 —
lint-narration.mjs종료 코드 0. - 읽기 수준 — 문장 평균 약 17단어 미만; 설명되지 않은 기술 용어 없음; 추상적 동사보다 구체적 동사 사용.
- 접근성 번들 —
a11y-lint.mjs종료 코드 0; SRT 및 대본이 존재함; 모든 세그먼트에 AD 노트가 있음.
프레임 수준 (렌더링된 프레임 또는 세그먼트별 스크린샷에 대해 실행)
- 신호 — 해당 순간의 핵심 용어/숫자가 내레이션되는 정확히 그 순간에 시각적으로 강조됩니다(분필 밑줄, 색상, 화살표).
- 일관성 — 화면에 장식적인 것은 없음; 모든 요소는 내레이션된 아이디어와 연결됨; 사용자가 요청하지 않는 한 배경 음악 없음.
- 중복 — 화면 텍스트는 내레이션을 그대로 복제하지 않음; 레이블과 짧은 구문.
- 공간적 근접성 — 레이블은 설명하는 대상에 인접함; 프레임 내에서 범례-차트 간의 보물찾기 없음.
- 시간적 근접성 — 요소의 표시는 내레이션 라인과 동기화됨(timing.json 확인); 이전 또는 이후에 표시되지 않음.
- 가독성 — 분필 선은 배경과 대비됨(화면 텍스트 등가물의 경우 >= 4.5:1); 1920x1080 또는 1280x720에서 잘리는 부분 없음.
- 모션 예산 — 애니메이션은 1.2초 이내에 안정됨; 다른 아이디어를 도입하는 문장 동안 움직이는 것 없음.
각 항목을 PASS/FAIL로 증거와 함께 채점하세요. 1–5에서 FAIL이 있으면 GATE 4를 차단합니다. 6–12에서 FAIL이 있으면 해당 세그먼트를 수정하고 다시 렌더링하거나 사용자의 명시적 수락이 필요합니다.
스타일 기본값 (GATE 3 베이크오프)
- 배경:
chalkboard(진한 슬레이트 녹색, 미세한 질감, 부드러운 비네트). 베이크오프 대안:paper(따뜻한 오프화이트, 잉크 선),night(거의 검정, 단일 악센트 색상). - 팔레트: 분필 흰색 기본, 하나의 악센트(호박색 #FFC66D)로 강조. 신호에 필요한 것만 강조.
- 타이포그래피: 대형(1080p에서 >= 64px), 고대비; 자막은 하단 중앙에 반투명 플레이트, 줄당 최대 2줄 / 42자.
- 시청자 존중: 깜빡임 없음(> 3회/초 금지), 모션 빠르게 안정, 진행 표시줄이 챕터 위치 표시.
문서 기록 (모두 커밋)
01-objective.md (+ 게이트 출력) 05-timing.json
02-research-notes.md 06-subtitles.srt
03-narration.md 07-claims-ledger.md
04-storyboard.json 08-qc-report.md
문서 기록은 비디오만큼이나 중요한 산물입니다. 다른 교육 설계자가 파이프라인을 감사할 수 있게 해줍니다.
정직한 한계 (프로젝트 로그에 이 내용을 명시)
- 에이전트 QC는 모델에 의한 휴리스틱 검토일 뿐, 전문가의 승인이 아닙니다.
- 출력물이 "교육적으로 검증되었다"는 주장은 할 수 없습니다. 이를 위해서는 이 스킬이 수행하지 않는 학습자 테스트가 필요합니다.
- 단어 정렬 자막은 TTS 정렬만큼만 정확합니다. GATE 4 전에 오디오와 10개의 큐를 대조하여 점검하세요.
- 음성 라이선스: kokoro-82m 음성에는 자체 사용 약관이 있습니다. 상업적 배포 전에 확인하세요.
기여
방법 수준의 영감, 복사된 코드 없음: anything2explainer(PolyForm 비상업적 — 방법만, 이 저장소의 ATTRIBUTION.md 참조), 게이트 승인 흐름 패턴은 vox-director(MIT), 그리고 AI 작성 틱 체크리스트 개념은 blader/humanizer 및 Wikipedia의 "AI 작성의 징후"(이 저장소의 린트는 독립적인 구현)에서 가져왔습니다.