Communitygithub.com

Kanban Motion

코드 기반 모션 그래픽 비디오를 제작 및 편집합니다: 프로젝트, 웹사이트 또는 스크립트로부터 론칭 비디오, 설명 영상, 프로모션 영상을 생성하며, 음성 해설(생성 또는 녹음), 배경 음악, 사운드 효과가 단어 단위로 동기화됩니다. Motion as Code 키트(음성 동기화 플레이트, 미리보기, 스틸, 렌더링, SFX 믹스) 또는 번들 스타터 키트와 함께 작동합니다.

Kanban Motion란 무엇인가요?

Kanban Motion은 개발자가 TypeScript나 JavaScript로 모션 그래픽 비디오를 코딩할 수 있게 해주는 AI 에이전트 스킬입니다. After Effects 없이도 모든 프레임이 시간의 순수 함수인 '플레이트(plate)'를 사용하여, 음성 해석의 단어 단위 타이밍에 맞춰 애니메이션을 작동시킵니다. Claude Code, Cursor, Codex 등 코드 지원 AI 어시스턴트와 함께 사용하도록 설계되었으며, 브라우저 미리보기와 최종 MP4 출력이 완전히 동일하게 보장됩니다. 이 스킬은 두 가지 워크플로우를 제공합니다: 완전히 구축된 Motion as Code 키트(three.js, bun, Vite, ffmpeg 기반)와, 의존성이 없는 간단한 스타터 키트(Node.js, Chrome, ffmpeg만 필요)입니다. 두 키트 모두 음성 해석 생성(Kokoro 오픈 웨이트 모델), 단어 정렬(faster-whisper), CC0 사운드 라이브러리, 배경 음악 생성, 론칭 비디오 기획(사용자 프로젝트 검사, 계획, 톤 설정) 및 최종 배포(포스터 프레임, 공유 카피) 기능을 제공합니다. 사용자는 단순히 '모션 그래픽을 만들어 줘' 또는 '이 웹사이트를 론칭 비디오로 만들어 줘'와 같은 자연어 명령으로 비디오 제작을 시작할 수 있습니다. AI 에이전트는 사용자의 파일 구조를 검사하고, 적절한 키트를 선택하며, 스크립트를 작성하고, 음성을 생성하고, 모든 것을 단어 수준까지 동기화한 후 최종 비디오를 렌더링합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/4waiz/kanban-motion/tree/HEAD/skills/kanban-motion

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

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

문서

Kanban Motion은(는) 무엇을 하나요?

Kanban Studios 제작. 코드로 작성되고 음성에 고정된 모션 그래픽입니다. 이 스킬은 두 개의 레이어로 구성됩니다:

  1. Motion as Code (아래, 변경 없음): Motion as Code 키트의 전체 워크플로우입니다.
  2. Kanban Motion 추가 기능 (그 뒤): 외부 프로젝트가 필요 없는 스타터 키트, 음성 해설 생성 및 단어 정렬, 론칭 비디오 기획(검사, 계획, 톤, 크리에이티브 법칙), 오리지널 배경 음악, CC0 사운드 라이브러리 및 믹서, 그리고 최종 배포(포스터 프레임 및 공유 카피)를 제공합니다.

사용자가 키트를 가지고 있거나 편집 중일 때는 키트를 사용하고, 그렇지 않으면 스타터 키트를 사용하세요. 두 경우 모두 동일한 규칙이 적용됩니다: 플레이트는 시간의 순수 함수이며, 렌더링 전에 스틸을 확인하고, 전체 렌더링 전에 반드시 물어보세요.

Motion as Code

After Effects 없이 코드로 모션 그래픽을 만들고 음성 해설에 고정하는 워크플로우입니다. 각 장면( "플레이트" )은 모든 프레임을 시간의 순수 함수로 그리는 TypeScript 파일입니다. 음성 해설의 단어 수준 타이밍이 각 플레이트의 애니메이션 시점을 결정합니다. 브라우저 미리보기와 내보낸 MP4는 동일합니다.

출력: 1920x1080, 60fps. 스택: TypeScript + three.js, bun + Vite, headless Chrome + ffmpeg.

키트 위치

프로젝트 폴더는 사용자 Documents 폴더 안의 Motion_as_kit입니다(Windows PC의 경우 C:\Users\awaiz\OneDrive\Documents\Motion_as_kit). 폴더에 접근할 수 없거나 이동된 경우 사용자에게 위치를 물어보세요. 폴더 구조를 정확히 유지하세요: 스크립트는 상대 경로를 사용합니다.

세션의 첫 번째 변경 전에 README.md, app/src/timeline.ts, 그리고 app/src/engine/scene.ts를 읽으세요.

요구 사항 (사용자 머신)

  • bun (bun.sh): 패키지 설치 및 스크립트 실행
  • Google Chrome: 렌더러가 헤드리스 모드로 구동합니다 (BROWSER_CHANNEL을 설정하여, 예: msedge, 다른 브라우저 사용 가능)
  • libx264가 포함된 ffmpeg
  • Python + uv: 새 음성 해설 재정렬 또는 SFX 믹스 재구축에만 필요하며, python -m uv로 실행합니다.

app/node_modules는 제공되지 않습니다. app/ 내에서 bun install을 먼저 실행하세요.

레이아웃

경로역할
audio/voiceover.mp3음성 해설
audio/sfx/28개의 사운드 효과 (name_1.mp3, name_2.mp3는 대체 테이크)
data/lyrics.json단어 수준 타이밍, analysis/align_vo.py로 생성 (CTC 강제 정렬, wav2vec2 ONNX)
data/audio.json음성 음량 엔벨로프, 단어 시작점, 기본 비트 그리드, analysis/audio_vo.py로 생성
analysis/sfx_mix.py큐 시트 (~500 큐) 및 SFX 믹서
app/src/engine/pdoom-video 엔진. 편집하지 마세요.
app/src/scenes/_vo.ts공유 툴킷: 2D 카메라, 플로터 펜, 월드 공간 가라오케 단어, 그래프 용지
app/src/scenes/*.ts플레이트들
app/src/timeline.ts각 플레이트 재생 시점; 컷은 각 대사 직전의 일시 정지에 위치
app/scripts/render.ts오프라인 렌더러: headless Chrome -> raw 프레임 -> ffmpeg
out/렌더링 결과물

제공되는 데모는 9개의 플레이트로 구성됩니다: hook, model, prompt, crazy, code, frames, pipeline, edits, verdict (총 92.6초; verdict는 프레임 0으로 되돌아갑니다).

규칙

  • 플레이트의 모든 것은 시간의 결정론적 함수여야 합니다. 시드 없는 Math.random(), 실제 시간, 시크 시 리셋되지 않는 상태를 사용하지 마세요.
  • app/src/engine/을 편집하지 마세요.
  • 사용자에게 먼저 묻지 않고 전체 렌더링을 실행하지 마세요. 절대 4K 렌더링을 실행하지 마세요. 작업 확인에는 스틸을 사용하세요.
  • 각 변경 사항을 적용하기 전에 한두 문장으로 설명하세요.
  • 프로젝트와 함께 LICENSE.pdoom-engine을 유지하세요 (엔진 및 시각적 스타일은 mexicat의 pdoom-video, MIT 라이선스).

워크플로우

1. 미리보기 (빠른 루프)

cd app
bun install      # 처음 한 번만
bunx vite        # http://localhost:5173

편집 내용이 핫 리로드됩니다. 키: space 재생/일시정지, left/right 1초 탐색 (shift 누르면 5초), , . 한 프레임씩 이동, [ ] 이전/다음 플레이트, l 플레이트 반복, h UI 숨기기. URL에 ?t=35를 추가하면 35초부터 시작합니다.

2. 편집 중 스틸 확인

cd app
bun scripts/render.ts stills --t 12.5,40.2 --only code --out ../out/wip

단일 프레임을 렌더링합니다 (여기서는 code 플레이트의 12.5초와 40.2초 지점). 스틸을 보고 전체 렌더링을 제안하기 전에 사용자에게 보여주세요.

3. 비디오 렌더링 (먼저 물어보기)

cd app
bun run render

bun scripts/render.ts video --samples auto --min-samples 4 --max-samples 12 --shutter 0.5 --crf 17 --out ../out/motion-as-code.mp4와 동일합니다.

  • --samples 4: 약 4배 빠른 드래프트; 빠른 움직임에서 계단식 복사본이 보일 수 있음
  • --samples auto: 움직임이 빠른 곳에서 더 많은 서브 프레임 사용 (기본값)
  • --scale 2: 4K (3840x2160)

4. 사운드 효과

재렌더링 불필요: 믹스를 재구축한 다음 영상을 복사하고 오디오를 추가하세요. 프로젝트 루트에서 실행합니다.

python -m uv run --no-project --with numpy python analysis/sfx_mix.py
cd out
ffmpeg -i motion-as-code.mp4 -i mix.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 320k -shortest motion-as-code_sfx.mp4

효과는 음성 아래에서 최대 7dB까지 음량이 낮아집니다(ducking); 믹스는 -14 LUFS로 노멀라이즈됩니다. 효과의 음량을 변경하려면 큐 시트에서 해당 db 값을 편집하세요; 시간을 옮기려면 시간 표현식을 편집하세요.

5. 음성 해설 교체

  1. audio/voiceover.mp3를 교체합니다.
  2. analysis/align_vo.py에서 SCRIPT (그리고 숫자/약어를 위한 SPOKEN)를 편집합니다.
  3. 프로젝트 루트에서 다시 실행합니다:
python -m uv run --no-project --with onnxruntime --with numpy python analysis/align_vo.py
python -m uv run --no-project --with numpy python analysis/audio_vo.py

플레이트는 내용(lineOf, wordOf)으로 단어를 찾기 때문에, 동일한 스크립트라면 모든 애니메이션이 자동으로 재타이밍됩니다. 문구가 변경된 경우 timeline.ts의 cut(...) 호출에서 앵커 문구를 업데이트하고 사용자에게 어떤 문구가 변경되었는지 알려주세요.

플레이트 작성 또는 변경

플레이트는 Scene (app/src/engine/scene.ts)을 확장하는 클래스이며 파일의 기본 내보내기(default export)여야 합니다. 엔진은 프레임당 한 번씩 render(f, out)을 호출하며, 다음 인자를 전달합니다:

  • f.t: 노래 시간, f.lt: 플레이트 시작 이후 시간, f.p: 플레이트 진행률 0~1
  • f.a: 해당 순간의 오디오 특징 (음성 엔벨로프, 히트 펄스)
  • f.seeked: 탐색 후 true; 상태를 가진 플레이트는 이 값을 받으면 리셋되어야 함

플레이트를 추가하려면: app/src/scenes/yourplate.ts를 생성한 다음 timeline.ts에 E('yourplate', 'yourplate', start, end) 라인을 하나 추가하세요. 시작 시간은 스크립트에서 유래합니다: cut('This is Claude')는 해당 대사의 첫 단어보다 0.18초 전에 컷됩니다. timeline.ts의 파일 이름은 app/src/scenes/의 파일과 일치해야 합니다.

prompt 플레이트는 app/src/scenes/prompt-data.ts에서 토큰 분석 정보를 읽습니다.

새 플레이트를 작성하기 전에 기존 플레이트와 _vo.ts를 연구하고, 새로운 헬퍼를 만들기보다는 툴킷과 팔레트(ink, bone, signal orange)를 재사용하세요.

문제 해결

문제해결 방법
localhost:5173에서 빈 페이지app/에서 bun install 실행; vite 터미널에서 오류 확인
미리보기에서 소리 없음스페이스바 누르기; 브라우저는 상호작용이 있을 때까지 오디오를 차단합니다. 탭이 음소거되었는지 확인
렌더러가 Chrome을 찾을 수 없음Chrome 설치, 또는 BROWSER_CHANNEL 설정 (예: msedge)
ffmpeg를 찾을 수 없음 / libx264 없음전체 ffmpeg 빌드 설치; 새 터미널에서 ffmpeg -version 확인
렌더링이 매우 느림드래프트용 --samples 4; 스틸 명령어로 단일 플레이트 렌더링
새 음성 해설 후 애니메이션 어긋남두 분석 스크립트 재실행; 문구가 변경된 경우 cut(...) 구문 업데이트
씬 모듈을 찾을 수 없음timeline.ts의 파일 이름이 app/src/scenes/의 파일과 일치해야 함

Kanban Motion 추가 기능

아래의 모든 내용은 위의 Motion as Code 워크플로우에 추가되는 것이며, 대체하지 않습니다. <skill-dir>는 이 SKILL.md가 포함된 폴더입니다 (Claude Code는 "Base directory for this skill"로 표시합니다). 설치 경로를 추측하지 마세요.

경로 선택

상황수행할 작업
사용자가 Motion_as_kit을 가지고 있거나, 플레이트 편집, 렌더링, 음성 해설 교체를 요청함위의 Motion as Code를 따르세요. 도움이 되는 경우 추가 기능(음성 해설 생성, 배경 음악, 론칭 기획, 배포)을 사용하세요.
프로젝트, 웹사이트, 스크립트 또는 아이디어에서 새 비디오를 만들며, 키트가 없음아래의 스타터 키트와 론칭 워크플로우를 사용합니다.
"론칭 비디오 만들어 줘", "이것을 비디오로 만들어 줘", "프로모션"사용 가능한 키트에 대해 론칭 워크플로우 (검사, 계획, 제작, 배포)를 실행합니다.

출력물은 현재 디렉토리의 kanban-motion-output/ 또는 해당 폴더가 이미 존재하는 경우 타임스탬프가 포함된 kanban-motion-output-YYYY-MM-DD-HHmmss/로 이동합니다. 내부 구조: reel/ (플레이트), out/ (렌더링, 믹스, 스틸), work/ (다운로드, 임시 파일), 그리고 plan.md, script.txt, share-copy.txt가 포함됩니다.

스타터 키트

동일한 아이디어의 작고 의존성이 없는 버전입니다: 브라우저에서 실행되는 일반 ES 모듈, headless Chrome으로 캡처된 프레임, ffmpeg로 인코딩. 요구 사항: Node 18+, Chrome 또는 Edge, libx264가 포함된 ffmpeg, 그리고 uv (오디오 스크립트용). 머신당 한 번: npm install --prefix <skill-dir>/scripts.

<skill-dir>/template/을 kanban-motion-output/reel/로 복사하세요. 첫 번째 변경 전에 reel.js, engine.js 및 하나의 플레이트를 읽으세요.

경로역할
reel.js타임라인: 플레이트당 E(plate({...}), start, end)와 cut('phrase')를 통한 음성 컷
engine.js미리보기, 탐색 및 렌더링 훅. 편집하지 마세요.
motion.js툴킷: range, ease, 닫힌 형태 spring, 시드 기반 rng/hash, typed, 음성 동기화 lineOf, wordOf, wordsIn, cut
plates/*.jspaper (음성과 함께 호흡하는 그래프 용지 배경), say (말할 때 착지하는 운동 에너지 단어), code (코드 입력 에디터), shot (창 안의 실제 스크린샷), outro (이름, 펜 밑줄, 태그라인, URL). 론칭 비디오용: bg (움직이는 그라데이션), photo (전면 이미지와 밀어내기 효과 및 선택적 스캔라인 "전환"), screen (카메라 키 및 추적 콜아웃이 있는 실제 UI), typewrite (글자 단위 헤드라인), stats (숫자 카운트업), steps (음성에 따라 순차적으로 켜지는 파이프라인), cap (현재 말하는 대사의 자막), logo (태그라인, 배지, URL, 크레딧이 포함된 로고 공개). 시네마틱 시퀀스용: space (변형 와이어프레임 솔리드, 원근 그리드, 3D 운동 에너지 타이포그래피로 구성된 3D 장면을 통한 하나의 원활한 카메라 이동)
style.css팔레트 및 타입 토큰 (ink, bone, signal orange). 프로젝트의 정확한 색상 및 글꼴로 교체하세요.
audio/, data/, cues.json음성 해설 및 음악; words.json, lines.json 및 audio.json; 사운드 큐 시트. 템플릿은 세 가지 모두의 작동 데모를 제공하므로 미리보기와 렌더링이 즉시 작동합니다. 이미지는 assets/에 넣으세요.

플레이트는 { name, setup(root), draw(f) }입니다. draw는 f.t (전역 시간), f.lt (플레이트 시작 이후 시간), f.p (플레이트 진행률 01), f.dur, f.env (음성 음량 01), f.fps를 받습니다. f만으로 모든 시각적 속성을 설정해야 합니다: Math.random() 사용 금지 (rng(seed) 사용), 실제 시간 사용 금지, 탐색 시 리셋되지 않는 상태 사용 금지. 플레이트에 E(...)에서 tail: 0.4를 지정하면 전환을 위해 다음 플레이트와 겹칠 수 있습니다.

node <skill-dir>/scripts/render.mjs preview --dir reel                         # http://127.0.0.1:5173, 키트와 동일한 키
node <skill-dir>/scripts/render.mjs stills --dir reel --plates --out out/wip   # 플레이트당 안정화 프레임 + 컷 직전 프레임
node <skill-dir>/scripts/render.mjs stills --dir reel --t 2.4,6.1 --only say --out out/wip
node <skill-dir>/scripts/render.mjs video --dir reel --samples 4 --audio out/mix.wav --out out/reel.mp4   # 먼저 물어보기

렌더링 플래그는 키트와 동일합니다: --samples (모션 블러 서브 프레임, 드래프트용 4, 최종본용 8~12), --shutter 0.5, --scale 2 (4K, 먼저 물어보기), --crf 17, --from/--to, --fps. Chrome이 없는 경우 BROWSER_CHANNEL=msedge 또는 BROWSER_PATH=...를 사용하세요. 세로 (1080x1920) 및 정사각형 (1080x1080)은 reel.js에서 width/height를 변경하여 작동합니다; 변경 시 모든 플레이트의 레이아웃을 스틸에서 다시 확인하세요.

작동 예제는 리포지토리의 examples/ 폴더에 있습니다 (5개의 실제 프로젝트: 음성 해설이 있는 가로형, 비트 컷 세로형, 음성 해설이 있는 정사각형 설명 영상, 2개의 3D 시네마틱 시퀀스). 새 릴을 작성하기 전에 요청과 가장 가까운 예제를 읽으세요. 실제 UI를 "실제 제품 보여주기" 자료로 캡처하세요:

  • 라이브 사이트: 2배율 headless Chrome 스크린샷 사용.
  • 사용자가 소유한 앱: localhost에서 실행하고, 가능한 경우 앱 자체 데모 또는 "채우기" 로그인을 사용하세요.

그런 다음 각 스크린샷의 그리드 복사본에서 읽은 0..1 분수로 카메라와 콜아웃을 조준하세요.

음성 해설

사용자가 나레이션 또는 음성 해설을 요청하거나 --voice를 전달할 때 추가하세요. 자세한 내용은 references/voiceover.md에 있습니다.

  1. script.txt 작성: 비트당 한 줄, 줄이 컷이 되기 때문입니다. 빈 줄은 더 긴 일시 정지를 추가합니다; [pause 0.8]은 정확한 일시 정지를 추가합니다; [at 6.0]은 다음 줄을 정확한 시간에 시작하여 기존 편집에 음성을 맞춥니다. 숫자와 약어는 말하는 방식대로 작성하세요. 나레이션은 시각 자료를 그대로 읽기보다는 보완해야 하며, 장면 속도에 맞추고, 대화체처럼 들리며, 제품에 구체적이어야 합니다. 초당 약 2.5단어를 예산으로 잡으세요.
  2. 생성 로컬에서 실행되는 오픈 웨이트 음성 모델인 Kokoro를 사용합니다. 모델은 한 번 다운로드됩니다(약 340 MB).
    uv run <skill-dir>/scripts/voiceover.py script.txt -o reel/audio/voiceover.wav --lines reel/data/lines.json --voice af_heart
    
    좋은 음성: af_heart, af_bella, am_michael, am_fenrir, bf_emma, bm_george (--voice af_heart:0.6,af_bella:0.4로 혼합 가능; --speed로 속도 조절). --engine system은 다운로드 없이 OS 음성을 사용합니다. 사용자가 자신의 목소리를 녹음했다면 reel/audio/voiceover.wav에 넣고 이 단계를 건너뛰세요.
  3. 정렬 단어 수준 타이밍을 얻습니다. faster-whisper의 단어 타이밍은 스크립트 자체 단어에 스냅되고, 2단계의 줄 경계는 정확히 고정됩니다:
    uv run <skill-dir>/scripts/align.py reel/audio/voiceover.wav --script script.txt --lines reel/data/lines.json -o reel/data/words.json
    
    이 명령은 words.json과 audio.json (f.env 뒤의 음성 엔벨로프)을 작성합니다.
  4. 플레이트 동기화: cut('Every frame')은 해당 대사보다 0.18초 전에 플레이트를 시작합니다. lineOf, wordOf 및 wordsIn은 정렬된 words.json을 기반으로 작업합니다. 줄이 변경되면 reel.js에서 cut(...) 인수를 업데이트하세요.

배경 음악

사용자가 요청하거나 --music을 전달할 때 추가하세요./scripts/music.py는 수정된 사운드 폰트 (GeneralUser GS v1.471 기반, 약 130 MB)를 사용하여 MIDI 시퀀스를 오디오로 렌더링합니다. 생성된 음악은 10초 인트로, 메인 루프, 8초 아웃트로 패턴을 따릅니다. 자세한 내용은 references/music.md를 참조하세요.

톤 및 크리에이티브 법칙

<skill-dir>/references/style-guide.md를 읽으세요. 각 비디오는 브랜드의 톤과 시각적 정체성에 맞춰져야 합니다. 팔레트, 타이포그래피, 모션 언어에 대한 지침을 제공합니다.

론칭 워크플로우

비디오 기획, 제작 및 배포에 사용합니다. <skill-dir>/references/launch-workflow.md를 읽으세요.

1. 검사

  • 프로젝트/웹사이트/스크립트를 살펴보세요. 핵심 기능, 독특한 가치 제안, 대상 고객을 식별하세요.
  • 리포지토리 README, 랜딩 페이지 또는 스크립트를 검사하여 적절한 톤을 파악하세요.
  • 스크린샷, UI 요소 및 기타 시각적 자료를 수집하세요.

2. 계획

kanban-motion-output/plan.md에 계획을 작성하세요. 다음을 포함해야 합니다:

  • 톤: 브랜드에 맞는 하나의 지배적인 톤 (예: "장난기 넘치고 활기찬", "깔끔하고 전문적인", "영화적이고 서사적인")
  • 스크립트: 각 장면에 대한 대사와 시각적 설명. 초당 약 2.5단어로 시간을 예산 잡으세요.
  • 장면 목록: 필요한 플레이트 유형과 순서 (예: 후크 -> 문제 -> 해결책 -> 기능 -> 결과 -> 클릭 유도 문구)
  • 시각적 방향: 색상 팔레트, 타이포그래피, 전반적인 분위기

3. 제작

  • 계획된 장면 목록에 따라 reel/ 디렉토리의 플레이트 파일을 생성하거나 수정하세요.
  • reel.js에서 각 플레이트를 시간 순서대로 배치하세요.
  • 음성 해설을 생성하고 위 설명대로 정렬하세요.
  • 배경 음악을 생성하거나 기존 트랙을 사용하세요.
  • --plates 플래그와 함께 스틸을 렌더링하고 사용자에게 보여주어 승인을 받으세요.
  • 먼저 묻고, 전체 비디오를 렌더링하세요.

4. 배포

  • 포스터 프레임: <skill-dir>/scripts/poster.js를 사용하여 최종 비디오의 대표 프레임을 선택하거나 생성하세요.
  • 공유 카피: kanban-motion-output/share-copy.txt에 비디오 설명, 소셜 미디어 게시물, 제목 옵션을 생성하세요.
  • 최종 출력물은 kanban-motion-output/out/ 디렉토리에 있습니다.

참조 파일

다음 파일에는 중요한 세부 정보가 포함되어 있습니다. 작업을 시작하기 전에 읽으세요:

관련 스킬