# Stable Audio 3 Stable Audio 3 (SA3) — это модель text-to-audio от [Stability AI](https://stability.ai/), которая генерирует высококачественный стереозвук с частотой 44,1 кГц. Она использует rectified-flow DiT, обусловленный двумя сигналами: * **Text** — кодируется замороженным энкодером T5Gemma и вводится через кросс-внимание. * **Duration** — число с плавающей точкой (в секундах), встроенное с помощью [StableAudio3DurationEmbedder](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder) и используемое в качестве глобального вектора условий для адаптивной нормализации слоёв. Аудио декодируется автоэнкодером SAME (Semantically-Aligned Music Encoder), [AutoencoderSAME](/docs/diffusers/v0.43.0/ru/api/models/autoencoder_same#diffusers.AutoencoderSAME). Оба контрольных пункта используют [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ru/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) с логарифмически-нормальным распределением сигм по SNR, различаясь только параметром `stochastic_sampling` и количеством шагов по умолчанию: | Чекпоинт | `diffusion_objective` | `stochastic_sampling` | `num_inference_steps` | |---|---|---|---| | `stable-audio-3-medium-base` | `rectified_flow` | `False` (детерминированный Эйлер) | **100** (не дистиллированные) | | `stable-audio-3-medium` (дистиллированный) | `rf_denoiser` | `True` (повторный шум в режиме «пинг-понг») | **8** (дистилляция за 8 шагов) | Правильная конфигурация планировщика встроена в каждый конвертированный чекпоинт, поэтому `num_inference_steps` по умолчанию принимает правильное значение, если вы не задаёте его явно. Передавайте этот параметр только для переопределения. Исходная кодовая база: [Stability-AI/stable-audio-3](https://github.com/Stability-AI/stable-audio-3). ## Конвертация исходных контрольных точек Чекпоинты Stability AI не публикуются в формате diffusers, поэтому конвертируйте их локально. Скрипт загружает `model_config.json` чекпоинта и выбирает планировщик на основе его `diffusion_objective`: ```bash 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 ``` > [!TIP] > `stable-audio-3-medium-base` — это **закрытый** репозиторий. Перед конвертацией выполните `hf auth login` с аккаунтом, имеющим доступ, иначе загрузка завершится ошибкой 401. ## Пример использования Загрузите преобразованный контрольный пункт из его локального выходного каталога (установите [`soundfile`](https://pypi.org/project/soundfile/) с помощью `pip install soundfile`): ```py 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](/docs/diffusers/v0.43.0/ru/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio), который автоматически определяет контрольную точку как `StableAudio3Pipeline`: ```py from diffusers import AutoPipelineForText2Audio pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32) ``` > [!NOTE] > В примерах используется локальный путь, так как `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`) получена методом **adversarial distillation** — 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]] #### diffusers.StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]] ```python diffusers.StableAudio3Pipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L157) **Параметры:** 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__[[diffusers.StableAudio3Pipeline.__call__]] ```python __call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, guidance_scale: float = 1.0, negative_prompt: typing.Union[str, typing.List[str], NoneType] = None, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt') ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L398) **Параметры:** 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` отключает guidance (значение по умолчанию и единственное разумное для дистиллированного чекпоинта SA3 Medium, в весах которого CFG уже «запечено»). Значения `> 1.0` имеют смысл для недистиллированного чекпоинта `stable-audio-3-medium-base`; более высокие значения точнее следуют промпту, но снижают разнообразие. negative_prompt (*str* или *list[str]*, *необязательный*) : Промпт(ы), описывающие, от чего следует отклоняться, когда `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)`. Генерация аудио по текстовому запросу. Примеры: ```py >>> 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[[diffusers.StableAudio3Pipeline.encode_duration]] ```python encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L289) **Параметры:** duration : Длительность в секундах, применяемая к каждому образцу в батче. device : Целевое устройство. num_waveforms_per_prompt : Коэффициент тайлинга. batch_size : Количество промптов. **Возвращает:** `(batch * num_waveforms_per_prompt, output_dim)` тензор. Встраивайте значение длительности в глобальный вектор условий. #### encode_prompt[[diffusers.StableAudio3Pipeline.encode_prompt]] ```python encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L223) **Параметры:** prompt : Текстовый промпт или список промптов. Игнорируется, если предоставлено `prompt_embeds`. device : Целевое устройство. num_waveforms_per_prompt : количество выходных волновых форм, генерируемых на один запрос; тензоры условий дублируются соответственно. prompt_embeds : Предварительно вычисленные текстовые эмбеддинги `(batch, seq_len, hidden_size)`. encoder_attention_mask : Булевая маска `(batch, seq_len)` для предварительно вычисленных эмбеддингов; `1` = реальный токен, `0` = заполнитель. **Возвращает:** `(prompt_embeds, encoder_attention_mask)` оба тайлятся до `batch * num_waveforms_per_prompt`. Кодирует текстовые промпты в тензоры для кросс-внимания. #### prepare_cross_attention[[diffusers.StableAudio3Pipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L313) **Возвращает:** `(context, context_mask)` форм `(batch, T_text + 1, dim)` и `(batch, T_text + 1)`. Сформируйте контекст кросс-внимания, добавив эмбеддинг длительности в качестве дополнительного токена. SA3 направляет conditioner `seconds_total` на *оба* глобальный вход (AdaLN) и контекст кросс-внимания (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). Встраивание длительности конкатенируется после текстовых токенов, а маска внимания расширяется на одну валидную запись. ## StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]] #### diffusers.StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]] ```python diffusers.StableAudio3InpaintPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L158) **Параметры:** 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__[[diffusers.StableAudio3InpaintPipeline.__call__]] ```python __call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, audio: typing.Optional[torch.Tensor] = None, mask: typing.Optional[torch.Tensor] = None, mask_start_seconds: typing.Union[float, typing.List[float], NoneType] = None, mask_end_seconds: typing.Union[float, typing.List[float], NoneType] = None, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt') ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L455) **Параметры:** 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*, *необязательный*) : Вызывается в конце каждого шага денойзинга с аргументами *(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"`. **Возвращает:** [*~pipelines.AudioPipelineOutput*] с `.audios`. Сгенерируйте восстановленный аудио, обусловленный текстовым запросом и эталонным образцом. Примеры: ```py >>> 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[[diffusers.StableAudio3InpaintPipeline.encode_duration]] ```python encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L290) **Параметры:** duration : Длительность в секундах, применяемая к каждому образцу в батче. device : Целевое устройство. num_waveforms_per_prompt : Коэффициент тайлинга. batch_size : Количество промптов. **Возвращает:** `(batch * num_waveforms_per_prompt, output_dim)` тензор. Встраивайте значение длительности в глобальный вектор условий. #### encode_prompt[[diffusers.StableAudio3InpaintPipeline.encode_prompt]] ```python encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L223) **Параметры:** prompt : Текстовый промпт или список промптов. Игнорируется, если предоставлено `prompt_embeds`. device : Целевое устройство. num_waveforms_per_prompt : количество выходных волновых форм, генерируемых на один запрос; тензоры условий дублируются соответственно. prompt_embeds : Предварительно вычисленные текстовые эмбеддинги `(batch, seq_len, hidden_size)`. encoder_attention_mask : Булевая маска `(batch, seq_len)` для предварительно вычисленных эмбеддингов; `1` = реальный токен, `0` = заполнитель. **Возвращает:** `(prompt_embeds, encoder_attention_mask)` оба тайлятся до `batch * num_waveforms_per_prompt`. Кодирует текстовые промпты в тензоры для кросс-внимания. #### prepare_cross_attention[[diffusers.StableAudio3InpaintPipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L315) **Возвращает:** `(context, context_mask)` форм `(batch, T_text + 1, dim)` и `(batch, T_text + 1)`. Сформируйте контекст кросс-внимания, добавив эмбеддинг длительности в качестве дополнительного токена. SA3 направляет conditioner `seconds_total` на *оба* глобальный вход (AdaLN) и контекст кросс-внимания (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). Встраивание длительности конкатенируется после текстовых токенов, а маска внимания расширяется на одну валидную запись. ## StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]] Генерирует вариацию опорного аудиоклипа: весь опорный фрагмент шумится до уровня `init_noise_level` и затем очищается от шума, в отличие от пофреймового локально-аддитивного обусловливания в [StableAudio3InpaintPipeline](/docs/diffusers/v0.43.0/ru/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline), которое сохраняет конкретные кадры без изменений. #### diffusers.StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]] ```python diffusers.StableAudio3AudioToAudioPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L154) **Параметры:** 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__[[diffusers.StableAudio3AudioToAudioPipeline.__call__]] ```python __call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, audio: typing.Optional[torch.Tensor] = None, init_noise_level: float = 1.0, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt') ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L424) **Параметры:** 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*, *необязательный*) : Вызывается в конце каждого шага денойзинга с аргументами *(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"`. **Возвращает:** [*~pipelines.AudioPipelineOutput*] с `.audios`. Сгенерируйте вариацию аудио, обусловленную текстовым запросом и эталонной волной. Примеры: ```py >>> 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[[diffusers.StableAudio3AudioToAudioPipeline.encode_duration]] ```python encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L287) **Параметры:** duration : Длительность в секундах, применяемая к каждому образцу в батче. device : Целевое устройство. num_waveforms_per_prompt : Коэффициент тайлинга. batch_size : Количество промптов. **Возвращает:** `(batch * num_waveforms_per_prompt, output_dim)` тензор. Встраивайте значение длительности в глобальный вектор условий. #### encode_prompt[[diffusers.StableAudio3AudioToAudioPipeline.encode_prompt]] ```python encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L220) **Параметры:** prompt : Текстовый промпт или список промптов. Игнорируется, если предоставлено `prompt_embeds`. device : Целевое устройство. num_waveforms_per_prompt : количество выходных волновых форм, генерируемых на один запрос; тензоры условий дублируются соответственно. prompt_embeds : Предварительно вычисленные текстовые эмбеддинги `(batch, seq_len, hidden_size)`. encoder_attention_mask : Булевая маска `(batch, seq_len)` для предварительно вычисленных эмбеддингов; `1` = реальный токен, `0` = заполнитель. **Возвращает:** `(prompt_embeds, encoder_attention_mask)` оба тайлятся до `batch * num_waveforms_per_prompt`. Кодирует текстовые промпты в тензоры для кросс-внимания. #### prepare_cross_attention[[diffusers.StableAudio3AudioToAudioPipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L312) **Возвращает:** `(context, context_mask)` форм `(batch, T_text + 1, dim)` и `(batch, T_text + 1)`. Сформируйте контекст кросс-внимания, добавив эмбеддинг длительности в качестве дополнительного токена. SA3 направляет conditioner `seconds_total` на *оба* глобальный вход (AdaLN) и контекст кросс-внимания (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). Встраивание длительности конкатенируется после текстовых токенов, а маска внимания расширяется на одну валидную запись. ## StableAudio3DurationEmbedder[[diffusers.StableAudio3DurationEmbedder]] #### diffusers.StableAudio3DurationEmbedder[[diffusers.StableAudio3DurationEmbedder]] ```python diffusers.StableAudio3DurationEmbedder(output_dim: int = 768, fourier_dim: int = 256, min_val: float = 0.0, max_val: float = 384.0, min_freq: float = 0.5, max_freq: float = 10000.0) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L43) **Параметры:** output_dim (*int*, по умолчанию 768) : Размерность выходного эмбеддинга. Должна совпадать с `global_cond_dim` DiT. fourier_dim (*int*, по умолчанию 256) : Внутреннее размерность Фурье-признаков (должно быть чётным). min_val (*float*, по умолчанию 0.0) : Минимальное значение длительности для ограничения при нормализации. max_val (*float*, по умолчанию 384.0) : Максимальное значение длительности для нормализации с ограничением. Значения выше этого ограничиваются. 384 секунды — это верхняя граница для производственной модели 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[[diffusers.StableAudio3DurationEmbedder.forward]] ```python forward(seconds: Tensor) ``` [Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L90) **Параметры:** seconds (`torch.Tensor` формы `(batch,)`) : Значения длительности в секундах. **Возвращает:** `torch.Tensor` формы `(batch, output_dim)` — эмбеддинги длительности.