ACE-Step 1.5

ACE-Step 1.5 se presentó en ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation por el equipo ACE-Step (ACE Studio y StepFun). Es un modelo de base de música de código abierto que genera música estéreo de calidad comercial con letra a partir de indicaciones de texto.

ACE-Step 1.5 genera audio estéreo de longitud variable a 48 kHz (de 10 segundos a 10 minutos) a partir de indicaciones de texto y letras opcionales. El sistema completo combina un planificador de Language Model con un sintetizador Diffusion Transformer (DiT); este pipeline encapsula la mitad DiT de esa pila y consta de tres componentes: un VAE AutoencoderOobleck que comprime las formas de onda en latentes estéreo de 25 Hz, un codificador de texto basado en Qwen3 para la condicionamiento de la indicación y las letras, y un DiT AceStepTransformer1DModel que opera en el espacio latente del VAE utilizando flow matching.

El modelo admite más de 50 idiomas para letras —incluidos inglés, chino, japonés, coreano, francés, alemán, español, italiano, portugués y ruso— y se ejecuta en GPUs de consumo (menos de 4 GB de VRAM cuando se descarga).

Este pipeline fue aportado por el ACE-Step Team. La base de código original se encuentra en ace-step/ACE-Step-1.5.

Variantes

ACE-Step 1.5 incluye tres puntos de control de DiT que comparten la misma arquitectura de transformador pero difieren en el comportamiento de guía; la línea de producción detecta automáticamente los puntos de control turbo a partir de la configuración del transformador cargado e ignora la guía CFG para esos pesos destilados de guía.

Variante	CFG	Pasos predeterminados	Valor predeterminado de `guidance_scale`	Desplazamiento `shift` predeterminado	Repositorio de HF
`turbo` (destilado con guía)	off	8	ignored	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 y SFT utilizan el null_condition_emb aprendido para la guía sin clasificador (APG, no CFG estándar). Los usuarios suelen reemplazar num_inference_steps por 30–60 en base/sft para obtener una mayor calidad.

Consejos

Al construir un prompt, ten en cuenta:

Las entradas de prompt descriptivas funcionan mejor; usa adjetivos para describir el estilo musical, los instrumentos, el estado de ánimo y el tempo.
El prompt debe describir las características musicales generales (p. ej., “canción pop animada con guitarra eléctrica y batería”).
Las letras deben estructurarse con etiquetas como [verse], [chorus], [bridge], etc.

Durante la inferencia:

num_inference_steps, guidance_scale y shift toman por defecto los valores mostrados arriba. Para los puntos de control turbo, guidance_scale > 1.0 se ignora con una advertencia porque la guía se destila en los pesos.
El parámetro audio_duration controla la duración de la música generada en segundos.
El parámetro vocal_language debe coincidir con el idioma de la letra.
pipe.sample_rate y pipe.latents_per_second se obtienen de la configuración del VAE (48000 Hz y 25 fps para los puntos de control publicados).
Para tareas de audio a audio, pase src_audio y reference_audio como tensores estéreo preprocesados a pipe.sample_rate.
flash y flash_hub utilizan el soporte nativo de ventana deslizante de FlashAttention para la autoatención de ACE-Step y esperan lotes de texto sin relleno. Si un lote de indicaciones contiene relleno, use flash_varlen o flash_varlen_hub en su lugar. La inferencia con una sola indicación con padding="longest" normalmente no tiene relleno.

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

clase 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 de Variational Auto-Encoder (VAE) para codificar y decodificar formas de onda de audio hacia y desde representaciones latentes.
text_encoder (AutoModel) — Modelo de codificador de texto (p. ej., Qwen3-Embedding-0.6B) para codificar prompts de texto y letras.
tokenizer (AutoTokenizer) — Tokenizer para el codificador de texto.
transformer (AceStepTransformer1DModel) — El modelo Diffusion Transformer (DiT) para el desruido de latentes de audio.
condition_encoder (AceStepConditionEncoder) — Codificador de condiciones que combina los embeddings de texto, letra y timbre para la atención cruzada.
scheduler (FlowMatchEulerDiscreteScheduler) — Programador de Euler para flow-matching. ACE-Step alimenta los timesteps del DiT en [0, 1], por lo que el programador se configura con num_train_timesteps=1 y shift=1.0 — la pipeline calcula su propio programa de sigma desplazado / turbo y lo pasa mediante set_timesteps(sigmas=...).

Pipeline para la generación de música a partir de texto usando ACE-Step 1.5.

Este modelo hereda de DiffusionPipeline. Consulta la documentación de la clase superior para los métodos genéricos implementados en todas las tuberías (descarga, guardado, ejecución en un dispositivo específico, etc.).

El pipeline utiliza flow matching con un programa de pasos de tiempo personalizado para el proceso de difusión. La variante turbo del modelo utiliza 8 pasos de inferencia de forma predeterminada.

Tipos de tareas admitidos:

"text2music": Genera música a partir de indicaciones de texto y letras.
"cover": Genera audio a partir de audio de origen / códigos semánticos con transferencia de timbre desde audio de referencia.
"repaint": Regenera una sección del audio existente manteniendo el resto.
"extract": Extrae una pista específica (p. ej., voces, batería) del audio.
"lego": Genera una pista específica en función del contexto de audio.
"complete": Completa un audio de entrada con pistas adicionales.

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 o List[str], opcional) — El prompt o prompts para guiar la generación de música. Describe el estilo, el género, los instrumentos, etc.
lyrics (str o List[str], opcional, valor predeterminado "") — El texto de la letra de la música. Admite letras estructuradas con etiquetas como [verse], [chorus], etc.
audio_duration (float, opcional, valor predeterminado 60.0) — Duración del audio generado en segundos.
vocal_language (str o List[str], opcional, valor predeterminado "en") — Código de idioma para la letra (p. ej., "en", "zh", "ja").
num_inference_steps (int, opcional, valor predeterminado 8) — El número de pasos de desruido. El modelo turbo está diseñado para 8 pasos.
guidance_scale (float, opcional, valor predeterminado 7.0) — Escala de guía para la guía libre de clasificador. Un valor de 1.0 desactiva CFG.
shift (float, opcional, valor predeterminado 3.0) — Parámetro de desplazamiento para la programación de pasos de tiempo (1.0, 2.0 o 3.0).
generator (torch.Generator o List[torch.Generator], opcional) — Un generador para hacer la generación determinista.
latents (torch.Tensor, opcional) — Latentes de ruido pregenerados de forma (batch_size, latent_length, acoustic_dim).
output_type (str, opcional, por defecto "pt") — Formato de salida. "pt" para tensor de PyTorch, "np" para array de NumPy, "latent" para latentes crudos.
return_dict (bool, opcional, valor predeterminado True) — Si se devuelve un AudioPipelineOutput o una tupla simple.
callback (Callable, opcional) — Una función que se llama cada callback_steps pasos con (step, timestep, latents).
callback_steps (int, opcional, valor predeterminado 1) — Frecuencia de la función de callback.
callback_on_step_end (Callable, opcional) — Una función que se llama al final de cada paso de desruido durante la inferencia. La función se llama con los siguientes argumentos: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs incluirá una lista de todos los tensores especificados por callback_on_step_end_tensor_inputs.
callback_on_step_end_tensor_inputs (List, opcional) — La lista de entradas de tensor para la función callback_on_step_end. Los tensores especificados en la lista se pasarán como argumento callback_kwargs. Solo podrá incluir variables listadas en el atributo ._callback_tensor_inputs de su clase de pipeline.
instruction (str, opcional) — Texto de instrucción personalizado para la tarea de generación. Si no se proporciona, se genera automáticamente en función de task_type.
max_text_length (int, opcional, valor predeterminado 256) — Longitud máxima de tokens para la codificación del prompt de texto.
max_lyric_length (int, opcional, valor predeterminado 2048) — Longitud máxima de tokens para la codificación de letras.
bpm (int, opcional) — BPM (golpes por minuto) para los metadatos de la música. Si es None, el modelo lo estima.
keyscale (str, opcional) — Tono musical (p. ej., "C major", "A minor"). Si es None, el modelo lo estima.
timesignature (str, opcional) — Firma de compás (p. ej., "4" para 4/4, "3" para 3/4). Si es None, el modelo la estima.
task_type (str, opcional, valor predeterminado "text2music") — El tipo de tarea de generación. Uno de "text2music", "cover", "repaint", "extract", "lego", "complete".
track_name (str, opcional) — Nombre de la pista para las tareas "extract" o "lego" (p. ej., "vocals", "drums").
complete_track_classes (List[str], opcional) — Clases de seguimiento para la tarea "complete".
src_audio (torch.Tensor, opcional) — Tensor de audio de origen con forma [channels, samples] a 48 kHz para tareas de audio a audio (repaint, lego, cover, extract, complete). El audio se codifica a través del VAE para producir latentes de origen.
reference_audio (torch.Tensor, opcional) — Tensor de audio de referencia de forma [channels, samples] a 48 kHz para el condicionamiento del timbre. Se utiliza para extraer características de timbre para la transferencia de estilo.
audio_codes (str o List[str], opcional) — Cadenas de códigos semánticos de audio (p. ej. "<|audio_code_123|><|audio_code_456|>..."). Si se proporciona, la tarea se cambia automáticamente al modo "cover" y los módulos de tokenizador / detokenizador de audio de ACE-Step registrados decodifican los códigos de 5 Hz en condicionamiento acústico de 25 Hz.
repainting_start (float, opcional) — Tiempo de inicio en segundos para la región de repintado (para las tareas "repaint" y "lego").
repainting_end (float, opcional) — Tiempo final en segundos para la región de repintado. Use -1 o None para hasta el final.
audio_cover_strength (float, opcional, valor predeterminado 1.0) — Intensidad de la mezcla de la cubierta de audio (0.0 a 1.0). Cuando es < 1.0, combina las salidas condicionadas por la cubierta y las condicionadas solo por texto. Los valores más bajos producen un mayor efecto de transferencia de estilo.
cfg_interval_start (float, opcional, valor predeterminado 0.0) — Proporción de inicio (0.0-1.0) del rango de pasos de tiempo donde se aplica CFG.
cfg_interval_end (float, opcional, valor predeterminado 1.0) — Proporción final (0.0-1.0) del rango de pasos de tiempo donde se aplica CFG.
timesteps (List[float], opcional) — Programa de pasos de tiempo personalizado. Si se proporciona, reemplaza a num_inference_steps y shift.
attention_kwargs (dict, opcional) — Un diccionario de kwargs que se pasa al AttentionProcessor. Se utiliza para pasar la escala de LoRA mediante {"scale": float}.

Devuelve

AudioPipelineOutput o tuple

Si return_dict es True, se devuelve un AudioPipelineOutput; en caso contrario, se devuelve una tupla con el audio generado.

La función de llamada para la pipeline de generación de música.

Ejemplos:

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

Validar los argumentos orientados al usuario antes de comenzar a asignar tensores de ruido.

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 o List[str]) — Leyenda(s) de texto que describen la música.
lyrics (str o List[str]) — Texto(s) de la letra.
device (torch.device) — Dispositivo para los tensores.
vocal_language (str o List[str], opcional, valor predeterminado "en") — Código(s) de idioma para las letras.
audio_duration (float, opcional, valor predeterminado 60.0) — Duración del audio en segundos.
instruction (str, opcional) — Texto de instrucción para la generación.
bpm (int, opcional) — BPM (golpes por minuto) para los metadatos.
keyscale (str, opcional) — Tono musical (p. ej., "C major").
timesignature (str, opcional) — Firma de compás (p. ej., "4" para 4/4).
max_text_length (int, opcional, valor predeterminado 256) — Longitud máxima de tokens para los prompts de texto.
max_lyric_length (int, opcional, valor predeterminado 2048) — Longitud máxima de tokens para las letras.

Codifica los prompts de texto y las letras en embeddings.

Los prompts de texto se codifican a través del modelo completo de codificador de texto para producir estados ocultos contextuales. Las letras solo se pasan por la capa de incrustación del codificador de texto (búsqueda de tokens), ya que el codificador de letras dentro del codificador de condiciones se encarga de la codificación 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 muestras a generar.
audio_duration (float) — Duración del audio en segundos.
dtype (torch.dtype) — Tipo de datos para los latentes.
device (torch.device) — Dispositivo para los latentes.
generator (torch.Generator o List[torch.Generator], opcional) — Generador(es) de números aleatorios.
latents (torch.Tensor, opcional) — Latentes pregenerados.

Prepara los latentes de ruido inicial para el proceso de flow matching.

prepare_reference_audio_latents

< source >

( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )

Parámetros

reference_audio (torch.Tensor) — Tensor de audio de referencia de forma [channels, samples] a self.sample_rate.
batch_size (int) — Tamaño del lote.
device (torch.device) — Dispositivo de destino.
dtype (torch.dtype) — dtype de destino.

Procesa el audio de referencia en latentes acústicos para el codificador de timbre.

El audio de referencia se repite o recorta a 30 segundos (3 segmentos de 10 segundos cada uno, del inicio, el medio y el final), se codifica a través del VAE y luego se transpone para el 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 audio de origen de forma [channels, samples] a self.sample_rate.
audio_codes (str o List[str], opcional) — Cadenas de códigos semánticos de audio.
latent_length (int, opcional) — Longitud latente objetivo cuando no se proporciona audio de origen ni códigos de audio.
device (torch.device) — Dispositivo de destino.
dtype (torch.dtype) — dtype de destino.
batch_size (int) — Tamaño del lote.
task_type (str) — Tipo de tarea actual.

Prepara los latentes de origen para tareas de texto a música y de audio a audio.

Update on GitHub

Diffusers

ACE-Step 1.5

Variantes

Consejos

AceStepPipeline

clase diffusers.AceStepPipeline

__call__

check_inputs

encode_prompt

prepare_latents

prepare_reference_audio_latents

prepare_src_latents

call