acestep-simplemv

MV レンダリング

音声と歌詞を入力して、波形ビジュアライゼーションと同期した歌詞付きのミュージックビデオをレンダリングします。

前提条件

• このスキル内の scripts/ ディレクトリにある Remotion プロジェクト
• Node.js と npm の依存関係がインストール済みであること
• ffprobe が利用可能であること（音声の長さの検出に使用）

初回セットアップ

初回使用の前に、依存関係を確認してインストールしてください。

# 1. Check Node.js
node --version

# 2. Install npm dependencies
cd {project_root}/{.claude or .codex}/skills/acestep-simplemv/scripts && npm install

# 3. Check ffprobe
ffprobe -version

ffprobe が利用できない場合は、ffprobe を含む ffmpeg をインストールしてください。

• Windows：choco install ffmpeg を実行するか、https://ffmpeg.org/download.html からダウンロードして PATH に追加します
• macOS：brew install ffmpeg を実行します
• Linux：sudo apt-get install ffmpeg（Debian/Ubuntu）または sudo dnf install ffmpeg（Fedora）を実行します

クイックスタート

cd {project_root}/{.claude or .codex}/skills/acestep-simplemv/
./scripts/render-mv.sh --audio /path/to/song.mp3 --lyrics /path/to/song.lrc --title "Song Title"

出力：out/<audio_basename>.mp4 の MP4 ファイル（またはカスタムの --output パス）。

スクリプトの使い方

./scripts/render-mv.sh --audio <file> --lyrics <lrc_file> --title "Title" [options]

Options:
  --audio        Audio file path (absolute paths supported)
  --lyrics       LRC format lyrics file (timestamped)
  --lyrics-json  JSON lyrics file [{start, end, text}] (alternative to --lyrics)
  --title        Video title (default: "Music Video")
  --subtitle     Subtitle text
  --credit       Bottom credit text
  --offset       Lyric timing offset in seconds (default: -0.5)
  --output       Output file path (default: out/<audio_basename>.mp4)
  --codec        h264|h265|vp8|vp9 (default: h264)
  --background   Background image file path (if omitted, uses animated gradient)
  --browser      Custom browser executable path (Chrome/Edge/Chromium)
  --max-size     Max output file size in MB (e.g. 24). Auto-compresses if exceeded.
                 Use for IM platforms (WhatsApp≤16MB, Discord≤25MB, Telegram≤50MB)

Environment variables:
  BROWSER_EXECUTABLE  Path to browser executable (overrides auto-detection)

ブラウザーの検出

Remotion でのレンダリングには、Chromium ベースのブラウザーが必要です。スクリプトは次の優先順位でブラウザーを自動検出します。

1. BROWSER_EXECUTABLE 環境変数
2. --browser CLI 引数
3. Remotion キャッシュ（Remotion がダウンロードする chrome-headless-shell）
4. システムの Chrome（--chrome-mode=chrome-for-testing を自動使用）
5. システムの Edge（Windows 10/11 にプリインストール済み。--chrome-mode=chrome-for-testing を自動使用）
6. システムの Chromium（--chrome-mode=chrome-for-testing を自動使用）

重要：新しいバージョンの Chrome/Edge では、従来のヘッドレスモードが削除されています。通常の Chrome/Edge/Chromium を使う場合、スクリプトは --chrome-mode=chrome-for-testing（--headless=new を使用）を自動的に設定します。chrome-headless-shell を使う場合は、デフォルトの headless-shell モード（--headless=old を使用）が使われます。これらの処理は透過的に行われます。

ブラウザーが見つからない場合、Remotion は Google のサーバーから chrome-headless-shell のダウンロードを試みます。ネットワークから Google のサーバーにアクセスできない場合、ダウンロードは失敗します。

制限されたネットワークでの回避策

Edge は Windows 10/11 にプリインストールされているため、手動で設定しなくても自動検出されるはずです。スクリプトは Chrome/Edge を自動検出し、適切なヘッドレスモードを使用します。自動検出に失敗する場合は、次を実行してください。

# Option 1: Set environment variable
export BROWSER_EXECUTABLE="/path/to/msedge.exe"

# Option 2: Pass as CLI argument
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --browser "/path/to/msedge.exe"

# Option 3: Enable proxy and let Remotion download chrome-headless-shell

使用例

# Basic render
./scripts/render-mv.sh --audio /tmp/abc123_1.mp3 --lyrics /tmp/abc123.lrc --title "夜桜"

# Custom output path
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "My Song" --output /tmp/my_mv.mp4

# With subtitle and credit
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --subtitle "Artist Name" --credit "Generated by ACE-Step"

# With background image
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --background /path/to/cover.jpg

# Compress for Discord upload (max 25MB)
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --max-size 24

# Compress for WhatsApp (max 16MB)
./scripts/render-mv.sh --audio song.mp3 --lyrics song.lrc --title "Song" --max-size 15

IM プラットフォームへのアップロード制限

チャットプラットフォームに MV を送信する場合は、--max-size を使って自動圧縮します。

プラットフォーム	制限	推奨 --max-size
WhatsApp	16MB	10
Discord（無料版）	25MB	10
QQ	10MB	10
Telegram	50MB	20
Slack（無料版）	1GB	-

圧縮には ffmpeg の 2 パスエンコードを使用し、サイズ制限内で最高の品質を実現します。

コンテナー／Docker のフォントサポート

コンテナー（例：OpenClaw）内で実行する場合、CJK フォントがインストールされていないことがあり、歌詞が □ のボックスとして表示される場合があります。スクリプトは次の処理を自動で行います。

1. CJK フォントが利用可能かどうかを検出します（fc-list を使用）
2. fonts-noto-cjk（Debian/Ubuntu）、font-noto-cjk（Alpine）、または google-noto-sans-cjk-fonts（Fedora/RHEL）のインストールを試みます
3. 自動インストールに失敗した場合、警告と手動インストールの手順を表示して続行します

自動インストールが機能しない場合は、レンダリングの前にフォントを手動でインストールしてください。

# Debian/Ubuntu
apt-get install -y fonts-noto-cjk

# Alpine
apk add font-noto-cjk

# Fedora/RHEL
dnf install -y google-noto-sans-cjk-fonts

ファイル名

重要：上書きを防ぐため、出力ファイル名には音声ファイルのジョブ ID を使用してください。--output my_song.mp4 のようなカスタム名は使用しないでください。デフォルトの命名（音声ファイル名から生成）を使用してください。

デフォルトの出力では、音声ファイル名がベース名として使用されます。

• 音声：acestep_output/{job_id}_1.mp3
• 歌詞：acestep_output/{job_id}_1.lrc
• 動画：--output acestep_output/{job_id}.mp4 を渡します（音声ファイルのジョブ ID を使用）

例：音声ファイルが chatcmpl-abc123_1.mp3 の場合、--output acestep_output/chatcmpl-abc123.mp4 を渡します。

タイトルのガイドライン

• --title は短く、1 行に収めてください（最大約 50 文字。超過分は自動的に切り詰められます）
• 追加情報には --subtitle を使用してください
• --title に改行を入れないでください

良い例：--title "Open Source" --subtitle "ACE-Step v1.5" 悪い例：--title "Open Source - ACE-Step v1.5\nCelebrating Music AI"

注意事項

• 絶対パスを指定したオーディオファイルは、render.mjs によって public/ に自動コピーされます
• 再生時間は ffprobe によって自動検出されます
• 一般的なレンダリング時間：90 秒の曲で約 1～2 分
• 出力解像度：1920x1080、30fps