Communitygithub.com

digitalsamba/claude-code-video-toolkit

Pythonによる動画合成ツールキット。moviepy 2.xを用いてAI生成動画(LTX-2、SadTalker)に決定論的なテキストを重ねたり、クリップを合成したり、単一ファイルのbuild.py動画プロジェクトを構築します。ラベル/キャプション/ローワーサードの追加、Remotionを使わない純Pythonでの短尺広告スポット作成、プログラムによる動画合成に最適です。

claude-code-video-toolkit とは?

このスキルは、AIエージェント(Claude Codeなど)がmoviepy 2.xライブラリを使って動画をプログラム的に合成するための実践的なガイドです。主な目的は、LTX-2やSadTalkerが出力する「生のAI動画」に対し、人間が確認可能でピクセル単位の精度が求められるテキスト(氏名、価格、出典クレジットなど)を重ね合わせることです。AIでは生成が困難な「信頼できるテキスト」を実現するため、Pillow (PIL) でテキストを画像としてレンダリングし、それをmoviepyの`ImageClip`として合成する「PIL回避策」を推奨しています。スキルの核となるパターンは「AI生成動画(背景) + PILテキスト画像(前景) = `CompositeVideoClip`」という単純かつ強力な構成です。これにより、ニュースの人名テロップ、ドキュメンタリーのローワーサード、広告のタイトルカード、SNSショート動画のキャプションなど、様々なジャンルのプロダクション品質の動画を、Remotionのような重いツールチェーンなしに、Python単一ファイル(`build.py`)で作成できます。また、音声ファイルのタイムスタンプに全てのビジュアル要素のタイミングを固定する「オーディオアンカー型タイムライン」パターンにより、フレーム単位の編集が求められる広告スポットなどでもタイミングのずれを完全に排除します。`examples/`ディレクトリには2つの実用的なサンプル(15秒広告スポット、データ可視化チャート)が含まれており、`uv run build.py`で即座に実行・確認できます。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/digitalsamba/claude-code-video-toolkit/tree/HEAD/.claude/skills/moviepy

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

digitalsamba/claude-code-video-toolkit

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

digitalsamba/ideogram4

Prompting patterns for Ideogram 4 text-to-image — best-in-class in-image text rendering and exact color/layout control via structured JSON captions. Use when generating images that need legible on-image text (title cards, thumbnails, logos, signage, CTAs), precise brand colors, or controlled spatial layout. Triggers include title slide image, thumbnail with text, on-image text, legible text in image, brand color palette image, bounding-box layout, Ideogram.

digitalsamba/parody-short

Comedy shorts about a group's own life - a team's launch, quarter end, office move or leaving do; a club's season; a class's year; a family's Christmas - or about a shared topic everyone recognises (video calls, the return to the office), told in a borrowed genre (80s action intro, creature feature, Dickens Christmas ad, heist, nature documentary) and starring the group's real, animated photos or an invented cast. Covers mining the group's own context for in-jokes (chat, email, calendars,...

digitalsamba/synthetic-ui-demo

Product demo and release-notes videos with no screen recording. Rebuild the app's screens as static React from its source code, then drive them in Remotion with a scripted cursor and camera (lib/components Stage + Cursor). Use when making a product walkthrough, feature demo, release-notes or changelog video for an app whose source you can read, or when a Playwright recording would be flaky, need test data, or go stale. Triggers include synthetic demo, rebuild the UI, release video, feature...

関連スキル