# ACE-Step Gradio デモユーザーガイド

**Language / 语言 / 言語:** [English](../en/GRADIO_GUIDE.md) | [中文](../zh/GRADIO_GUIDE.md) | [日本語](GRADIO_GUIDE.md)

---

本ガイドはACE-Step Gradio Webインターフェースを使用した音楽生成の包括的なドキュメントを提供し、すべての機能と設定を含みます。

## 目次

- [はじめに](#はじめに)
- [サービス設定](#サービス設定)
- [生成モード](#生成モード)
- [タスクタイプ](#タスクタイプ)
- [入力パラメータ](#入力パラメータ)
- [高度な設定](#高度な設定)
- [結果セクション](#結果セクション)
- [LoRAトレーニング](#loraトレーニング)
- [ヒントとベストプラクティス](#ヒントとベストプラクティス)

---

## はじめに

### デモの起動

```bash
# 基本的な起動
python app.py

# 事前初期化付き
python app.py --config acestep-v15-turbo --init-llm

# 特定のポートで
python app.py --port 7860
```

### インターフェース概要

Gradioインターフェースは以下の主要セクションで構成されています：

1. **サービス設定** - モデルの読み込みと初期化
2. **必須入力** - タスクタイプ、オーディオアップロード、生成モード
3. **音楽キャプションと歌詞** - 生成用のテキスト入力
4. **オプションパラメータ** - BPM、キー、durationなどのメタデータ
5. **高度な設定** - 生成の細かい制御
6. **結果** - 生成されたオーディオの再生と管理

---

## サービス設定

### モデル選択

| 設定 | 説明 |
|---------|-------------|
| **チェックポイントファイル** | トレーニング済みモデルチェックポイントを選択（利用可能な場合）|
| **メインモデルパス** | DiTモデル設定を選択（例：`acestep-v15-turbo`、`acestep-v15-turbo-shift3`）|
| **デバイス** | 処理デバイス：`auto`（推奨）、`cuda`、または `cpu` |

### 5Hz LM設定

| 設定 | 説明 |
|---------|-------------|
| **5Hz LMモデルパス** | 言語モデルを選択（例：`acestep-5Hz-lm-0.6B`、`acestep-5Hz-lm-1.7B`）|
| **5Hz LMバックエンド** | `vllm`（より高速、推奨）または `pt`（PyTorch、互換性が高い）|
| **5Hz LMを初期化** | 初期化時にLMを読み込むためにチェック（thinkingモードに必要）|

### パフォーマンスオプション

| 設定 | 説明 |
|---------|-------------|
| **Flash Attentionを使用** | より高速な推論のために有効化（flash_attnパッケージが必要）|
| **CPUにオフロード** | アイドル時にモデルをCPUにオフロードしてGPUメモリを節約 |
| **DiTをCPUにオフロード** | DiTモデルを特にCPUにオフロード |

### LoRAアダプター

| 設定 | 説明 |
|---------|-------------|
| **LoRAパス** | トレーニング済みLoRAアダプターディレクトリへのパス |
| **LoRAを読み込み** | 指定されたLoRAアダプターを読み込み |
| **アンロード** | 現在読み込まれているLoRAを削除 |
| **LoRAを使用** | 推論用の読み込まれたLoRAを有効化/無効化 |

### 初期化

**サービスを初期化** をクリックしてモデルを読み込みます。ステータスボックスに進捗と確認が表示されます。

---

## 生成モード

### シンプルモード

シンプルモードは、迅速な自然言語ベースの音楽生成用に設計されています。

**使用方法：**
1. 生成モードラジオボタンで「シンプル」を選択
2. 「曲の説明」フィールドに自然言語の説明を入力
3. ボーカルが不要な場合は「インストゥルメンタル」をオプションでチェック
4. オプションで希望するボーカル言語を選択
5. **サンプルを作成** をクリックしてcaption、歌詞、メタデータを生成
6. 展開されたセクションで生成されたコンテンツを確認
7. **音楽を生成** をクリックしてオーディオを作成

**説明の例：**
- 「静かな夜のための柔らかいベンガルのラブソング」
- 「重いベースドロップのアップビートなエレクトロニックダンスミュージック」
- 「アコースティックギターのメランコリックなインディーフォーク」
- 「煙たいバーで演奏するジャズトリオ」

**ランダムサンプル：** 🎲 ボタンをクリックしてランダムな例の説明を読み込みます。

### カスタムモード

カスタムモードはすべての生成パラメータの完全な制御を提供します。

**使用方法：**
1. 生成モードラジオボタンで「カスタム」を選択
2. Captionと歌詞フィールドを手動で入力
3. オプションのメタデータを設定（BPM、キー、Durationなど）
4. オプションで **フォーマット** をクリックしてLMを使用して入力を強化
5. 必要に応じて高度な設定を構成
6. **音楽を生成** をクリックしてオーディオを作成

---

## タスクタイプ

### text2music（デフォルト）

テキスト説明および/または歌詞から音楽を生成。

**ユースケース：** プロンプトに基づいて新しい音楽をゼロから作成。

**必須入力：** Captionまたは歌詞（少なくとも1つ）

### cover

既存のオーディオを構造を維持しながらスタイルを変更して変換。

**ユースケース：** 異なるスタイルのカバーバージョンを作成。

**必須入力：**
- ソースオーディオ（オーディオアップロードセクションでアップロード）
- ターゲットスタイルを説明するCaption

**重要なパラメータ：** `オーディオカバー強度`（0.0-1.0）
- 高い値は元の構造をより多く維持
- 低い値はより創造的な自由を許可

### repaint

オーディオの特定の時間セグメントを再生成。

**ユースケース：** 生成された音楽の特定のセクションを修正または変更。

**必須入力：**
- ソースオーディオ
- リペイント開始（秒）
- リペイント終了（秒、ファイル終端には-1）
- 希望するコンテンツを説明するCaption

### lego（Baseモデルのみ）

既存のオーディオのコンテキストで特定の楽器トラックを生成。

**ユースケース：** バッキングトラックに楽器レイヤーを追加。

**必須入力：**
- ソースオーディオ
- トラック名（ドロップダウンから選択）
- トラック特性を説明するCaption

**利用可能なトラック：** vocals、backing_vocals、drums、bass、guitar、keyboard、percussion、strings、synth、fx、brass、woodwinds

### extract（Baseモデルのみ）

ミックスオーディオから特定の楽器トラックを抽出/分離。

**ユースケース：** ステム分離、楽器の分離。

**必須入力：**
- ソースオーディオ
- 抽出するトラック名

### complete（Baseモデルのみ）

指定された楽器で部分的なトラックを完成。

**ユースケース：** 不完全な作品の自動アレンジ。

**必須入力：**
- ソースオーディオ
- トラック名（複数選択）
- 希望するスタイルを説明するCaption

---

## 入力パラメータ

### 必須入力

#### タスクタイプ
ドロップダウンから生成タスクを選択。選択されたタスクに基づいて指示フィールドが自動的に更新されます。

#### オーディオアップロード

| フィールド | 説明 |
|-------|-------------|
| **参照オーディオ** | スタイル参照用のオプションオーディオ |
| **ソースオーディオ** | cover、repaint、lego、extract、completeタスクに必須 |
| **コードに変換** | ソースオーディオから5Hzセマンティックコードを抽出 |

#### LMコードヒント

事前計算されたオーディオセマンティックコードをここに貼り付けて生成をガイドできます。**トランスクライブ** ボタンを使用してコードを分析しメタデータを抽出します。

### 音楽キャプション

希望する音楽のテキスト説明。以下について具体的に：
- ジャンルとスタイル
- 楽器
- ムードと雰囲気
- テンポ感（BPMを指定しない場合）

**例：** 「エレキギター、力強いドラム、キャッチーなシンセフックのアップビートなポップロック」

🎲 をクリックしてランダムな例のcaptionを読み込みます。

### 歌詞

構造タグ付きの歌詞を入力：

```
[Verse 1]
今日街を歩いていて
君が言っていた言葉を思い出していた

[Chorus]
前に進んでいく、強くいる
ここが僕の居場所

[Verse 2]
...
```

**インストゥルメンタルチェックボックス：** これをチェックすると、歌詞の内容に関係なくインストゥルメンタル音楽を生成します。

**ボーカル言語：** ボーカルの言語を選択。自動検出またはインストゥルメンタルトラックには「unknown」を使用。

**フォーマットボタン：** クリックして5Hz LMを使用してcaptionと歌詞を強化。

### オプションパラメータ

| パラメータ | デフォルト | 説明 |
|-----------|---------|-------------|
| **BPM** | 自動 | 1分あたりのビート数（30-300）|
| **キースケール** | 自動 | 音楽キー（例：「C Major」、「Am」、「F# minor」）|
| **拍子記号** | 自動 | 拍子記号：2（2/4）、3（3/4）、4（4/4）、6（6/8）|
| **オーディオ長** | 自動/-1 | 目標長（秒）（10-600）。-1で自動 |
| **バッチサイズ** | 2 | 生成するオーディオバリエーションの数（1-8）|

---

## 高度な設定

### DiTパラメータ

| パラメータ | デフォルト | 説明 |
|-----------|---------|-------------|
| **推論ステップ** | 8 | デノイズステップ。Turbo：1-20、Base：1-200 |
| **ガイダンススケール** | 7.0 | CFG強度（baseモデルのみ）。高い = プロンプトにより従う |
| **シード** | -1 | ランダムシード。バッチにはカンマ区切りの値を使用 |
| **ランダムシード** | ✓ | チェック時にランダムシードを生成 |
| **オーディオ形式** | mp3 | 出力形式：mp3、flac |
| **シフト** | 3.0 | タイムステップシフト係数（1.0-5.0）。turboには3.0推奨 |
| **推論方法** | ode | ode（Euler、より高速）またはsde（確率的）|
| **カスタムタイムステップ** | - | タイムステップをオーバーライド（例：「0.97,0.76,0.615,0.5,0.395,0.28,0.18,0.085,0」）|

### Baseモデルのみのパラメータ

| パラメータ | デフォルト | 説明 |
|-----------|---------|-------------|
| **ADGを使用** | ✗ | より良い品質のために適応デュアルガイダンスを有効化 |
| **CFG区間開始** | 0.0 | CFGを適用し始めるタイミング（0.0-1.0）|
| **CFG区間終了** | 1.0 | CFGの適用を停止するタイミング（0.0-1.0）|

### LMパラメータ

| パラメータ | デフォルト | 説明 |
|-----------|---------|-------------|
| **LM温度** | 0.85 | サンプリング温度（0.0-2.0）。高い = より創造的 |
| **LM CFGスケール** | 2.0 | LMガイダンス強度（1.0-3.0）|
| **LM Top-K** | 0 | Top-Kサンプリング。0で無効 |
| **LM Top-P** | 0.9 | 核サンプリング（0.0-1.0）|
| **LMネガティブプロンプト** | "NO USER INPUT" | CFG用のネガティブプロンプト |

### CoT（思考の連鎖）オプション

| オプション | デフォルト | 説明 |
|--------|---------|-------------|
| **CoT Metas** | ✓ | LM推論でメタデータを生成 |
| **CoT Language** | ✓ | LMでボーカル言語を検出 |
| **制約付きデコーディングデバッグ** | ✗ | デバッグログを有効化 |

### 生成オプション

| オプション | デフォルト | 説明 |
|--------|---------|-------------|
| **LMコード強度** | 1.0 | LMコードが生成に与える影響の強さ（0.0-1.0）|
| **自動スコア** | ✗ | 品質スコアを自動計算 |
| **自動LRC** | ✗ | 歌詞タイムスタンプを自動生成 |
| **LMバッチチャンクサイズ** | 8 | LMバッチあたりの最大アイテム数（GPUメモリ）|

### メイン生成コントロール

| コントロール | 説明 |
|---------|-------------|
| **Think** | コード生成とメタデータ用の5Hz LMを有効化 |
| **ParallelThinking** | 並列LMバッチ処理を有効化 |
| **CaptionRewrite** | LMに入力captionを強化させる |
| **AutoGen** | 完了後に次のバッチを自動開始 |

---

## 結果セクション

### 生成されたオーディオ

バッチサイズに基づいて最大8つのオーディオサンプルが表示されます。各サンプルには以下が含まれます：

- **オーディオプレーヤー** - 生成されたオーディオの再生、一時停止、ダウンロード
- **ソースに送信** - このオーディオをソースオーディオ入力に送信してさらに処理
- **保存** - オーディオとメタデータをJSONファイルに保存
- **スコア** - パープレキシティベースの品質スコアを計算
- **LRC** - 歌詞タイムスタンプを生成（LRC形式）

### 詳細アコーディオン

「スコア & LRC & LMコード」をクリックして展開し、以下を表示：
- **LMコード** - このサンプルの5Hzセマンティックコード
- **品質スコア** - パープレキシティベースの品質メトリック
- **歌詞タイムスタンプ** - LRC形式のタイミングデータ

### バッチナビゲーション

| コントロール | 説明 |
|---------|-------------|
| **◀ 前へ** | 前のバッチを表示 |
| **バッチインジケーター** | 現在のバッチ位置を表示（例：「バッチ 1 / 3」）|
| **次バッチステータス** | バックグラウンド生成の進捗を表示 |
| **次へ ▶** | 次のバッチを表示（AutoGenがオンの場合は生成をトリガー）|

### パラメータの復元

**これらの設定をUIに適用** をクリックして、現在のバッチからすべての生成パラメータを入力フィールドに復元。良い結果を反復するのに便利。

### バッチ結果

「バッチ結果と生成詳細」アコーディオンには以下が含まれます：
- **すべての生成ファイル** - すべてのバッチからすべてのファイルをダウンロード
- **生成詳細** - 生成プロセスに関する詳細情報

---

## LoRAトレーニング

LoRAトレーニングタブはカスタムLoRAアダプターを作成するためのツールを提供します。

### データセットビルダータブ

#### ステップ1：読み込みまたはスキャン

**オプションA：既存のデータセットを読み込み**
1. 以前保存したデータセットJSONへのパスを入力
2. **読み込み** をクリック

**オプションB：新しいディレクトリをスキャン**
1. オーディオフォルダへのパスを入力
2. **スキャン** をクリックしてオーディオファイルを検索（wav、mp3、flac、ogg、opus）

#### ステップ2：データセットの設定

| 設定 | 説明 |
|---------|-------------|
| **データセット名** | データセットの名前 |
| **すべてインストゥルメンタル** | すべてのトラックにボーカルがない場合にチェック |
| **カスタムアクティベーションタグ** | このLoRAのスタイルをアクティブにするユニークなタグ |
| **タグ位置** | タグを配置する場所：前に追加、後に追加、またはcaptionを置換 |

#### ステップ3：自動ラベル

**すべて自動ラベル** をクリックしてすべてのオーディオファイルのメタデータを生成：
- Caption（音楽の説明）
- BPM
- キー
- 拍子記号

**Metasをスキップ** オプションはLLMラベリングをスキップしてN/A値を使用します。

#### ステップ4：プレビューと編集

スライダーを使用してサンプルを選択し、手動で編集：
- Caption
- 歌詞
- BPM、キー、拍子記号
- 言語
- インストゥルメンタルフラグ

**変更を保存** をクリックしてサンプルを更新。

#### ステップ5：データセットを保存

保存パスを入力し、**データセットを保存** をクリックしてJSONとしてエクスポート。

#### ステップ6：前処理

高速トレーニングのためにデータセットを事前計算テンソルに変換：
1. オプションで既存のデータセットJSONを読み込み
2. テンソル出力ディレクトリを設定
3. **前処理** をクリック

これによりオーディオがVAE潜在変数にエンコードされ、テキストが埋め込みにエンコードされ、条件エンコーダーが実行されます。

### LoRAトレーニングタブ

#### データセット選択

前処理されたテンソルディレクトリへのパスを入力し、**データセットを読み込み** をクリック。

#### LoRA設定

| 設定 | デフォルト | 説明 |
|---------|---------|-------------|
| **LoRAランク (r)** | 64 | LoRAの容量。高い = より多くの容量、より多くのメモリ |
| **LoRA Alpha** | 128 | スケーリング係数（通常はランクの2倍）|
| **LoRA Dropout** | 0.1 | 正則化のためのドロップアウト率 |

#### トレーニングパラメータ

| 設定 | デフォルト | 説明 |
|---------|---------|-------------|
| **学習率** | 1e-4 | 最適化学習率 |
| **最大エポック** | 500 | 最大トレーニングエポック |
| **バッチサイズ** | 1 | トレーニングバッチサイズ |
| **勾配累積** | 1 | 有効バッチ = batch_size × accumulation |
| **Nエポックごとに保存** | 200 | チェックポイント保存頻度 |
| **シフト** | 3.0 | turboモデルのタイムステップシフト |
| **シード** | 42 | 再現性のためのランダムシード |

#### トレーニングコントロール

- **トレーニング開始** - トレーニングプロセスを開始
- **トレーニング停止** - トレーニングを中断
- **トレーニング進捗** - 現在のエポックとロスを表示
- **トレーニングログ** - 詳細なトレーニング出力
- **トレーニングロスプロット** - 視覚的なロス曲線

#### LoRAのエクスポート

トレーニング後、最終アダプターをエクスポート：
1. エクスポートパスを入力
2. **LoRAをエクスポート** をクリック

---

## ヒントとベストプラクティス

### 最高品質のために

1. **thinkingモードを使用** - LM強化生成のために「Think」チェックボックスを有効に保つ
2. **captionを具体的に** - ジャンル、楽器、ムード、スタイルの詳細を含める
3. **LMにメタデータを検出させる** - 自動検出のためにBPM/キー/Durationを空のままにする
4. **バッチ生成を使用** - 2-4のバリエーションを生成し、最良のものを選ぶ

### より高速な生成のために

1. **turboモデルを使用** - `acestep-v15-turbo` または `acestep-v15-turbo-shift3` を選択
2. **推論ステップを8に保つ** - turboに最適なデフォルト
3. **バッチサイズを減らす** - 迅速な結果が必要な場合はバッチサイズを下げる
4. **AutoGenを無効化** - バッチ生成の手動制御

### 一貫した結果のために

1. **特定のシードを設定** - 「ランダムシード」のチェックを外してシード値を入力
2. **良い結果を保存** - 再現のためにパラメータをエクスポートするために「保存」を使用
3. **「これらの設定を適用」を使用** - 良いバッチからパラメータを復元

### 長尺音楽のために

1. **明示的なdurationを設定** - 秒単位でdurationを指定
2. **repaintタスクを使用** - 初期生成後に問題のあるセクションを修正
3. **生成をチェーン** - 以前の結果の上に構築するために「ソースに送信」を使用

### スタイルの一貫性のために

1. **LoRAをトレーニング** - あなたのスタイル用のカスタムアダプターを作成
2. **参照オーディオを使用** - オーディオアップロードでスタイル参照をアップロード
3. **一貫したcaptionを使用** - 類似の説明的な言語を維持

### トラブルシューティング

**オーディオが生成されない：**
- モデルが初期化されていることを確認（緑のステータスメッセージ）
- thinkingモードを使用している場合は5Hz LMが初期化されていることを確認
- エラーメッセージのステータス出力を確認

**結果の品質が悪い：**
- 推論ステップを増やす（baseモデルの場合）
- ガイダンススケールを調整
- 異なるシードを試す
- captionをより具体的にする

**メモリ不足：**
- バッチサイズを減らす
- CPUオフロードを有効化
- LMバッチチャンクサイズを減らす

**LMが機能しない：**
- 初期化時に「5Hz LMを初期化」がチェックされていたことを確認
- 有効なLMモデルパスが選択されていることを確認
- vllmまたはPyTorchバックエンドが利用可能であることを確認

---

## キーボードショートカット

Gradioインターフェースは標準的なWebショートカットをサポート：
- **Tab** - 入力フィールド間を移動
- **Enter** - テキスト入力を送信
- **Space** - チェックボックスを切り替え

---

## 言語サポート

インターフェースは複数のUI言語をサポート：
- **英語** (en)
- **中国語** (zh)
- **日本語** (ja)

サービス設定セクションで好みの言語を選択してください。

---

詳細については以下を参照：
- メインREADME：[`../../README.md`](../../README.md)
- REST APIドキュメント：[`API.md`](API.md)
- Python推論API：[`INFERENCE.md`](INFERENCE.md)