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

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

Fonte

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) : Tokenizador para o codificador de texto.

transformer (AceStepTransformer1DModel) : O modelo Diffusion Transformer (DiT) para desruído de 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 correspondência de fluxo. O ACE-Step fornece os passos de tempo 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[[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)

Fonte

Parâmetros:

prompt (str ou List[str], opcional) : O prompt ou os 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 as letras (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 livre de classificador. Um valor de 1.0 desativa o CFG.

shift (float, opcional, padrão 3.0) : Parâmetro de deslocamento para o agendamento 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 desruidamento 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) : Tonalidade musical (ex.: "C major", "A minor"). Se None, o modelo a 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 dos "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 formato [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 fornecidas, 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 de cobertura de áudio (0.0 a 1.0). Quando < 1.0, mistura as saídas condicionadas por cobertura e as condicionadas apenas por texto. Valores mais baixos 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 timesteps onde o CFG é aplicado.

cfg_interval_end (float, opcional, padrão 1.0) : Razão final (0.0-1.0) do intervalo de timestep onde 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[[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])

Fonte

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

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)

Fonte

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 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.

Retorna:

Tupla de (text_hidden_states, text_attention_mask, lyric_hidden_states, lyric_attention_mask).

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 trata da codificação contextual.

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)

Fonte

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 para os 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.

Retorna:

Latentes de ruído com forma (batch_size, latent_length, acoustic_dim).

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

prepare_reference_audio_latents[[diffusers.AceStepPipeline.prepare_reference_audio_latents]]

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

Fonte

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.

Retorna:

Tupla de (refer_audio_acoustic, refer_audio_order_mask).

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 fim), codificado por meio do VAE e, em seguida, transposto para o codificador de timbre.

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

Fonte

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ódigo semântico 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.

Retorna:

Tupla de (src_latents, latent_length) onde src_latents tem a forma [batch, T, D].

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