Communitygithub.com

코드 애니메이션

추상적인 개념을 1~2분 분량의 애니메이션 동영상으로 제작합니다. **생성형 비디오가 아닙니다** — 모든 프레임은 브라우저에서 계산된 벡터 그래픽이며, 프레임별로 재현 가능하고 부분 수정이 가능합니다.

코드 애니메이션란 무엇인가요?

이 스킬은 코드를 사용하여 과학, 수학, 기술, 역사 등의 추상적인 개념을 설명하는 1~2분 분량의 애니메이션 동영상을 제작하는 전문 도구입니다. 생성형 AI 비디오와 달리 모든 프레임이 브라우저에서 실시간으로 계산되는 벡터 그래픽이므로, 각 프레임을 정확히 재현하고 원하는 부분만 수정할 수 있습니다. 사용자는 storyboard.json 파일을 통해 이야기 구조, 장면 템플릿, 지속 시간, 자막 등을 정의하고, 제공된 Python 스크립트로 렌더링 및 품질 검사를 수행합니다. 또한 numpy로 배경 음악을 합성하거나 사전 정의된 템플릿을 기반으로 새 장면 유형을 확장할 수 있습니다. 이 접근 방식은 모든 데이터와 아트워크를 코드 기반으로 관리하여 버전 관리, 재현성, 정밀한 편집을 보장하며, 과학 커뮤니케이션, 기술 데모, 데이터 스토리텔링에 이상적입니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Shang-en-yee/code-animation-skill/tree/HEAD

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

코드 애니메이션 워크숍 (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의 비율에 따라 조정하세요.


새 쇼트 확장하기

  1. base.html의 drawScene() 함수에 case 추가
  2. L2(본체)만 작성; L1은 polarGrid / ringTicks / axisTicks / drawInstrument, L3은 drawLeader를 사용
  3. 조정 가능한 항목을 매개변수 객체로 추출하여 templates/shots/<name>.json에 저장
  4. measure.py를 실행하여 세 가지 지표가 모두 기준을 충족해야 완료

예제

examples/gravity.storyboard.json — 2분 완성 영상 《중력》의 전체 스토리보드, 8개 쇼트 모두 실제 사용 가능. 시작점으로 직접 문구를 수정하여 사용할 수 있습니다.

관련 스킬