ACE-Step 1.5

ACE-Step 1.5 a été présenté dans ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation par l'équipe ACE-Step (ACE Studio et StepFun). Il s'agit d'un modèle de fondation open source pour la musique qui génère de la musique stéréo de qualité commerciale avec paroles à partir de prompts texte.

ACE-Step 1.5 génère de l’audio stéréo de longueur variable à 48 kHz (de 10 secondes à 10 minutes) à partir de prompts texte et de paroles facultatives. Le système complet associe un planificateur basé sur un Language Model à un synthétiseur Diffusion Transformer (DiT) ; ce pipeline encapsule la partie DiT de cette pile et se compose de trois composants : un VAE AutoencoderOobleck qui compresse les formes d’onde en latents stéréo à 25 Hz, un encodeur de texte basé sur Qwen3 pour le conditionnement par prompt et paroles, et un DiT AceStepTransformer1DModel qui opère dans l’espace latent du VAE en utilisant le flow matching.

Le modèle prend en charge plus de 50 langues pour les paroles — y compris l'anglais, le chinois, le japonais, le coréen, le français, l'allemand, l'espagnol, l'italien, le portugais et le russe — et fonctionne sur des GPU grand public (moins de 4 Go de VRAM en cas de déchargement).

Ce pipeline a été contribué par l'ACE-Step Team. Le code source original est disponible sur ace-step/ACE-Step-1.5.

Variantes

ACE-Step 1.5 fournit trois points de contrôle DiT qui partagent la même architecture de transformateur mais diffèrent par leur comportement de guidage ; le pipeline détecte automatiquement les points de contrôle turbo à partir de la configuration du transformateur chargé et ignore le guidage CFG pour ces poids distillés par guidage.

Variante	CFG	Étapes par défaut	Valeur par défaut de `guidance_scale`	Défaut `shift`	Dépôt HF
`turbo` (guidance distillée)	off	8	ignoré	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 et SFT utilisent le null_condition_emb appris pour le guidage sans classifieur (APG, et non CFG classique). Les utilisateurs passent couramment num_inference_steps à 30–60 sur base/sft pour une meilleure qualité.

Astuces

Lors de la construction d'un prompt, gardez à l'esprit :

Les entrées de prompt descriptives fonctionnent le mieux ; utilisez des adjectifs pour décrire le style musical, les instruments, l’ambiance et le tempo.
Le prompt doit décrire les caractéristiques musicales générales (par exemple, « chanson pop entraînante avec guitare électrique et batterie »).
Les paroles doivent être structurées avec des balises telles que [verse], [chorus], [bridge], etc.

Pendant l'inférence :

num_inference_steps, guidance_scale et shift prennent par défaut les valeurs indiquées ci-dessus. Pour les points de contrôle turbo, guidance_scale > 1.0 est ignoré avec un avertissement car le guidage est distillé dans les poids.
Le paramètre audio_duration contrôle la durée de la musique générée, en secondes.
Le paramètre vocal_language doit correspondre à la langue des paroles.
pipe.sample_rate et pipe.latents_per_second sont issus de la configuration du VAE (48000 Hz et 25 ips pour les points de contrôle publiés).
Pour les tâches audio-vers-audio, passez src_audio et reference_audio sous forme de tenseurs stéréo prétraités à pipe.sample_rate.
flash et flash_hub utilisent la prise en charge native des fenêtres glissantes de FlashAttention pour l’auto-attention d’ACE-Step et s’attendent à des lots de texte non rembourrés. Si un lot de prompts contient du bourrage, utilisez plutôt flash_varlen ou flash_varlen_hub. L’inférence avec un seul prompt et padding="longest" est normalement non rembourrée.

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 )

Paramètres

vae (AutoencoderOobleck) — Modèle Variational Auto-Encoder (VAE) pour encoder et décoder des formes d’onde audio vers et depuis des représentations latentes.
text_encoder (AutoModel) — Modèle d’encodeur de texte (par ex. Qwen3-Embedding-0.6B) pour encoder les invites de texte et les paroles.
tokenizer (AutoTokenizer) — Tokeniseur pour l'encodeur de texte.
transformer (AceStepTransformer1DModel) — Le modèle Diffusion Transformer (DiT) pour le débruitage des latents audio.
condition_encoder (AceStepConditionEncoder) — Encodeur de condition qui combine les embeddings de texte, de paroles et de timbre pour l'attention croisée.
scheduler (FlowMatchEulerDiscreteScheduler) — Planificateur Euler de flow-matching. ACE-Step transmet les timesteps du DiT dans [0, 1], le planificateur est donc configuré avec num_train_timesteps=1 et shift=1.0 — le pipeline calcule lui-même son plan de sigma décalé / turbo et le transmet via set_timesteps(sigmas=...).

Pipeline pour la génération de musique à partir de texte utilisant ACE-Step 1.5.

Ce modèle hérite de DiffusionPipeline. Consultez la documentation de la classe parente pour les méthodes génériques implémentées pour tous les pipelines (téléchargement, sauvegarde, exécution sur un appareil particulier, etc.).

Le pipeline utilise le flow matching avec un calendrier de pas de temps personnalisé pour le processus de diffusion. La variante turbo du modèle utilise 8 étapes d'inférence par défaut.

Types de tâches pris en charge :

"text2music" : Générer de la musique à partir de prompts textuels et de paroles.
"cover" : générer de l’audio à partir d’un audio source / de codes sémantiques avec transfert de timbre depuis un audio de référence.
"repaint" : Régénérer une section d’audio existant tout en conservant le reste.
"extract" : Extraire une piste spécifique (par exemple, les voix, les percussions) de l’audio.
"lego" : Générer une piste spécifique en fonction du contexte audio.
"complete" : Compléter un audio d’entrée avec des pistes supplémentaires.

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

Paramètres

prompt (str ou List[str], facultatif) — Le prompt ou les prompts pour guider la génération musicale. Décrivent le style, le genre, les instruments, etc.
lyrics (str ou List[str], facultatif, par défaut "") — Le texte des paroles de la musique. Prend en charge les paroles structurées avec des balises telles que [verse], [chorus], etc.
audio_duration (float, facultatif, valeur par défaut 60.0) — Durée de l'audio généré, en secondes.
vocal_language (str ou List[str], facultatif, par défaut "en") — Code de langue pour les paroles (par ex. "en", "zh", "ja").
num_inference_steps (int, facultatif, valeur par défaut 8) — Le nombre d'étapes de débruitage. Le modèle turbo est conçu pour 8 étapes.
guidance_scale (float, facultatif, valeur par défaut 7.0) — Échelle de guidage pour le guidage sans classifieur. Une valeur de 1.0 désactive le CFG.
shift (float, facultatif, valeur par défaut 3.0) — Paramètre de décalage pour l’ordonnancement des pas de temps (1.0, 2.0 ou 3.0).
generator (torch.Generator ou List[torch.Generator], facultatif) — Un générateur pour rendre la génération déterministe.
latents (torch.Tensor, facultatif) — Latents de bruit pré-générés de forme (batch_size, latent_length, acoustic_dim).
output_type (str, facultatif, par défaut "pt") — Format de sortie. "pt" pour un tenseur PyTorch, "np" pour un tableau NumPy, "latent" pour des latents bruts.
return_dict (bool, facultatif, par défaut True) — Indique s'il faut retourner un AudioPipelineOutput ou un simple tuple.
callback (Callable, facultatif) — Une fonction appelée toutes les callback_steps étapes avec (step, timestep, latents).
callback_steps (int, facultatif, valeur par défaut 1) — Fréquence de la fonction de rappel.
callback_on_step_end (Callable, facultatif) — Une fonction appelée à la fin de chaque étape de débruitage pendant l'inférence. La fonction est appelée avec les arguments suivants : callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs contiendra une liste de tous les tenseurs spécifiés par callback_on_step_end_tensor_inputs.
callback_on_step_end_tensor_inputs (List, facultatif) — La liste des entrées tensorielles pour la fonction callback_on_step_end. Les tenseurs spécifiés dans la liste seront passés en tant qu'argument callback_kwargs. Vous ne pourrez inclure que les variables listées dans l'attribut ._callback_tensor_inputs de votre classe de pipeline.
instruction (str, facultatif) — Texte d'instruction personnalisé pour la tâche de génération. S'il n'est pas fourni, il est généré automatiquement en fonction de task_type.
max_text_length (int, facultatif, valeur par défaut 256) — Longueur maximale en jetons pour l'encodage du prompt texte.
max_lyric_length (int, facultatif, valeur par défaut 2048) — Longueur maximale en jetons pour l'encodage des paroles.
bpm (int, facultatif) — BPM (battements par minute) pour les métadonnées musicales. Si None, le modèle l’estime.
keyscale (str, facultatif) — Tonalité musicale (par ex. "C major", "A minor"). Si None, le modèle l'estime.
timesignature (str, facultatif) — Signature rythmique (par ex. "4" pour 4/4, "3" pour 3/4). Si None, le modèle l'estime.
task_type (str, facultatif, par défaut "text2music") — Le type de tâche de génération. L’un des "text2music", "cover", "repaint", "extract", "lego", "complete".
track_name (str, facultatif) — Nom de la piste pour les tâches "extract" ou "lego" (par exemple, "vocals", "drums").
complete_track_classes (List[str], facultatif) — Classes de suivi pour la tâche "complete".
src_audio (torch.Tensor, facultatif) — Tenseur audio source de forme [channels, samples] à 48 kHz pour les tâches audio-vers-audio (repaint, lego, cover, extract, complete). L’audio est encodé via le VAE pour produire les latents source.
reference_audio (torch.Tensor, facultatif) — Tenseur audio de référence de forme [channels, samples] à 48 kHz pour le conditionnement du timbre. Utilisé pour extraire les caractéristiques de timbre en vue du transfert de style.
audio_codes (str ou List[str], facultatif) — Chaînes de codes sémantiques audio (par ex. "<|audio_code_123|><|audio_code_456|>..."). Si fournies, la tâche est automatiquement basculée en mode "cover" et les modules de tokeniseur / détokeniseur audio ACE-Step enregistrés décodent les codes 5 Hz en conditionnement acoustique 25 Hz.
repainting_start (float, facultatif) — Temps de début en secondes pour la zone de repeint (pour les tâches "repaint" et "lego").
repainting_end (float, facultatif) — Temps de fin en secondes pour la zone de repeinture. Utilisez -1 ou None pour jusqu'à la fin.
audio_cover_strength (float, facultatif, valeur par défaut 1.0) — Intensité du mélange de la couverture audio (de 0.0 à 1.0). Si la valeur est < 1.0, les sorties conditionnées par la couverture et les sorties conditionnées uniquement par le texte sont mélangées. Des valeurs plus faibles produisent un effet de transfert de style plus prononcé.
cfg_interval_start (float, facultatif, valeur par défaut 0.0) — Ratio de début (0.0-1.0) de l'intervalle des pas de temps où le CFG est appliqué.
cfg_interval_end (float, facultatif, valeur par défaut 1.0) — Ratio de fin (0.0-1.0) de l'intervalle de pas de temps où le CFG est appliqué.
timesteps (List[float], facultatif) — Planification personnalisée des pas de temps. Si fourni, remplace num_inference_steps et shift.
attention_kwargs (dict, facultatif) — Dictionnaire de kwargs transmis à l'AttentionProcessor. Utilisé pour passer l'échelle LoRA via {"scale": float}.

Retourne

AudioPipelineOutput ou tuple

Si return_dict est True, un AudioPipelineOutput est renvoyé, sinon un tuple contenant l'audio généré.

La fonction d'appel du pipeline pour la génération musicale.

Exemples :

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

Valider les arguments destinés à l'utilisateur avant de commencer à allouer les tenseurs de bruit.

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 )

Paramètres

prompt (str ou List[str]) — Légende(s) textuelle(s) décrivant la musique.
lyrics (str ou List[str]) — Texte(s) de la (des) paroles.
device (torch.device) — Appareil pour les tenseurs.
vocal_language (str ou List[str], facultatif, par défaut "en") — Code(s) de langue pour les paroles.
audio_duration (float, facultatif, valeur par défaut 60.0) — Durée de l’audio en secondes.
instruction (str, optional) — Instruction text for generation.
bpm (int, facultatif) — BPM (battements par minute) pour les métadonnées.
keyscale (str, facultatif) — Tonalité musicale (par exemple, "C major").
timesignature (str, facultatif) — Signature rythmique (par exemple, "4" pour 4/4).
max_text_length (int, facultatif, par défaut 256) — Longueur maximale en jetons pour les invites de texte.
max_lyric_length (int, facultatif, valeur par défaut 2048) — Longueur maximale en jetons pour les paroles.

Encode les prompts de texte et les paroles en embeddings.

Les prompts de texte sont encodés via le modèle d'encodeur de texte complet pour produire des états cachés contextuels. Les paroles ne passent que par la couche d'incorporation de l'encodeur de texte (recherche de jetons), car l'encodeur de paroles dans l'encodeur de condition gère l'encodage contextuel.

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 )

Paramètres

batch_size (int) — Nombre d'échantillons à générer.
audio_duration (float) — Durée de l’audio en secondes.
dtype (torch.dtype) — Type de données des latents.
device (torch.device) — Appareil pour les latents.
generator (torch.Generator ou List[torch.Generator], facultatif) — Générateur(s) de nombres aléatoires.
latents (torch.Tensor, facultatif) — Latents pré-générés.

Préparez les latents de bruit initiaux pour le processus de flow matching.

prepare_reference_audio_latents

< source >

( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )

Paramètres

reference_audio (torch.Tensor) — Tenseur audio de référence de forme [channels, samples] à self.sample_rate.
batch_size (int) — Taille du lot.
device (torch.device) — Appareil cible.
dtype (torch.dtype) — dtype cible.

Traitez l'audio de référence en latents acoustiques pour l'encodeur de timbre.

L'audio de référence est répété/rogné à 30 secondes (3 segments de 10 secondes chacun, issus du début, du milieu et de la fin), encodé via le VAE, puis transposé pour l'encodeur 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' )

Paramètres

src_audio (torch.Tensor, facultatif) — Tenseur audio source de forme [channels, samples] à self.sample_rate.
audio_codes (str ou List[str], facultatif) — Chaînes de codes sémantiques audio.
latent_length (int, facultatif) — Longueur latente cible lorsqu’aucun audio source ni aucun code audio n’est fourni.
device (torch.device) — Appareil cible.
dtype (torch.dtype) — dtype cible.
batch_size (int) — Taille du lot.
task_type (str) — Type de tâche actuel.

Préparez les latents source pour les tâches de texte vers musique et d'audio vers audio.

Update on GitHub

Diffusers

ACE-Step 1.5

Variantes

Astuces

AceStepPipeline

classe diffusers.AceStepPipeline

__call__

check_inputs

encode_prompt

prepare_latents

prepare_reference_audio_latents

prepare_src_latents

call