concept-to-video

コンセプトから動画へ

Manim（Python）をプログラムによるアニメーションエンジンとして使用し、コンセプトから解説動画を作成します。

参考ファイル

ファイル	用途
references/rules/pipeline-flow.md	RAG、ETL、CI/CD — 矢印を使った連続するステージのアニメーション
references/rules/architecture-layers.md	システムスタック、ネットワーク層、抽象化の階層
references/rules/algorithm-stepthrough.md	ソート、検索、グラフ探索 — 状態を保ちながら順を追って進めるアニメーション
references/rules/comparison.md	AとBの並列比較、前後比較、トレードオフの視覚化
references/rules/agent-interaction.md	複数エージェント間のメッセージパッシング、分散システム、パブリッシュ／サブスクライブ
references/rules/math-concept.md	方程式、数式、幾何学的証明 — デフォルトではLaTeXを使用しません
references/rules/training-loop.md	勾配降下法、RLのループ、循環的な反復プロセス
references/rules/transitions.md	シーンのセクション間のフェードおよびワイプトランジション
references/rules/text-animation.md	テキストの置き換え、箇条書きの段階的表示、コールアウト、強調
references/rules/layout.md	キャンバスの座標、VGroupの配置、間隔のガイドライン
references/rules/audio-overlay.md	ffmpegによる音声の重ね合わせ — BGM、ナレーション、複数トラックのミキシング
references/rules/voiceover-scaffold.md	タイミングスクリプトの生成、TTSへの引き継ぎ、ナレーションのベストプラクティス
references/rules/images.md	ImageMobjectの使用、ロゴ／スクリーンショットのパターン、拡大縮小と配置
references/rules/subtitles.md	シーンのタイミングに基づくSRT生成、ffmpegによる字幕の焼き込み
references/rules/multi-scene.md	複数のSceneクラス、ffmpegによる連結、チャプター単位の構成
references/templates/data_flow_template.py	パラメーター指定可能なパイプライン／データフローアニメーション（設定駆動のSTAGESリスト）
references/templates/comparison_template.py	パラメーター指定可能な並列比較（設定駆動のLEFT／RIGHT項目）
references/templates/timeline_template.py	パラメーター指定可能なタイムラインアニメーション（設定駆動のEVENTSリスト）
scripts/render_video.py	Manim CLIのラッパー — 品質、形式、出力パスのクリーンアップを処理します
scripts/add_audio.py	ffmpegのラッパー — 音声の重ね合わせ、音量、フェードイン／アウト、動画に合わせたトリミング

エンジンにManimを使う理由

Manimは「動画のSVG」です。アニメーションを宣言的に記述するPythonコードを書き、任意の解像度でMP4／GIFにレンダリングします。Pythonのシーンファイル自体が編集可能な中間生成物です。ユーザーはコードを確認して変更を依頼でき（「矢印を赤にする」「3つ目のステップを追加する」「トランジションを遅くする」など）、納得した後に最終的な高品質レンダリングを一度だけ行えます。このため、コンセプトから画像を作る際にHTMLを中間生成物として使うのと同様に、反復的で制御しやすいワークフローを実現できます。

ワークフロー

Concept → Manim scene (.py) → Preview (low-quality) → Iterate → Final render (MP4/GIF)

1. 解釈 — ユーザーのコンセプトを解釈し、最適なアニメーション手法を判断します
2. 設計 — 自己完結型のManimシーンファイルを設計します — 1ファイル、1つのSceneクラス
3. プレビュー — 低品質（-ql）でレンダリングして、素早く反復します
4. 反復 — ユーザーからのフィードバックに基づいてシーンを調整します
5. エクスポート — scripts/render_video.pyを使って、高品質で最終動画を出力します

ステップ0：依存関係を確認する

シーンを書く前に、Manimがインストールされていることを確認します。

# System deps (usually pre-installed)
apt-get install -y libpango1.0-dev libcairo2-dev ffmpeg 2>/dev/null

# Python package
pip install manim --break-system-packages -q

次のコマンドで確認します：python3 -c "import manim; print(manim.__version__)"

ステップ 1：コンセプトを解釈する

最適なアニメーションパターンを決め、コードを書く前に該当するルールファイルを読んでください。

ユーザーの意図	読むルールファイル	主な Manim プリミティブ
パイプライン／フローを説明する	references/rules/pipeline-flow.md	Arrow, Rectangle, Text, AnimationGroup
アーキテクチャのレイヤーを示す	references/rules/architecture-layers.md	VGroup, Arrange, FadeIn with shift
アルゴリズムを段階的に説明する	references/rules/algorithm-stepthrough.md	Transform, ReplacementTransform, Indicate
アプローチを比較する	references/rules/comparison.md	Split screen VGroups, simultaneous animations
数学的なコンセプト	references/rules/math-concept.md	MathTex, geometric shapes, Rotate, Scale
エージェント／複数システム間の相互作用	references/rules/agent-interaction.md	Arrows between entities, Create/FadeOut
トレーニング／最適化ループ	references/rules/training-loop.md	Loop with Transform, ValueTracker, plots
タイムライン／歴史	references/templates/timeline_template.py	NumberLine, sequential Indicate
画像やスクリーンショットを埋め込む	references/rules/images.md	ImageMobject, SVGMobject
字幕やキャプションを追加する	references/rules/subtitles.md	SRT generation, ffmpeg subtitle burn
複数の独立した章	references/rules/multi-scene.md	Multiple Scene classes, ffmpeg concat
音声やナレーションを追加する	references/rules/audio-overlay.md	ffmpeg, scripts/add_audio.py
セクション間を移行する	references/rules/transitions.md	FadeOut all, shift off-screen
テキストの表示、コールアウト、強調	references/rules/text-animation.md	ReplacementTransform, LaggedStart, Indicate
配置、間隔、レイアウト	references/rules/layout.md	next_to, arrange, to_edge, move_to

ステップ 2：Manim のシーンを設計する

テンプレート優先と一からの作成

シーンを一から作成する前に、パラメトリックテンプレートでコンセプトに対応できるか確認します。

コンセプトが...	使用するテンプレート
線形パイプライン（A→B→C→D）	references/templates/data_flow_template.py — STAGES を編集
2つの選択肢の比較	references/templates/comparison_template.py — LEFT_ITEMS、RIGHT_ITEMS を編集
時系列のタイムライン	references/templates/timeline_template.py — EVENTS を編集
その他	該当するルールファイルを使って一から作成します

テンプレートを使用する場合は、作業ディレクトリにコピーし、先頭にある設定定数を編集してください。クラスの構造は変更しないでください。

基本ルール：

• 単一ファイル、単一 Scene クラス：すべてを1つの .py ファイルに記述し、class XxxScene(Scene) を1つだけ含めます。
• 自己完結型：どうしても必要な場合を除き、外部アセットは使いません。すべてに Manim のプリミティブを使用します。
• 読みやすいコード：シーンファイル自体がユーザーの成果物です。わかりやすい変数名を使い、各アニメーションの区切りにコメントを付けます。
• 意図を持った配色：Manim の色定数（BLUE、RED、GREEN、YELLOW など）または16進数の色を使用します。色数は最大4～5色にします。各色に意味を持たせます。
• ペース配分：論理的なセクションの間に self.wait() を入れます。間を取る場合は0.5秒、大きな切り替えでは1～2秒にします。
• テキストの読みやすさ：本文には最低でも font_size=36、タイトルには font_size=48+ を使用します。目標とする解像度で確認してください。
• シーンの寸法：Manim のキャンバスはデフォルトで14.2 × 8単位（16:9）です。コンテンツは水平方向に±6、垂直方向に±3.5の範囲内に収めます。

アニメーションのベストプラクティス

# DO: Use animation groups for simultaneous effects
self.play(FadeIn(box), Write(label), run_time=1)

# DO: Use .animate syntax for property changes
self.play(box.animate.shift(RIGHT * 2).set_color(GREEN))

# DO: Stagger related elements
self.play(LaggedStart(*[FadeIn(item) for item in items], lag_ratio=0.2))

# DON'T: Add/remove without animation (jarring)
self.add(box)  # Only for setup before first frame

# DON'T: Make animations too fast
self.play(Transform(a, b), run_time=0.3)  # Too fast to read

構成テンプレート

from manim import *

class ConceptScene(Scene):
    def construct(self):
        # === Section 1: Title / Setup ===
        title = Text("Concept Name", font_size=56, weight=BOLD)
        self.play(Write(title))
        self.wait(1)
        self.play(FadeOut(title))

        # === Section 2: Core animation ===
        # ... main content here ...

        # === Section 3: Summary / Conclusion ===
        # ... wrap-up animation ...
        self.wait(2)

ステップ3：プレビューをレンダリングする

すばやく反復できるように、低画質でレンダリングします。

python3 scripts/render_video.py scene.py ConceptScene --quality low --format mp4

これは480p／15fpsでレンダリングされるため、タイミングやレイアウトをすばやく確認できます。動画をユーザーに提示してください。

ステップ4：反復する

よくある調整依頼とその対応方法：

依頼	対応
「遅く／速くして」	run_time= のパラメーターと self.wait() の時間を調整します
「色を変更して」	色定数を更新します
「ステップを追加して」	セクション間に新しいアニメーションブロックを挿入します
「順番を入れ替えて」	コードブロックを移動します
「レイアウトを変更して」	.shift()、.next_to()、.arrange() の呼び出しを調整します
「ラベル／注釈を追加して」	.next_to() を使って Text または MathTex オブジェクトを追加します
「ループさせて」	対応する開始状態と終了状態を追加します

ステップ5：最終版を書き出す

ユーザーが満足したら：

python3 scripts/render_video.py scene.py ConceptScene --quality high --format mp4

品質プリセット

プリセット	解像度	FPS	フラグ	用途
low	480p	15	-ql	高速プレビュー
medium	720p	30	-qm	草案のレビュー
high	1080p	60	-qh	最終納品
4k	2160p	60	-qk	プレゼンテーション品質

フォーマットのオプション

フォーマット	フラグ	用途
mp4	--format mp4	標準的な動画の納品
gif	--format gif	ドキュメントやソーシャルメディアへの埋め込み
webm	--format webm	Web 向けに最適化

出力の納品

次の両方を提示します。

1. .py シーンファイル（後から編集するため）
2. レンダリング済みの動画ファイル（最終成果物）

最終動画を /mnt/user-data/outputs/ にコピーして、提示してください。

ステップ 5.5：音声オーバーレイ（任意）

ユーザーが音声（音楽またはナレーション）を提供した場合、または音声をリクエストした場合：

# Background music at 25% volume with fade-in/out
python3 scripts/add_audio.py final.mp4 music.mp3 \
    --output final_with_audio.mp4 \
    --volume 0.25 --fade-in 2 --fade-out 3 --trim-to-video

# Voiceover at full volume, trimmed to video length
python3 scripts/add_audio.py final.mp4 voiceover.mp3 \
    --output final_narrated.mp4 --trim-to-video

録音前にナレーションの台本を作成する場合は、references/rules/voiceover-scaffold.md をお読みください。 字幕を作成する場合は、references/rules/subtitles.md をお読みください。 高度なマルチトラックミキシングについては、references/rules/audio-overlay.md をお読みください。

エラー処理

エラー	原因	解決策
ModuleNotFoundError: manim	Manim がインストールされていない	ステップ 0 のセットアップコマンドを実行します
pangocairo のビルドエラー	システムの開発用ヘッダーが不足している	apt-get install -y libpango1.0-dev
FileNotFoundError: ffmpeg	ffmpeg がインストールされていない	apt-get install -y ffmpeg
シーンクラスが見つからない	クラス名が一致していない	クラス名が CLI 引数と一致しているか確認します
オブジェクトが重なっている	位置が計算されていない	.next_to()、.arrange()、明示的な .shift() の呼び出しを使用します
テキストが切れている	テキストが大きすぎる、または端に近い位置にある	font_size を小さくするか、±6、±3.5 の範囲内に位置を調整します
レンダリングが遅い	オブジェクトが多すぎる、または変形が複雑	オブジェクト数を減らし、パスを簡素化して、低い品質設定を使用します
LaTeX Error	LaTeX がインストールされていない（MathTex 用）	代わりに Text を使用するか、texlive-latex-base をインストールします

LaTeX の代替手段

LaTeX が利用できない場合は、MathTex と Tex を避けてください。代わりに、Unicode の数式記号を使った Text を使用してください。

# Instead of: MathTex(r"\frac{1}{n} \sum_{i=1}^{n} x_i")
# Use:        Text("(1/n) Σ xᵢ", font_size=36)

エージェントモード（オプトイン）

デフォルトのワンショットモードは高速かつ低コストで、コーダーがコンセプトから直接 scene.py を作成します。レイアウトの正確さやアセットの解決が重要で、追加の LLM および VLM 呼び出しに見合う本番品質のレンダリングが必要な場合は、エージェントモードを使用してください。

パイプライン

concept
  └─► plan_storyboard.py ──► storyboard.json
            │
            ▼
      fetch_assets.py (optional)
            │
            ▼
      coder writes scene.py
            │
            ▼
      render_video.py --max-fix-attempts N
            │  ▲
            │  └─ LLM fixup loop (on failure, up to N retries)
            ▼
      critic_pass.py --critic
            │  ▲
            │  └─ VLM layout patch (1 call with M image blocks)
            ▼
       final MP4

フラグのリファレンス

スクリプト	フラグ	デフォルト	上限	効果	コストへの影響
render_video.py	--max-fix-attempts	0	3	レンダリング失敗時に LLM が自動修正します。0 = 無効	再試行ごとに LLM 呼び出しが 1 回増加します
critic_pass.py	--critic	無効	—	VLM による批評パスを有効にします。このフラグがない場合は noop	VLM 呼び出しが 1 回増加します（N 個の画像ブロック）
critic_pass.py	--critic-budget	50000	—	批評呼び出しのトークン予算。超過するとエラーで停止します	上限を設定します。予算の際限ない消費を防ぐために使用します
critic_pass.py	--frames	5	10	批評用にレンダリング済み動画からサンプリングするフレーム数	フレーム数が多いほど、批評実行ごとのトークンコストが高くなります
fetch_assets.py	--adapter	none	—	アセットのバックエンド：local、iconfinder、none	iconfinder は外部 API 呼び出しを追加します
fetch_assets.py	--asset-dir	—	—	--adapter=local のルートディレクトリ。local 使用時は必須	なし

コストのトレードオフ

修正ループでは、レンダリングに失敗するたびに LLM 呼び出しが 1 回追加されます。--max-fix-attempts 3 を指定すると、ループが終了するか成功するまでに、最大 3 回の追加呼び出しが発生する可能性があります。批評パスでは、N 個の PNG 画像ブロックを含む VLM 呼び出しが 1 回追加されます（デフォルトは 5 個、最大 10 個）。各フレームのトークン数は、base64 エンコードされた PNG の約 800 バイトにつき 1 トークンです。そのため、高解像度の複雑なシーンでは、コストが大幅に増加します。--critic-budget に控えめなトークン上限（例：20000）を設定すると、API 呼び出しの前に BudgetExceededError が発生するため、意図せずサイズの大きいリクエストに対して料金が発生することはありません。このエラーは明確に通知され、設計上、復旧できません。

呼び出しの例

# 1. Plan
python3 scripts/plan_storyboard.py "explain transformer self-attention" \
    --output storyboard.json

# 2. (Optional) Fetch assets
python3 scripts/fetch_assets.py storyboard.json \
    --adapter local --asset-dir ./assets --output resolved.json

# 3. Coder writes scene.py (Claude writes this from storyboard.json)

# 4. Render with auto-fix
python3 scripts/render_video.py scene.py AttentionScene \
    --quality high --format mp4 --max-fix-attempts 3 \
    --output final.mp4

# 5. Critic pass
python3 scripts/critic_pass.py scene.py final.mp4 \
    --critic --critic-budget 40000 --frames 5

エージェント型パイプラインの設計（ストーリーボードプランナー、自動修正ループ、VLM クリティック）は、Code2Video（arXiv 2510.01174、MIT）を基にしています。ベンダー提供のプロンプトテンプレートは、上流の LICENSE とともに references/code2video/ にあります。ベンダリングの記録、固定されたコミット、再同期ポリシーの詳細は、ルートの ATTRIBUTIONS.md で管理されています。

制限事項

• Manim と ffmpeg が必要です — これらの依存関係がないとレンダリングできません。
• 音声はレンダリング後にのみ追加できます — Manim は無音の MP4 をレンダリングします。エクスポート後に音声を重ねるには、scripts/add_audio.py を使用してください。
• LaTeX は任意です — MathTex には LaTeX のインストールが必要です。数式には Unicode を使った Text を代わりに使用してください。
• レンダリング時間は複雑さに応じて増加します — 多数のオブジェクトを含む 30 秒の 1080p シーンでは、レンダリングに 1～2 分かかることがあります。
• 3D シーンには OpenGL が必要です — ThreeDScene はヘッドレスコンテナーでは動作しない場合があります。2D の Scene クラスを使用してください。
• インタラクティブ性はありません — 出力は静的な動画ファイルであり、インタラクティブなウィジェットではありません。
• GIF 出力は無音です — 音声を重ねられるのは、MP4／WEBM 出力形式のみです。

避けるべき設計上のアンチパターン

• 画面に文字を詰め込みすぎる — ラベルは 3～5 語、最大 2 行に抑えます
• すべてを一度に表示する — LaggedStart を使った段階的なアニメーションにします
• タイミングを一律にする — run_time に変化をつけてリズムを作ります（単純な内容は速く、重要な内容は遅くします）
• 視覚的な階層がない — サイズ、色、位置を使って視線を誘導します
• 虹のような色使い — 意図的に選んだ色を最大 3～4 色にします
• グリッドを無視する — arrange／align を使ってオブジェクトを一貫した位置に揃えます