Hugging Face's logo

Diffusers documentation

Stable Audio 3

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

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

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→