manim-tts
Skill1 starsChanged 3 months agoMITView on GitHub
Building narrated explainer videos with manim + VOICEVOX TTS — hard-won pitfalls that produce silently broken output. Load whenever adding, editing, or re-rendering a manim scene that has audio, syncing narration to animation, or debugging missing sound / reappearing mobjects / LaTeX failures on Japanese text.
In this repository15 other files it gives its agents.
- autonomy-statSkill
- check-usageSkill
- compact-unfreezeSkill
- edit-statuslineSkill
- formalization-statement-fidelity-auditSkill
- get-contextSkill
- github-math-checkSkill
- heart-beatSkill
- mermaidSkill
- my-github-md-ruleSkill
- nostrSkill
- sessiondbSkill
- use-bmsSkill
- use-fandomSkill
- webapp-defaultsSkill
The file
Files
manim + TTS ナレーション動画
manim のシーンに VOICEVOX のナレーションを乗せて解説動画を作るときの知見。 どれも「エラーを出さずに壊れる」種類の罠なので、知らないと目視するまで気付けない。
最重要: 音声付きシーンは必ず --disable_caching
manim -ql --disable_caching scenes/foo.py SceneNamemanim の Scene.add_sound() はこうなっている。
if self.renderer.skip_animations:
return # 音を登録せずに戻る
time = self.time + time_offset
self.renderer.file_writer.add_sound(sound_file, time, gain)再レンダリング時、manim は変更のないアニメーションのキャッシュ済み部分動画を再利用し、
その区間を skip_animations=True で飛ばす。映像はキャッシュから復元されるが
音声はキャッシュに含まれないので、add_sound が無言で捨てられる。
症状は「2回目以降に焼いた動画は、修正で触らなかった区間だけ音が消える」。 初回は正常に鳴るので、バグ修正で焼き直した瞬間に壊れる。エラーは一切出ない。
キャッシュ無効でも 480p15 なら十数本を1分程度で焼けるので、常に付けてよい。
音量は TTS の素のままだと小さい
TTS の出力はピークが -7 dB ほどしかなく、そのままだと明らかに小さい。 一律に持ち上げてから、天井を超える分だけ抑える。
持ち上げ量 +10 dB
天井 -3 dBFS
測定窓 10 ms天井を 0 dB 近くに置いてはいけない。標本値を天井以下に抑えても、
- 標本間で再構成される波形(トゥルーピーク)は標本の最大値を超えうる
- 非可逆圧縮(AAC など)は復号後の標本値を膨らませる
の2つで超過する。実測では両方で 0.1 dB ずつ浮いた。 -3 dB にすれば余裕を持って収まり、ラウドネスの低下は 0.5 dB 程度で済む。
リミッターはフレームごとに必要な減衰量を出し、隣のフレームとの min を取って 標本ごとに線形補間する。こうすると境界で不連続にならず、 フレーム内のどの標本も天井を超えない。
章ごとに音量を揃えるのは1本に繋いだあと。 章ごとに正規化すると、繋いだときに章の切れ目で段差になる。
検証は目視と実測でやる
このワークフローの不具合は全て「レンダリングは成功するが中身が違う」型。 手順は references/verify-audio.md。要点だけ:
- フレームを抜いて実際に見る。
ffmpeg -sseof -1.4 -i out.mp4 -vframes 1 f.png - 音声の欠落は
silencedetectの差分では判定できない。 各台詞の予定位置で音量を直接測る - 複数シーンをまとめて焼くときは成功した本数を数える。 一部が落ちても後段の処理は古いファイルを拾って成功したように見える
- 検証スクリプト自体が「0件検査して合格」を出す偽の合格に注意。 必ず検査件数を表示して期待値と突き合わせる
- 図の重なりは計算で検査する。線を細かくサンプリングして、 端点以外の要素との最短距離を測る。目視は必ず見落とす
- 解説する内容そのものを外部の実装と総当たりで突き合わせる。 絵が綺麗でも中身が間違っていたら動画の意味がない
罠の一覧
詳細と対処コードは references/pitfalls.md。
| 症状 | 原因 |
| 焼き直したら一部だけ無音 | キャッシュ再利用で add_sound が飛ばされる |
| 消したはずの mobject が復活する | FadeOut は VGroup の子を消せない |
| 複製したものだけ大きい | 強調で .scale() したまま .copy() した |
latex error converting to dvi | MathTex に日本語を入れた |
| 行列が11列以上で落ちる | pmatrix の列数上限。array を使う |
| 変化の前後で図がずれる | 前後で別々に配置を計算した |
| 添字で引いていた要素が別物になる | 並列コレクションを足して刻み幅が変わった |
| 消したものを台詞がまだ指している | 説明の途中で消した。印→残す→消す の順にする |
| 説明と絵がちぐはぐで頭に入らない | その単語を言い終わった瞬間に動かす |
| 定義なのか結果なのか分からず考え込ませる | 新しい言葉を断定形で出した |
| 同じ絵なのに意味が違って読めない | 見た目を変えずに中身の意味だけ変えた |
| 直したのに古い動画を見ている | 配布が手動の別工程になっている。1コマンドにまとめる |
| 台本と実際の台詞が食い違う | 台本を手で持っている。シーンから生成する |
| 音が小さい | TTS の素の出力はピーク -7 dB ほど。持ち上げてリミッターをかける |
| 天井以下に抑えたのにクリップする | トゥルーピークと非可逆圧縮で浮く。天井を -3 dB に下げる |
出力が多段なら1コマンドにまとめる
レンダリング先と配布先が分かれていると、手動の2段目は必ず忘れる。 実際に、焼き直したのに配布を忘れて旧版を見ながら手直しを続けたことがある。
焼く → 配る → 台本を更新、までを1コマンドにする。 キャッシュ無効の指定もそこに埋め込んでおけば、指定漏れも起きない。
台本はシーンから生成する
読み上げ原稿を手で持つと、台詞を直したときに必ずずれる。
シーンを走らせて台詞と配置時刻を吸い出し、原稿を生成する。
--dry_run を使えば動画を書き出さないので速い。
ついでに、使われなくなった台詞の音声を自動で片付ける。 台詞を統廃合すると古いキーの wav が残り続ける。 ただし走らせて台詞が1件も取れなかったときは何もしないこと。 レンダリング失敗と区別が付かず、全部消してしまう。
教える順序を先に決める
1つの例につき、新しく導入する規則は1つだけにする。 規則の分岐を数え上げて、それぞれに最小の例を割り当てると、 一度に説明する量が小さくなる。
作り始める前に構成を文書にしておくと、 台詞の重複や、定義していない語を使う事故が減る。
視聴者がまだ答えられないことを質問しない
質問形を使うのは、そこまでに提示した情報だけで視聴者が答えを導ける場合だけ。 まだ説明していない規則や、これから初めて起こる現象を質問にすると、 視聴者は根拠のない推測を求められ、説明を聞く前に止まってしまう。
悪い: 「悪い部分は何個にコピーされるのだ?」
(コピーが起こることも、個数の規則もまだ説明していない)
良い: 「親は悪い部分ごと分裂するのだ。増える数は、カッコの中の数なのだ。」新しい現象と規則は、まず断定文で順に提示する。質問は、既知の規則を 次の例へ適用させる確認にだけ使う。
ナレーションと尺を合わせる
台詞ごとに wav をキャッシュし、wave で秒数を取ってアニメの尺に使う。
実装パターンは references/narration.md。
マーキングはその単語を言い終わった瞬間に始める。 喋りながら同時に動かすと 耳と目が別のものを追うことになり、文が終わるまで待つとどの言葉の話か分からなくなる。 合わせる先は文の終わりではなく単語の終わり。 TTS のモーラ長から台詞の途中の時刻を逆算すれば、1本の wav のまま複数の時点に合わせられる。 ただし間を空けたいときは、1本に無音を差し込まずフレーズごとに別々に合成する。 続きとして合成された音声を途中で切ると、ぶつ切れに聞こえる。
消すのは説明が終わってから。 台詞が「消す」と言った瞬間に消すと、 その後の数秒で語られる性質を視聴者が確かめられない。 印を付ける → 説明が終わるまで残す → 消す、の3段階に分ける。 出やすい不具合なので references/narration.md を読むこと。
say_and_play(key, text, *anims, run_time=...)— 台詞を流しつつアニメ、残りを待つsay_over(key, text, build)— 台詞の尺に合わせて一連のアニメを流す- 台詞テキストのハッシュを manifest に持ち、変えた行だけ再合成する
wav は再生成できるので .gitignore に入れ、台詞を持つ manifest.json だけコミットする。
VOICEVOX
セットアップ、話者ID、ライセンスは references/voicevox.md。 要点だけ:
- Docker で
voicevox/voicevox_engine:cpu-latest、127.0.0.1:50021 - クレジット表記が必須。無い商用利用は1キャラ40万円
- WSL の再生は
paplay --server=unix:/mnt/wslg/PulseServer foo.wav
日本語
Text()は Pango 経由でシステムフォントを使う。フォント指定なしで日本語が出るMathTex()/Tex()は LaTeX 経由で、CJK テンプレートが無いと日本語で落ちる- 日本語は
Text()、数式はMathTex()と徹底する
図の読みやすさ
- 値を高さや位置で表すなら、その値の数字も併記する。 段が2つ以上になると、高さだけでは読み取れなくなる
- 基準線(0の位置)に点線を通すと、各要素の値が目で追える
- 呼び名は最初から一般化できる語にする。 2段しかない前提の呼び名(例:「ラベル」)は3段目で破綻するので、 「1行目」「2行目」のように番号で呼ぶ
- 同じ見た目のまま、中身の意味だけ変えない。 「丸の中の数字」が、ある場面では高さで、別の場面では別の値、という作りにすると、 視聴者はどちらを見ているのか判別できない。色か形を変えて、意味の違いを目に出す
- 新しい言葉は「こう呼ぶことにする」で導入する。 断定形で出すと、 定義なのか導かれた結果なのかが分からず、視聴者がそこで考え込む。 表記そのものにも名前を付けて、あとから呼び戻せるようにする
環境
- manim 0.20.1 は Python >= 3.11 が必要。システムの python3 が古いなら uv で入れる
pycairoは PyPI に Windows 版 wheel しか無く Linux はソースビルド。manimpangoも pangocairo を要求するのでbuild-essential pkg-config libcairo2-dev libpango1.0-devが要る
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

