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 分钟不等）。完整系统将语言模型规划器与扩散 Transformer（DiT）合成器相结合；该流水线封装了该架构中的 DiT 部分，由三个组件构成：一个将波形压缩为 25 Hz 立体声潜变量的 AutoencoderOobleck VAE、一个基于 Qwen3 的文本编码器用于提示和歌词条件化，以及一个在 VAE 潜空间中利用流匹配进行操作的 AceStepTransformer1DModel DiT。

该模型支持 50 多种语言的歌词——包括英语、中文、日语、韩语、法语、德语、西班牙语、意大利语、葡萄牙语和俄语——并可在消费级 GPU 上运行（卸载后显存占用低于 4 GB）。

此流水线由 ACE-Step Team 贡献。原始代码库可在 ace-step/ACE-Step-1.5 中找到。

变体

ACE-Step 1.5 提供了三个 DiT 检查点，它们共享相同的 transformer 架构，但在 guidance 行为上有所不同；该 pipeline 会从加载的 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`	on	8	7.0	3.0	`ACE-Step/acestep-v15-base`
`sft`	on	8	7.0	3.0	`ACE-Step/acestep-v15-sft`

Base 和 SFT 使用学习到的 null_condition_emb 进行无分类器引导（APG，而非原生 CFG）。用户通常会将 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）。
对于音频到音频任务，请将 src_audio 和 reference_audio 作为以 pipe.sample_rate 为采样率的预处理立体声张量传入。
flash 和 flash_hub 利用 FlashAttention 原生的滑动窗口支持来处理 ACE-Step 的自注意力机制，并期望输入未填充的文本批次。如果批量提示中包含填充，请改用 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

< source >

( 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 — 流水线自行计算其移位 / turbo sigma 调度，并通过 set_timesteps(sigmas=...) 传入。

使用 ACE-Step 1.5 进行文本到音乐生成的 Pipeline。

该模型继承自 DiffusionPipeline。有关为所有 pipeline 实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

该流水线使用带有自定义时间步调度的流匹配（flow matching）来执行扩散过程。turbo 模型变体默认使用 8 个推理步骤。

支持的任务类型：

"text2music"：根据文本提示和歌词生成音乐。
"cover"：根据源音频/语义代码生成音频，并从参考音频中迁移音色。
"repaint"：重新生成现有音频的某一部分，同时保留其余部分。
"extract"：从音频中提取特定音轨（例如人声、鼓声）。
"lego"：根据音频上下文生成特定轨道。
"complete"：通过添加额外的音轨来补全输入音频。

call

< source >

( 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) — 时间步调度的 Shift 参数（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，可选) — 一个函数，每隔 callback_steps 步调用一次，参数为 (step, timestep, latents)。
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) — 文本提示编码的最大 token 长度。
max_lyric_length (int，可选，默认为 2048) — 歌词编码的最大 token 长度。
bpm (int, 可选) — 音乐元数据的 BPM（每分钟节拍数）。如果为 None，模型将对其进行估计。
keyscale (str，可选) — 音乐调性（例如 "C major"、"A minor"）。如果为 None，模型将自动估计。
timesignature (str, 可选) — 拍号（例如，"4" 表示 4/4 拍，"3" 表示 3/4 拍）。如果为 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）的源音频张量，形状为 [channels, samples]，采样率为 48kHz。该音频将通过 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，可选，默认值为 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 字典。用于通过 {"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

< source >

( 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

< source >

( 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) — 文本提示词的最大 token 长度。
max_lyric_length（int，可选，默认值为 2048）— 歌词的最大 token 长度。

将文本提示和歌词编码为嵌入。

文本提示词通过完整的文本编码器模型进行编码，以生成上下文隐藏状态。歌词仅通过文本编码器的嵌入层（token 查找）处理，因为条件编码器中的歌词编码器负责上下文编码。

prepare_latents

< source >

( 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

< source >

( 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

< source >

( 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, 可选) — 形状为 [channels, samples] 的源音频张量，采样率为 self.sample_rate。
audio_codes（str 或 List[str]，可选）— 音频语义编码字符串。
latent_length (int, 可选) — 在未提供源音频或音频代码时，目标潜在长度。
device (torch.device) — 目标设备。
dtype (torch.dtype) — 目标 dtype。
batch_size (int) — 批大小。
task_type (str) — 当前任务类型。

为文本生成音乐和音频到音频任务准备源潜在变量。

Update on GitHub

Diffusers

ACE-Step 1.5

变体

提示

AceStepPipeline

类 diffusers.AceStepPipeline

__call__

check_inputs

encode_prompt

prepare_latents

prepare_reference_audio_latents

prepare_src_latents

call