srt-whiteboard-animation を実際に動かしてみた動いた

SRT字幕を解析して幕(シーン)に分け、線画イラスト1枚とその要素配置(annotation.json)から、ペン先が動いて線画→彩色の順に描かれる白板手描き風のMP4を作るPythonツール。

配布元: https://github.com/geeklee/srt-whiteboard-animation 　／　2026-09-08 時点で確認

この日に実際に動かした結果です。内容の誤りに気づかれた場合はお問い合わせください。確認のうえ訂正します。

使い方

やること：SRT字幕と1枚の線画イラストから、字幕の流れに沿って一筆書きで絵が浮かび上がる白板動画(MP4)を1本作る。

1. 付属の環境準備スクリプトを実行する。専用の仮想環境を作り、必要なライブラリを自動でインストールする。

   python3 scripts/prepare_env.py --check
   python3 scripts/prepare_env.py

   最終行に `ENV_PY=<パス>` が出て、`.venv/` の中に opencv-python・numpy・av・Pillow が入る

2. 自分で用意したSRT字幕を解析し、幕の区切りと各幕の尺(sceneDurationMs)を決める。

   python3 scripts/parse_srt.py /tmp/demo.srt --target-sec 30 --min-sec 25 --max-sec 35

   字幕ごとの開始・終了ミリ秒と、幕としてまとめた区間・合計尺がJSONで出力される。日本語の字幕をそのまま渡しても文字化けせず解析できた

3. 線画イラストのPNGと、要素ごとの表示順・時間・字幕を紐づけた`annotation.json`を用意する(本検証では同梱サンプルを使用)。区域番号を確認したいのでプレビュー画像を作る(フォントパスの修正が必要だった点は下記「不便だった点」を参照)。

   sed -i "s#C:/Windows/Fonts/msyh.ttc#/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc#" render_annotation_preview_fixed.py
   .venv/bin/python render_annotation_preview_fixed.py examples/scene-01-monkey-mountain-banana.png examples/scene-01-monkey-mountain-banana.annotation.json /tmp/preview.png

   各要素に番号・向きの矢印を重ねたPNGができる

4. 標注済みの線画から、白板動画を1幕分レンダリングする。

   time .venv/bin/python scripts/render_stream_whiteboard.py examples/scene-01-monkey-mountain-banana.png examples/scene-01-monkey-mountain-banana.annotation.json /tmp/scene01.mp4 assets/drawing-hand.png --ink-path grid --color-fill contour-wipe

   約35秒で `OUTPUT=/tmp/scene01.mp4` が出力され、1080x600・60fps・約1.7MBのMP4(H.264)ができる。annotation.jsonの`sceneDurationMs`(8600ms)通りの長さになる

通した結果

======================================================== SRT 白板动画整合渲染器 (mask 编排 + stream 画法) ======================================================== 输入: examples/scene-01-monkey-mountain-banana.png 输出尺寸: 1080x600, 帧率: 60 区域数: 3, 总时长: 8600ms, 笔迹: grid, 上色: contour-wipe H.264 转码完成(PyAV): /tmp/scene01.mp4

最终视频: /tmp/scene01.mp4 (1.72 MB) ======================================================== OUTPUT=/tmp/scene01.mp4

使ってみて良かった点

• 単幕なら「字幕解析→線画+標注→MP4化」まで、pipでインストールしたライブラリだけで一気通貫して動いた。GPUや有料APIは不要で無料
• `prepare_env.py`が仮想環境の作成からライブラリの導入まで自動でやってくれるため、依存関係を手で書く必要がない
• 生成されたMP4は指定通り1080x600・60fpsで、annotation.jsonの`sceneDurationMs`に沿った長さになっていた

使ってみて不便だった点

• 複数幕を1本に結合する`merge_scenes.py`が、システムに`ffmpeg`が無い環境ではPyAVによるフォールバック処理でエラーになり、結合できなかった(単幕のレンダリング自体は問題なく動く)
• `render_annotation_preview.py`を動かすにはPillow入りの`.venv`のPythonを使う必要があるが、無印の`python`で実行すると`ModuleNotFoundError: No module named 'PIL'`になる
• `render_annotation_preview.py`内のラベル用フォントパスが`C:/Windows/Fonts/msyh.ttc`にハードコードされており、Linux/macOSではそのままでは`OSError: cannot open resource`で失敗する。別のCJKフォントのパスに書き換えると動いた
• 実際に使う線画イラストとannotation.json(要素の座標・表示順)は自分で用意する必要があり、単体のPythonスクリプトだけでは作れない(本来はAIエージェントとの対話で線画生成・標注まで行う設計)

詰まった点と、効いた対処

python3 scripts/render_annotation_preview.py examples/scene-01-monkey-mountain-banana.png examples/scene-01-monkey-mountain-banana.annotation.json /tmp/preview.png

ModuleNotFoundError: No module named 'PIL'

.venv/bin/python scripts/render_annotation_preview.py examples/scene-01-monkey-mountain-banana.png examples/scene-01-monkey-mountain-banana.annotation.json /tmp/preview.png

OSError: cannot open resource

.venv/bin/python scripts/merge_scenes.py --inputs /tmp/scene01.mp4 /tmp/scene01b.mp4 --output /tmp/final.mp4

av.error.ArgumentError: Invalid argument: '/tmp/final.mp4' returned 22

確認した条件