내레이션 포함 데이터 레슨
참조 예제와 같은 레슨을 만듭니다 (예: '우리가 나이별로 누구와 시간을 보내는지'): 라이브 차트 위에서 재생되는 내레이션 비디오와, 학습자가 데이터를 가지고 놀 수 있는 탐색 탭을 제공합니다. 하나의 레슨 = index.html, lesson.json, data.json, video.json(스토리보드), 내레이션 오디오, 그리고 선택적 배경 음악이 포함된 하나의 폴더입니다.
먼저 읽으세요: 참조/디자인-규칙.md (승인된 디자인, 움직임 및 강조 규칙; 정확히 따르세요) 및 참조/사용자-가이드.md (사용자와 작업하는 방법).
아래 경로는 이 스킬의 폴더를 기준으로 합니다 (${CLAUDE_SKILL_DIR}).
작업 대상 사용자
사용자가 기술적이지 않다고 가정하세요. 평이하게, 한 번에 한 단계씩 말하고, 무언가 클릭이 필요할 때(파일 다운로드, ElevenLabs 로그인, 대본 승인 등) 무엇을 클릭해야 하는지 정확히 알려주세요. 코드나 JSON을 편집하도록 요청하지 마세요. 참조/사용자-가이드.md의 안내를 사용하세요.
워크플로우 (체크포인트 및 자체 점검 포함)
모든 단계 끝에 자체 점검을 실행하세요. 실패(FAIL)가 발생하면 다음 단계로 넘어가지 마세요.
1. 데이터 가져오기
- 링크, 파일 또는 PDF를 받습니다. 링크가 차단된 경우(사이트에서 자동 다운로드를 차단하는 경우가 많음), 사용자에게 브라우저에서 다운로드하고 파일을 공유하도록 안내합니다.
- 프로파일링:
python3 scripts/profile_data.py <파일-또는-URL>
2. 적합한가? (항상 사용자에게 알림)
프로파일러의 판정과 참조/차트-선택기.md를 읽고, 사용자에게 평이한 언어로 알려주세요:
- 적합: "이 데이터는 ___ 차트로 작동합니다. 이유는 ___ 때문입니다." 답변하는 학습 질문을 명시합니다.
- 부분 적합: 무엇이 작동하고, 무엇이 부족하며, 절충점이 무엇인지 설명합니다.
- 부적합: 명확하게 말하고, 이유를 설명하며, 어떤 데이터가 작동할지 설명합니다. 억지로 맞추지 마세요.
✋ 체크포인트 1: 차트 유형과 스토리 각도
차트 유형, 주요 학습 질문, 그리고 4~6개의 스토리 비트(내레이터가 지적할 사항)를 제안합니다. 각 비트는 계산할 숫자와 연결됩니다. 사용자의 승인을 기다리세요.
3. 데이터 형태 만들기
- 레슨 폴더 시작:
python3 scripts/new_lesson.py --chart <유형> --out <폴더> - 레슨 폴더에 작고 재실행 가능한 스크립트를 작성하여, 소스 데이터를 차트 형식의
data.json(참조/데이터-형식.md)으로 변환하고 동시에facts.json을 작성합니다. 여기에는 내레이터가 말할 모든 숫자가 소스 데이터에서 계산되어 포함되며, 어떻게 발화될지도 명시합니다. - 자체 점검:
python3 scripts/check_lesson.py <폴더>; 또한 2~3개 값을 소스 데이터와 수동으로 대조 확인합니다(원본 파일을 열어 찾음). 확인한 내용을 보고합니다.
4. 이야기 쓰기
video.json(장면, 비트, 큐)을 참조/스토리보드.md와 디자인-규칙 §1(도입 훅 → 차트 읽는 방법 → 스토리 비트 → 요약 → 성찰 → '당신 차례')의 스토리 아크에 따라 작성합니다.- ElevenLabs 스타일(참조/내레이션.md)로 내레이션 대본을
narration/script.txt에 작성합니다. 모든 주장은facts.json과 일치해야 하며, 과장하지 않아야 합니다(디자인-규칙 §8). lesson.json을 작성합니다: 제목, 킬러, 키 레이블, 그룹 설명, 노트, 출처.
✋ 체크포인트 2: 대본 승인
대본을 일반 텍스트로 보여줍니다. 사용자가 요청할 때 옵션을 제공하고, 승인하지 않은 변경 사항은 적용하지 마세요.
5. 미리보기 (녹음 전)
- 무음 미리보기:
python3 scripts/estimate_timing.py <폴더>/video.json --out <폴더>/narration/narration.words.json그 다음python3 scripts/time_storyboard.py <폴더>/video.json <폴더>/narration/narration.words.json - 서빙하고 열기:
python3 scripts/devserver.py 8123(레슨 폴더의 상위 폴더에서 실행), 그 다음http://localhost:8123/<레슨>/ - 자체 점검 (브라우저): 참조/자체-점검.md을 따릅니다: 모든 비트에서 스크린샷, 겹치는 요소 없음, 콘솔 오류 없음, 모든 명명된 항목이 해당 단어에서 강조 표시됨.
6. 내레이션 및 음악 (사용자의 ElevenLabs 계정 필요)
- 사용자를 로그인 절차로 안내합니다(사용자-가이드.md → ElevenLabs). 설정: 음성 Quentin – Narrator and Educator, Eleven v4, 안정성 ≈ 80%, 영어; 전체 대본을 한 번에 녹음합니다.
narration/narration.mp3로 저장합니다. - ElevenLabs가 없습니까? 무료 플레이스홀더를 제공합니다:
python3 scripts/placeholder_voice.py <폴더>(Mac). - 단어 시간 맞추기:
python3 scripts/align_narration.py <폴더>/narration/narration.mp3 --out <폴더>/narration/narration.words.json, 그 다음time_storyboard.py를 다시 실행합니다. 단어 매칭률 ≥ 99%를 목표로 합니다. - 음악 (선택 사항, ElevenLabs Music, 악기, 차분함, 약 2분):
prep_music.py로 준비합니다. 비디오가 트랙보다 길면,find_loop.py+extend_music.py로 확장합니다(내레이터 아래에서 음악이 끝나거나 반복되지 않도록 합니다). - 자체 점검:
check_lesson.py(오디오 길이, 사실) + 브라우저에서 전체 재생.
✋ 체크포인트 3: 함께 검토
완성된 레슨을 사용자와 함께 살펴봅니다: 무엇을 확인해야 하는지, 탐색 탭을 사용하는 방법을 설명합니다. 사용자가 요청하는 변경 사항을 적용하고, 각 변경 후 자체 점검을 다시 실행합니다.
7. 공개 (선택 사항)
GitHub Pages 또는 모든 정적 호스트(사용자-가이드.md → 공개)를 통해 사용자를 안내합니다. 레슨 폴더는 독립적입니다.
자체 점검 규칙 (항상)
- 3, 4, 5, 6단계 후 및 모든 수정 후에
scripts/check_lesson.py를 실행합니다. - 시각적 변경 후 브라우저에서 확인합니다: 내레이션 시점에 스크린샷을 찍고 스토리보드와 비교합니다. 확인한 내용을 말합니다.
- 모든 내레이션 숫자를 소스 데이터에서 다시 계산하고, 기억에서 숫자를 입력하지 마세요.
- 무언가 실패하면 고치고 사용자에게 완료되었다고 말하기 전에 다시 확인합니다.
참조 파일
| 파일 | 용도 |
|---|---|
| 참조/디자인-규칙.md | 외관, 움직임, 강조, 내레이션, 동기화, 음악, 데이터 정직성 |
| 참조/차트-선택기.md | 어떤 차트가 어떤 질문에 적합한지, 적합 기준 |
| 참조/데이터-형식.md | 네 가지 data.json 형식 |
| 참조/스토리보드.md | video.json: 차트 유형별 장면, 비트, 큐, facts.json |
| 참조/내레이션.md | 대본 스타일, ElevenLabs 설정, 타이밍, 음악 |
| 참조/자체-점검.md | 각 단계에서 확인할 사항 |
| 참조/사용자-가이드.md | 사용자를 위한 평이한 언어 안내 |
| 참조/차트-인터페이스.md | 새 차트 유형 추가 방법 |