Hugging Face's logo

Diffusers documentation

ACE-Step 1.5

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ACE-Step 1.5

ACE-Step 1.5 был представлен в статье ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation командой ACE-Step (ACE Studio и StepFun). Это открытая фундаментальная модель для музыки, которая генерирует стерео-музыку коммерческого качества с текстом песни по текстовым запросам.

ACE-Step 1.5 генерирует стереозвук переменной длины (от 10 секунд до 10 минут) с частотой дискретизации 48 кГц по текстовым запросам и необязательным текстам песен. Полная система объединяет планировщик на основе языковой модели и синтезатор на основе диффузионного трансформера (DiT); данный конвейер инкапсулирует DiT-часть этого стека и состоит из трёх компонентов: VAE AutoencoderOobleck, сжимающего звуковые сигналы в стерео-латенты с частотой 25 Гц, текстового энкодера на базе Qwen3 для условного кодирования запросов и текстов песен, а также DiT AceStepTransformer1DModel, работающего в латентном пространстве VAE с использованием flow matching.

Модель поддерживает более 50 языков для текста песен — включая английский, китайский, японский, корейский, французский, немецкий, испанский, итальянский, португальский и русский — и работает на потребительских GPU (менее 4 ГБ VRAM при offload).

Этот конвейер был предоставлен командой ACE-Step Team. Исходная кодовая база доступна по адресу ace-step/ACE-Step-1.5.

Варианты

ACE-Step 1.5 включает три контрольные точки DiT, которые используют одну и ту же архитектуру трансформера, но различаются поведением при управлении (guidance); конвейер автоматически определяет турбо-контрольные точки по конфигурации загруженного трансформера и игнорирует управление CFG для этих весов, дистиллированных по управлению.

ВариантCFGШаги по умолчаниюЗначение guidance_scale по умолчаниюПо умолчанию shiftРепозиторий HF
turbo (с дистиллированным guidance)off8ignored3.0ACE-Step/acestep-v15-xl-turbo-diffusers
baseвкл87.03.0ACE-Step/acestep-v15-base
sftвкл87.03.0ACE-Step/acestep-v15-sft

Base и SFT используют обученный null_condition_emb для classifier-free guidance (APG, а не обычный CFG). Пользователи часто переопределяют num_inference_steps в 30–60 для base/sft, чтобы повысить качество.

Советы

При составлении промпта помните:

  • Описательные входные промпты работают лучше всего; используйте прилагательные для описания стиля музыки, инструментов, настроения и темпа.
  • Промпт должен описывать общие музыкальные характеристики (например, «энергичная поп-песня с электрической гитарой и барабанами»).
  • Текст песни должен быть структурирован с помощью тегов, таких как [verse], [chorus], [bridge] и т. д.

Во время инференса:

  • num_inference_steps, guidance_scale и shift по умолчанию принимают значения, показанные выше. Для turbo-чекпоинтов guidance_scale > 1.0 игнорируется с предупреждением, поскольку guidance дистиллирован в веса.
  • Параметр audio_duration управляет длительностью генерируемой музыки в секундах.
  • Параметр vocal_language должен соответствовать языку текста песни.
  • pipe.sample_rate и pipe.latents_per_second берутся из конфигурации VAE (48000 Гц и 25 к/с для выпущенных контрольных точек).
  • Для задач аудио-в-аудио передавайте src_audio и reference_audio в виде предобработанных стереотензоров с частотой дискретизации pipe.sample_rate.
  • flash и flash_hub используют нативную поддержку скользящего окна в FlashAttention для self-attention в ACE-Step и ожидают текстовые батчи без padding. Если батч промптов содержит padding, используйте вместо них flash_varlen или flash_varlen_hub. Инференс с одним промптом при padding="longest" обычно выполняется без padding.
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

< >

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

Параметры

  • vae (AutoencoderOobleck) — модель вариационного автоэнкодера (VAE) для кодирования и декодирования аудиосигналов в латентные представления и обратно.
  • text_encoder (AutoModel) — Модель текстового кодировщика (например, Qwen3-Embedding-0.6B) для кодирования текстовых подсказок и текстов песен.
  • tokenizer (AutoTokenizer) — токенизатор для текстового энкодера.
  • transformer (AceStepTransformer1DModel) — Модель Diffusion Transformer (DiT) для шумоподавления аудиолатентов.
  • condition_encoder (AceStepConditionEncoder) — Кодер условий, объединяющий эмбеддинги текста, текста песни и тембра для кросс-внимания.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Euler-планировщик для flow-matching. ACE-Step передаёт шаги времени DiT в диапазоне [0, 1], поэтому планировщик настраивается с параметрами num_train_timesteps=1 и shift=1.0 — пайплайн самостоятельно вычисляет свой сдвинутый / turbo-расписание сигм и передаёт его через set_timesteps(sigmas=...).

Пайплайн для генерации музыки из текста с использованием ACE-Step 1.5.

Эта модель наследуется от DiffusionPipeline. Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.

Пайплайн использует flow matching с пользовательским расписанием шагов времени для процесса диффузии. Вариант модели turbo по умолчанию использует 8 шагов инференса.

Поддерживаемые типы задач:

  • "text2music": Генерация музыки по текстовым запросам и текстам песен.
  • "cover": Генерация аудио из исходного аудио / семантических кодов с переносом тембра из референсного аудио.
  • "repaint": Пересоздаёт часть существующего аудио, сохраняя остальное.
  • "extract": Извлечь конкретный трек (например, вокал или ударные) из аудио.
  • "lego": Генерация конкретного трека на основе аудиоконтекста.
  • "complete": Дополнить входной аудиодорожкой дополнительными треками.

__call__

< >

( 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

Параметры

  • prompt (str или List[str], необязательный) — Промпт или промпты для управления генерацией музыки. Описывает стиль, жанр, инструменты и т. д.
  • lyrics (str или List[str], необязательный, по умолчанию "") — Текст песни. Поддерживает структурированные тексты с тегами, такими как [verse], [chorus] и т. д.
  • audio_duration (float, необязательный, по умолчанию 60.0) — Длительность сгенерированного аудио в секундах.
  • vocal_language (str или List[str], необязательный, по умолчанию "en") — Код языка для текста песни (например, "en", "zh", "ja").
  • num_inference_steps (int, необязательный, по умолчанию 8) — Количество шагов денойзинга. Турбо-модель рассчитана на 8 шагов.
  • guidance_scale (float, необязательный, по умолчанию 7.0) — Масштаб руководства для classifier-free guidance. Значение 1.0 отключает CFG.
  • shift (float, необязательный, по умолчанию 3.0) — Параметр сдвига для расписания временных шагов (1.0, 2.0 или 3.0).
  • generator (torch.Generator или List[torch.Generator], необязательный) — Генератор для обеспечения детерминированности генерации.
  • latents (torch.Tensor, необязательный) — Предварительно сгенерированные шумовые латенты формы (batch_size, latent_length, acoustic_dim).
  • output_type (str, необязательный, по умолчанию "pt") — Формат вывода. "pt" для тензора PyTorch, "np" для массива NumPy, "latent" для необработанных латентов.
  • return_dict (bool, необязательный, по умолчанию True) — Определяет, возвращать ли AudioPipelineOutput или обычный кортеж.
  • callback (Callable, необязательный) — Функция, вызываемая каждые callback_steps шагов с аргументами (step, timestep, latents).
  • callback_steps (int, необязательный, по умолчанию 1) — Частота вызова функции обратного вызова.
  • callback_on_step_end (Callable, необязательный) — Функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs будет содержать список всех тензоров, указанных в callback_on_step_end_tensor_inputs.
  • callback_on_step_end_tensor_inputs (List, необязательный) — Список тензорных входных данных для функции callback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргумента callback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте ._callback_tensor_inputs вашего класса конвейера.
  • instruction (str, необязательный) — Пользовательский текст инструкции для задачи генерации. Если не указан, генерируется автоматически на основе task_type.
  • max_text_length (int, необязательный, по умолчанию 256) — Максимальная длина токенов для кодирования текстового промпта.
  • max_lyric_length (int, необязательный, по умолчанию 2048) — Максимальная длина токенов для кодирования текста песни.
  • bpm (int, необязательный) — BPM (ударов в минуту) для метаданных музыки. Если None, модель оценивает его автоматически.
  • keyscale (str, необязательный) — Музыкальная тональность (например, "C major", "A minor"). Если None, модель определяет её автоматически.
  • timesignature (str, необязательный) — Размер (например, "4" для 4/4, "3" для 3/4). Если None, модель оценивает его автоматически.
  • task_type (str, необязательный, по умолчанию "text2music") — Тип задачи генерации. Один из "text2music", "cover", "repaint", "extract", "lego", "complete".
  • track_name (str, необязательный) — Название дорожки для задач "extract" или "lego" (например, "vocals", "drums").
  • complete_track_classes (List[str], необязательный) — Классы треков для задачи "complete".
  • src_audio (torch.Tensor, необязательный) — Исходный аудиотензор формы [channels, samples] с частотой дискретизации 48 кГц для задач аудио-в-аудио (repaint, lego, cover, extract, complete). Аудио кодируется через VAE для получения исходных латентов.
  • reference_audio (torch.Tensor, необязательный) — Тензор опорного аудио с формой [channels, samples] при частоте дискретизации 48 кГц для настройки тембра. Используется для извлечения тембровых признаков при переносе стиля.
  • audio_codes (str или List[str], необязательный) — Строки семантических кодов аудио (например, "<|audio_code_123|><|audio_code_456|>..."). Если параметр указан, задача автоматически переключается в режим "cover", а зарегистрированные модули токенизатора / детокенизатора аудио ACE-Step декодируют коды с частотой 5 Гц в акустическое условие с частотой 25 Гц.
  • repainting_start (float, необязательный) — Начальное время в секундах для области перерисовки (для задач "repaint" и "lego").
  • repainting_end (float, необязательный) — Время окончания в секундах для области перерисовки. Используйте -1 или None для указания до конца.
  • audio_cover_strength (float, необязательный, по умолчанию 1.0) — Сила смешивания аудио-покрытия (от 0.0 до 1.0). При значении < 1.0 выполняется смешивание выходов, обусловленных покрытием, и выходов, обусловленных только текстом. Более низкие значения создают более выраженный эффект переноса стиля.
  • cfg_interval_start (float, необязательный, по умолчанию 0.0) — Начальная доля (0.0–1.0) диапазона временных шагов, в которой применяется CFG.
  • cfg_interval_end (float, необязательный, по умолчанию 1.0) — Конечное соотношение (0.0-1.0) диапазона временных шагов, в котором применяется CFG.
  • timesteps (List[float], необязательный) — Пользовательское расписание шагов. Если указано, переопределяет num_inference_steps и shift.
  • attention_kwargs (dict, необязательный) — Словарь kwargs, передаваемый в AttentionProcessor. Используется для передачи масштаба LoRA через {"scale": float}.

Возвращает

AudioPipelineOutput или tuple

Если return_dict равно True, возвращается AudioPipelineOutput, иначе — кортеж с сгенерированным аудио.

Функция вызова pipeline для генерации музыки.

Примеры:

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

< >

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

Проверяйте аргументы, предназначенные для пользователя, до начала выделения тензоров шума.

encode_prompt

< >

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

Параметры

  • prompt (str или List[str]) — Текстовые описания музыки.
  • lyrics (str или List[str]) — Текст(ы) песни.
  • device (torch.device) — Устройство для тензоров.
  • vocal_language (str или List[str], необязательный, по умолчанию "en") — Код(ы) языка для текста песни.
  • audio_duration (float, необязательный, по умолчанию 60.0) — Длительность аудио в секундах.
  • instruction (str, необязательный) — Текст инструкции для генерации.
  • bpm (int, необязательный) — BPM (ударов в минуту) для метаданных.
  • keyscale (str, необязательный) — Музыкальная тональность (например, "C major").
  • timesignature (str, необязательный) — Размер (например, "4" для 4/4).
  • max_text_length (int, необязательный, по умолчанию 256) — Максимальная длина токенов для текстовых подсказок.
  • max_lyric_length (int, необязательный, по умолчанию 2048) — Максимальная длина токенов для текста песни.

Кодируйте текстовые подсказки и тексты песен в эмбеддинги.

Текстовые промпты кодируются с помощью полной модели текстового энкодера для получения контекстных скрытых состояний. Текст песни проходит только через слой эмбеддингов текстового энкодера (поиск токенов), поскольку контекстное кодирование обрабатывается энкодером текста песни в условном энкодере.

prepare_latents

< >

( batch_size: intaudio_duration: floatdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = None )

Параметры

  • batch_size (int) — Количество генерируемых образцов.
  • audio_duration (float) — Длительность аудио в секундах.
  • dtype (torch.dtype) — Тип данных для латентов.
  • device (torch.device) — Устройство для латентов.
  • generator (torch.Generator или List[torch.Generator], необязательный) — Генератор(ы) случайных чисел.
  • latents (torch.Tensor, необязательный) — Предварительно сгенерированные латенты.

Подготовьте начальные шумовые латенты для процесса flow matching.

prepare_reference_audio_latents

< >

( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )

Параметры

  • reference_audio (torch.Tensor) — тензор опорного аудио с формой [channels, samples] при частоте дискретизации self.sample_rate.
  • batch_size (int) — Размер батча.
  • device (torch.device) — Целевое устройство.
  • dtype (torch.dtype) — Целевой dtype.

Обработайте эталонный аудиосигнал в акустические латенты для энкодера тембра.

Справочный аудиосигнал повторяется/обрезается до 30 секунд (3 сегмента по 10 секунд каждый из начала, середины и конца), кодируется через VAE, а затем транспонируется для энкодера тембра.

prepare_src_latents

< >

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

Параметры

  • src_audio (torch.Tensor, необязательный) — исходный аудиотензор формы [channels, samples] с частотой дискретизации self.sample_rate.
  • audio_codes (str или List[str], необязательный) — Строки семантических кодов аудио.
  • latent_length (int, необязательный) — Целевая длина латентного представления, если не заданы исходный аудиосигнал или аудиокоды.
  • device (torch.device) — Целевое устройство.
  • dtype (torch.dtype) — Целевой dtype.
  • batch_size (int) — Размер батча.
  • task_type (str) — Текущий тип задачи.

Подготовьте исходные латенты для задач генерации музыки по тексту и преобразования аудио в аудио.

Update on GitHub

←AutoPipeline AudioLDM 2→