Communitygithub.com

MSP — Manim 스타일 및 프로토콜

AI 에이전트가 'MSP — Manim 스타일 및 프로토콜'에 따라 계획을 세우고, 제작하거나 수정하여 실제로 사용 가능한 복사본이나 스크립트를 만들 수 있도록 안내합니다. 'AI 생성 Manim 애니메이션을 위한 프로덕션급 기술 사양', 0. 최우선 지시, 1. 환경 및 버전 고정 단계를 거쳐 진행됩니다. 새로운 작업에서 이 기술이 필요할 때 사용하세요.

MSP — Manim 스타일 및 프로토콜란 무엇인가요?

MSP(Manim 스타일 및 프로토콜)는 AI 시스템(예: Claude Code, Cursor, Codex)이 Manim(Manim Community Edition v0.18 이상)을 사용하여 스튜디오/프로덕션 수준의 애니메이션을 일관되게 생성할 수 있도록 설계된 포괄적인 기술 사양입니다. 이 사양은 원시적인 학생 스크립트 수준이 아닌 전문 애니메이션 스튜디오에서 제작된 듯한 결과물을 기본값으로 보장하는 데 중점을 둡니다. 주요 기능으로는 프로젝트 구조 표준화(theme.py, helpers.py, scenes/ 디렉토리), 엄격한 비주얼 디자인 규칙(색상 팔레트, 타이포그래피, 레이아웃), '변환 프로토콜'(TransformMatchingTex, Transform, FadeTransform 등)을 통한 부드러운 모핑 애니메이션, 타이밍 및 이징 표준, 씬 및 카메라(2D 및 3D) 구성 규칙, 렌더링 워크플로우 등이 포함됩니다. 이 사양을 따르면 AI 에이전트는 처음부터 명확하고, 일관되며, 시각적으로 우아한 Manim 애니메이션을 생성할 수 있어 수동 수정 작업을 대폭 줄일 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Frqme21/MSP-Manim-Style-protocol/tree/HEAD/v1

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

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

문서

MSP — Manim 스타일 및 프로토콜은(는) 무엇을 하나요?

AI 생성 Manim 애니메이션을 위한 프로덕션급 기술 사양

버전: 1.0
대상: Manim Community Edition (ManimCE) ≥ v0.18
목적: AI 시스템이 기본적으로 깔끔하고, 체계적이며, 부드럽게 모핑되는 스튜디오/프로덕션 수준의 Manim 애니메이션을 생성할 수 있도록 합니다. 예외가 아닌 기본값으로 말이죠.

0. 최우선 지시

여러분이 작성하는 모든 씬은 학생 스크립트가 아닌 전문 애니메이션 스튜디오에서 나온 것처럼 보여야 합니다. 선택이 모호할 경우, 더 부드럽고, 더 깔끔하며, 더 의도적인 옵션을 선택하세요. 가장 게으른 기본값이 아닙니다.

코드를 작성하기 전에 다음 체크리스트를 묵묵히 실행하세요:

  1. 이 씬이 전달하는 하나의 아이디어는 무엇인가?
  2. 시각적 계층 구조는 무엇인가? (눈에 가장 먼저 들어와야 하는 것은? 두 번째는? 세 번째는?)
  3. 어떤 색상 팔레트와 폰트를 사용하고 있으며, 프로젝트 전체에서 일관성이 있는가?
  4. 각 오브젝트는 어떻게 등장하고, 변환되고, 퇴장하는가? — 애니메이션 동사 없이 단순히 "나타나거나" "사라져서는" 안 됩니다.
  5. 씬의 페이싱(전체 run_time 예산)은 어떻게 되는가?

1. 환경 및 버전 고정

사용자가 명시적으로 3b1b 스타일의 ManimGL을 요청하지 않는 한, 항상 Manim Community Edition을 기본값으로 사용하세요. ManimGL이 아닙니다.

from manim import *
  • CLI 바이너리: manim (manimgl 아님)
  • 생성 동사: Create() (ShowCreation() 아님)
  • 수식 렌더링: MathTex(r"...") (Tex(R"...") 아님)

절대로 API를 혼용하지 마세요. 코드 조각에 MovingCameraScene이나 ThreeDScene 없이 self.camera.frame이 사용되면 플래그를 지정하세요. 이는 ManimGL 구문이 섞여 들어온 것입니다.


2. 프로젝트 파일 구조

단일 사소한 씬 이상의 경우 항상 이 구조를 적용하세요. 모든 것을 하나의 모놀리식 파일에 덤프하지 마세요:

project/
├── manim.cfg              # 고정된 렌더링 설정 (§9 참고)
├── theme.py               # 색상, 폰트, 상수 (유일한 진실 공급원)
├── helpers.py             # 재사용 가능한 mobject 빌더 / 레이아웃 함수
├── scenes/
│   ├── 01_intro.py
│   ├── 02_derivation.py
│   └── 03_outro.py
└── assets/                # svgs, 이미지, 오디오

theme.py 예시 (다중 씬 프로젝트의 경우 항상 생성하세요):

from manim import *

# ---- 팔레트 ----
BG_COLOR      = "#0E0E12"
PRIMARY       = "#58C4DD"   # manim 기본 파란색 또는 브랜드 색상
SECONDARY     = "#FFD166"
ACCENT        = "#EF476F"
TEXT_MAIN     = "#F5F5F5"
TEXT_MUTED    = "#8A8A8F"
SUCCESS       = "#06D6A0"

# ---- 타이포그래피 ----
FONT_MAIN = "Helvetica"      # 또는 프로젝트별 폰트
FONT_MONO = "JetBrains Mono"

# ---- 타이밍 상수 ----
T_FAST   = 0.5
T_NORMAL = 1.0
T_SLOW   = 1.8
LAG      = 0.08   # 그룹화된 등장을 위한 기본 lag_ratio

config.background_color = BG_COLOR

모든 씬 파일은 theme.py를 임포트합니다. 테마 파일이 존재하는 인라인에 16진수 색상이나 매직 run_time 숫자를 하드코딩하지 마세요. 이것이 비전문적이고 일관성 없는 결과물의 #1 지표입니다.


3. 시각 디자인 표준

3.1 색상 규칙

  • 프로젝트당 최대 4–5가지 색상 사용 (배경 1개, 기본 1–2개, 강조 1–2개). 더 많으면 지저분하고 아마추어처럼 보입니다.
  • 색상을 의미론적으로 사용하세요: 동일한 색상은 전체 비디오에서 동일한 의미를 가져야 합니다 (예: 항상 파란색은 "주어진 것", 항상 빨간색은 "알 수 없는 것").
  • 배경은 거의 절대 순수한 검정(#000000)이나 순수한 흰색이어서는 안 됩니다. 눈의 피로를 줄이고 "스튜디오" 느낌을 주기 위해 부드러운 검정에 가까운 색(#0E0E12)이나 부드러운 흰색에 가까운 색을 사용하세요.

3.2 타이포그래피 규칙

  • UI 레이블, 제목, 캡션에는 Text()를 사용하세요. 빠르고 LaTeX 종속성이 없습니다.
  • 모든 수학적 표기법에는 MathTex()를 사용하세요. Text()로 수학을 흉내내지 마세요.
  • Tex()는 혼합 산문+수학 LaTeX 블록에만 사용하세요.
  • 전역적으로 하나의 font=를 테마 상수로 설정하세요. 씬마다 폰트 선택이 달라지지 않도록 합니다.
  • 제목 규칙: .to_edge(UP), 굵게, 모든 씬에서 일관된 폰트 크기 (예: 40pt).

3.3 레이아웃 규칙

  • 3분할 법칙을 존중하세요. 기본적으로 모든 것을 정중앙에 배치하지 말고, .to_edge(), .shift(), .next_to()를 의도적으로 사용하세요.
  • 일관된 여백(buff 값)을 유지하세요. MARGIN = 0.75 상수를 정의하고 모든 .to_edge(..., buff=MARGIN) 호출에서 재사용하세요.
  • 관련 오브젝트를 단일 VGroup 으로 그룹화하고 그룹을 위치 지정 및 애니메이션 처리하세요. 느슨한 개별 mobject를 사용하지 마세요. 이렇게 하면 나중에 변환해도 정렬이 올바르게 유지됩니다.
  • 그룹에 대해 수동으로 좌표를 계산하는 대신 항상 .arrange() 또는 .arrange_in_grid()를 호출하세요. 수동 좌표 계산은 취약하며, 이후 편집 시 레이아웃이 깨지는 #1 원인입니다.

4. 모핑 및 변환 프로토콜

이것이 "부드럽고 모핑되는" 애니메이션의 핵심입니다. 고급 설명 동영상의 시그니처 스타일입니다.

4.1 규칙: 절대 컷하지 말고, 항상 변환하세요

오브젝트가 개념적으로 다른 오브젝트가 되는 경우 (방정식 재배열, 모양이 다른 모양으로 변환, 레이블 업데이트), 절대 별개의 관련 없는 mobject로 FadeOut + FadeIn을 사용하지 마세요. 이는 점프 컷처럼 읽힙니다. 항상 변환 계열을 사용하세요:

상황올바른 도구
방정식 재배열, 항 유지TransformMatchingTex(기존, 신규)
모양이 다른 모양으로 변환Transform(기존, 신규) 또는 ReplacementTransform(기존, 신규)
mobject 그룹 재구성 (예: 글머리 기호 목록 → 다이어그램)TransformMatchingShapes(기존_그룹, 신규_그룹)
한 오브젝트가 씬 그래프에서 다른 오브젝트를 명시적으로 대체ReplacementTransform (self.mobjects에서 기존을 신규로 교체)
연속성을 암시하면서 페이드 (예: 고스트/오버레이)FadeTransform(기존, 신규)

TransformMatchingTex 프로토콜 세부 사항: 일관된 하위 문자열 그룹화(동일한 LaTeX 조각을 별도의 {} 그룹으로)를 사용하여 두 MathTex mobject를 모두 빌드하세요. 그러면 Manim이 동일한 기호를 일치시킬 수 있습니다. 이것이 크로스페이드 대신 용어가 시각적으로 새 위치로 "슬라이드"되도록 만드는 요소입니다.

eq1 = MathTex("a", "+", "b", "=", "c")
eq2 = MathTex("c", "=", "a", "+", "b")
self.play(TransformMatchingTex(eq1, eq2), run_time=1.2)

4.2 규칙: 단순 속성 변환에는 .animate 사용

하나의 mobject에 대한 단일 연속 속성 변경(위치, 크기, 색상, 회전)의 경우 .animate 구문을 선호하세요. 더 깔끔하고 Manim이 최종 변환을 자동으로 보간합니다:

self.play(square.animate.shift(RIGHT * 2).scale(1.5).set_color(ACCENT), run_time=1.0)

주의사항 (매우 중요, AI 환각 버그 방지): 체이닝된 .animate 호출은 최종 최종 상태를 보간하며, 각 중간 단계를 순차적으로 보간하지 않습니다. 중간 결과에 의존하는 .animate 호출을 체이닝하지 마세요 (예: .animate.move_to(X).rotate(angle_depending_on_position)) — 대신 별도의 self.play() 호출로 분할하세요.

4.3 규칙: 연속/종속 동작에는 Updater 사용

오브젝트의 상태가 다른 오브젝트를 지속적으로 추적해야 할 때마다 (레이블이 점을 따라가거나, 값 표시가 ValueTracker를 추적), add_updater를 사용하세요. 수동으로 매 프레임을 play하지 마세요:

tracker = ValueTracker(0)
label = DecimalNumber(0).add_updater(lambda d: d.set_value(tracker.get_value()))
dot = Dot().add_updater(lambda m: m.move_to(axes.c2p(tracker.get_value(), f(tracker.get_value()))))
self.add(label, dot)
self.play(tracker.animate.set_value(5), run_time=3, rate_func=linear)

오브젝트의 종속성 단계가 끝나면 항상 remove_updater(또는 더 깔끔한 처음부터 다시 계산 로직을 위해 always_redraw 사용)하여 긴 씬에서 나중에 발생할 수 있는 오래된 업데이터 버그를 방지하세요.


5. 타이밍, 페이싱 및 이징 프로토콜

5.1 기본 속도 함수 정책

  • 기본값 (재정의하지 마세요): smooth — S-곡선 ease-in/ease-out. 애니메이션의 90%에 사용하세요. — 방정식 등장, 모양 생성, 표준 이동.
  • linear: 문자 그대로 일정한 속도의 물리적 움직임을 묘사하는 모든 것에 필수 — 궤도를 도는 점, 등속 벡터, 회전하는 시계 바늘, 실제 경과 시간에 연결된 진행률 표시줄.
  • rush_into / rush_from: 무언가가 제자리에 딱 맞춰지거나 튀어나가는 느낌을 주어야 하는 강조 등장/퇴장에 사용하세요.
  • there_and_back / there_and_back_with_pause: Indicate 스타일의 주의 집중 펄스에 사용하며, 영구적인 상태 변경에는 절대 사용하지 마세요.
  • ease_out_bounce / ease_out_elastic: 재미있고 비공식적인 콘텐츠용으로만 제한하세요. 공식적인 수학/과학 유도에서는 절대 사용하지 마세요. 비전문적으로 보입니다.

5.2 타이밍 예산 규칙

  • 개별 run_time은 0.4초에서 3초 사이로 유지하세요. 0.4초 미만은 성가시게 보이고, 3초 초과는 (이야기적 이유 없이) 지루합니다.
  • 제목/섹션 헤더 등장: 0.8–1.2초.
  • 방정식/다이어그램 변환: 1.0–1.5초.
  • 강조 펄스 (Indicate, Flash, Circumscribe): 0.5–0.8초.
  • 카메라 이동 (move_camera, self.camera.frame.animate): 1.5–3초 — 이보다 빠른 카메라 이동은 메스꺼움을 유발합니다.
  • 주요 등장 후에는 의도적으로 self.wait(0.3–1.0) 호흡을 삽입하세요. self.play() 호출을 멈춤 없이 연속으로 체이닝하지 마세요. 시청자를 압도합니다.

5.3 구성 프로토콜

  • 동시적이지만 독립적인 이벤트 → 단일 self.play(AnimA, AnimB, ...) 호출.
  • 시차를 둔 시작으로 동시 (예: 6개의 글머리 기호가 순차적으로 나타나지만 겹침) → LaggedStart(*anims, lag_ratio=0.15).
  • 엄격하게 순차적이고 종속적인 이벤트 → Succession(*anims) 또는 별도의 self.play() 호출.
  • 목록/그리드 등장 (글머리 기호, 모양 그리드) → 항상 단일 동시 FadeIn(group) 대신 LaggedStartMap(FadeIn, group, lag_ratio=0.08, shift=UP*0.3)을 사용하세요. 시작 시간을 엇갈리게 하는 것이 그룹 등장을 기계적이지 않고 유기적으로 느끼게 만듭니다.

6. 씬 및 코드 구성 프로토콜

6.1 Construct 메서드 형태

항상 construct()를 주석이나 헬퍼 메서드를 통해 명확하게 구분되고 이름이 지정된 단계로 분해하세요. 절대 하나의 끊어지지 않은 100줄 블록으로 만들지 마세요:

class DerivationScene(Scene):
    def construct(self):
        self.setup_title()
        self.show_initial_equation()
        self.derive_steps()
        self.highlight_result()
        self.cleanup()

    def setup_title(self):
        self.title = Text("Deriving the Quadratic Formula", font=FONT_MAIN).to_edge(UP)
        self.play(Write(self.title), run_time=T_NORMAL)
        self.wait(T_FAST)

    def show_initial_equation(self):
        ...

긴 비디오의 경우, 하나의 거대한 construct() 대신 여러 씬 클래스로 분할하세요 (논리적 섹션당 하나씩). 그러면 -n을 통해 대상 재렌더링과 병렬 반복이 가능합니다.

6.2 Mobject 구성 프로토콜

  • 복잡한 사용자 정의 시각 자료(다이어그램, 그래프, 아이콘)는 construct()에 인라인으로 작성하지 말고 VGroup을 반환하는 helpers.py의 독립 실행형 함수로 빌드하세요:
# helpers.py
def make_neuron(radius=0.3, color=PRIMARY) -> VGroup:
    circle = Circle(radius=radius, color=color, fill_opacity=0.8)
    label = Text("n", font_size=20).move_to(circle)
    return VGroup(circle, label)
  • mobject에 항상 의미 있는 이름을 지정하세요 (title, eq_initial, graph_group). 나중에 변형하거나 변환해야 할 참조되지 않은 익명 리터럴을 남겨두지 마세요.
  • 겹치는 레이어가 있는 씬의 경우 z_index를 명시적으로 사용하세요 (레이어가 2개를 초과하면 추가 순서만으로는 충분하지 않습니다).

6.3 스타일 / 린팅 규칙

  • 변수/메서드는 snake_case, Scene 하위 클래스는 PascalCase를 사용하세요.
  • 가독성을 위해 코드에서 애니메이션 "비트" 사이에 빈 줄 하나를 넣으세요. 코드 구조는 비디오의 페이싱을 시각적으로 반영해야 합니다.
  • 색상/위치/타이밍에 베어 매직 넘버를 사용하지 마세요. 항상 theme.py 상수를 참조하세요.
  • 더 큰 프로젝트의 유지 관리를 위해 헬퍼 함수에 타입 힌트를 추가하세요 (def make_axes() -> Axes:).

7. 구성 및 카메라 프로토콜 (2D 및 3D)

2D

  • 비디오가 2D에서 팬/줌해야 할 때마다 (예: 다이어그램의 하위 영역에 초점 맞추기) MovingCameraScene을 사용하세요. self.camera.frame.animate.move_to(...).set(width=...)를 통해 애니메이션 처리하고, 항상 명시적인 run_time을 사용하세요.

3D

  • ThreeDScene을 서브클래싱하세요.
  • 전용 설정 단계에서 self.set_camera_orientation(phi=70*DEGREES, theta=-45*DEGREES, zoom=1)로 초기 방향을 설정하세요. 의도하지 않은 한 기본 방향을 그대로 두지 마세요.
  • 시청자가 움직임으로 인식해야 하는 카메라 재배치의 경우 self.move_camera(phi=..., theta=..., run_time=2.5)를 사용하세요. 씬 중간에 set_camera_orientation을 통해 점프 컷을 하지 마세요.
  • 내레이션 아래에서 느린 유휴 회전을 위해 self.begin_ambient_camera_rotation(rate=0.15)를 사용하세요. 이후 의도적인 move_camera 전에 항상 self.stop_ambient_camera_rotation()과 쌍을 이루도록 하세요.
  • 카메라 각도에 관계없이 읽기 쉬워야 하는 HUD/레이블/제목 → self.add_fixed_in_frame_mobjects(label).
  • 3D 오브젝트를 추적하지만 읽기 쉬운 상태를 유지해야 하는 레이블 → self.add_fixed_orientation_mobjects(label).
  • 반복 중에는 3D 표면 resolution 튜플을 낮게 유지하세요 (예: (24,24)). 최종 프로덕션 렌더링을 위해서만 높이세요. 이는 순전히 성능/워크플로우 규칙이며 시각적인 규칙이 아닙니다.

8. 강조 및 주의 집중 프로토콜

핵심 결과를 시각적으로 지원 콘텐츠와 동일하게 두지 마세요. 씬의 "결과"(최종 방정식, 핵심 통찰력, 결과)를 공개한 후에는 정확히 하나의 강조 기법을 적용하세요. 두 개 이상을 쌓으면 혼란스러워 보입니다:

  • Circumscribe(mobject, color=ACCENT, run_time=1.2) — 주위에 모양을 그립니다.
  • Indicate(mobject, scale_factor=1.15) — 짧은 펄스 스케일 + 색상 플래시.
  • Flash(point, color=ACCENT) — 방사형 버스트, 특정 좌표/교차점에 적합합니다.
  • mobject.animate.set_color(ACCENT)를 약간의 스케일과 결합 — "이것이 정답입니다."를 알리는 영구적인 색상 변경용.

9. 렌더링 및 내보내기 프로토콜

9.1 고정된 설정 파일 (이것을 커밋하세요. 최종 전달을 위해 임시 플래그에 의존하지 마세요)

manim.cfg:

[CLI]
quality = production_quality
preview = False
background_color = "#0E0E12"
output_file = {scene_name}
frame_rate = 60
pixel_height = 1080
pixel_width = 1920

9.2 워크플로우 단계 (항상 이 순서를 따르고, 절대 처음부터 최종 품질로 렌더링하지 마세요)

  1. 초안 패스: manim -pql scenes/02_derivation.py DerivationScene — 빠른 반복, 로직/타이밍 확인.
  2. 스팟 체크 패스: manim -pqh -s scenes/02_derivation.py DerivationScene — 구성/색상의 단일 프레임 고품질 확인.

…

[번역을 위해 잘림]

관련 스킬