Hugging Face's logo

Diffusers documentation

ACE-Step 1.5

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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デフォルトのshiftHF リポジトリ
turbo（guidance-distilled）off8無視3.0ACE-Step/acestep-v15-xl-turbo-diffusers
baseオン87.03.0ACE-Step/acestep-v15-base
sftオン87.03.0ACE-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

class diffusers.AceStepPipeline

< >

( vae: AutoencoderOoblecktext_encoder: PreTrainedModeltokenizer: TokenizersBackendtransformer: AceStepTransformer1DModelcondition_encoder: AceStepConditionEncoderscheduler: FlowMatchEulerDiscreteScheduleraudio_tokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenizer] = Noneaudio_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__

< >

( prompt: typing.Union[str, typing.List[str]] = Nonelyrics: typing.Union[str, typing.List[str]] = ''audio_duration: float = 60.0vocal_language: typing.Union[str, typing.List[str]] = 'en'num_inference_steps: int = 8guidance_scale: float = 7.0shift: float = 3.0generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pt'return_dict: bool = Truecallback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = Nonecallback_steps: typing.Optional[int] = 1callback_on_step_end: typing.Optional[typing.Callable[..., dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ('latents',)instruction: typing.Optional[str] = Nonemax_text_length: int = 256max_lyric_length: int = 2048bpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonetask_type: str = 'text2music'track_name: typing.Optional[str] = Nonecomplete_track_classes: typing.Optional[typing.List[str]] = Nonesrc_audio: typing.Optional[torch.Tensor] = Nonereference_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonerepainting_start: typing.Optional[float] = Nonerepainting_end: typing.Optional[float] = Noneaudio_cover_strength: float = 1.0cfg_interval_start: float = 0.0cfg_interval_end: float = 1.0timesteps: typing.Optional[typing.List[float]] = Noneattention_kwargs: typing.Optional[dict] = None ) → AudioPipelineOutput or tuple

パラメータ

  • 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、任意、デフォルト値は 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、任意、デフォルトは 256) — テキストプロンプトのエンコードにおける最大トークン長です。
  • max_lyric_length (int、任意、デフォルト値: 2048) — 歌詞エンコード用の最大トークン長。
  • bpm (int, 任意) — 音楽メタデータ用の BPM(分速)。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 を通してエンコードされ、ソース潜在変数（source latents）が生成されます。
  • reference_audio (torch.Tensor, 任意) — 音色の条件付けに使用する、48kHz の形状 [channels, samples] の参照オーディオテンソル。スタイル転送のために音色特徴を抽出するために使用されます。
  • 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、任意、デフォルト値は 1.0) — オーディオカバレッジのブレンド強度 (0.0 から 1.0)。1.0 未満の場合、カバレッジ条件付き出力とテキストのみ条件付き出力をブレンドします。値が低いほど、スタイル転移の効果が強くなります。
  • cfg_interval_start (float、任意、デフォルト値は 0.0)— CFG が適用されるタイムステップ範囲の開始比率 (0.0-1.0)。
  • cfg_interval_end (float、任意、デフォルト値は 1.0)— CFG が適用されるタイムステップ範囲の終了比率 (0.0-1.0)。
  • timesteps (List[float]、任意) — カスタムなタイムステップスケジュールを指定します。指定した場合、num_inference_steps および shift を上書きします。
  • attention_kwargs (dict, 任意) — AttentionProcessor に渡される kwargs の辞書です。LoRA のスケールを {"scale": float} として渡すために使用します。

戻り値

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

< >

( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]task_type: strnum_inference_steps: intguidance_scale: floatshift: floataudio_cover_strength: floatcfg_interval_start: floatcfg_interval_end: floatrepainting_start: typing.Optional[float]repainting_end: typing.Optional[float] )

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

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]device: devicevocal_language: typing.Union[str, typing.List[str]] = 'en'audio_duration: float = 60.0instruction: typing.Optional[str] = Nonebpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonemax_text_length: int = 256max_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、任意、デフォルトは 256) — テキストプロンプトの最大トークン長。
  • max_lyric_length (int、任意、デフォルト値は 2048)— 歌詞の最大トークン長。

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

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

prepare_latents

< >

( batch_size: intaudio_duration: floatdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: 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, 任意) — 事前生成された潜変数。

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

prepare_reference_audio_latents

< >

( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )

パラメータ

  • reference_audio (torch.Tensor) — 形状が [channels, samples] で、サンプリングレートが self.sample_rate の参照オーディオテンソル。
  • batch_size (int) — バッチサイズ。
  • device (torch.device) — 対象デバイス。
  • dtype (torch.dtype) — 対象の dtype。

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

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

prepare_src_latents

< >

( device: devicedtype: dtypebatch_size: int = 1src_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonelatent_length: typing.Optional[int] = Nonetask_type: str = 'text2music' )

パラメータ

  • src_audio (torch.Tensor, 任意) — self.sample_rate で、形状が [channels, samples] のソースオーディオテンソル。
  • audio_codes (str または List[str]、省略可) — 音声セマンティックコード文字列。
  • latent_length (int, 任意) — ソース音声や音声コードが指定されていない場合の、ターゲットの潜在長。
  • device (torch.device) — 対象デバイス。
  • dtype (torch.dtype) — 対象の dtype。
  • batch_size (int) — バッチサイズ。
  • task_type (str) — 現在のタスクタイプ。

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

Update on GitHub

←AutoPipeline AudioLDM 2→