video-toolkit

動画ツールキット

テキストのブリーフからプロ品質の解説動画を作成します。このツールキットは、ナレーション、画像生成、音楽、トーキングヘッドアニメーションに、クラウド GPU（Modal または RunPod）上のオープンソース AI モデルを使用します。Remotion（React）が合成とレンダリングを担当します。

重要：ツールキットのパス

ツールキットは固定パスにあります。ツールのコマンドを実行する前に、必ずここに cd してください。

TOOLKIT=~/.openclaw/workspace/claude-code-video-toolkit
cd $TOOLKIT

プロジェクトディレクトリ内からツールのコマンドを実行しないでください。 ツールはツールキットのルートを基準にパスを解決します。

セットアップ

ステップ 1：現在の状態を確認する

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/verify_setup.py

すべてが [x] と表示される場合は、下の「クイックテスト」に進んでください。それ以外の場合は、セットアップを続けてください。

ステップ 2：Python の依存関係をインストールする

cd ~/.openclaw/workspace/claude-code-video-toolkit
pip3 install --break-system-packages -r tools/requirements.txt

注：管理対象の Python（PEP 668）を使用する Debian／Ubuntu では、--break-system-packages が必要です。コンテナ内であれば安全に使用できます。

ステップ 3：クラウド GPU エンドポイントを設定する

このツールキットでは、.env にクラウド GPU エンドポイントの URL が必要です。.env が存在し、Modal エンドポイントが設定されているか確認します。

cat ~/.openclaw/workspace/claude-code-video-toolkit/.env | grep MODAL

Modal エンドポイントが設定されていれば、準備完了です。設定されていない場合は、Modal のエンドポイント URL をユーザーに尋ねるか、Modal をセットアップしてください。

pip3 install --break-system-packages modal
python3 -m modal setup   # Opens browser for authentication

# Deploy each tool — capture the endpoint URL from output
cd ~/.openclaw/workspace/claude-code-video-toolkit
modal deploy docker/modal-qwen3-tts/app.py
modal deploy docker/modal-flux2/app.py
modal deploy docker/modal-music-gen/app.py
modal deploy docker/modal-sadtalker/app.py
modal deploy docker/modal-image-edit/app.py
modal deploy docker/modal-upscale/app.py
modal deploy docker/modal-propainter/app.py
modal deploy docker/modal-ltx2/app.py      # Requires: modal secret create huggingface-token HF_TOKEN=hf_...

LTX-2 の前提条件： LTX-2 をデプロイする前に、HuggingFace シークレットを作成し、Gemma 3 ライセンスに同意してください。

modal secret create huggingface-token HF_TOKEN=hf_your_read_access_token

各 URL を .env に追加します。

MODAL_QWEN3_TTS_ENDPOINT_URL=https://...modal.run
MODAL_FLUX2_ENDPOINT_URL=https://...modal.run
MODAL_MUSIC_GEN_ENDPOINT_URL=https://...modal.run
MODAL_SADTALKER_ENDPOINT_URL=https://...modal.run
MODAL_IMAGE_EDIT_ENDPOINT_URL=https://...modal.run
MODAL_UPSCALE_ENDPOINT_URL=https://...modal.run
MODAL_DEWATERMARK_ENDPOINT_URL=https://...modal.run
MODAL_LTX2_ENDPOINT_URL=https://...modal.run

任意ですが、安定したファイル転送のために Cloudflare R2 の使用をおすすめします。

R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=video-toolkit

ステップ 4：確認とクイックテスト

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/verify_setup.py

すべてのツールが [x] と表示されるはずです。次に、GPU パイプラインが動作することを確認するため、簡単なテストを実行します。

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/qwen3_tts.py --text "Hello, this is a test." --speaker Ryan --tone warm --output /tmp/video-toolkit-test.mp3 --cloud modal

有効な .mp3 ファイルが生成されれば、セットアップは完了です。失敗した場合は、次を確認してください。

• .env に正しい MODAL_QWEN3_TTS_ENDPOINT_URL が設定されていること
• python3 tools/verify_setup.py --json を実行し、不足しているエンドポイントを modal_tools で確認すること

費用： Modal では毎月 30 ドル分のコンピューティングを無料で利用できます。通常、60 秒の動画の費用は 1～3 ドルです。

---

動画の作成

ステップ 1：プロジェクトを作成する

cd ~/.openclaw/workspace/claude-code-video-toolkit
cp -r templates/product-demo projects/PROJECT_NAME
cd projects/PROJECT_NAME
npm install

テンプレート：product-demo（マーケティング／解説）、sprint-review、sprint-review-v2（シーンを組み合わせ可能）。

ステップ 2：設定を書く

projects/PROJECT_NAME/src/config/demo-config.ts を編集します。

export const demoConfig: ProductDemoConfig = {
  product: {
    name: 'My Product',
    tagline: 'What it does in one line',
    website: 'example.com',
  },
  scenes: [
    { type: 'title', durationSeconds: 9, content: { headline: '...', subheadline: '...' } },
    { type: 'problem', durationSeconds: 14, content: { headline: '...', problems: ['...', '...'] } },
    { type: 'solution', durationSeconds: 13, content: { headline: '...', highlights: ['...', '...'] } },
    { type: 'stats', durationSeconds: 12, content: { stats: [{value: '99%', label: '...'}, ...] } },
    { type: 'cta', durationSeconds: 10, content: { headline: '...', links: ['...'] } },
  ],
  audio: {
    backgroundMusicFile: 'audio/bg-music.mp3',
    backgroundMusicVolume: 0.12,
  },
};

シーンの種類：title、problem、solution、demo、feature、stats、cta。

長さの目安： durationSeconds は ceil(word_count / 2.5) + 2 で見積もります。ステップ 4 で音声を生成した後に調整します。

ステップ 3：ナレーションの台本を書く

projects/PROJECT_NAME/VOICEOVER-SCRIPT.md を作成します。

## Scene 1: Title (9s, ~17 words)
Build videos with AI. The product name toolkit makes it easy.

## Scene 2: Problem (14s, ~30 words)
The problem statement goes here. Keep it punchy and relatable.

シーンごとの語数の目安： (durationSeconds - 2) * 2.5 語です。-2 は、音声の遅延 1 秒と余白 1 秒を考慮したものです。

ステップ 4：素材を生成する

重要：以下のコマンドはすべて、プロジェクトディレクトリではなく、ツールキットのルートから実行してください。

cd ~/.openclaw/workspace/claude-code-video-toolkit

4a. BGM

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/music_gen.py \
  --preset corporate-bg \
  --duration 90 \
  --output projects/PROJECT_NAME/public/audio/bg-music.mp3 \
  --cloud modal

プリセット：corporate-bg、upbeat-tech、ambient、dramatic、tension、hopeful、cta、lofi。

4b. ナレーション（シーンごと）

シーンごとに .mp3 ファイルを 1 つ生成します。ナレーションファイルを 1 つだけ生成しないでください。

cd ~/.openclaw/workspace/claude-code-video-toolkit

# Scene 01
python3 tools/qwen3_tts.py \
  --text "The voiceover text for scene one." \
  --speaker Ryan --tone warm \
  --output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
  --cloud modal

# Scene 02
python3 tools/qwen3_tts.py \
  --text "The voiceover text for scene two." \
  --speaker Ryan --tone warm \
  --output projects/PROJECT_NAME/public/audio/scenes/02.mp3 \
  --cloud modal

# ... repeat for each scene

話者： Ryan、Aiden、Vivian、Serena、Uncle_Fu、Dylan、Eric、Ono_Anna、Sohee トーン： neutral、warm、professional、excited、calm、serious、storyteller、tutorial

音声クローンを使用する場合（参照録音が必要です）。

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/qwen3_tts.py \
  --text "Text to speak" \
  --ref-audio assets/voices/reference.m4a \
  --ref-text "Exact transcript of the reference audio" \
  --output projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
  --cloud modal

4c. シーン画像

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/flux2.py \
  --prompt "Dark tech background with blue geometric grid, cinematic lighting" \
  --width 1920 --height 1080 \
  --output projects/PROJECT_NAME/public/images/title-bg.png \
  --cloud modal

画像プリセット（--prompt --width --height の代わりに --preset を使用）： title-bg、problem、solution、demo-bg、stats-bg、cta、thumbnail、portrait-bg

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/flux2.py \
  --preset title-bg \
  --output projects/PROJECT_NAME/public/images/title-bg.png \
  --cloud modal

4d. 動画クリップ — Bロールとアニメーション背景（任意）

Bロールのカットアウェイ、アニメーション付きスライド背景、イントロ／アウトロのシーケンス用に、AI 動画クリップを生成します。

cd ~/.openclaw/workspace/claude-code-video-toolkit

# B-roll clip from text
python3 tools/ltx2.py \
  --prompt "Aerial drone shot over a European city at golden hour, cinematic wide angle" \
  --output projects/PROJECT_NAME/public/videos/broll-europe.mp4 \
  --cloud modal

# Animate a slide/screenshot (image-to-video)
python3 tools/ltx2.py \
  --prompt "Gentle particle effects, soft ambient light shifts, very slight camera drift" \
  --input projects/PROJECT_NAME/public/images/title-bg.png \
  --output projects/PROJECT_NAME/public/videos/animated-title.mp4 \
  --cloud modal

# Abstract intro/outro background
python3 tools/ltx2.py \
  --prompt "Dark moody abstract background with flowing blue light streaks, bokeh particles, cinematic" \
  --output projects/PROJECT_NAME/public/videos/intro-bg.mp4 \
  --cloud modal

Remotion のコンポジションでは、<OffthreadVideo> を使います。

<OffthreadVideo src={staticFile('videos/broll-europe.mp4')} />

LTX-2 のルール：

• クリップは最大約 8 秒（24fps で 193 フレーム）です。デフォルトは約 5 秒（121 フレーム）です。
• 幅と高さは 64 で割り切れる値にする必要があります。デフォルトは 768x512 です。
• クリップ 1 本あたり約 $0.20～0.25、生成時間は約 2.5 分です。
• コールドスタートは約 60～90 秒です。GPU がウォーム状態の場合、以降のクリップはより速く生成されます。
• 生成される音声は環境音のみです。音声や音楽には、ボイスオーバー／音楽ツールを使ってください。
• 生成の約 30% で、学習データに由来するアーティファクト（ロゴ／テキスト）が発生する場合があります。--seed を指定して再実行すると、結果を変えられます。

4e. トーキングヘッドナレーター（任意）

プレゼンターのポートレートを生成し、シーンごとにクリップをアニメーション化します。

cd ~/.openclaw/workspace/claude-code-video-toolkit

# 1. Generate portrait
python3 tools/flux2.py \
  --prompt "Professional presenter portrait, clean style, dark background, facing camera, upper body" \
  --width 1024 --height 576 \
  --output projects/PROJECT_NAME/public/images/presenter.png \
  --cloud modal

# 2. Generate per-scene narrator clips (one per scene, NOT one long video)
python3 tools/sadtalker.py \
  --image projects/PROJECT_NAME/public/images/presenter.png \
  --audio projects/PROJECT_NAME/public/audio/scenes/01.mp3 \
  --preprocess full --still --expression-scale 0.8 \
  --output projects/PROJECT_NAME/public/narrator-01.mp4 \
  --cloud modal

# Repeat for each scene that needs a narrator

SadTalker のルール — 以下を必ず守ってください：

• 必ず --preprocess full を使ってください（デフォルトの crop では正方形になり、アスペクト比が正しくありません）。
• 必ず --still を使ってください（頭の動きが抑えられ、プロフェッショナルな見た目になります）。
• 必ず シーンごとにクリップを生成してください（各 6～15 秒）。長い動画を 1 本だけ生成するのは絶対に避けてください。
• 処理時間：Modal A10G で音声 10 秒あたり約 3～4 分です。
• --expression-scale 0.8 を指定すると、表情を控えめにできます（範囲は 0.0～1.5 です）。

4e. 画像編集（任意）

既存の画像からシーンのバリエーションを作成します。

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/image_edit.py \
  --input projects/PROJECT_NAME/public/images/title-bg.png \
  --prompt "Make it darker with red tones, more ominous" \
  --output projects/PROJECT_NAME/public/images/problem-bg.png \
  --cloud modal

4f. アップスケーリング（任意）

cd ~/.openclaw/workspace/claude-code-video-toolkit
python3 tools/upscale.py \
  --input projects/PROJECT_NAME/public/images/some-image.png \
  --output projects/PROJECT_NAME/public/images/some-image-4x.png \
  --scale 4 --cloud modal

ステップ 5：タイミングを同期する

ボイスオーバーの生成後は、必ずこれを実行してください。 音声の長さは推定値と異なります。

cd ~/.openclaw/workspace/claude-code-video-toolkit
for f in projects/PROJECT_NAME/public/audio/scenes/*.mp3; do
  echo "$(basename $f): $(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f")s"
done

demo-config.ts の各シーンの durationSeconds を、ceil(実際の音声の長さ + 2) に更新します。

例：01.mp3 が 6.8 秒の場合、シーン 1 の durationSeconds を 9 に設定します（ceil(6.8 + 2) = 9）。

ステップ 6：静止フレームを確認する

cd ~/.openclaw/workspace/claude-code-video-toolkit/projects/PROJECT_NAME
npx remotion still src/index.ts ProductDemo --frame=100 --output=/tmp/review-scene1.png
npx remotion still src/index.ts ProductDemo --frame=400 --output=/tmp/review-scene2.png

確認項目：テキストの切れ、アニメーションのタイミング、ナレーターの PiP の配置、背景とのコントラスト。

ステップ 7：レンダリングする

cd ~/.openclaw/workspace/claude-code-video-toolkit/projects/PROJECT_NAME
npm run render

出力： out/ProductDemo.mp4

---

コンポジションのパターン

シーンごとの音声

1 秒の遅延を設定して、シーンごとに音声を使います（from={30} = 30 フレーム = 30fps で 1 秒）。

<Sequence from={30}>
  <Audio src={staticFile('audio/scenes/01.mp3')} volume={1} />
</Sequence>

シーンごとのナレーター PiP

<Sequence from={30}>
  <OffthreadVideo
    src={staticFile('narrator-01.mp4')}
    style={{ width: 320, height: 180, objectFit: 'cover' }}
    muted
  />
</Sequence>

必ず <OffthreadVideo> を使い、<video> は絶対に使わないでください。 Remotion でフレーム精度の高いレンダリングを行うには、専用のコンポーネントが必要です。

トランジション

import { TransitionSeries, linearTiming } from '@remotion/transitions';
import { fade } from '@remotion/transitions/fade';
import { glitch } from '../../../lib/transitions/presentations/glitch';
import { lightLeak } from '../../../lib/transitions/presentations/light-leak';

lib/transitions のバレルからインポートするのは絶対に避けてください — カスタムトランジションは lib/transitions/presentations/ から直接インポートしてください。

---

エラーからの復旧

問題	解決方法
ツールのコマンドが「No module named...」で失敗する	ツールキットのルートから pip3 install --break-system-packages -r tools/requirements.txt を実行します
「MODAL_*_ENDPOINT_URL not configured」	.env にエンドポイント URL があるか確認します。python3 tools/verify_setup.py を実行します
SadTalker の出力が正方形／トリミングされている	--preprocess full を指定し忘れています。このフラグを付けて再実行します
音声がシーンに対して短すぎる／長すぎる	ステップ 5（タイミングの同期）を再実行し、設定を更新します
npm run render が失敗する	ツールキットのルートではなく、プロジェクトのディレクトリにいることを確認します。先に npm install を実行します
Remotion で「Cannot find module」が表示される	インポートパスを確認します。カスタムコンポーネントでは ../../../lib/ の相対パスを使います
Modal でコールドスタートがタイムアウトする	アイドル状態の後の最初の呼び出しには 30～120 秒かかります。一度再試行してください。2 回目の呼び出しでは GPU がウォーム状態になります

---

コストの見積もり（Modal）

ツール	一般的なコスト	備考
Qwen3-TTS	シーンあたり約 $0.01	ウォーム状態の GPU でシーンあたり約 20 秒
FLUX.2	画像あたり約 $0.01	ウォーム状態では約 3 秒、コールド状態では約 30 秒
ACE-Step	約 $0.02～0.05	長さによって異なります
SadTalker	シーンあたり約 $0.05～0.20	音声 10 秒あたり約 3～4 分
Qwen-Edit	約 $0.03～0.15	コールドスタートは約 8 分（25GB のモデル）
RealESRGAN	画像あたり約 $0.005	非常に高速です
LTX-2.3	クリップあたり約 $0.20～0.25	5 秒のクリップあたり約 2.5 分、A100-80GB

60 秒の動画の合計： シーン数とナレーターのクリップ数によって、約 $1～3 です。

Modal Starter プラン：月額 $30 分の無料コンピューティング。アイドル状態になると、アプリはゼロまでスケールします。