moviepy による動画制作
moviepy は、AI生成動画に決定論的なテキストを重ねるため、およびRemotionツールチェーンを使わずに短い単一ファイルのPython動画プロジェクトを構築するための、ツールキットの主要ライブラリです。
根底にある原則は信頼できるテキストです。テキストが読みやすく、正確で、一貫していることが法的、編集的、または商業的に要求されるあらゆるジャンルにおいて、AIレンダリングによるフレーム内テキストは許容できず、moviepyによるオーバーレイが自然な修正方法となります。名前は正しく綴られていなければなりません。価格は正確でなければなりません。出典クレジットはピクセル単位で完璧でなければなりません。AI生成モデルはそれらのいずれも保証できません。
moviepy と Remotion の使い分け
| moviepy を使用する場合… | Remotion を使用する場合… |
|---|---|
| LTX-2 や SadTalker の出力にテキスト/ラベルを重ねる | 長尺のスプリントレビューやプロダクトデモを構築する |
単一の build.py で30秒未満の広告スタイルスポットを構築する | マルチテンプレート、マルチブランド、デザイン重視の作業 |
データ駆動型ビジュアル(matplotlib FuncAnimation → mp4)を合成する | Reactコンポーネントやデザインシステムの再利用が必要なもの |
| 既存の動画ファイルに対する一回限りの変換 | プロジェクトのライフサイクル(計画→レンダリング)が重要なもの |
| Node.js / React のメンタルオーバーヘッドをゼロにしたい | Remotion Studio のホットリロードプレビューが欲しい |
このスキル内のすべての実用的なリファレンスは examples/ にあります。
examples/quick-spot/build.py— 15秒の広告スタイルスポット。オーディオアンカー型タイムライン、テキストオーバーレイ、オプションのVO+ダック音楽。外部アセットゼロでデフォルトでは無音でレンダリングされます。examples/data-viz-chart/build.py— 決定論的なタイトルと出典クレジットを備えたアニメーション時系列チャート。matplotlib(データ)とmoviepy(信頼できるテキスト)の分割を示しています。
どちらも uv run build.py で実行でき、すぐに実際の out.mp4 を生成します。このスキルと一緒に読んでください。以下のすべてのパターンが動作しているところを示しています。
依存関係。 moviepy、Pillow、matplotlib はルートの pyproject.toml で宣言されており、ツールキットの一行Pythonセットアップ uv sync でインストールされます。サンプル実行時に Missing dependency が発生した場合は、リポジトリのルートからそのコマンドを実行してください。サンプルの build.py ファイルはエラーメッセージで同じことを伝え、生のトレースバックを出力する代わりにクリーンに終了します。
主なユースケース:AI生成動画へのテキストオーバーレイ
LTX-2 と SadTalker の両方は、裸のビジュアルを出力します。
- LTX-2 は読み取り可能なテキストを確実にレンダリングできません(モデルが文字形状を幻覚します — ltx2スキルの「Bad Prompts」を参照)。
- SadTalker は、キャプション、ラベル、ローワーサード、コンテキストなしのトーキングヘッドを出力します。
修正方法は、ビジュアルをクリーンに生成し、その後 moviepy で決定論的にテキストを合成することです。これはこのツールキットにおける標準的なパターンです。
from moviepy import VideoFileClip, ImageClip, CompositeVideoClip
# 1. AI生成ビジュアル(LTX-2 または SadTalker 出力)
bg = VideoFileClip("lugh_ltx.mp4").without_audio()
# 2. PIL 経由でレンダリングされたテキスト → ImageClip(以下の「テキストレンダリング」を参照)
title = (
ImageClip("text_cache/intro_title.png")
.with_duration(2.0)
.with_start(0.5)
.with_position(("center", 880))
)
# 3. 合成
final = CompositeVideoClip([bg, title], size=(1920, 1080))
final.write_videofile("lugh_with_caption.mp4", fps=30, codec="libx264")
これがよく取る形状:
| 形状 | LTX-2 での使用 | SadTalker での使用 |
|---|---|---|
| メインビジュアル上のタイトルカード | 映画的なLTX-2 Bロール上に「INTRODUCING LONGARM」 | n/a |
| ローワーサード / ネームプレート | n/a | トーキングヘッドの下に「Lugh — Ancient Warrior God」 |
| 引用キャプション | LTX-2キャラクターカメオ上に「I am going home.」 | 同様に、SadTalkerのトーキングヘッド上に |
| ブランド帰属表示 | 最後の1秒にロゴ+URLフェードイン | 同様 |
| コントラスト用の着色オーバーレイ | テキストの背後に濃紺の半透明レイヤー | 同様 |
このパターンが活躍するジャンル
「AIビジュアル+決定論的テキストオーバーレイ」パターンは、いくつかの動画スタイルにとって自然な制作パイプラインです。リクエストがこれらのいずれかに該当する場合は、デフォルトで moviepy を使用してください。
| ジャンル | 何をオーバーレイするか | moviepy が適切な理由 |
|---|---|---|
| ニュース / トーキングヘッドジャーナリズム | スピーカーネームプレート、ロケーションバー、速報バナー、出典クレジット、プルクォート | 名前は正しく綴られなければならない(編集上/法律上)。最大のカテゴリー。 |
| ドキュメンタリーセグメント | インタビュイーローワーサード、章タイトル、アーカイブ出典クレジット、ロケーションスタンプ | ニュースと同じ信頼性要件。 |
| 予告編 / プロモーションスポット | タイトルカード、クレジットオーバーレイ(「FROM THE DIRECTOR OF…」)、日付スティング、クォートカード、CTA | タイトにタイミングが決められ、テキストが多く、すべてのフレームが重要。q2-townhall-longarm-ad の例はまさにこれ。 |
| ソーシャルショートフォーム(Reels、TikTok、Shorts) | 無音視聴のための単語単位の正確なキャプション、ハッシュタグオーバーレイ | ほとんどのソーシャル視聴はミュートされており、キャプションは必須。 |
| 注釈付きプロダクトデモ | 価格コールアウト、機能ラベル、スクリーンレコーディング上の「ここをクリック」ポインター、ビフォー/アフターラベル | 価格と製品名は正確でなければならない。 |
| チュートリアル / 解説 | ステップ番号オーバーレイ、ターミナルコマンドキャプション、キーボードショートカットコールアウト | ステップ番号は連続している必要があり、コマンドはコピペ可能でなければならない。 |
あまり一般的ではないが実際に適合するもの:ミュージックビデオ(歌詞オーバーレイ)、リアクション動画(出典クレジット)、スポーツダイジェスト(スコアオーバーレイ)、不動産ツアー(価格/平方フィート)、カンファレンストーク(スピーカー+セッションプレート)。
完全なSRT駆動字幕(長尺、タイムコード化、多言語)には、moviepyは使えますが理想的ではありません — ffmpeg の subtitles フィルターまたは専用の字幕ツールを使用してください。moviepyはバルクのキャプショントラックではなく、手動配置のオーバーレイに最適です。
テキストレンダリング — TextClip ではなく PIL を使用
重要な落とし穴: moviepy 2.x の TextClip(method='label') には、タイトバウンディングボックスのバグがあり、文字のアセンダーとディセンダーをクリップします(大文字の上部、g/p/y の尾部)。Apple Siliconでは、文字の端が切り取られているのを見て、何時間も原因に気づかないでしょう。
回避策: PIL を介してテキストを透明なPNGにレンダリングし、それを ImageClip として読み込みます。結果をコンテンツハッシュでキャッシュして、再ビルドを無料にします。
import hashlib
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
ARIAL_BOLD = "/System/Library/Fonts/Supplemental/Arial Bold.ttf"
def render_text_png(txt, size, hex_color, cache_dir="./text_cache"):
cache = Path(cache_dir); cache.mkdir(parents=True, exist_ok=True)
key = hashlib.sha1(f"{txt}|{size}|{hex_color}".encode()).hexdigest()[:16]
path = cache / f"{key}.png"
if path.exists():
return str(path)
font = ImageFont.truetype(ARIAL_BOLD, size)
bbox = ImageDraw.Draw(Image.new("RGBA", (1, 1))).textbbox((0, 0), txt, font=font)
tw, th = bbox[2] - bbox[0], bbox[3] - bbox[1]
pad = max(20, size // 4)
img = Image.new("RGBA", (tw + pad * 2, th + pad * 2), (0, 0, 0, 0))
rgb = tuple(int(hex_color.lstrip("#")[i:i+2], 16) for i in (0, 2, 4))
ImageDraw.Draw(img).text((pad - bbox[0], pad - bbox[1]), txt, font=font, fill=(*rgb, 255))
img.save(path)
return str(path)
完全なヘルパー(bold、position、fades、およびよりクリーンなエルゴノミクスのためのkwargs付き)は examples/quick-spot/build.py にあります — 再実装せずにコピーしてください。
オーディオアンカー型タイムラインパターン
すべてのフレームが重要な広告スタイルの編集の場合、まずシーンごとのVOを生成し、すべてのビジュアルを既知の絶対タイムスタンプに固定します。これによりタイミングのずれが完全に排除されます。完全なパターンについては CLAUDE.md → Video Timing → Audio-Anchored Timelines を参照してください。短いバージョン:
# オーディオアンカー型タイムライン(25秒):
# シーン1 tired 0.3 → 3.74 (オーディオ 3.44秒)
# シーン2 worries 4.0 → 8.88 (オーディオ 4.88秒)
text_clip("TIRED OF", start=0.5, duration=1.2)
text_clip("THIRD-PARTY", start=1.0, duration=1.8)
vo_clip("01_tired.mp3", start=0.3)
vo_clip("02_worries.mp3", start=4.0)
よく使うレシピ
単一のAI生成クリップへのテキストオーバーレイ
from moviepy import VideoFileClip, ImageClip, CompositeVideoClip
bg = VideoFileClip("ltx_hero.mp4").without_audio()
caption = (
ImageClip(render_text_png("THE FUTURE OF AGENTS", 140, "#FFFFFF"))
.with_duration(bg.duration)
.with_position(("center", 880))
)
CompositeVideoClip([bg, caption], size=bg.size).write_videofile("captioned.mp4", fps=30)
SadTalkerトーキングヘッド上のローワーサード
from moviepy import VideoFileClip, ImageClip, ColorClip, CompositeVideoClip
talking = VideoFileClip("narrator_sadtalker.mp4")
W, H = talking.size
# コントラストのために下部に半透明のバー
bar = (
ColorClip((W, 140), color=(20, 24, 38))
.with_duration(talking.duration)
.with_opacity(0.75)
.with_position(("center", H - 160))
)
name = (
ImageClip(render_text_png("LUGH", 72, "#F06859"))
.with_duration(talking.duration)
.with_position((80, H - 150))
)
title = (
ImageClip(render_text_png("Ancient Warrior God", 36, "#FFFFFF"))
.with_duration(talking.duration)
.with_position((80, H - 80))
)
CompositeVideoClip([talking, bar, name, title]).write_videofile("with_lower_third.mp4", fps=30)
派手な映像上でテキストコントラストを高めるための着色オーバーレイ
LTX-2のBロールは、読み取り可能なテキストには視覚的に派手すぎることがよくあります。ビデオとテキストの間に半透明のネイビーレイヤーを挿入します:
from moviepy import ColorClip
tint = (
ColorClip((W, H), color=(20, 24, 38))
.with_duration(duration)
.with_opacity(0.55)
)
# 合成順序: bg → tint → text
CompositeVideoClip([bg, tint, text_clip])
サイドバイサイド合成
from moviepy import VideoFileClip, CompositeVideoClip, ColorClip
left = VideoFileClip("demo_a.mp4").resized(width=960).with_position(( 0, "center"))
right = VideoFileClip("demo_b.mp4").resized(width=960).with_position((960, "center"))
bg = ColorClip((1920, 1080), color=(0, 0, 0)).with_duration(max(left.duration, right.duration))
CompositeVideoClip([bg, left, right]).write_videofile("split.mp4", fps=30)
シーンごとのVOとダック音楽のミックス
from moviepy import AudioFileClip, CompositeAudioClip
from moviepy.audio.fx.MultiplyVolume import MultiplyVolume
from moviepy.audio.fx.AudioFadeIn import AudioFadeIn
from moviepy.audio.fx.AudioFadeOut import AudioFadeOut
music = AudioFileClip("music.mp3").with_effects([
MultiplyVolume(0.22), # VOの下にダック
AudioFadeIn(0.5),
AudioFadeOut(1.5),
])
vo = [
AudioFileClip(f"scenes/0{i}.mp3").with_effects([MultiplyVolume(1.15)]).with_start(start)
for i, start in [(1, 0.3), (2, 4.0), (3, 9.1)]
]
final_audio = CompositeAudioClip([music] + vo)
落とし穴
- moviepy 2.x ではメソッド名が変更されました。
subclipped(subclipではなく)、with_duration/with_start/with_position(set_durationなどではなく)、.fadein()/.fadeout()の代わりにwith_effects([...])を使用します。多くのオンラインチュートリアルはまだ1.xの構文を示しています — 疑いを持ってください。 TextClip(method='label')はアセンダー/ディセンダーをクリップします。 常に上記のPIL回避策を使用してください。OffthreadVideoはRemotion専用です。 moviepy はVideoFileClipを使用します。これらを混在させないでください。- リサイズには Pillow ≥ 10.0 が必要です(LANCZOSリサンプルのため)。
ANTIALIASエラーが表示された場合は、Pillowをアップグレードしてください。 ColorClipはRGBタプルを受け取り、16進文字列は受け取りません。"#141826"ではなく(20, 24, 38)を使用してください。VideoFileClipのオーディオはデフォルトで読み込まれます。 ビジュアルのみが必要な場合は.without_audio()を呼び出してください — 不要なオーディオで合成すると、CompositeAudioClipで静かなVOドロップが発生します。CompositeVideoClipには常にsize=(W, H)を設定してください。 設定しないと、出力サイズは最初のクリップに従い、ターゲットより小さくなる可能性があります。
何をいつ使うか
| タスク | ツール |
|---|---|
| 静止画像をアニメーション化 | tools/ltx2.py --input |
| フォトリアルな肖像画からのトーキングヘッド | tools/sadtalker.py |
| スタイライズされたキャラクターからのトーキングヘッド | tools/ltx2.py --input(ltx2スキルを参照) |
| 上記のいずれかにラベル/キャプション/ローワーサードを追加 | moviepy + PIL(このスキル) |
| 既存ファイルの変換/圧縮/リサイズ | ffmpeg(ffmpegスキルを参照) |
| 長尺のデザインシステム駆動の動画 | Remotion(remotionスキルを参照) |
参考文献
- 実用的なサンプル — 短い広告スタイルスポット:
examples/quick-spot/build.py - 実用的なサンプル — テキストオーバーレイ付きデータ可視化:
examples/data-viz-chart/build.py - オーディオアンカー型タイムライン:
CLAUDE.md → Video Timing → Audio-Anchored Timelines - 関連スキル:
ltx2、ffmpeg、remotion