manim-tts

Files (5)

• SKILL.md
• narration.md · references/
• pitfalls.md · references/
• verify-audio.md · references/
• voicevox.md · references/

SKILL.md (first lines)

# manim + TTS ナレーション動画

manim のシーンに VOICEVOX のナレーションを乗せて解説動画を作るときの知見。
**どれも「エラーを出さずに壊れる」種類の罠**なので、知らないと目視するまで気付けない。

## 最重要: 音声付きシーンは必ず `--disable_caching`

```bash
manim -ql --disable_caching scenes/foo.py SceneName
```

manim の `Scene.add_sound()` はこうなっている。

```python
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](references/verify-audio.md)。要点だけ:

- **フレームを抜いて実際に見る**。`ffmpeg -sseof -1.4 -i out.mp4 -vframes 1 f.png`
- 音声の欠落は `silencedetect` の差分では判定できない。
  **各台詞の予定位置で音量を直接測る**
- 複数シーンをまとめて焼くときは**成功した本数を数える**。
  一部が落ちても後段の処理は古いファイルを拾って成功したように見える
- 検証スクリプト自体が「0件検査して合格」を出す偽の合格に注意。
  **必ず検査件数を表示して期待値と突き合わせる**
- **図の重なりは計算で検査する**。線を細かくサンプリングして、
  端点以外の要素との最短距離を測る。目視は必ず見落とす
- **解説する内容そのものを外部の実装と総当たりで突き合わせる**。
  絵が綺麗でも中身が間違っていたら動画の意味がない

## 罠の一覧

詳細と対処コードは [references/pitfalls.md](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つだけ**にする。
規則の分岐を数え上げて、それぞれに最小の例を割り当てると、
一度に説明する量が小さくなる。

From koteitan/my-skills, MIT.

More from koteitan/my-skills