# ACE-Step 1.5

ACE-Step 1.5 foi introduzido em [ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation](https://arxiv.org/abs/2602.00744) 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](/docs/diffusers/main/pt/api/models/autoencoder_oobleck#diffusers.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](/docs/diffusers/main/pt/api/models/ace_step_transformer#diffusers.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](https://github.com/ace-step). A base de código original pode ser encontrada em [ace-step/ACE-Step-1.5](https://github.com/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`](https://huggingface.co/ACE-Step/acestep-v15-xl-turbo-diffusers) |
| `base` | on | 8 | 7.0 | 3.0 | [`ACE-Step/acestep-v15-base`](https://huggingface.co/ACE-Step/acestep-v15-base) |
| `sft` | on | 8 | 7.0 | 3.0 | [`ACE-Step/acestep-v15-sft`](https://huggingface.co/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.

```python
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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L134)

**Parâmetros:**

vae ([AutoencoderOobleck](/docs/diffusers/main/pt/api/models/autoencoder_oobleck#diffusers.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](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModel)) : Modelo de codificador de texto (por exemplo, Qwen3-Embedding-0.6B) para codificar prompts de texto e letras.

tokenizer ([AutoTokenizer](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoTokenizer)) : Tokenizador para o codificador de texto.

transformer ([AceStepTransformer1DModel](/docs/diffusers/main/pt/api/models/ace_step_transformer#diffusers.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](/docs/diffusers/main/pt/api/schedulers/flow_match_euler_discrete#diffusers.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](/docs/diffusers/main/pt/api/pipelines/overview#diffusers.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__]]

```python
__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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L785)

**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](/docs/diffusers/main/pt/api/pipelines/audioldm2#diffusers.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:
```py
>>> 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]]

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L233)

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

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L402)

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

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L507)

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

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L581)

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

```python
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](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L634)

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