ACE-Step 1.5

ACE-Step 1.5 foi introduzido em ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation pela equipe ACE-Step (ACE Studio e StepFun). É um modelo de fundação de música de código aberto que gera música estéreo de qualidade comercial com letras a partir de prompts de texto.

ACE-Step 1.5 gera áudio estéreo de comprimento variável a 48 kHz (de 10 segundos a 10 minutos) a partir de prompts de texto e letras opcionais. O sistema completo combina um planejador de Language Model com um sintetizador Diffusion Transformer (DiT); este pipeline encapsula a metade DiT dessa pilha e consiste em três componentes: um VAE AutoencoderOobleck que comprime formas de onda em latentes estéreo de 25 Hz, um codificador de texto baseado em Qwen3 para condicionamento de prompt e letra, e um DiT AceStepTransformer1DModel que opera no espaço latente do VAE usando flow matching.

O modelo suporta mais de 50 idiomas para letras — incluindo inglês, chinês, japonês, coreano, francês, alemão, espanhol, italiano, português e russo — e roda em GPUs de consumo (menos de 4 GB de VRAM quando offloaded).

Este pipeline foi contribuído pela ACE-Step Team. A base de código original pode ser encontrada em ace-step/ACE-Step-1.5.

Variantes

ACE-Step 1.5 inclui três checkpoints DiT que compartilham a mesma arquitetura de transformer, mas diferem no comportamento de orientação; o pipeline detecta automaticamente checkpoints turbo a partir da configuração do transformer carregado e ignora a orientação CFG para esses pesos destilados de orientação.

Variante	CFG	Etapas padrão	Padrão de `guidance_scale`	Padrão `shift`	Repositório do HF
`turbo` (destilado com orientação)	off	8	ignorado	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 e SFT usam o null_condition_emb aprendido para classifier-free guidance (APG, não CFG vanilla). Os usuários comumente substituem num_inference_steps por 30–60 em base/sft para maior qualidade.

Dicas

Ao construir um prompt, tenha em mente:

Prompts descritivos funcionam melhor; use adjetivos para descrever o estilo musical, os instrumentos, o clima e o andamento.
O prompt deve descrever as características musicais gerais (por exemplo, “música pop animada com guitarra elétrica e bateria”).
As letras devem ser estruturadas com tags como [verse], [chorus], [bridge], etc.

Durante a inferência:

num_inference_steps, guidance_scale e shift assumem, por padrão, os valores mostrados acima. Para checkpoints turbo, guidance_scale > 1.0 é ignorado com um aviso, pois o guidance é destilado nos pesos.
O parâmetro audio_duration controla a duração da música gerada, em segundos.
O parâmetro vocal_language deve corresponder ao idioma da letra.
pipe.sample_rate e pipe.latents_per_second são obtidos da configuração do VAE (48000 Hz e 25 fps para os checkpoints liberados).
Para tarefas de áudio para áudio, passe src_audio e reference_audio como tensores estéreo pré-processados em pipe.sample_rate.
flash e flash_hub usam o suporte nativo de janela deslizante do FlashAttention para a autoatenção do ACE-Step e esperam lotes de texto sem preenchimento. Se um lote de prompts contiver preenchimento, use flash_varlen ou flash_varlen_hub em vez disso. A inferência com um único prompt usando padding="longest" normalmente não tem preenchimento.

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

classe 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 )

Parâmetros

vae (AutoencoderOobleck) — Modelo Variational Auto-Encoder (VAE) para codificar e decodificar formas de onda de áudio para e a partir de representações latentes.
text_encoder (AutoModel) — Modelo de codificador de texto (por exemplo, Qwen3-Embedding-0.6B) para codificar prompts de texto e letras.
tokenizer (AutoTokenizer) — Tokenizer para o codificador de texto.
transformer (AceStepTransformer1DModel) — O modelo Diffusion Transformer (DiT) para desruidar latentes de áudio.
condition_encoder (AceStepConditionEncoder) — Codificador de condição que combina embeddings de texto, letra e timbre para cross-attention.
scheduler (FlowMatchEulerDiscreteScheduler) — Agendador Euler de fluxo. O ACE-Step fornece os timesteps do DiT em [0, 1], portanto, o agendador é configurado com num_train_timesteps=1 e shift=1.0 — o pipeline calcula seu próprio agendamento de sigma deslocado / turbo e o passa via set_timesteps(sigmas=...).

Pipeline para geração de música a partir de texto usando ACE-Step 1.5.

Este modelo herda de DiffusionPipeline. Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines (download, salvamento, execução em um dispositivo específico, etc.).

O pipeline usa flow matching com um cronograma de timestep personalizado para o processo de difusão. A variante turbo do modelo usa 8 etapas de inferência por padrão.

Tipos de tarefas suportados:

"text2music": Gera música a partir de prompts de texto e letras.
"cover": Gera áudio a partir de áudio de origem / códigos semânticos com transferência de timbre a partir de áudio de referência.
"repaint": Regenera uma seção do áudio existente, mantendo o restante.
"extract": Extrai uma faixa específica (por exemplo, vocais, bateria) do áudio.
"lego": Gera uma trilha específica com base no contexto de áudio.
"complete": Complete um áudio de entrada com faixas adicionais.

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

Parâmetros

prompt (str ou List[str], opcional) — O prompt ou prompts para orientar a geração de música. Descreve o estilo, o gênero, os instrumentos, etc.
lyrics (str ou List[str], opcional, padrão "") — O texto da letra da música. Suporta letras estruturadas com tags como [verse], [chorus], etc.
audio_duration (float, opcional, padrão 60.0) — Duração do áudio gerado em segundos.
vocal_language (str ou List[str], opcional, padrão "en") — Código de idioma para a letra (por exemplo, "en", "zh", "ja").
num_inference_steps (int, opcional, padrão 8) — O número de etapas de desruidamento. O modelo turbo é projetado para 8 etapas.
guidance_scale (float, opcional, padrão 7.0) — Escala de orientação para orientação sem classificador. Um valor de 1.0 desativa o CFG.
shift (float, opcional, padrão 3.0) — Parâmetro de deslocamento para o cronograma de passos de tempo (1.0, 2.0 ou 3.0).
generator (torch.Generator ou List[torch.Generator], opcional) — Um gerador para tornar a geração determinística.
latents (torch.Tensor, opcional) — Latentes de ruído pré-gerados com forma (batch_size, latent_length, acoustic_dim).
output_type (str, opcional, padrão "pt") — Formato de saída. "pt" para tensor do PyTorch, "np" para array do NumPy, "latent" para latentes brutos.
return_dict (bool, opcional, padrão True) — Se deve retornar um AudioPipelineOutput ou uma tupla simples.
callback (Callable, opcional) — Uma função chamada a cada callback_steps passos com (step, timestep, latents).
callback_steps (int, opcional, padrão 1) — Frequência da função de callback.
callback_on_step_end (Callable, opcional) — Uma função que é chamada no final de cada etapa de remoção de ruído durante a inferência. A função é chamada com os seguintes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá uma lista de todos os tensores, conforme especificado por callback_on_step_end_tensor_inputs.
callback_on_step_end_tensor_inputs (List, opcional) — A lista de entradas de tensor para a função callback_on_step_end. Os tensores especificados na lista serão passados como argumento callback_kwargs. Você só poderá incluir variáveis listadas no atributo ._callback_tensor_inputs da sua classe de pipeline.
instruction (str, opcional) — Texto de instrução personalizado para a tarefa de geração. Se não for fornecido, ele é gerado automaticamente com base em task_type.
max_text_length (int, opcional, padrão 256) — Comprimento máximo de tokens para a codificação do prompt de texto.
max_lyric_length (int, opcional, padrão 2048) — Comprimento máximo de tokens para a codificação de letras.
bpm (int, opcional) — BPM (batidas por minuto) para metadados de música. Se None, o modelo o estima.
keyscale (str, opcional) — Tom musical (por exemplo, "C major", "A minor"). Se None, o modelo o estima.
timesignature (str, opcional) — Assinatura de compasso (por exemplo, "4" para 4/4, "3" para 3/4). Se None, o modelo a estima.
task_type (str, opcional, padrão "text2music") — O tipo de tarefa de geração. Um de "text2music", "cover", "repaint", "extract", "lego", "complete".
track_name (str, opcional) — Nome da faixa para as tarefas "extract" ou "lego" (por exemplo, "vocals", "drums").
complete_track_classes (List[str], opcional) — Classes de rastreamento para a tarefa "complete".
src_audio (torch.Tensor, opcional) — Tensor de áudio de origem com forma [channels, samples] a 48 kHz para tarefas de áudio para áudio (repaint, lego, cover, extract, complete). O áudio é codificado por meio do VAE para produzir latentes de origem.
reference_audio (torch.Tensor, opcional) — Tensor de áudio de referência com forma [channels, samples] a 48 kHz para condicionamento de timbre. Usado para extrair características de timbre para transferência de estilo.
audio_codes (str ou List[str], opcional) — Strings de códigos semânticos de áudio (por exemplo, "<|audio_code_123|><|audio_code_456|>..."). Quando fornecido, a tarefa é automaticamente alterada para o modo "cover" e os módulos de tokenizer / detokenizer de áudio ACE-Step registrados decodificam os códigos de 5 Hz em condicionamento acústico de 25 Hz.
repainting_start (float, opcional) — Tempo de início em segundos para a região de repintura (para as tarefas "repaint" e "lego").
repainting_end (float, opcional) — Tempo final em segundos para a região de repintura. Use -1 ou None para até o final.
audio_cover_strength (float, opcional, padrão 1.0) — Força da mistura da capa de áudio (0.0 a 1.0). Quando < 1.0, mistura as saídas condicionadas pela capa e as saídas condicionadas apenas pelo texto. Valores menores produzem mais efeito de transferência de estilo.
cfg_interval_start (float, opcional, padrão 0.0) — Proporção inicial (0.0-1.0) do intervalo de passos de tempo em que o CFG é aplicado.
cfg_interval_end (float, opcional, padrão 1.0) — Proporção final (0.0-1.0) do intervalo de passos de tempo em que o CFG é aplicado.
timesteps (List[float], opcional) — Agenda de timesteps personalizada. Se fornecida, substitui num_inference_steps e shift.
attention_kwargs (dict, opcional) — Um dicionário de kwargs passado para o AttentionProcessor. Usado para passar a escala do LoRA via {"scale": float}.

Retorna

AudioPipelineOutput ou tuple

Se return_dict for True, um AudioPipelineOutput é retornado; caso contrário, uma tupla com o áudio gerado é retornada.

A função de chamada do pipeline para geração de música.

Exemplos:

>>> 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] )

Valide os argumentos voltados para o usuário antes de começarmos a alocar os tensores de ruído.

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 )

Parâmetros

prompt (str ou List[str]) — Legenda(s) de texto descrevendo a música.
lyrics (str ou List[str]) — Texto(s) da letra.
device (torch.device) — Dispositivo para os tensores.
vocal_language (str ou List[str], opcional, padrão "en") — Código(s) de idioma para as letras.
audio_duration (float, opcional, padrão 60.0) — Duração do áudio em segundos.
instruction (str, opcional) — Texto de instrução para a geração.
bpm (int, opcional) — BPM (batidas por minuto) para metadados.
keyscale (str, opcional) — Tom musical (ex.: "C major").
timesignature (str, opcional) — Assinatura de compasso (por exemplo, "4" para 4/4).
max_text_length (int, opcional, padrão 256) — Comprimento máximo de tokens para prompts de texto.
max_lyric_length (int, opcional, padrão 2048) — Comprimento máximo de tokens para as letras.

Codifique prompts de texto e letras em embeddings.

Os prompts de texto são codificados por meio do modelo completo de codificador de texto para produzir estados ocultos contextuais. As letras são passadas apenas pela camada de incorporação do codificador de texto (consulta de tokens), pois o codificador de letras no codificador de condição lida com a codificação contextual.

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 )

Parâmetros

batch_size (int) — Número de amostras a serem geradas.
audio_duration (float) — Duração do áudio em segundos.
dtype (torch.dtype) — Tipo de dados dos latentes.
device (torch.device) — Dispositivo para os latentes.
generator (torch.Generator ou List[torch.Generator], opcional) — Gerador(es) de números aleatórios.
latents (torch.Tensor, opcional) — Latentes pré-gerados.

Prepare os latentes de ruído inicial para o processo de flow matching.

prepare_reference_audio_latents

< source >

( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )

Parâmetros

reference_audio (torch.Tensor) — Tensor de áudio de referência com forma [channels, samples] em self.sample_rate.
batch_size (int) — Tamanho do lote.
device (torch.device) — Dispositivo de destino.
dtype (torch.dtype) — dtype de destino.

Processe o áudio de referência em latentes acústicos para o codificador de timbre.

O áudio de referência é repetido/recortado para 30 segundos (3 segmentos de 10 segundos cada, do início, do meio e do final), codificado por meio do VAE e, em seguida, transposto para o codificador de timbre.

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' )

Parâmetros

src_audio (torch.Tensor, opcional) — Tensor de áudio de origem com forma [channels, samples] em self.sample_rate.
audio_codes (str ou List[str], opcional) — Strings de códigos semânticos de áudio.
latent_length (int, opcional) — Comprimento latente alvo quando nenhum áudio de origem ou códigos de áudio são fornecidos.
device (torch.device) — Dispositivo de destino.
dtype (torch.dtype) — dtype de destino.
batch_size (int) — Tamanho do lote.
task_type (str) — Tipo de tarefa atual.

Prepare os latentes de origem para tarefas de texto para música e áudio para áudio.

Update on GitHub

Diffusers

ACE-Step 1.5

Variantes

Dicas

AceStepPipeline

classe diffusers.AceStepPipeline

__call__

check_inputs

encode_prompt

prepare_latents

prepare_reference_audio_latents

prepare_src_latents

call