# 22 · 영상 도구 에러 → 조치

**사용법**: 에러 메시지나 증상을 아래에서 **문자열로 찾는다.** 없으면 추측하지 말고 "이 지식팩에 없는 에러"라고 답한다.

---

## 설치 · 실행 에러

| 에러 / 증상 | 조치 (그대로 실행) |
|---|---|
| `zsh: command not found: manim` | `export PATH="$HOME/Library/Python/3.11/bin:$PATH"` <br>영구 적용: `echo 'export PATH="$HOME/Library/Python/3.11/bin:$PATH"' >> ~/.zshrc` 후 **새 터미널** |
| `command not found: uvx` | `brew install uv` 또는 `pip3 install --user uv` |
| `pycairo` 빌드 실패 | `brew install cairo pango pkgconf` 후 `pip3 install --user manim` 재실행 |
| `brew install pkg-config` 실패 | 이름이 틀렸다. `brew install pkgconf` |
| brew 설치가 ghcr.io에서 멈춤 | GitHub 차단 환경이다. ffmpeg는 ffmpeg.org 공식 빌드, uv는 `pip3 install --user uv`, Blender는 blender.org에서 받는다 |
| Remotion `Cannot find module` / 버전 충돌 | Node 버전 미달. `node -v`가 v20.19+/v22.13+/v24+ 인지 확인. `brew install node` |
| `hyperframes add` 실패 | 레지스트리가 GitHub이다. 차단 환경이면 블록 설치는 불가. **직접 작성한 컴포지션 렌더는 정상 동작한다** |

---

## 렌더 결과가 이상하다

| 증상 | 원인 | 조치 |
|---|---|---|
| Remotion 렌더 결과가 **완전히 비어 있다** | 기본 스캐폴드의 `MyComp`는 `null`을 반환한다 | **정상 동작이다.** 실제 내용이 있는 컴포지션을 렌더한다 |
| CSS 애니메이션이 영상에 안 나온다 | 렌더는 재생이 아니라 프레임 시킹 | Remotion: `useCurrentFrame()`+`interpolate()`로 다시 작성. HyperFrames: GSAP 타임라인 사용 |
| HyperFrames 렌더가 **정지 화면** | ① `paused: true` 누락 ② `window.__timelines["id"]` 미등록 ③ `tl.seek(0)` 누락 | 3개 모두 확인한다 |
| Manim에서 **아무 움직임이 없다** | `.animate`를 빼고 속성을 직접 바꿈 | `self.play(obj.animate.shift(UP))` 형태로 수정 |
| Manim에서 한글이 **네모**로 나온다 | 기본 폰트에 한글 글리프 없음 | `Text("한글", font="Pretendard")` 처럼 설치된 폰트명을 명시 |
| 영상 용량이 비정상적으로 작다 (10초 1080p가 수십 KB) | 빈 화면일 가능성 | 프레임을 뽑아 확인: `ffmpeg -y -ss 2 -i out.mp4 -frames:v 1 c.png` |
| 영상 길이가 의도보다 짧다 | 마지막 대기/퇴장 구간 누락 | Manim은 `self.wait()`, Remotion은 `durationInFrames` 확인 |
| 여러 영상을 합쳤더니 깨진다 | 해상도·fps·코덱이 다름 | 합치기 전에 `ffprobe`로 대조하고, 다르면 통일 후 재인코딩 |

---

## Blender

| 증상 | 조치 |
|---|---|
| `claude mcp list`는 Connected인데 조작이 안 된다 | Blender 앱에서 **N키 → MCP 탭 → Start MCP Server**를 누른다. 이것이 가장 흔한 원인이다 |
| Add-ons 목록에 "MCP for Blender"가 없다 | `~/Library/Application Support/Blender/<버전>/scripts/addons/blender_mcp.py` 존재 확인. Blender 버전이 다르면 경로의 숫자가 다르다 |
| Blender를 껐다 켠 뒤 작동하지 않는다 | 서버가 함께 꺼진다. Start MCP Server를 다시 누른다 |

---

## Claude Code 쪽

| 증상 | 조치 |
|---|---|
| 스킬을 설치했는데 Claude가 모른다 | ① 경로 구조 확인: `~/.claude/skills/<이름>/SKILL.md` — 폴더가 한 겹 더 들어가면 인식 안 됨 ② **세션을 새로 시작**한다 |
| 플러그인이 목록에 없다 | `claude plugin list`로 확인. 없으면 `claude plugin install hyperframes@hyperframes` |
| MCP 서버가 목록에 없다 | `claude mcp add -s user blender -- uvx mcp-for-blender` |

---

## 자막 · 로컬 오디오

| 증상 | 조치 |
|---|---|
| `error: failed to read audio` | 16kHz 모노 WAV가 아니다. `ffmpeg -i in.mp4 -ar 16000 -ac 1 -c:a pcm_s16le out.wav` 먼저 |
| 한국어인데 영어로 받아씀 | `-l ko`를 빠뜨렸다 |
| 모델을 못 찾음 | `-m ~/.cache/whisper-models/ggml-large-v3-turbo.bin` 경로 확인. 없으면 20번 파일에서 다운로드 |
| 자막이 영상에서 네모로 나옴 | `force_style`의 `FontName`을 설치된 폰트명으로 변경 |
| 받아쓰기가 너무 느림 | 작은 모델 사용: `ggml-small.bin`(488MB) 또는 `ggml-base.bin`(148MB) |
| `hyperframes doctor`에서 TTS 미설치 | `pip3 install --user kokoro-onnx soundfile` |
| OpenMontage `make setup` 실패 | python3.10+ / node18+ / ffmpeg 가 있는지 확인. venv는 프로젝트 안에 만들어진다 |
| Lottie 결과가 MP4가 아님 | 정상이다. 이 도구는 Lottie JSON을 만든다 |

---

## 판단 기준

- **에러 메시지가 없는데 결과가 이상하다** → 이 파일의 "렌더 결과가 이상하다"를 먼저 본다.
- **여기 없는 에러다** → 추측으로 고치지 말고, 에러 전문을 사용자에게 보여주고 "지식팩에 없는 에러"라고 말한다.
- **고친 뒤에는 반드시 다시 렌더하고 프레임을 뽑아 확인한다.** 로그만 보고 해결됐다고 하지 않는다.