diffusers/main/ja/api/pipelines/ace_step.md

ACE-Step 1.5

ACE-Step 1.5 は、ACE-Step チーム（ACE Studio と StepFun）による ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation で紹介されました。これは、テキストプロンプトから歌詞付きの商用レベルのステレオ音楽を生成するオープンソースの音楽基盤モデルです。

ACE-Step 1.5 は、テキストプロンプトと任意の歌詞から、48 kHz の可変長ステレオオーディオ（10 秒から 10 分）を生成します。完全なシステムは、Language Model によるプランナーと Diffusion Transformer (DiT) によるシンセサイザーを組み合わせる構成です。このパイプラインは、そのスタックの DiT 部分をラップしており、3 つのコンポーネントで構成されています。波形を 25 Hz のステレオ潜在変数に圧縮する AutoencoderOobleck VAE、プロンプトと歌詞の条件付けを行う Qwen3 ベースのテキストエンコーダー、そしてフローマッチングを用いて VAE の潜在空間で動作する AceStepTransformer1DModel DiT です。

このモデルは、英語、中国語、日本語、韓国語、フランス語、ドイツ語、スペイン語、イタリア語、ポルトガル語、ロシア語を含む50以上の言語の歌詞に対応しており、オフロード時にVRAM 4 GB未満で動作するため、コンシューマー向けGPUでも実行できます。

このパイプラインはACE-Step Teamによって提供されました。元のコードベースはace-step/ACE-Step-1.5で確認できます。

バリアント

ACE-Step 1.5には、同じtransformerアーキテクチャを共有しながらもguidanceの挙動が異なる3つのDiTチェックポイントが含まれています。パイプラインは、読み込まれたtransformerの設定からturboチェックポイントを自動検出し、guidance蒸留済みの重みに対してはCFG guidanceを無視します。

バリアント	CFG	デフォルトのステップ	デフォルトのguidance_scale	デフォルトのshift	HF リポジトリ
turbo（guidance-distilled）	off	8	無視	3.0	ACE-Step/acestep-v15-xl-turbo-diffusers
base	オン	8	7.0	3.0	ACE-Step/acestep-v15-base
sft	オン	8	7.0	3.0	ACE-Step/acestep-v15-sft

Base と SFT は、classifier-free guidance（APG、vanilla CFG ではありません）のために学習された null_condition_emb を使用します。ユーザーは、より高い品質を得るために、base/sft で num_inference_steps を 30〜60 に上書きすることが一般的です。

ヒント

プロンプトを構築する際は、以下の点に注意してください。

• 説明的なプロンプト入力が最も効果的です。音楽のスタイル、楽器、ムード、テンポを形容詞で記述してください。
• プロンプトには、音楽全体の特性（例:「エレキギターとドラムを伴うアップビートなポップソング」）を記述する必要があります。
• 歌詞は、[verse]、[chorus]、[bridge]などのタグで構成される必要があります。

推論中:

• num_inference_steps、guidance_scale、shift は、上記に示された値がデフォルトです。turbo チェックポイントの場合、guidance_scale > 1.0 は警告とともに無視されます。これは、guidance が重みに蒸留されているためです。
• audio_duration パラメータは、生成される音楽の長さを秒単位で制御します。
• vocal_language パラメータは、歌詞の言語と一致させる必要があります。
• pipe.sample_rate と pipe.latents_per_second は VAE の設定から取得されます（公開されているチェックポイントでは 48000 Hz と 25 fps です）。
• 音声から音声へのタスクでは、pipe.sample_rate で前処理されたステレオテンソルとして src_audio と reference_audio を渡します。
• flash と flash_hub は、ACE-Step の自己注意機構において FlashAttention のネイティブなスライディングウィンドウサポートを利用し、パディングなしのテキストバッチを前提としています。バッチ化されたプロンプトにパディングが含まれる場合は、代わりに flash_varlen または flash_varlen_hub を使用してください。padding="longest" を用いた単一プロンプトの推論は、通常パディングなしです。

import torch
import soundfile as sf
from diffusers import AceStepPipeline

pipe = AceStepPipeline.from_pretrained("ACE-Step/acestep-v15-xl-turbo-diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

audio = pipe(
    prompt="A beautiful piano piece with soft melodies and gentle rhythm",
    lyrics="[verse]\nSoft notes in the morning light\nDancing through the air so bright\n[chorus]\nMusic fills the air tonight\nEvery note feels just right",
    audio_duration=30.0,
).audios

sf.write("output.wav", audio[0].T.cpu().float().numpy(), pipe.sample_rate)

AceStepPipeline[[diffusers.AceStepPipeline]]

diffusers.AceStepPipeline[[diffusers.AceStepPipeline]]

diffusers.AceStepPipeline(vae: AutoencoderOobleck, text_encoder: PreTrainedModel, tokenizer: TokenizersBackend, transformer: AceStepTransformer1DModel, condition_encoder: AceStepConditionEncoder, scheduler: FlowMatchEulerDiscreteScheduler, audio_tokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenizer] = None, audio_token_detokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenDetokenizer] = None)

ソース

パラメータ:

vae (AutoencoderOobleck) : 音声波形を潜在表現にエンコードし、潜在表現からデコードするための変分オートエンコーダ（VAE）モデル。

text_encoder (AutoModel) : テキストプロンプトや歌詞をエンコードするためのテキストエンコーダーモデル（例: Qwen3-Embedding-0.6B）。

tokenizer (AutoTokenizer) : テキストエンコーダー用のトークナイザー。

transformer (AceStepTransformer1DModel) : 音声潜在変数のノイズ除去に使用される Diffusion Transformer (DiT) モデル。

condition_encoder (AceStepConditionEncoder) : テキスト、歌詞、および音色の埋め込みを組み合わせ、クロスアテンションに使用する条件エンコーダー。

scheduler (FlowMatchEulerDiscreteScheduler) : Flow-matching Euler スケジューラ。ACE-Step は DiT のタイムステップを [0, 1] で入力するため、スケジューラは num_train_timesteps=1 および shift=1.0 で設定されます。パイプラインはシフト付き / ターボのシグマスケジュールを自身で計算し、set_timesteps(sigmas=...) を通じて渡します。

ACE-Step 1.5 を使用したテキストから音楽を生成する Pipeline です。

このモデルは DiffusionPipeline を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

パイプラインは、拡散プロセスにおいてカスタムなタイムステップスケジュールを用いたフローマッチングを使用します。ターボモデルのバリアントは、デフォルトで8回の推論ステップを使用します。

サポートされているタスクの種類:

• "text2music": テキストプロンプトと歌詞から音楽を生成します。
• "cover": 参照音声からの音色転送により、ソース音声 / 意味コードから音声を生成します。
• "repaint": 既存の音声の一部を再生成し、残りの部分はそのまま維持します。
• "extract": 音声から特定のトラック（ボーカルやドラムなど）を抽出します。
• "lego": 音声コンテキストに基づいて特定のトラックを生成します。
• "complete": 追加トラックを使用して入力オーディオを補完します。

call[[diffusers.AceStepPipeline.call]]

__call__(prompt: typing.Union[str, typing.List[str]] = None, lyrics: typing.Union[str, typing.List[str]] = '', audio_duration: float = 60.0, vocal_language: typing.Union[str, typing.List[str]] = 'en', num_inference_steps: int = 8, guidance_scale: float = 7.0, shift: float = 3.0, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: typing.Optional[str] = 'pt', return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: typing.Optional[int] = 1, callback_on_step_end: typing.Optional[typing.Callable[..., dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ('latents',), instruction: typing.Optional[str] = None, max_text_length: int = 256, max_lyric_length: int = 2048, bpm: typing.Optional[int] = None, keyscale: typing.Optional[str] = None, timesignature: typing.Optional[str] = None, task_type: str = 'text2music', track_name: typing.Optional[str] = None, complete_track_classes: typing.Optional[typing.List[str]] = None, src_audio: typing.Optional[torch.Tensor] = None, reference_audio: typing.Optional[torch.Tensor] = None, audio_codes: typing.Union[str, typing.List[str], NoneType] = None, repainting_start: typing.Optional[float] = None, repainting_end: typing.Optional[float] = None, audio_cover_strength: float = 1.0, cfg_interval_start: float = 0.0, cfg_interval_end: float = 1.0, timesteps: typing.Optional[typing.List[float]] = None, attention_kwargs: typing.Optional[dict] = None)

ソース

パラメータ:

prompt (str または List[str]、任意) : 音楽生成をガイドするためのプロンプトです。スタイル、ジャンル、楽器などを記述します。

lyrics (str または List[str]、任意、デフォルトは "") : 音楽の歌詞テキストです。[verse]、[chorus] などのタグを使った構造化歌詞に対応しています。

audio_duration (float、任意、デフォルト値は 60.0) : 生成されるオーディオの長さ（秒）。

vocal_language (str または List[str]、任意、デフォルトは "en") : 歌詞の言語コード（例: "en"、"zh"、"ja"）。

num_inference_steps (int、任意、デフォルトは 8) : デノイジングのステップ数です。Turbo モデルは 8 ステップ用に設計されています。

guidance_scale (float、optional、デフォルト値は 7.0) : classifier-free guidance のガイダンススケールです。1.0 を指定すると CFG が無効になります。

shift (float、任意、デフォルト値は 3.0) : タイムステップスケジュールのシフトパラメータ（1.0、2.0、または 3.0）。

generator (torch.Generator または List[torch.Generator]、任意) : 生成を決定論的にするためのジェネレーター。

latents (torch.Tensor, 任意) : 形状が (batch_size, latent_length, acoustic_dim) の、事前生成されたノイズの潜在変数。

output_type (str、任意、デフォルトは"pt") : 出力形式。"pt"はPyTorchテンソル、"np"はNumPy配列、"latent"は生の潜在変数です。

return_dict (bool、任意、デフォルトはTrue) : AudioPipelineOutputを返すか、通常のタプルを返すかを指定します。

callback (Callable、任意) : (step, timestep, latents) を引数として、callback_steps ステップごとに呼び出される関数。

callback_steps (int、任意、デフォルトは 1) : コールバック関数の実行頻度。

callback_on_step_end (Callable、任意) : 推論中の各デノイジングステップの終了時に呼び出される関数です。この関数は、以下の引数とともに呼び出されます: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict)。 callback_kwargs には、callback_on_step_end_tensor_inputs で指定されたすべてのテンソルのリストが含まれます。

callback_on_step_end_tensor_inputs (List, 任意) : callback_on_step_end 関数へのテンソル入力のリストです。リストで指定されたテンソルは、callback_kwargs 引数として渡されます。パイプラインクラスの ._callback_tensor_inputs 属性にリストされている変数のみを包含できます。

instruction (str, 任意) : 生成タスク用のカスタム指示テキスト。指定しない場合、task_typeに基づいて自動生成されます。

max_text_length (int、optional、デフォルトは 256) : テキストプロンプトのエンコードにおける最大トークン長です。

max_lyric_length (int、任意、デフォルトは 2048) : 歌詞エンコードの最大トークン長。

bpm (int, optional) : 音楽メタデータ用のBPM (beats per minute) です。Noneの場合、モデルが推定します。

keyscale (str, 任意) : 調（例: "C major"、"A minor"）。None の場合、モデルが推定します。

timesignature (str, 任意) : 拍子(例: 4/4拍子は"4"、3/4拍子は"3")。Noneの場合、モデルが推定します。

task_type (str、任意、デフォルトは"text2music") : 生成タスクの種類。"text2music"、"cover"、"repaint"、"extract"、"lego"、"complete"のいずれかです。

track_name (str, 任意) : "extract" または "lego" タスクのトラック名（例: "vocals"、"drums"）。

complete_track_classes (List[str]、任意) : "complete"タスクのトラッキングクラス。

src_audio (torch.Tensor, 任意) : 音声から音声へのタスク（repaint、lego、cover、extract、complete）において、48kHz のソース音声テンソルで、形状は [channels, samples] です。この音声は VAE を通してエンコードされ、ソース潜在変数が生成されます。

reference_audio (torch.Tensor, 任意) : タイムブリーディング用の参照オーディオテンソル。形状は [channels, samples] で、48kHz です。スタイル転送のためにタイムブリー特徴を抽出するために使用されます。

audio_codes (str または List[str]、省略可) : 音声セマンティックコードの文字列（例: "<|audio_code_123|><|audio_code_456|>..."）。指定された場合、タスクは自動的に "cover" モードに切り替わり、登録済みの ACE-Step 音声トークナイザー / デトークナイザーモジュールが 5 Hz のコードを 25 Hz の音響条件付けにデコードします。

repainting_start (float, 任意) : 再描画領域の開始時刻（秒）（"repaint"および"lego"タスク用）。

repainting_end (float, 任意) : 再描画領域の終了時刻（秒）。終了まで続ける場合は -1 または None を使用します。

audio_cover_strength (float、optional、デフォルト値は 1.0) : 音声カバレッジブレンドの強度（0.0 から 1.0）。1.0 未満の場合、カバレッジ条件付き出力とテキストのみ条件付き出力をブレンドします。値が低いほど、スタイル転移の効果が強くなります。

cfg_interval_start (float、任意、デフォルトは 0.0) : CFG が適用されるタイムステップ範囲の開始比率 (0.0-1.0)。

cfg_interval_end (float、optional、デフォルト値は 1.0) : CFG が適用されるタイムステップ範囲の終了比率 (0.0-1.0)。

timesteps (List[float], 任意) : カスタムのタイムステップスケジュール。指定された場合、num_inference_steps および shift を上書きします。

attention_kwargs (dict, 任意) : AttentionProcessor に渡される kwargs の辞書です。{"scale": float} を介して LoRA スケールを渡すために使用されます。

戻り値: AudioPipelineOutput または tuple

return_dict が True の場合、AudioPipelineOutput が返され、それ以外の場合は生成されたオーディオを含むタプルが返されます。

音楽生成用の pipeline の呼び出し関数。

例:

>>> import torch
>>> import soundfile as sf
>>> from diffusers import AceStepPipeline

>>> pipe = AceStepPipeline.from_pretrained(
...     "ACE-Step/acestep-v15-xl-turbo-diffusers", torch_dtype=torch.bfloat16
... )
>>> pipe = pipe.to("cuda")

>>> # Text-to-music generation with metadata
>>> audio = pipe(
...     prompt="A beautiful piano piece with soft melodies",
...     lyrics="[verse]\nSoft notes in the morning light\n[chorus]\nMusic fills the air tonight",
...     audio_duration=30.0,
...     num_inference_steps=8,
...     bpm=120,
...     keyscale="C major",
...     timesignature="4",
... ).audios

>>> # Save the generated audio
>>> sf.write("output.wav", audio[0, 0].cpu().numpy(), 48000)

>>> # Repaint task: regenerate a section of existing stereo 48kHz audio
>>> src_audio, sr = sf.read("input.wav")
>>> src_audio = torch.from_numpy(src_audio).float().T
>>> audio = pipe(
...     prompt="Epic rock guitar solo",
...     lyrics="",
...     task_type="repaint",
...     src_audio=src_audio,
...     repainting_start=10.0,
...     repainting_end=20.0,
... ).audios

>>> # Cover task with reference audio for timbre transfer
>>> ref_audio, sr = sf.read("reference.wav")
>>> ref_audio = torch.from_numpy(ref_audio).float().T
>>> audio = pipe(
...     prompt="Pop song with bright vocals",
...     lyrics="[verse]\nHello world",
...     task_type="cover",
...     reference_audio=ref_audio,
...     audio_cover_strength=0.8,
... ).audios

check_inputs[[diffusers.AceStepPipeline.check_inputs]]

check_inputs(prompt: typing.Union[str, typing.List[str]], lyrics: typing.Union[str, typing.List[str]], task_type: str, num_inference_steps: int, guidance_scale: float, shift: float, audio_cover_strength: float, cfg_interval_start: float, cfg_interval_end: float, repainting_start: typing.Optional[float], repainting_end: typing.Optional[float])

ソース

ノイズテンソルの割り当てを開始する前に、ユーザー向けの引数を検証します。

encode_prompt[[diffusers.AceStepPipeline.encode_prompt]]

encode_prompt(prompt: typing.Union[str, typing.List[str]], lyrics: typing.Union[str, typing.List[str]], device: device, vocal_language: typing.Union[str, typing.List[str]] = 'en', audio_duration: float = 60.0, instruction: typing.Optional[str] = None, bpm: typing.Optional[int] = None, keyscale: typing.Optional[str] = None, timesignature: typing.Optional[str] = None, max_text_length: int = 256, max_lyric_length: int = 2048)

ソース

パラメータ:

prompt (str または List[str]) : 音楽を説明するテキストキャプション。

lyrics (str または List[str]) : 歌詞テキスト。

device (torch.device) : テンソル用のデバイス。

vocal_language (str または List[str]、任意、デフォルトは "en") : 歌詞の言語コード。

audio_duration (float、任意、デフォルト値は 60.0) : 音声の長さ（秒）。

instruction (str, 任意) : 生成用の指示テキスト。

bpm (int, 任意) : メタデータ用の BPM（毎分ビート数）。

keyscale (str, 任意) : 調（例: "C major"）。

timesignature (str, 任意) : 拍子（例："4" は 4/4 拍子）。

max_text_length (int、optional、デフォルトは 256) : テキストプロンプトの最大トークン長。

max_lyric_length (int、任意、デフォルトは 2048) : 歌詞の最大トークン長。

戻り値:

(text_hidden_states, text_attention_mask, lyric_hidden_states, lyric_attention_mask) のタプル。

テキストプロンプトと歌詞を埋め込みベクトルに変換します。

テキストプロンプトは、完全なテキストエンコーダーモデルを介してエンコードされ、文脈付きの隠れ状態が生成されます。歌詞は、条件エンコーダー内の歌詞エンコーダーが文脈エンコーディングを処理するため、テキストエンコーダーの埋め込み層（トークン検索）のみを通過します。

prepare_latents[[diffusers.AceStepPipeline.prepare_latents]]

prepare_latents(batch_size: int, audio_duration: float, dtype: dtype, device: device, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None)

ソース

パラメータ:

batch_size (int) : 生成するサンプルの数。

audio_duration (float) : 音声の長さ（秒）。

dtype (torch.dtype) : 潜在変数のデータ型。

device (torch.device) : 潜在変数に使用するデバイス。

generator (torch.Generator または List[torch.Generator]、任意) : 乱数ジェネレーター。

latents (torch.Tensor, 任意) : 事前生成された潜変数（latents）。

戻り値:

(batch_size, latent_length, acoustic_dim) の形状を持つノイズ潜在変数。

フローマッチングプロセス用の初期ノイズ潜在変数を準備します。

prepare_reference_audio_latents[[diffusers.AceStepPipeline.prepare_reference_audio_latents]]

prepare_reference_audio_latents(reference_audio: Tensor, batch_size: int, device: device, dtype: dtype)

ソース

パラメータ:

reference_audio (torch.Tensor) : self.sample_rate で、形状が [channels, samples] の参照オーディオテンソル。

batch_size (int) : バッチサイズ。

device (torch.device) : ターゲットデバイス。

dtype (torch.dtype) : 対象の dtype。

戻り値:

(refer_audio_acoustic, refer_audio_order_mask) のタプル。

音色エンコーダー用の音響潜在変数に変換するために、参照オーディオを処理します。

参照オーディオは30秒（先頭、中央、末尾からそれぞれ10秒の3セグメント）に繰り返し/クロップされ、VAEでエンコードされた後、ティンバーエンコーダーのために転置されます。

prepare_src_latents[[diffusers.AceStepPipeline.prepare_src_latents]]

prepare_src_latents(device: device, dtype: dtype, batch_size: int = 1, src_audio: typing.Optional[torch.Tensor] = None, audio_codes: typing.Union[str, typing.List[str], NoneType] = None, latent_length: typing.Optional[int] = None, task_type: str = 'text2music')

ソース

パラメータ:

src_audio (torch.Tensor, 任意) : self.sample_rate の [channels, samples] 形状のソースオーディオテンソル。

audio_codes (str または List[str]、省略可能) : 音声セマンティックコードの文字列。

latent_length (int, 任意) : ソース音声や音声コードが指定されない場合の、ターゲットの潜在変数（latent）の長さ。

device (torch.device) : ターゲットデバイス。

dtype (torch.dtype) : 対象の dtype。

batch_size (int) : バッチサイズ。

task_type (str) : 現在のタスクの種類。

戻り値:

(src_latents, latent_length) のタプルで、src_latents の形状は [batch, T, D] です。

テキストから音楽への変換およびオーディオからオーディオへの変換タスク用に、ソースの潜在変数（latents）を準備します。