video_toolkit

Video Toolkit

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

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

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

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

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

重要：進捗報告

**すべてのクラウド GPU ツールコマンドに、必ず --progress json を追加してください。**これにより、stderr に構造化された JSON Lines が出力され、ジョブの状態を監視し、停止したジョブを検出して、進捗をリアルタイムでユーザーに報告できます。

# CORRECT — always include --progress json
uv run tools/music_gen.py --preset corporate-bg --duration 60 --output bg.mp3 --progress json

# WRONG — no visibility into job status
uv run tools/music_gen.py --preset corporate-bg --duration 60 --output bg.mp3

--progress json に対応するツール：music_gen.py、qwen3_tts.py、flux2.py、upscale.py、sadtalker.py、image_edit.py、dewatermark.py、ltx2.py、chain_video.py。

出力形式とステージの定義については、以下の進捗報告セクションを参照してください。

重要：時間のかかるタスクでは background:true ではなく yieldMs を使用する

**30 秒以上かかるツールコマンドは、すべて yieldMs を指定して exec で実行し、進捗をユーザーにリアルタイムで報告してください。**これには、FLUX の一括生成、chain_video、SadTalker、音楽生成、複数シーンのパイプラインが含まれます。

exec command:"cd ~/.openclaw/workspace/claude-code-video-toolkit && uv run tools/chain_video.py --output-dir /path/ --progress json ..." yieldMs:10000

ポーリングの手順：

1. yieldMs:10000 を指定した exec でコマンドを開始し、10 秒ごとに制御を戻します
2. --progress json の出力を読み取り、"stage":"item"（シーン完了）または "stage":"complete"（すべて完了）を確認します
3. 進捗をユーザーに報告します（「Scene 05/30 complete, 17%」）
4. 再度ポーリングします：process action:poll sessionId:<id>
5. "stage":"complete" になるまで繰り返します

**理由：**応答を終えると、エージェントの実行は終了します。bash background:true を使用すると進捗を報告できなくなり、ユーザーが促すまで何も表示されません。yieldMs を使えば、処理を継続して確認できます。

次のようなことは絶対にしないでください：

• bash background:true command:"long running thing" を実行してから「監視する」と約束すること。実行が終了するため、監視できません
• 一括処理を個別のツール呼び出しに分けて、別々のメッセージで実行すること。各メッセージの間に実行が終了します
• 「自律的に処理を続ける」と約束すること。外部からのトリガーがなければ、実際には続行できません

セットアップ

Step 1: 現在の状態を確認する

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

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

Step 2: Python の依存関係をインストールする

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

注：uv sync はロックファイルから独自の .venv/ を作成するため、Debian/Ubuntu の管理対象 Python に関する制限（PEP 668）を回避でき、--break-system-packages は不要です。uv がインストールされていない場合は、先にインストールしてください：curl -LsSf https://astral.sh/uv/install.sh | sh。

Step 3: クラウド GPU エンドポイントを設定する

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

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

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

uv sync --extra modal
uv run modal setup   # Opens browser for authentication

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

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

uv run modal secret create huggingface-token HF_TOKEN=hf_your_read_access_token

各 URL を .env に追加してください。

ACEMUSIC_API_KEY=...                          # Free key from acemusic.ai/api-key (best music quality)
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

Step 4: 検証してクイックテストを実行する

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

すべてのツールに [x] が表示されるはずです。その後、クイックテストを実行して GPU パイプラインが動作することを確認してください。

cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run 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 が設定されていること
• uv run tools/verify_setup.py --json を実行し、modal_tools で不足しているエンドポイントを確認すること

**費用：**Modal には月あたり 30 ドル分の無料コンピューティングが含まれています。通常、60 秒の動画の費用は 1～3 ドルです。

---

動画の作成

Step 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

デフォルトのプロバイダーは acemusic（公式クラウド API、無料キー）です。GPU は不要です。セルフホスト用の Modal/RunPod にフォールバックします。

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

# Using acemusic cloud API (default — best quality, XL Turbo 4B model)
uv run tools/music_gen.py \
  --preset corporate-bg \
  --duration 90 \
  --output projects/PROJECT_NAME/public/audio/bg-music.mp3 \
  --progress json

# Or with custom prompt and thinking mode
uv run tools/music_gen.py \
  --prompt "Subtle ambient tech, soft synth pads" \
  --duration 90 \
  --output projects/PROJECT_NAME/public/audio/bg-music.mp3 \
  --progress json

# Fall back to self-hosted Modal if no acemusic key
uv run tools/music_gen.py \
  --preset corporate-bg \
  --duration 90 \
  --output projects/PROJECT_NAME/public/audio/bg-music.mp3 \
  --cloud modal --progress json

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

セットアップ：echo "ACEMUSIC_API_KEY=your_key" >> .env（無料キーは acemusic.ai/api-key で取得できます）。

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

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

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

# Scene 01
uv run 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 --progress json

# Scene 02
uv run 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 --progress json

# ... 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
uv run 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 --progress json

4c. シーン画像

cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run 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 --progress json

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

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

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

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

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

# B-roll clip from text
uv run 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 --progress json

# Animate a slide/screenshot (image-to-video)
uv run 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 --progress json

# Abstract intro/outro background
uv run 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 --progress json

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 を変更して再実行してください。

4d-chain. 連鎖動画シーケンス（視覚的な連続性）

前のシーンの最後のフレームから続く動画クリップのシーケンスを生成します。単一のコマンドで実行できます。シーン間で手動調整する必要はありません。

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

# Chain scenes 1-30 from a directory of FLUX images
uv run tools/chain_video.py \
  --scenes-dir projects/PROJECT_NAME/public/images/scenes/ \
  --output-dir projects/PROJECT_NAME/public/videos/chain/ \
  --prompt "Cinematic continuation, flowing transition" \
  --start 1 --end 30 \
  --progress json

# Resume from scene 10 (skips existing files automatically)
uv run tools/chain_video.py \
  --scenes-dir projects/PROJECT_NAME/public/images/scenes/ \
  --output-dir projects/PROJECT_NAME/public/videos/chain/ \
  --start 10 --end 30 \
  --progress json

# Per-scene prompts from JSON file
uv run tools/chain_video.py \
  --scenes-dir projects/PROJECT_NAME/public/images/scenes/ \
  --output-dir projects/PROJECT_NAME/public/videos/chain/ \
  --prompts-file projects/PROJECT_NAME/scenes.json \
  --progress json

# Chain from an existing clip (no scene images needed)
uv run tools/chain_video.py \
  --first-clip output/chain-04.mp4 \
  --output-dir output/ \
  --start 5 --end 30 \
  --prompt "Celtic mythology, flowing transition" \
  --progress json

プロンプトファイルの形式（scenes.json）：

{"1": "Ancient stone circle at dawn", "2": "Celtic spirals emerge from stone", "3": "Portal opens with golden light"}

連鎖のルール：

• シーン N の最後のフレームを抽出し、LTX-2 経由でシーン N+1 の --input として渡します
• ディスク上にすでに存在するシーンはスキップします（安全に再開できます）
• 連鎖に失敗した場合は、--scenes-dir のシーン画像にフォールバックします
• --prefix で出力ファイル名のプレフィックスを設定します（デフォルト：chain）
• シーンあたり約 2.5 分、クリップあたり約 $0.20-0.25 です
• 追加の引数（例：--negative-prompt、--seed）は ltx2.py に渡されます

重要：連鎖シーケンスにおけるスタイルの逸脱。 LTX-2 のトレーニングデータには約 30% の汚染（アニメ／アジア系コンテンツ）があります。「cinematic transition」のような汎用的なプロンプトでは、5～10 シーン連鎖した時点でアニメ風のスタイルに逸脱します。これを防ぐには、次の手順に従ってください。

1. 必ず --prompts-file を使い、シーンごとに具体的なプロンプトを指定してください。連鎖全体に単一の汎用プロンプトを使わないでください
2. 不要なスタイルを除外するため、必ず --negative-prompt を追加してください：

   --negative-prompt "anime, manga, asian, cartoon, illustration, watermark, text, logo"
   

3. シーンごとのプロンプトには、対象の説明だけでなく、強力なスタイルのアンカー（例：「アイルランドの風景、ケルトの組紐模様、油絵のスタイル」）を含めてください

重要：進行状況をリアルタイムで報告するには、yieldMs を指定して実行してください。 シーンごとにツール呼び出しを分けないでください。呼び出しの間に OpenClaw のエージェント実行が終了し、シーケンスが停止する原因になります。代わりに yieldMs を指定して exec を使い、処理を継続しながらユーザーに進行状況を伝えてください。

exec command:"cd ~/.openclaw/workspace/claude-code-video-toolkit && uv run tools/chain_video.py --scenes-dir /path/to/images/ --output-dir /path/to/output/ --prompts-file scenes.json --progress json" yieldMs:10000

仕組み：

• yieldMs:10000 を指定すると、10 秒ごとに制御が戻ります
• --progress json の出力（ステージ、パーセンテージ、メッセージを含む、stderr 上の JSON Lines）を読み取ります
• ユーザーに進行状況を報告します（「シーン 05/30 完了、17%」）
• その後、再度ポーリングします：process action:poll sessionId:<id>
• "stage":"complete" が表示されるまで繰り返します

これは、時間のかかるすべてのツールコマンド（chain_video、batch flux、batch sadtalker など）で使うべき正しいパターンです。 bash background:true を使って放置しないでください。exec + yieldMs + process poll のループを使い、進行状況をリアルタイムで報告してください。

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

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

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

# 1. Generate portrait
uv run 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 --progress json

# 2. Generate per-scene narrator clips (one per scene, NOT one long video)
uv run 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 --progress json

# 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
uv run 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 --progress json

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

cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run 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 --progress json

ステップ 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/ から直接インポートしてください。

---

進行状況の報告

すべてのクラウド GPU ツールは、自動監視のための構造化された進行状況出力に対応しています。

使い方

任意のツールコマンドに --progress json を追加すると、stderr に JSON Lines が出力されます。

cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run tools/music_gen.py \
  --preset corporate-bg --duration 60 \
  --output projects/PROJECT_NAME/public/audio/bg-music.mp3 \
  --progress json

出力形式

stderr の各行は JSON オブジェクトです。

{"ts":"14:23:15","stage":"submit","msg":"Sending to acemusic.ai (XL Turbo 4B, thinking: on)...","pct":null,"elapsed":0.0}
{"ts":"14:23:30","stage":"waiting","msg":"Waiting for acemusic.ai response... (15s)","pct":null,"elapsed":15.0}
{"ts":"14:23:45","stage":"waiting","msg":"Waiting for acemusic.ai response... (30s)","pct":null,"elapsed":30.0}
{"ts":"14:24:02","stage":"complete","msg":"Saved: bg-music.mp3 (245 KB, 60.1s)","pct":100,"elapsed":47.3}

ステージ

ステージ	意味
submit	ジョブをプロバイダーに送信しました
queue	RunPod：GPU の待機中
processing	RunPod：GPU で処理中
waiting	同期呼び出し中のハートビート（acemusic、Modal）
complete	ジョブが正常に完了しました
error	何らかのエラーが発生しました — 詳細は msg を確認してください
item	複数アイテムの進行状況（例：シーン 3/7） — pct に値が設定されます
cost	操作の推定コスト

プロバイダーごとの動作

• acemusic：submit → 定期的な waiting ハートビート（15 秒ごと）→ complete を出力します
• RunPod：submit → queue → processing → complete を出力します（ポーリングのたび）
• Modal：submit → 定期的な waiting ハートビート → complete を出力します

デフォルトモード（--progress human）では、同じイベントが色付きのターミナル出力で表示されます — 既存の動作に変更はありません。

---

エラーからの復旧

問題	解決策
ツールコマンドが「No module named...」で失敗する	toolkit のルートで uv sync を実行し、uv run 経由でツールを呼び出してください
「MODAL_*_ENDPOINT_URL not configured」	.env にエンドポイント URL が設定されていることを確認してください。uv run tools/verify_setup.py を実行してください
SadTalker の出力が正方形／クロップされる	--preprocess full を指定し忘れています。このフラグを指定して再実行してください
シーンに対して音声が短すぎる／長すぎる	ステップ 5（タイミングの同期）を再実行し、設定を更新してください
npm run render が失敗する	toolkit のルートではなく、プロジェクトディレクトリにいることを確認してください。先に npm install を実行してください
Remotion で「Cannot find module」と表示される	インポートパスを確認してください。カスタムコンポーネントでは ../../../lib/ の相対パスを使用します
Modal のコールドスタートがタイムアウトする	アイドル後の最初の呼び出しには 30～120 秒かかります。一度再試行してください — 2 回目の呼び出しではウォーム状態の GPU が使われます
SadTalker クライアントがタイムアウトする（音声が長い場合）	Modal の処理が完了する前に、クライアントの HTTP リクエストがタイムアウトすることがあります。Modal は引き続き結果を R2 にアップロードします。 出力を確認するには、video-toolkit R2 バケット内の sadtalker/results/ を確認してください。.env の R2 認証情報を使って uv run python -c "import boto3; ..." を実行すると、ファイルの一覧表示や署名付き URL の生成ができます

---

コストの目安（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 分の無料コンピューティング。アイドル状態になるとアプリはゼロまでスケールダウンします。