acestep

ACE-Step 1.5 音楽生成

tools/music_gen.py を使ったオープンソースの音楽生成です。

クラウドプロバイダー：

• acemusic（デフォルト）— XL Turbo（4B）モデルと5Hz LM思考モードを備えた、ACE-Step公式クラウドAPIです。acemusic.ai/api-key から無料のAPIキーを取得できます。GPUは不要です。
• modal — Modal A10G上でACE-Step 1.5 XL Turbo（4B DiT、LMなし）をセルフホストします。MODAL_MUSIC_GEN_ENDPOINT_URL が必要です。
• runpod — RunPod上でACE-Step 2B Turboをセルフホストします。RUNPOD_ACESTEP_ENDPOINT_ID が必要です。

セットアップ

# acemusic (recommended — free, best quality, no GPU)
echo "ACEMUSIC_API_KEY=your_key" >> .env
# Get key at https://acemusic.ai/api-key

# Self-hosted (optional fallback)
uv run tools/music_gen.py --setup             # RunPod
uv run modal deploy docker/modal-music-gen/app.py    # Modal

クイックリファレンス

# Basic generation (uses acemusic XL Turbo by default)
uv run tools/music_gen.py --prompt "Upbeat tech corporate" --duration 60 --output bg.mp3

# Generate 4 variations, pick the best
uv run tools/music_gen.py --prompt "Calm ambient piano" --duration 30 --variations 4 --output ambient.mp3

# Fast mode (disable thinking)
uv run tools/music_gen.py --no-thinking --prompt "Quick draft" --duration 30 --output draft.mp3

# With musical control
uv run tools/music_gen.py --prompt "Calm ambient piano" --duration 30 --bpm 72 --key "D Major" --output ambient.mp3

# Scene presets (video production)
uv run tools/music_gen.py --preset corporate-bg --duration 60 --output bg.mp3
uv run tools/music_gen.py --preset tension --duration 20 --output problem.mp3
uv run tools/music_gen.py --preset cta --brand digital-samba --duration 15 --output cta.mp3

# Vocals with lyrics
uv run tools/music_gen.py --prompt "Indie pop jingle" --lyrics "[verse]\nBuild it better\nShip it faster" --duration 30 --output jingle.mp3

# Cover / style transfer
uv run tools/music_gen.py --cover --reference theme.mp3 --prompt "Jazz piano version" --duration 60 --output jazz_cover.mp3

# Repaint a weak section
uv run tools/music_gen.py --repaint --input track.mp3 --repaint-start 15 --repaint-end 25 --prompt "Guitar solo" --output fixed.mp3

# Continue from existing audio
uv run tools/music_gen.py --continuation --input track.mp3 --prompt "Continue with jazz piano" --output extended.mp3

# Stem extraction
uv run tools/music_gen.py --extract vocals --input mixed.mp3 --output vocals.mp3

# Fall back to self-hosted
uv run tools/music_gen.py --cloud modal --prompt "Background music" --duration 60 --output bg.mp3

「似通った」出力の改善

生成された音楽が単調に感じられたり、バリエーションに乏しかったりする場合は、次の方法を順番に試してください。

1. acemusic クラウドを使う（デフォルト）— XL Turbo 4B に加えて 5Hz LMを使用します。Modalは同じXL Turbo DiTを実行しますが、LMはありません。RunPodは引き続き2Bです
2. 思考モードをオンにする（acemusicではデフォルト）— 5Hz LMが簡潔なプロンプトを詳細な音楽の説明に膨らませます
3. バリエーションを生成する — --variations 4 で4パターンを生成し、最良のものを選びます
4. 確率的推論を使う — --infer-method sde でランダム性を加えます（同じシードでも異なる結果になります）
5. シーンごとにBPMとキーを変える — すべてのシーンで同じプリセットを使わないでください
6. 簡潔なプロンプトを書く — 「明るいインディーロック」のほうが、細部まで記述した説明よりもモデルに創造の余地を与えます
7. シードを変える — --seed を省略すると、生成ごとに異なる結果になります

曲の作成（ステップごと）

1. インストゥルメンタルのBGM（最も簡単）

uv run tools/music_gen.py --prompt "Upbeat indie rock, driving drums, jangly guitar" --duration 60 --bpm 120 --key "G Major" --output track.mp3

2. ボーカルと歌詞のある曲

歌詞は一時ファイルに書くか、インラインで渡します。構成タグを使って曲の各セクションを制御します。

# Write lyrics to a file first (recommended for longer songs)
cat > /tmp/lyrics.txt << 'LYRICS'
[Verse 1]
Walking through the morning light
Coffee in my hand feels right
Another day to build and dream
Nothing's ever what it seems

[Chorus - anthemic]
WE KEEP MOVING FORWARD
Through the noise and doubt
We keep moving forward
That's what it's about

[Verse 2]
Screens are glowing late at night
Shipping code until it's right
The deadline's close but so are we
Almost there, just wait and see

[Chorus - bigger]
WE KEEP MOVING FORWARD
Through the noise and doubt
We keep moving forward
That's what it's about

[Outro - fade]
(Moving forward...)
LYRICS

# Generate the song
uv run tools/music_gen.py \
  --prompt "Upbeat indie rock anthem, male vocal, driving drums, electric guitar, studio polish" \
  --lyrics "$(cat /tmp/lyrics.txt)" \
  --duration 60 \
  --bpm 128 \
  --key "G Major" \
  --output my_song.mp3

3. 出来のよくないセクションを再生成する

サビの出来がよくない場合は、そのセクションだけを再生成します。

uv run tools/music_gen.py --repaint --input my_song.mp3 --repaint-start 20 --repaint-end 35 --prompt "Powerful anthemic chorus, big drums" --output fixed.mp3

4. トラックを続ける／延長する

uv run tools/music_gen.py --continuation --input my_song.mp3 --prompt "Continue with gentle acoustic outro" --output extended.mp3

良い結果を得るためのポイント

• キャプション＝全体的なスタイル（ジャンル、楽器、雰囲気、音質）
• 歌詞＝時間的な構成（Aメロ／サビの流れ、ボーカルの歌い方）
• 歌詞を大文字にする＝ボーカルの強度を高めます
• 括弧＝バックボーカルを表します：「We rise (together)」
• 自然なリズムにするため、1行あたりの音節数を6～10にします
• キャプションでメロディーを説明しないでください — 音や雰囲気を説明します
• プロンプトや歌詞を調整するときは、--seed を使ってランダム性を固定します

ボーカルの性別を指定する

モデルは「女性ボーカル」や「男性ボーカル」の指示だけでは、安定して従いません。次の2つを両方使ってください。

1. プロンプト内：明確に指定します — 「ソロの女性歌手、アルトボイス」や「女性ボーカルのみ、息遣いのある親密な声」などです。アーティストを参考として加えるのも効果的です（例：「Brandi Carlile風」）。
2. 歌詞内：各セクションの前に [female vocal] タグを追加します。

[female vocal]
[Verse 1]
Walking through the morning light...

[female vocal]
[Chorus - anthemic]
WE KEEP MOVING FORWARD...

プロンプトに「女性ボーカル」と書くだけでは、無視されることがよくあります。プロンプトと歌詞タグの組み合わせが効果的です。

デュエットとボーカルの掛け合い

男女のボーカルが各節を交互に歌うデュエットでは、プロンプトとセクションごとの歌詞タグの両方を使います。

• プロンプト：「デュエット、男女のボーカルが各節を交互に歌う、サビでは温かみのあるハーモニー」
• 歌詞：各セクションに歌う人のタグを付けます。

[Verse 1 - male vocal, storytelling]
First verse lyrics here...

[Chorus - male and female duet, harmonies]
Chorus lyrics here...

[Verse 2 - female vocal, wry]
Second verse lyrics here...

[Bridge - male vocal, spoken]
Spoken bridge...

[Bridge - female vocal, sung]
Sung response...

この方法を使うと、セクションごとのボーカルの掛け合いと、複数人で歌うパートのハーモニーを安定して生成できます。

シーンプリセット

プリセット	BPM	キー	用途
corporate-bg	110	C Major	プロ向けのBGM、プレゼンテーション
upbeat-tech	128	G Major	製品発表、テックデモ
ambient	72	D Major	概要スライド、内省的なコンテンツ
dramatic	90	D Minor	発表、告知
tension	85	A Minor	問題提起、課題
hopeful	120	C Major	解決策の提示、問題の解決
cta	135	E Major	行動喚起、締めくくりの盛り上がり
lofi	85	F Major	画面録画、コーディングデモ

タスクタイプ

text2music（デフォルト）

テキストプロンプトと、任意の歌詞から音楽を生成します。

cover

参照音声からのスタイル転送です。--cover-strength（0.0-1.0）でブレンドを調整します：

• 0.2 — 大まかなスタイルのインスピレーション（より自由な創作）
• 0.5 — バランスの取れたスタイル転送
• 0.7 — 元の構成に近い（デフォルト）
• 1.0 — ソースへの忠実度を最大化

extract

ステム分離 — ミックス音声から個別のトラックを分離します。 トラック：vocals、drums、bass、guitar、piano、keyboard、strings、brass、woodwinds、other

上流では、extract は base-model タスク（acestep-v15-base / -xl-base）として記載されています。セルフホスト型エンドポイントが提供する turbo DiT（Modal の XL Turbo、RunPod の 2B Turbo）はこれをサポートしていないため、そこでのステム分離の品質は低いと予想されます。

repainting (acemusic only)

既存の音声の特定の時間区間を再生成し、それ以外の部分は保持します。

uv run tools/music_gen.py --repaint --input track.mp3 --repaint-start 15 --repaint-end 25 --prompt "Guitar solo" --output fixed.mp3

continuation (acemusic only)

既存の音声の末尾から続けて再生し、音声を延長します。

uv run tools/music_gen.py --continuation --input track.mp3 --prompt "Continue with jazz piano" --output extended.mp3

プロンプトエンジニアリング

キャプションの作成 — 要素の重ね合わせ

単語だけの説明ではなく、複数の描写要素を重ね合わせてキャプションを作成します。

含める要素：

• ジャンル／スタイル：ポップ、ロック、ジャズ、エレクトロニック、ローファイ、シンセウェイヴ、オーケストラ
• 感情／ムード：メランコリック、高揚感のある、夢のような、ノスタルジック、親密な、緊張感のある
• 楽器：アコースティックギター、シンセパッド、808 ドラム、ストリングス、ブラス、ピアノ
• 音色：温かみのある、クリアな、エアリーな、力強い、豊かな、磨き上げられた、生々しい
• 時代：「80年代のシンセポップ」、「現代のインディー」、「古典派ロマン主義」
• プロダクション：ローファイ、スタジオ品質、ライブ録音、シネマティック
• ボーカル：息混じりの、力強い、ファルセット、しゃがれた、スポークンワード（または「インストゥルメンタル」）

良い例：「親密な女性ボーカルと温かみのあるストリングスが力強いサビに向けて盛り上がる、スタジオ品質のプロダクションによる、ゆったりとしたメランコリックなピアノバラード」 悪い例：「悲しい曲」

主な原則

1. 曖昧さより具体性を重視する — 楽器、ムード、プロダクションスタイルを説明します
2. 矛盾を避ける — 「クラシックなストリングス」と「ハードコアメタル」を同時に指定しないでください
3. 繰り返すことで優先度を強調する — 重要な要素を繰り返して強調します
4. 簡潔なキャプションほど創作の自由度が高まる — 詳細なキャプションはモデルを制約します
5. BPM／キーにはメタデータパラメーターを使う — キャプションに「120 BPM」と書かず、--bpm 120 を使います

歌詞のフォーマット

構成タグ（キャプションではなく歌詞に使用）：

[Intro]
[Verse]
[Chorus]
[Bridge]
[Outro]
[Instrumental]
[Guitar Solo]
[Build]
[Drop]
[Breakdown]

ボーカルの制御（行またはセクションの先頭に付ける）：

[raspy vocal]
[whispered]
[falsetto]
[powerful belting]
[harmonies]
[ad-lib]

エネルギーの指標：

• 大文字 = 強い強度（「WE RISE ABOVE」）
• 括弧 = バックグラウンドボーカル（「We rise (together)」）
• 自然なリズムにするため、セクション内の各行は 6～10 音節にします

動画制作との連携

シーンの種類に応じた音楽

シーン	プリセット	長さ	メモ
タイトル	dramatic または ambient	3-5s	短く、ムードを作る
問題	tension	10-15s	暗く、不穏
解決策	hopeful	10-15s	安堵、楽観
デモ	lofi または corporate-bg	30-120s	邪魔にならず、デモの長さに合わせる
統計	upbeat-tech	8-12s	信頼感を高める
CTA	cta	5-10s	最大限のエネルギー、力強い
クレジット	ambient	5-10s	穏やかにフェードアウト

タイミングのワークフロー

1. まずシーンの長さを計画します（ナレーション台本をもとにします）
2. 長さを合わせて音楽を生成します：--duration <scene_seconds>
3. 音楽の長さは正確です（指定した長さとの差は 0.1 秒以内です）
4. 複数のシーンにまたがるBGMには、長いトラックを1つ生成します

ナレーションとの組み合わせ

Remotion では、BGM を 10～20% の音量でミックスします：

<Audio src={staticFile('voiceover.mp3')} volume={1} />
<Audio src={staticFile('bg-music.mp3')} volume={0.15} />

ナレーション中に流す音楽には、インストゥルメンタルのプリセット（corporate-bg、ambient、lofi）を使います。 音楽を前面に出すシーン（タイトル、CTA）では、音量を上げるか、ボーカルトラックを使用できます。

ブランドの一貫性

--brand <name> を使うと、brands/<name>/brand.json からヒントを読み込みます。 --cover --reference brand_theme.mp3 を使うと、ブランドの音のアイデンティティをもとにバリエーションを作成できます。 プロジェクト全体でサウンドに一貫性を持たせるには、シード（--seed 42）を固定し、長さ／プロンプトだけを変えます。

高度なパラメーター

フラグ	デフォルト	説明
--thinking	on (acemusic)	5Hz の LM がプロンプトを拡充し、オーディオコードを生成します
--no-thinking	-	生成を高速化し、LM の推論を省略します
--variations N	1	N 個のバリエーションを生成します（1～8、acemusic のみ）
--guidance-scale	7.0	プロンプトへの準拠度（1.0～15.0）
--infer-method	ode	ode（決定論的）または sde（確率論的で、より多様な結果）
--seed	random	再現性を確保するため、乱数を固定します

技術的な詳細

• acemusic cloud：XL Turbo 4B DiT + 4B LM、最高品質、生成あたり約5～15秒
• Modal：XL Turbo 4B DiT（ACE-Step-1.5 v0.1.8）、LM なし、shift 3.0 で8ステップ（upstream の turbo 推奨値。リクエストの shift で上書きできます）、DCW サンプラー有効。10秒の音声を約4秒（ウォーム時）、約50秒（コールド時）で生成
• RunPod：標準の Turbo 2B DiT、LM なし、生成あたり約2～3秒
• 出力：48kHz の MP3/WAV/FLAC
• 再生時間の範囲：10～600秒
• BPM の範囲：30～300

ACE-Step を使用しない方がよい場合

• 音声のクローン作成 — 代わりに Qwen3-TTS または ElevenLabs を使用してください
• 効果音 — ElevenLabs SFX（tools/sfx.py）を使用してください
• 音声・ナレーション — 音楽生成ツールではなく、ボイスオーバーツールを使用してください
• 動画からのステム抽出 — まず FFmpeg で音声を抽出し、その後 --extract を使用してください