Hugging Face's logo

Diffusers documentation

Stable Audio 3

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Stable Audio 3

Stable Audio 3 (SA3) — это модель text-to-audio от Stability AI, которая генерирует стереозвук высокого качества с частотой дискретизации 44,1 кГц. Она использует rectified-flow DiT, обусловленный двумя сигналами:

  • Text — кодируется замороженным энкодером T5Gemma и вводится через кросс-внимание.
  • Duration — число с плавающей точкой (в секундах), встроенное с помощью StableAudio3DurationEmbedder и используемое в качестве глобального вектора условий для адаптивной нормализации слоёв.

Аудио декодируется автоэнкодером SAME (Semantically-Aligned Music Encoder), AutoencoderSAME.

Оба контрольных пункта используют FlowMatchEulerDiscreteScheduler с логарифмически-нормальным распределением сигм по SNR, различаясь только параметром stochastic_sampling и количеством шагов по умолчанию:

Чекпоинтdiffusion_objectivestochastic_samplingnum_inference_steps
stable-audio-3-medium-baserectified_flowFalse (детерминированный Эйлер)100 (не дистиллированные)
stable-audio-3-medium (дистиллированный)rf_denoiserTrue (повторный шум в режиме «пинг-понг»)8 (дистилляция за 8 шагов)

Правильная конфигурация планировщика встроена в каждый преобразованный чекпоинт, поэтому num_inference_steps по умолчанию принимает правильное значение, если вы не задаёте его явно. Передавайте этот параметр только для переопределения.

Исходная кодовая база: Stability-AI/stable-audio-3.

Конвертация исходных контрольных точек

Чекпоинты Stability AI не публикуются в формате diffusers, поэтому конвертируйте их локально. Скрипт загружает model_config.json чекпоинта и выбирает планировщик на основе его diffusion_objective:

python scripts/convert_stable_audio_3_to_diffusers.py \
  --checkpoint_path stabilityai/stable-audio-3-medium-base \
  --text_encoder_repo google/t5gemma-b-b-ul2 \
  --output_dir /tmp/sa3-diffusers-euler \
  --dtype float32

stable-audio-3-medium-base — это закрытый репозиторий. Перед конвертацией выполните hf auth login с аккаунтом, имеющим доступ, иначе загрузка завершится ошибкой 401.

Пример использования

Загрузите преобразованный контрольный пункт из его локального выходного каталога (установите soundfile с помощью pip install soundfile):

import torch
import soundfile as sf
from diffusers import StableAudio3Pipeline

pipe = StableAudio3Pipeline.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

generator = torch.Generator("cuda").manual_seed(0)
audio = pipe(
    "A gentle piano melody with soft strings in a concert hall",
    duration=10.0,  # seconds; latent length is computed automatically
    generator=generator,
).audios

sf.write("sa3_output.wav", audio[0].T.cpu().float().numpy(), samplerate=44100)

Пайплайн также зарегистрирован в AutoPipelineForText2Audio, который автоматически определяет контрольную точку как StableAudio3Pipeline:

from diffusers import AutoPipelineForText2Audio

pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)

В примерах используется локальный путь, так как stabilityai/stable-audio-3-medium и stable-audio-3-medium-base ещё не опубликованы в формате diffusers (загрузка по repo id возвращает ошибку 404). После публикации repo id можно использовать вместо локального пути.

Советы

  • Используйте torch.float32 на CPU или MPS (Apple Silicon) — torch.float16 на MPS приводит к появлению шума.
  • Дистиллированная модель (stable-audio-3-medium) получена методом адверсариальной дистилляции — guidance встроен в веса. Оставьте guidance_scale=1.0 (значение по умолчанию) и не передавайте negative_prompt для этого чекпоинта; оба параметра имеют смысл только для недистиллированного чекпоинта stable-audio-3-medium-base.
  • silence_padding_duration (по умолчанию 0.0) добавляет тишину в конце латентной последовательности. Оставьте значение 0.0, если модель не обучена маскировать эту заполняющую область — иначе дополнительные кадры снизят энергию вывода, и результат станет тише.
  • Установите num_waveforms_per_prompt > 1, чтобы генерировать несколько клипов на один промпт.

StableAudio3Pipeline

класс diffusers.StableAudio3Pipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Параметры

  • vae ([AutoencoderSAME]) — автоэнкодер SAME, используемый для кодирования и декодирования аудиолатентов.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Замороженный текстовый энкодер T5Gemma (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Токенизатор для текстового энкодера.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Преобразует duration в секунды в глобальный вектор условий для AdaLN в каждом блоке DiT.
  • transformer ([StableAudio3DiTModel]) — DiT для предсказания скорости в rectified-flow.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — планировщик для итеративного цикла удаления шума. Продакшн-чекпоинт (дистиллированный) SA3 Medium использует stochastic_sampling=True ровно для 8 шагов ping-pong; недистиллированный базовый чекпоинт использует stochastic_sampling=False для ~100 детерминированных шагов Эйлера.

Пайплайн для генерации аудио из текста с использованием Stable Audio 3.

SA3 использует дистиллированный rectified-flow DiT с ping-pong sampling. Classifier-free guidance (guidance_scale / negative_prompt) не требуется для дистиллированной контрольной точки (оставьте guidance_scale=1.0, значение по умолчанию), но имеет значение для недистиллированной контрольной точки stable-audio-3-medium-base.

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

__call__

< >

( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0guidance_scale: float = 1.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_encoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' ) → [~pipelines.AudioPipelineOutput] or tuple

Параметры

  • prompt (str или list[str], необязательный) — Текст промпта(ов). Передайте prompt_embeds вместо него, чтобы пропустить токенизацию и кодирование.
  • duration (float, по умолчанию 10.0) — Запрашиваемая длительность вывода в секундах.
  • num_inference_steps (int, optional) — Количество шагов денойзинга. Если None (по умолчанию), количество шагов выбирается из конфигурации stochastic_sampling планировщика: 8, если True (дистиллированная контрольная точка в стиле ping-pong), и 100 при False (базовая недистиллированная контрольная точка). Передайте явное значение для переопределения.
  • logsnr_min (float, по умолчанию -6.2) — Минимальное значение log-SNR для расписания шума — соответствует началу расписания с высоким уровнем шума.
  • logsnr_max (float, по умолчанию 2.0) — Максимальное значение log-SNR для расписания шума — соответствует концу расписания с низким уровнем шума.
  • silence_padding_duration (float, по умолчанию 0.0) — Дополнительные секунды латентного контекста, генерируемые сверх целевого контента, чтобы дать модели запас на границе; выходной сигнал затем обрезается до duration. По умолчанию 0.0 (отключено). Увеличивайте значение только если модель обучена/дистиллирована для маскирования этой отсечки — иначе дополнительные кадры будут поглощать энергию выходного сигнала.
  • guidance_scale (float, по умолчанию 1.0) — Масштаб классификаторного свободного руководства (classifier-free guidance). Значение 1.0 отключает руководство (это значение по умолчанию и единственное разумное для дистиллированной контрольной точки SA3 Medium, в весах которой CFG уже «запечено»). Значения > 1.0 имеют смысл для недистиллированной контрольной точки stable-audio-3-medium-base; более высокие значения приводят к более точному следованию промпту ценой снижения разнообразия.
  • negative_prompt (str или list[str], optional) — Промпт(ы), описывающие, от чего следует отклоняться, когда guidance_scale > 1.0. По умолчанию — пустая строка (безусловная генерация), если guidance_scale > 1.0 и не заданы ни этот параметр, ни negative_prompt_embeds. Игнорируется, когда guidance_scale <= 1.0.
  • num_waveforms_per_prompt (int, по умолчанию 1) — Количество волновых форм, генерируемых на один промпт.
  • generator (torch.Generator или list[torch.Generator], необязательный) — Для детерминированной генерации и воспроизводимого повторного добавления шума в цикле ping-pong.
  • latents (torch.Tensor, optional) — Предварительно сгенерированные начальные латенты. Если None, извлекается новый гауссов тензор.
  • prompt_embeds (torch.Tensor, optional) — Предварительно вычисленные текстовые эмбеддинги (batch, seq_len, 768).
  • encoder_attention_mask (torch.LongTensor, optional) — Булева маска для предварительно вычисленных эмбеддингов.
  • negative_prompt_embeds (torch.Tensor, optional) — Предварительно вычисленные эмбеддинги отрицательного текста, как альтернатива negative_prompt.
  • negative_encoder_attention_mask (torch.LongTensor, optional) — Булева маска для предварительно вычисленных отрицательных эмбеддингов.
  • return_dict (bool, по умолчанию True) — Возвращает AudioPipelineOutput или обычный кортеж.
  • callback_on_step_end (Callable, optional) — Вызывается в конце каждого шага денойзинга с аргументами (self, step_idx, timestep, callback_kwargs), где callback_kwargs содержит тензоры, перечисленные в callback_on_step_end_tensor_inputs. Должен возвращать словарь с (возможно, изменёнными) тензорами для использования в остальной части цикла.
  • callback_on_step_end_tensor_inputs (list[str], по умолчанию [“latents”]) — Тензоры, передаваемые в callback_on_step_end. Должны быть подмножеством self._callback_tensor_inputs.
  • output_type (str, по умолчанию "pt") — "pt" для тензора PyTorch, "np" для массива NumPy или "latent", чтобы пропустить декодирование и вернуть сырые латенты.

Возвращает

[~pipelines.AudioPipelineOutput] или tuple

.audios — это тензор / массив формы (batch * num_waveforms_per_prompt, audio_channels, samples).

Генерация аудио по текстовому запросу.

Примеры:

>>> import torch
>>> import soundfile as sf
>>> from diffusers import StableAudio3Pipeline

>>> pipe = StableAudio3Pipeline.from_pretrained("stabilityai/stable-audio-3-medium", torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)

encode_duration

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Параметры

  • duration — Длительность в секундах, применяемая к каждому образцу в батче.
  • device — Целевое устройство.
  • num_waveforms_per_prompt — Множитель тайлинга.
  • batch_size — Количество промптов.

Встраивайте значение длительности в глобальный вектор условий.

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )

Параметры

  • prompt — Текстовый промпт или список промптов. Игнорируется, если prompt_embeds предоставлен.
  • device — Целевое устройство.
  • num_waveforms_per_prompt — количество выходных волновых форм, генерируемых на один запрос; тензоры условий дублируются соответственно.
  • prompt_embeds — Предварительно вычисленные текстовые эмбеддинги (batch, seq_len, hidden_size).
  • encoder_attention_mask — булева маска (batch, seq_len) для предвычисленных эмбеддингов; 1 = реальный токен, 0 = заполнитель.

Кодирует текстовые промпты в тензоры для кросс-внимания.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Сформируйте контекст кросс-внимания, добавив эмбеддинг длительности в качестве дополнительного токена.

SA3 routes the seconds_total conditioner to both the global (AdaLN) input and the cross-attention context (cross_attention_cond_ids = ["prompt", "seconds_total"]). The duration embedding is concatenated after the text tokens, and the attention mask is extended with one valid entry.

StableAudio3InpaintPipeline

класс diffusers.StableAudio3InpaintPipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Параметры

  • vae ([AutoencoderSAME]) — автоэнкодер SAME, используемый для кодирования и декодирования аудиолатентов.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Замороженный текстовый энкодер T5Gemma (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Токенизатор для текстового энкодера.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Преобразует duration в секунды в глобальный вектор условий для AdaLN в каждом блоке DiT.
  • transformer ([StableAudio3DiTModel]) — DiT для предсказания скорости в rectified-flow.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — планировщик для итеративного цикла удаления шума. Продакшн-чекпоинт (дистиллированный) SA3 Medium использует stochastic_sampling=True ровно для 8 шагов ping-pong; недистиллированный базовый чекпоинт использует stochastic_sampling=False для ~100 детерминированных шагов Эйлера.

Конвейер для восстановления аудио в Stable Audio 3.

Shares its text-to-audio logic with [StableAudio3Pipeline] (kept in sync via # Copied from). When audio and mask are provided, encodes the reference audio with the frozen SAME encoder and injects masked_latent ∥ mask as local-additive conditioning into each DiT block via the transformer’s local_add_cond pathway (to_local_embed).

Расширение сигнатуры вызова (см. __call__): audio (torch.Tensor формы (batch, channels, samples)): Справочная аудиоволна с частотой дискретизации vae.config.sampling_rate Гц. mask (torch.Tensor формы (batch, 1, latent_length)): Двоичная маска для каждого кадра в латентном пространстве. 1 = сохранить исходный звук; 0 = область для инпейнтинга.

__call__

< >

( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Nonemask: typing.Optional[torch.Tensor] = Nonemask_start_seconds: typing.Union[float, typing.List[float], NoneType] = Nonemask_end_seconds: typing.Union[float, typing.List[float], NoneType] = Nonenum_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )

Параметры

  • prompt (str или list[str], необязательный) — Текст промпта(ов).
  • duration (float, по умолчанию 10.0) — Длительность вывода в секундах. Должна соответствовать эталонному аудио.
  • audio (torch.Tensor, optional) — Справочная волна (batch, channels, samples) с частотой дискретизации vae.config.sampling_rate Гц. Обязательна для inpainting.
  • mask (torch.Tensor, optional) — Маска в латентном пространстве для каждого кадра (batch, 1, L), где 0 = область для инпейнта, 1 = сохранить. Необходимо указать либо mask, либо mask_start_seconds / mask_end_seconds.
  • mask_start_seconds (float или list[float], необязательный) — Начальное время (в секундах) области инпейнта.
  • mask_end_seconds (float или list[float], необязательный) — Время окончания области inpaint (должно соответствовать mask_start_seconds).
  • num_inference_steps (int, optional) — Количество шагов денойзинга. Если None (по умолчанию), количество шагов выбирается из конфигурации stochastic_sampling планировщика, как в [StableAudio3Pipeline].
  • logsnr_min (float, по умолчанию -6.2) — Минимальное значение log-SNR для расписания шума — соответствует началу расписания с высоким уровнем шума.
  • logsnr_max (float, по умолчанию 2.0) — Максимальное значение log-SNR для расписания шума — соответствует концу расписания с низким уровнем шума.
  • silence_padding_duration (float, по умолчанию 0.0) — Дополнительное время тишины после целевого контента.
  • num_waveforms_per_prompt (int, по умолчанию 1) — Количество волновых форм на промпт.
  • generator — генератор случайных чисел для воспроизводимости.
  • latents — Предварительно сгенерированный начальный шум (None → сгенерировать новый).
  • prompt_embeds — Предварительно вычисленные текстовые эмбеддинги.
  • encoder_attention_mask — Маска для предварительно вычисленных эмбеддингов.
  • return_dict (bool, по умолчанию True) — Возвращает AudioPipelineOutput или кортеж.
  • callback_on_step_end (Callable, optional) — Вызывается в конце каждого шага денойзинга с аргументами (self, step_idx, timestep, callback_kwargs). Должен возвращать словарь с (опционально изменёнными) тензорами для использования в остальной части цикла.
  • callback_on_step_end_tensor_inputs (list[str], по умолчанию [“latents”]) — Тензоры, передаваемые в callback_on_step_end. Должны быть подмножеством self._callback_tensor_inputs.
  • output_type (str, по умолчанию "pt") — "pt" / "np" / "latent".

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

Примеры:

>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3InpaintPipeline

>>> pipe = StableAudio3InpaintPipeline.from_pretrained(
...     "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")

>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     audio=audio,
...     mask_start_seconds=4.0,
...     mask_end_seconds=6.0,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)

encode_duration

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Параметры

  • duration — Длительность в секундах, применяемая к каждому образцу в батче.
  • device — Целевое устройство.
  • num_waveforms_per_prompt — Множитель тайлинга.
  • batch_size — Количество промптов.

Встраивайте значение длительности в глобальный вектор условий.

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )

Параметры

  • prompt — Текстовый промпт или список промптов. Игнорируется, если prompt_embeds предоставлен.
  • device — Целевое устройство.
  • num_waveforms_per_prompt — количество выходных волновых форм, генерируемых на один запрос; тензоры условий дублируются соответственно.
  • prompt_embeds — Предварительно вычисленные текстовые эмбеддинги (batch, seq_len, hidden_size).
  • encoder_attention_mask — булева маска (batch, seq_len) для предвычисленных эмбеддингов; 1 = реальный токен, 0 = заполнитель.

Кодирует текстовые промпты в тензоры для кросс-внимания.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Сформируйте контекст кросс-внимания, добавив эмбеддинг длительности в качестве дополнительного токена.

SA3 routes the seconds_total conditioner to both the global (AdaLN) input and the cross-attention context (cross_attention_cond_ids = ["prompt", "seconds_total"]). The duration embedding is concatenated after the text tokens, and the attention mask is extended with one valid entry.

StableAudio3AudioToAudioPipeline

Генерирует вариацию референсного аудиоклипа: весь референс шумится до init_noise_level и затем денуизится, в отличие от пофреймового локально-аддитивного conditioning в StableAudio3InpaintPipeline, который сохраняет конкретные кадры точно.

класс diffusers.StableAudio3AudioToAudioPipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Параметры

  • vae ([AutoencoderSAME]) — автоэнкодер SAME, используемый для кодирования и декодирования аудиолатентов.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Замороженный текстовый энкодер T5Gemma (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Токенизатор для текстового энкодера.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Преобразует duration в секунды в глобальный вектор условий для AdaLN в каждом блоке DiT.
  • transformer ([StableAudio3DiTModel]) — DiT для предсказания скорости в rectified-flow.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — планировщик для итеративного цикла удаления шума. Продакшн-чекпоинт (дистиллированный) SA3 Medium использует stochastic_sampling=True ровно для 8 шагов ping-pong; недистиллированный базовый чекпоинт использует stochastic_sampling=False для ~100 детерминированных шагов Эйлера.

Конвейер вариаций аудио-в-аудио для Stable Audio 3.

Использует ту же логику генерации аудио из текста, что и [StableAudio3Pipeline] (синхронизация поддерживается через # Copied from). Кодирование эталонного аудио выполняется с помощью замороженного энкодера SAME, после чего оно смешивается с новым шумом в соответствии с init_noise_level, и далее выполняется денуазинг — весь сигнал подвергается шумлению/денуазингу глобально, в отличие от пофреймового локально-аддитивного обусловливания в [StableAudio3InpaintPipeline].

Расширение сигнатуры вызова (см. __call__): audio (torch.Tensor формы (batch, channels, samples)): Справочная аудиоволна с частотой дискретизации vae.config.sampling_rate Гц. init_noise_level (float): Количество шума, добавляемого к справочному сигналу перед шумоподавлением. 1.0 = полный шум (эквивалентно генерации аудио из текста); меньшие значения сохраняют больше исходного сигнала.

__call__

< >

( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Noneinit_noise_level: float = 1.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )

Параметры

  • prompt (str или list[str], необязательный) — Текст промпта(ов).
  • duration (float, по умолчанию 10.0) — Длительность вывода в секундах. Должна соответствовать эталонному аудио.
  • audio (torch.Tensor, optional) — Справочная волна (batch, channels, samples) с частотой дискретизации vae.config.sampling_rate Гц. Обязательный параметр.
  • init_noise_level (float, по умолчанию 1.0) — Уровень шума (в диапазоне (0, 1]), смешиваемый со ссылкой перед денойзингом: x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise. Значение 1.0 полностью отбрасывает ссылку (эквивалентно [StableAudio3Pipeline]); меньшие значения сохраняют всё больше структуры ссылки, при этом выполняется полное количество шагов.
  • num_inference_steps (int, optional) — Количество шагов денойзинга. Если None (по умолчанию), количество шагов выбирается из конфигурации stochastic_sampling планировщика, как в [StableAudio3Pipeline].
  • logsnr_min (float, по умолчанию -6.2) — Минимальное значение log-SNR для расписания шума — соответствует началу расписания с высоким уровнем шума.
  • logsnr_max (float, по умолчанию 2.0) — Максимальное значение log-SNR для расписания шума — соответствует концу расписания с низким уровнем шума.
  • silence_padding_duration (float, по умолчанию 0.0) — Дополнительное время тишины после целевого контента.
  • num_waveforms_per_prompt (int, по умолчанию 1) — Количество волновых форм на промпт.
  • generator — генератор случайных чисел для воспроизводимости.
  • latents — Предварительно сгенерированный начальный шум (None → сгенерировать новый).
  • prompt_embeds — Предварительно вычисленные текстовые эмбеддинги.
  • encoder_attention_mask — Маска для предварительно вычисленных эмбеддингов.
  • return_dict (bool, по умолчанию True) — Возвращает AudioPipelineOutput или кортеж.
  • callback_on_step_end (Callable, optional) — Вызывается в конце каждого шага денойзинга с аргументами (self, step_idx, timestep, callback_kwargs). Должен возвращать словарь с (опционально изменёнными) тензорами для использования в остальной части цикла.
  • callback_on_step_end_tensor_inputs (list[str], по умолчанию [“latents”]) — Тензоры, передаваемые в callback_on_step_end. Должны быть подмножеством self._callback_tensor_inputs.
  • output_type (str, по умолчанию "pt") — "pt" / "np" / "latent".

Сгенерируйте вариацию аудио, обусловленную текстовым запросом и эталонной волной.

Примеры:

>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3AudioToAudioPipeline

>>> pipe = StableAudio3AudioToAudioPipeline.from_pretrained(
...     "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")

>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     audio=audio,
...     init_noise_level=0.6,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)

encode_duration

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Параметры

  • duration — Длительность в секундах, применяемая к каждому образцу в батче.
  • device — Целевое устройство.
  • num_waveforms_per_prompt — Множитель тайлинга.
  • batch_size — Количество промптов.

Встраивайте значение длительности в глобальный вектор условий.

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )

Параметры

  • prompt — Текстовый промпт или список промптов. Игнорируется, если prompt_embeds предоставлен.
  • device — Целевое устройство.
  • num_waveforms_per_prompt — количество выходных волновых форм, генерируемых на один запрос; тензоры условий дублируются соответственно.
  • prompt_embeds — Предварительно вычисленные текстовые эмбеддинги (batch, seq_len, hidden_size).
  • encoder_attention_mask — булева маска (batch, seq_len) для предвычисленных эмбеддингов; 1 = реальный токен, 0 = заполнитель.

Кодирует текстовые промпты в тензоры для кросс-внимания.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Сформируйте контекст кросс-внимания, добавив эмбеддинг длительности в качестве дополнительного токена.

SA3 направляет conditioner seconds_total в оба глобальный вход (AdaLN) и контекст кросс-внимания (cross_attention_cond_ids = ["prompt", "seconds_total"]). Встраивание длительности конкатенируется после текстовых токенов, а маска внимания расширяется на одну валидную запись.

StableAudio3DurationEmbedder

класс diffusers.StableAudio3DurationEmbedder

< >

( output_dim: int = 768fourier_dim: int = 256min_val: float = 0.0max_val: float = 384.0min_freq: float = 0.5max_freq: float = 10000.0 )

Параметры

  • output_dim (int, по умолчанию 768) — Размерность выходного эмбеддинга. Должна совпадать с global_cond_dim DiT.
  • fourier_dim (int, по умолчанию 256) — Внутреннее размерность фурье-признаков (должно быть чётным).
  • min_val (float, по умолчанию 0.0) — Минимальное значение длительности для нормализации с ограничением.
  • max_val (float, по умолчанию 384.0) — Максимальное значение длительности для ограничения при нормализации. Значения выше этого ограничиваются. 384 секунды — это верхняя граница для production SA3 Medium для кондиционера seconds_total.
  • min_freq (float, по умолчанию 0.5) — Минимальная частота для экспоненциального базиса Фурье.
  • max_freq (float, по умолчанию 10000.0) — Максимальная частота для экспоненциального базиса Фурье.

Встраивает значение длительности (в секундах) в глобальный вектор условий для Stable Audio 3 DiT (используется как вход global_hidden_states для AdaLN).

Воспроизводит NumberConditioner(fourier_features_type="expo") из эталонной реализации SA3.

forward

< >

( seconds: Tensor )

Параметры

  • seconds (torch.Tensor формы (batch,)) — Значения длительности в секундах.
Update on GitHub

←Stable Audio Anima→