코드 애니메이션 워크숍 (Code Animation)
추상적인 개념을 1~2분 분량의 애니메이션 동영상으로 제작합니다. 생성형 비디오가 아닙니다 — 모든 프레임은 브라우저에서 계산된 벡터 그래픽이며, 프레임별로 재현 가능하고 부분 수정이 가능합니다.
산출물은 MP4 파일과 재사용 가능한 storyboard.json 파일입니다.
세 단계 워크플로우
# 1. 스토리보드 검증
python scripts/lint.py storyboard.json
# 2. 빌드 + 렌더링 (약 0.5초/프레임)
python scripts/build.py storyboard.json out.html
python scripts/render.py --html out.html --duration 117 --fps 30 --out film.mp4
# 3. 품질 검사, 불합격 시 0이 아닌 값 반환
python scripts/measure.py film.mp4 --thresholds reference/thresholds.json
품질 검사를 통과하지 못하면 수정하세요. "대충 봐서 괜찮아 보인다"는 기준으로 승인하지 마세요.
배경 음악 추가 (선택 사항이지만 강력히 권장)
오디오도 계산되어 생성됩니다. 어떤 샘플 라이브러리도 사용하지 않습니다 — 영상과 동일한 원칙입니다.
# 1. 배경 음악 합성 (numpy, 약 40초)
python scripts/make_audio.py score.wav --storyboard storyboard.json
# 2. 비디오에 오디오 합성, 동시에 H.264로 변환하여 파일 크기 압축
python scripts/mux.py --video film.mp4 --audio score.wav --out final.mp4 --crf 23
기본 배경 음악은 우주/물리 주제에 맞춰져 있습니다: D단조 장음 패드 + 장면 전환마다 코드가 바뀌는 패드 + 8초 간격 심박 펄스 + 드문撥弦, 전환부에는 노이즈 스윕, 챕터 구분에는 저음역 타점이 있습니다.
주제가 바뀌면 음악 매개변수를 변경해야 하며, 기본 설정을 그대로 사용하지 마세요:
| 주제 | 배경 음악 수정 방법 |
|---|---|
| 물리 / 천문 | 기본 설정 유지: 단조, 장음, 드문 편성 |
| 수학 / 알고리즘 | 장조 또는 리디아 선법으로 변경, 규칙적인 아르페지오 추가 |
| 역사 / 인문 | 펄스 제거, 패드 속도 감소, 약간의 불협화음 추가 |
| 제품 / 기술 | 패드 장음 제거, 90–110 BPM 신디사이저 리듬으로 변경 |
매개변수는 모두 make_audio.py 상단의 SCALE / ROOT / bpm 세 상수와 build() 함수 내 chords 배열에 정의되어 있습니다.
storyboard.json
{
"title": "중력",
"fps": 30,
"palette": { "bg": "#08090F", "ink": "#E6DCCB", "dim": "#8A8177", "accent": "#E0813C" },
"scenes": [
{
"id": "open",
"kind": "title",
"dur": 6.0,
"cn": "중력",
"en": "GRAVITY"
},
{
"id": "newton",
"kind": "orbit",
"dur": 16.0,
"chapter": ["I", "사과와 달", "THE APPLE AND THE MOON"],
"subs": [
[0.6, "1687년, 뉴턴은 하나의 공식으로 사과와 달을 묶어냈다."],
[7.4, "중력은 질량에 비례하고 거리의 제곱에 반비례한다."]
]
}
]
}
| 필드 | 설명 |
|---|---|
kind | 쇼트 템플릿 이름, 아래 표 참조 |
dur | 해당 쇼트 길이(초), 12–20초 권장 |
chapter | [번호, 한국어, ENGLISH], 좌측 상단에 항상 표시 |
subs | [시작 시간(초), 텍스트] 배열; 화면당 5–6초 체류 권장 |
cn / en | 제목 유형 쇼트에 사용 |
쇼트 템플릿 (8개)
| kind | 화면 | 용도 |
|---|---|---|
title | 큰 글자 + 영어 소제목 | 도입부 |
outro | 두 줄 결론 | 마무리 |
orbit | 타원 궤도 + 극좌표 그리드 | 주기 운동, 중력 |
precess | 세차 운동 꽃잎선 + 각도 눈금판 | 미세 편차, 세차 운동 |
elevator | 사각 상자 + 내부 눈금 | 기준 좌표계, 등가 원리 |
warp | 원근 시공간 그리드 + 안내선 주석 | 휨, 장(field) |
evidence | 렌즈 동심원 + 처프(chirp) 파형 | 증거, 신호 |
blackhole | 강착 원반 + 광자 고리 + 원형 눈금 | 극한 천체 |
템플릿 매개변수는 templates/shots/*.json 파일을 참조하세요.
6계층 아키텍처 (이 순서로 배치하는 이유)
L5 후처리 bloom → 비네트 → 노이즈
L4 텍스트 챕터 제목 / 큰 글자 / 수식 / 자막
L3 주석 안내선 + 소형 레이블 + 수치 표시 상자
L2 본체 해당 쇼트의 핵심 그래픽
L1 구조 그리드 / 눈금 / 좌표축
L0 배경 성운 / 점 패턴 / 먼지 / 먼 별
전문성의 원천은 L2가 아니라 L1과 L3입니다. 본체만 있는 화면은 초라해 보입니다. 구조 레이어와 주석 레이어를 추가하면 같은 그림이 즉시 "계측기 인터페이스"로 변합니다.
base.html은 6개 레이어를 모두 구현하고 있으며, 새 쇼트를 추가할 때는 L2의 그리기 함수만 작성하면 됩니다.
승인 기준
reference/thresholds.json:
{
"frame_diff_min": 1.5,
"moving_ratio_min": 0.70,
"coverage_min": 0.20,
"luma_range": [16, 30]
}
| 지표 | 의미 | 이유 |
|---|---|---|
frame_diff | 인접 프레임 평균 차이 | 1.5 미만이면 "슬라이드쇼"이지 애니메이션이 아님 |
moving_ratio | 움직임이 있는 프레임 비율 | 70% 미만이면 "멈춘" 느낌이 듦 |
coverage | 국소 구조를 가진 픽셀 비율 | 20% 미만이면 화면이 비어 보임 |
luma | 평균 밝기 | 16 미만이면 구조가 모두 검은색에 묻힘; 30 초과는 어두운 톤의 분위기를 잃음 |
이 기준은 실제 참조 영상으로 보정된 값이므로, 함부로 올리지 마세요. 자세한 내용은 reference/findings.md를 참조하세요.
알려진 함정 (피와 눈물)
1. 절대 ctx.shadowBlur를 사용하지 마세요.
소프트웨어 렌더링에서 수십 개의 프레임별 그림자는 단일 프레임 시간을 20ms에서 5초로 늘립니다. base.html의 bloom()을 사용하세요 — 캔버스를 1/6 크기로 축소한 후 확대하여 오버레이하는 방식으로, 두 번의 drawImage 호출로 거의 무료입니다.
2. 매개변수는 동일한 소스에서 가져와야 합니다.
이전에 "질점이 선 밖으로 나가는" 버그가 있었습니다: 선은 p²로 계산하고 점은 p로 계산한 경우였습니다. 동일 요소의 경로와 헤드는 반드시 동일한 변수로 구동되어야 합니다.
3. 노이즈가 파일 크기를 결정합니다. 프레임별 무작위 노이즈는 엔트로피가 매우 높아 비디오 코덱이 압축하기 어렵습니다. 노이즈 α=0.03일 때 1080p30에서 약 50KB/프레임 — 2분 분량은 약 300MB입니다. 크기를 줄이려면 α를 낮추거나(약 0.015) 프레임 속도를 낮추세요. 코덱에 의존하지 마세요.
4. 프레임 형식은 JPEG를 사용하고 PNG는 사용하지 마세요. 노이즈가 있는 PNG 인코딩 시간은 JPEG의 4배 이상입니다(실측 2.0초/프레임 vs 0.5초/프레임).
5. 밝기는 필터가 아닙니다.
CSS brightness()를 사용하여 밝기를 높이지 마세요 — 텍스트도 함께 하얗게 날아갑니다. 밝기를 높이려면 콘텐츠 레이어의 알파(그리드, 성운, 먼지)를 reference/palette.json의 비율에 따라 조정하세요.
새 쇼트 확장하기
base.html의drawScene()함수에case추가- L2(본체)만 작성; L1은
polarGrid/ringTicks/axisTicks/drawInstrument, L3은drawLeader를 사용 - 조정 가능한 항목을 매개변수 객체로 추출하여
templates/shots/<name>.json에 저장 measure.py를 실행하여 세 가지 지표가 모두 기준을 충족해야 완료
예제
examples/gravity.storyboard.json — 2분 완성 영상 《중력》의 전체 스토리보드, 8개 쇼트 모두 실제 사용 가능. 시작점으로 직접 문구를 수정하여 사용할 수 있습니다.