강의 비디오
당신은 학생의 강의 자료를 학습용 비디오로 만듭니다. 이 스킬의 핵심 규칙은 다음과 같습니다:
모든 숫자, 예제, 주장은 학생의 강의 자료에서만 가져옵니다. 어떤 것도 임의로 만들어내지 않습니다. 학생들은 이 비디오를 자신의 교수님이 채점하는 시험을 준비하는 데 사용합니다. 임의로 만든 숫자를 사용한 "더 좋은" 예제, 다른 표기법의 수식, 또는 강의 외부의 사실은 비록 올바른 경제학/물리학 등이라 하더라도 버그입니다.
0. 요구 사항 (한 번 확인)
python3 -m pip install -r requirements.txt && python3 -m playwright install chromium
ffmpeg -version | head -1 # brew install ffmpeg / apt install ffmpeg
선택 사항: 3D 장면과 마스코트 발표자를 위한 Blender 4.2+ (BLENDER=/path/to/blender (PATH에 없을 경우)), PDF 슬라이드 읽기를 위한 pdftotext (poppler) 또는 pip install pypdf, 녹음 파일 변환을 위한 openai-whisper, Grok 음성을 위한 XAI_API_KEY (그렇지 않으면 무료 Microsoft 신경망 음성이 사용됩니다).
1. 자료 수집
<course>/sources/ 폴더를 만들고 강의 자료만 넣습니다:
강의록 (.txt/.srt/.vtt), 슬라이드 (.pdf 또는 내보낸 텍스트), 학생의 노트, 문제 세트, 연습 시험.
- 녹음본만 있고 대본이 없는 경우 →
whisper lecture.mp4 --model base --output_format txt --output_dir sources/ - .docx →
textutil -convert txt file.docx(macOS) 또는pandoc file.docx -t plain -o file.txt - 학생에게 어떤 강의/주제를 비디오로 다룰지 물어보세요. 요청하지 않았다면 다른 주의 자료를 추가하지 마세요.
쓰기 전에 모든 자료를 완전히 읽으세요. 교수님의 정확한 표기법, 용어, 예제 풀이 및 숫자를 기록하세요.
2. 스크립트 작성 (content JSON)
engine/SCHEMA.md (시각적 유형, 큐 워드, 퀴즈 형식, 레이아웃 제한)에 따라 <course>/<name>.json을 작성하세요.
examples/lemonade/는 완전한 소규모 예제입니다.
규칙:
- 예제: 강의 자체의 예제 풀이와 동일한 숫자를 사용하세요. 강의에서 "가격 $4, 3개"라고 한다면 비디오에서도 "가격 $4, 3개"여야 하며 "가격 $10, 5개"가 아니어야 합니다.
- 퀴즈: 강의의 연습 문제, 클리커 질문 또는 예제 풀이에서 가져오세요. 새 질문을 작성해야 한다면 자료에 있는 숫자만 사용하고, 퀴즈 레이블에 그 사실을 명시하세요 ("시험 문제"가 아닌 "연습").
- 파생된 숫자 (계산한 총계, 차이 등)는 괜찮지만, 각각을 최상위
"derived"맵에 산술식과 함께 선언하고 자료의 숫자만 사용하세요:"derived": {"16": "4 * 4", "-6": "120 - 126"}. - 데이터가 아닌 작은 숫자 ("기억할 세 가지", "2단계")는
"allow": ["3"]에 넣으세요. 0과 1은 항상 허용됩니다. - 표기법과 용어: 교수님의 것을 사용하세요 (강의에서 "MR = MC"라고 썼다면 "∂R/∂q"로 바꾸지 마세요).
- 비디오에 필요한 사실이 자료에 없는 경우, 멈추고 학생에게 자료를 요청하거나 그 부분을 생략하세요. 일반 지식으로 빈칸을 채우지 마세요.
- 내레이션 (
say)은 듣기 좋게 작성하세요: 기호가 아닌 단어로 ("4 곱하기 4는 16달러").
3. 모든 숫자를 자료와 대조 확인 (필수, 빌드 전)
python3 tools/check_sources.py <course>/<name>.json <course>/sources --report <course>/<name>.sources.md
이 도구는 내레이션, 화면 텍스트, 퀴즈 옵션 및 3D 장면 레이블에서 모든 숫자를 추출하여 각각을 자료에서 찾습니다 (숫자 또는 철자 표기, 예: "one hundred twenty"). 파생된 숫자는 다시 계산하고 그 피연산자를 확인합니다. 빌드 전에 반드시 종료 코드 0이어야 합니다. 각 문제에 대해 보고합니다:
- 숫자가 오타이거나 임의로 만들어진 경우 → 자료의 숫자를 사용하도록 스크립트를 수정하세요.
- 실제 계산인 경우 →
"derived"에 추가하세요. - 도구가 놓친 형태로 자료에 있는 경우 (예: 이미지 내) → 학생에게 확인을 요청한 후
"derived"또는"allow"에 답변에 메모를 추가하세요.
그런 다음 보고서의 증거(Evidence) 섹션을 직접 읽어 각 숫자가 자료와 동일한 의미로 사용되었는지 점검하세요 (도구는 값만 대조하고 의미는 대조하지 않습니다: "$40" 가격과 "40 units" 수량은 구분됩니다).
4. 빌드 및 렌더링
cd engine
python3 build.py ../<course>/<name>.json # 음성, 타이밍, 자막, 음악 (TTS=xai XAI_API_KEY=... for Grok)
python3 lint.py build/<video-id>/spec.json # 늦게 도착하는 시각 요소 확인
python3 qa.py <video-id> # 모든 장면의 스틸 이미지 + 연속 시트: 확인하세요
OUT=../out python3 render.py <video-id> --workers 6 # 전체 1080p 렌더링 -> ../out/<video-id>.mp4 + .srt
렌더링 전에 QA 연속 시트를 확인하세요: 텍스트 겹침, 빈 화면, 화면 상의 잘못된 숫자 등.
5. 선택 사항: 3D 장면, 마스코트, 효과음
"v": {"type": "clip", "scene": "<name>"}이 포함된 비트는 engine/blender/scene_defs/<name>.py의 Blender 장면을 재생합니다
(engine/blender/scenelib.py의 docstring 참조; market.py와 safe.py는 경제학 강의용으로 작성된 전체 예제이므로 레이블에 해당 강의의 숫자가 포함되어 있습니다. 레이블을 자료에 맞게 변경하세요).
장면 레이블은 check_sources.py에서도 확인됩니다.
cd engine
python3 blend.py prep <video-id> # 마스코트 타임라인 + 장면별 입력
python3 blender/stills.py <scene> --dry # 빠르게 오류 감지, 그 다음 --dry 없이 스틸 이미지 생성
python3 blend.py clips <video-id> # 3D 장면 렌더링 (느림: 장면당 몇 분)
python3 blend.py mascot <video-id> && python3 blend.py pack <video-id>
python3 sfx.py mix <video-id> # 내레이션 아래 효과음 혼합
OUT=../out python3 blend.py comp <video-id> # -> ../out/<video-id>-3d.mp4
OUT=../out python3 blend.py site <id1>,<id2> --title "내 강의" --out ../out/site # 챕터가 있는 웹 페이지
렌더링은 느리고 디스크를 많이 사용합니다 (비디오당 수 GB의 프레임). 먼저 여유 공간을 확인하고, 랩탑에서는 한 번에 하나씩 장면을 렌더링하며, 기기가 절전 모드로 전환되지 않도록 하세요.
6. 인계
학생에게 다음을 알려주세요: 비디오 위치, 길이, 다루는 강의, 자료 확인 결과 (확인된 숫자, 파생 또는 허용된 숫자). 자료에 모호한 점이 있었다면 어떤 가정을 했는지 말해주세요. 비디오는 자료를 바탕으로 만든 학습 보조 도구이며 강의를 대체하지 않는다는 점, 그리고 강의 자료가 학생의 게시 권한이 아닐 수 있으므로 공개 게시 전에 확인해야 한다는 점을 상기시키세요.