# 20 · 모션그래픽 도구 설치 (macOS)

**언제 읽나**: 영상·3D·수학애니메이션·제너러티브아트 도구를 설치할 때.
**검증 환경**: macOS, Node v24.14.1, npm 11.11.0 (2026-10-17 실제 설치·렌더 확인)

---

## 0. 먼저 확인 (설치 전 필수)

```bash
node -v        # v20.19+ / v22.13+ / v24+ 중 하나여야 한다
brew --version # 없으면 brew.sh 안내대로 설치
claude --version
curl -fsS --max-time 6 -o /dev/null https://github.com && echo "GitHub OK" || echo "GitHub 차단"
```

**GitHub이 차단된 환경이면** 아래 3개는 설치할 수 없다 → 오프라인 팩을 쓴다(이 파일 맨 아래).

---

## 1. 시스템 패키지

```bash
brew install ffmpeg uv cairo pango pkgconf
```

- `ffmpeg` : 영상 인코딩 (모든 도구 공용)
- `uv` : Blender MCP 서버 실행용
- `cairo pango pkgconf` : Manim 렌더 백엔드

❌ `brew install pkg-config` 라고 쓰지 마라. **정확한 이름은 `pkgconf`** 다.

---

## 2. Remotion (React로 영상) — GitHub 불필요

```bash
npx create-video@latest my-video
cd my-video && npm install
npx remotion studio                            # 미리보기
```

공식 스킬 12종(이 명령만 GitHub 사용):
```bash
npx remotion skills add
```

---

## 3. HyperFrames (HTML로 영상)

```bash
claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes
claude plugin list        # hyperframes@hyperframes · enabled 확인
```

GitHub 차단 시 대안 — CLI만 npm으로 사용(스킬 9종은 오프라인 팩에 포함):
```bash
npx --yes hyperframes@0.8.167 init my-video
```

---

## 4. Blender MCP — GitHub 불필요

```bash
brew install --cask blender
claude mcp add -s user blender -- uvx mcp-for-blender
claude mcp list | grep blender     # "✔ Connected" 확인
```

애드온은 PyPI 패키지에 포함되어 자동 설치된다. 별도 다운로드 불필요.
경로: `~/Library/Application Support/Blender/5.2/scripts/addons/blender_mcp.py`

### ⚠️ 여기부터는 사람이 직접 해야 한다 (자동화 불가)

1. Blender 앱을 실행한다
2. Edit → Preferences → Add-ons → "MCP for Blender" 검색 → 체크해서 활성화
3. 3D 뷰포트에서 `N` 키 → 사이드바 → **Start MCP Server** 클릭

이 3단계를 하지 않으면 `claude mcp list`가 Connected여도 **조작되지 않는다.**
Blender를 종료하면 서버도 꺼진다. 쓸 때마다 다시 켠다.

---

## 5. Manim (수학 애니메이션) — 본체는 GitHub 불필요

```bash
pip3 install --user manim

# ⚠️ pip --user 실행파일은 기본 PATH에 없다. 이 줄을 반드시 추가한다.
echo 'export PATH="$HOME/Library/Python/3.11/bin:$PATH"' >> ~/.zshrc
export PATH="$HOME/Library/Python/3.11/bin:$PATH"   # 현재 터미널 즉시 적용

manim --version     # Manim Community v0.22.0 이상
```

스킬(GitHub 사용):
```bash
git clone https://github.com/awesome-skills/manim-skill.git ~/.claude/skills/manim-skill
```

---

## 6. algorithmic-art (제너러티브 아트) — GitHub 사용

```bash
git clone https://github.com/Pardesco/algorithmic-art-skill.git ~/.claude/skills/algorithmic-art
```

---

## 7. GitHub 차단 환경 — 오프라인 팩

GitHub을 쓰는 항목(HyperFrames 스킬 9종, manim-skill, algorithmic-art)을 한 번에 받는다.

```bash
curl -fsSL https://design-portfolio-7yo.pages.dev/motion-stack-offline.zip -o pack.zip
unzip pack.zip && cd motion-stack-offline
bash install-offline.sh
```

Homebrew까지 막힌 경우:
- ffmpeg → ffmpeg.org 공식 빌드
- Blender → blender.org 직접 다운로드
- uv → `pip3 install --user uv`
- cairo/pango → conda-forge

---

## 8. 자막 — whisper.cpp (완전 오프라인)

```bash
brew install whisper-cpp
mkdir -p ~/.cache/whisper-models && cd ~/.cache/whisper-models
curl -fL -o ggml-large-v3-turbo.bin \
  "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin"
```
모델 1.5GB. 가벼운 대안: `ggml-small.bin`(488MB) · `ggml-base.bin`(148MB).
설치 후 `whisper-cli --help`로 확인. API 키·인터넷 불필요.

## 9. text-to-lottie (웹·앱용 벡터 애니메이션)

```bash
git clone --depth 1 https://github.com/diffusionstudio/lottie.git /tmp/lottie
cp -R /tmp/lottie/skills/text-to-lottie ~/.claude/skills/text-to-lottie
mv /tmp/lottie <프로젝트>/lottie-player      # 검증용 플레이어 프로젝트
cd <프로젝트>/lottie-player && npm install
```
❌ 이것은 MP4를 만들지 않는다. 산출물은 Lottie JSON이다.

## 10. OpenMontage (실사 푸티지 조립·나레이션)

```bash
git clone --depth 1 https://github.com/calesthio/OpenMontage.git openmontage
cd openmontage && make setup        # .venv 격리 설치
make hyperframes-doctor             # 검증
make demo-list
.venv/bin/python render_demo.py code-to-screen   # 실측: 3.6MB mp4 산출
```

⚠️ **AGPLv3(copyleft)**. 개인 로컬 사용은 자유지만 수정본 배포·네트워크 서비스 제공 시 소스 공개 의무가 생긴다. ❌ 다른 배포물에 번들하지 마라.

## 11. 로컬 오디오 (로그인 불필요)

```bash
pip3 install --user kokoro-onnx soundfile    # 로컬 TTS(나레이션)
# 확인: hyperframes doctor → "TTS (Kokoro) Kokoro deps installed"
```
로컬 BGM(MusicGen)은 torch 포함 약 2.5GB라 기본 설치하지 않는다.
필요 시: `pip install transformers torch soundfile numpy`

---

## 확인 절차 (설치 완료 판정)

```bash
node -v
ffmpeg -version | head -1
uv --version
manim --version
ls -d /Applications/Blender.app
claude mcp list | grep blender
claude plugin list
ls ~/.claude/skills/
```

한 번에 확인:
```bash
curl -fsSL https://design-portfolio-7yo.pages.dev/motion-stack-setup.sh -o setup.sh
bash setup.sh --check     # 상태만 확인, 아무것도 설치/수정하지 않는다
```

**스킬을 추가한 뒤에는 Claude Code 세션을 새로 시작해야 인식된다.**
설치 후 실제 산출물을 뽑아보려면 파일 `21-motion-usage.md`로 간다.