# Stable Audio 3 Stable Audio 3 (SA3) は、[Stability AI](https://stability.ai/) によるテキストからオーディオを生成するモデルで、44.1 kHz の高品質なステレオオーディオを生成します。2つのシグナルで条件付けられた rectified-flow DiT を使用しています。 * **Text** — 凍結された T5Gemma エンコーダーでエンコードされ、クロスアテンションを介して注入されます。 * **Duration** — [StableAudio3DurationEmbedder](/docs/diffusers/main/ja/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder)によって埋め込まれる float（秒）で、適応型レイヤーノーマライゼーションのグローバル条件付けベクトルとして使用されます。 Audioは、SAME（Semantically-Aligned Music Encoder）オートエンコーダー、[AutoencoderSAME](/docs/diffusers/main/ja/api/models/autoencoder_same#diffusers.AutoencoderSAME)によってデコードされます。 両方のチェックポイントは、log-SNR 一様シグマスケジュールを用いた [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) を使用しており、`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 エラーで失敗します。 ## 使用例 ローカル出力ディレクトリから変換済みチェックポイントをロードします（`pip install soundfile` で [`soundfile`](https://pypi.org/project/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/main/ja/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 形式で公開されていないため（リポジトリ ID での読み込みは 404 を返す）、ローカルパスを使用しています。公開されれば、ローカルパスの代わりにリポジトリ ID を使用できます。 ## ヒント * CPU または MPS (Apple Silicon) では `torch.float32` を使用してください。MPS で `torch.float16` を使用するとノイズが発生します。 * 蒸留済みモデル (`stable-audio-3-medium`) は **敵対的蒸留** されています — ガイダンスが重みに焼き込まれています。このチェックポイントでは `guidance_scale=1.0` (デフォルト値) のままで、`negative_prompt` を渡さないでください。これらはどちらも、蒸留されていない `stable-audio-3-medium-base` チェックポイントでのみ意味のある動作をします。 * `silence_padding_duration`（デフォルト値 `0.0`）は、潜在シーケンスの末尾に無音の余白を追加します。モデルがそのパディングをマスクするように学習されていない限り、`0.0` のままにしてください。そうしないと、追加されたフレームが出力のエネルギーを奪い、結果が静かになってしまいます。 * 1つのプロンプトごとに複数のクリップを生成するには、`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/main/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`（秒）を、各 DiT ブロックの AdaLN 用のグローバル条件ベクトルにマッピングします。 transformer ([*StableAudio3DiTModel*]) : 修正フロー速度予測 DiT。 scheduler ([*FlowMatchEulerDiscreteScheduler*]) : 反復的なノイズ除去ループ用のスケジューラです。本番用（蒸留済み）の SA3 Medium チェックポイントは、ちょうど 8 ステップのピンポンステップに対して *stochastic_sampling=True* を使用します。一方、蒸留されていないベースのチェックポイントは、約 100 ステップの決定論的な Euler ステップに対して *stochastic_sampling=False* を使用します。 Stable Audio 3 を用いたテキストからオーディオを生成する Pipeline です。 SA3 は、ピンポンサンプリングを用いた蒸留済み rectified-flow DiT を使用します。蒸留済みチェックポイントでは、classifier-free guidance（`guidance_scale` / `negative_prompt`）は不要です（`guidance_scale=1.0` のまま、デフォルト値を維持してください）。一方、非蒸留の `stable-audio-3-medium-base` チェックポイントでは、classifier-free guidance は意味を持ちます。 このモデルは*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/main/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* 設定に基づいてステップ数が選択されます。*True* の場合は **8**（蒸留されたピンポン方式のチェックポイント）、*False* の場合は **100**（蒸留されていないベースのチェックポイント）です。明示的な値を渡すことで上書きできます。 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 を無効にします（デフォルトであり、CFG が重みに焼き込まれている蒸留済み SA3 Medium チェックポイントに対しては唯一妥当な値です）。`> 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*、*任意*) : *(self, step_idx, timestep, callback_kwargs)* を引数として、各デノイジングステップの終了時に呼び出されます。ここで、*callback_kwargs* には *callback_on_step_end_tensor_inputs* に列挙されたテンソルが含まれます。ループの残りの部分で使用するための（変更された場合のある）テンソルを dict として返す必要があります。 callback_on_step_end_tensor_inputs (*list[str]*、デフォルトは *["latents"]*) : *callback_on_step_end* に渡されるテンソル。*self._callback_tensor_inputs* の部分集合である必要があります。 output_type (*str*、デフォルトは `"pt"`) : PyTorch テンソルには `"pt"`、NumPy 配列には `"np"`、デコードをスキップして生の潜在変数を返すには `"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/main/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)` テンソル。 duration の値をグローバルな条件付けベクトルに埋め込みます。 #### 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/main/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/main/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 は、`seconds_total` のコンディショナーを、グローバル（AdaLN）入力とクロスアテンションのコンテキスト（`cross_attention_cond_ids = ["prompt", "seconds_total"]`）の*両方*にルーティングします。期間の埋め込みはテキストトークンの後に連結され、アテンションマスクには1つの有効なエントリが追加されます。 ## 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/main/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`（秒）を、各 DiT ブロックの AdaLN 用のグローバル条件ベクトルにマッピングします。 transformer ([*StableAudio3DiTModel*]) : 修正フロー速度予測 DiT。 scheduler ([*FlowMatchEulerDiscreteScheduler*]) : 反復的なノイズ除去ループ用のスケジューラです。本番用（蒸留済み）の SA3 Medium チェックポイントは、ちょうど 8 ステップのピンポンステップに対して *stochastic_sampling=True* を使用します。一方、蒸留されていないベースのチェックポイントは、約 100 ステップの決定論的な Euler ステップに対して *stochastic_sampling=False* を使用します。 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 signature extension (see `__call__`): audio (*torch.Tensor* of shape `(batch, channels, samples)`): Reference audio waveform at `vae.config.sampling_rate` Hz. mask (*torch.Tensor* of shape `(batch, 1, latent_length)`): Per-frame binary mask in latent space. `1` = preserve original audio; `0` = region to be inpainted. #### __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/main/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*) : `vae.config.sampling_rate` Hz の参照波形 `(batch, channels, samples)`。インペインティングには必須です。 mask (*torch.Tensor*, *optional*) : 0 = 補完領域、1 = 保持を表す、フレームごとの潜在空間マスク `(batch, 1, L)`。`mask` または `mask_start_seconds` / `mask_end_seconds` のいずれかを指定する必要があります。 mask_start_seconds (*float* または *list[float]*、*optional*) : インペイント領域の開始時刻（秒）。 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)* を引数として呼び出されます。ループの残りの部分で使用するための（変更された場合のある）テンソルを dict として返す必要があります。 callback_on_step_end_tensor_inputs (*list[str]*、デフォルトは *["latents"]*) : *callback_on_step_end* に渡されるテンソル。*self._callback_tensor_inputs* の部分集合である必要があります。 output_type (*str*、デフォルトは `"pt"`) : `"pt"` / `"np"` / `"latent"`。 **戻り値:** `.audios` を持つ [*~pipelines.AudioPipelineOutput*] テキストプロンプトと参照に基づいて、インペイントされたオーディオを生成します。 例: ```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/main/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)` テンソル。 duration の値をグローバルな条件付けベクトルに埋め込みます。 #### 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/main/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/main/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 は、`seconds_total` のコンディショナーを、グローバル（AdaLN）入力とクロスアテンションのコンテキスト（`cross_attention_cond_ids = ["prompt", "seconds_total"]`）の*両方*にルーティングします。期間の埋め込みはテキストトークンの後に連結され、アテンションマスクには1つの有効なエントリが追加されます。 ## StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]] 参照オーディオクリップのバリエーションを生成します。参照全体を`init_noise_level`までノイズ化してからデノイズする方式であり、[StableAudio3InpaintPipeline](/docs/diffusers/main/ja/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/main/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`（秒）を、各 DiT ブロックの AdaLN 用のグローバル条件ベクトルにマッピングします。 transformer ([*StableAudio3DiTModel*]) : 修正フロー速度予測 DiT。 scheduler ([*FlowMatchEulerDiscreteScheduler*]) : 反復的なノイズ除去ループ用のスケジューラです。本番用（蒸留済み）の SA3 Medium チェックポイントは、ちょうど 8 ステップのピンポンステップに対して *stochastic_sampling=True* を使用します。一方、蒸留されていないベースのチェックポイントは、約 100 ステップの決定論的な Euler ステップに対して *stochastic_sampling=False* を使用します。 Stable Audio 3用のオーディオからオーディオへの変換パイプライン。 [*StableAudio3Pipeline*] とテキストからオーディオへのロジックを共有しています（*# Copied from* によって同期が保たれています）。凍結された SAME エンコーダーで参照オーディオをエンコードし、`init_noise_level` に従って新しいノイズと混合してから、そこからデノイズを行います。全体シグナルがグローバルにノイズ化/デノイズ化される点で、[*StableAudio3InpaintPipeline*] のフレームごとのローカル加算型コンディショニングとは異なります。 コールシグネチャの拡張（`__call__`を参照）: audio (*torch.Tensor*、形状 `(batch, channels, samples)`): `vae.config.sampling_rate` Hz の参照オーディオ波形。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/main/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*) : `vae.config.sampling_rate` Hz の参照波形 `(batch, channels, samples)`。必須です。 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)* を引数として呼び出されます。ループの残りの部分で使用するための（変更された場合のある）テンソルを dict として返す必要があります。 callback_on_step_end_tensor_inputs (*list[str]*、デフォルトは *["latents"]*) : *callback_on_step_end* に渡されるテンソル。*self._callback_tensor_inputs* の部分集合である必要があります。 output_type (*str*、デフォルトは `"pt"`) : `"pt"` / `"np"` / `"latent"`。 **戻り値:** `.audios` を持つ [*~pipelines.AudioPipelineOutput*] テキストプロンプトと参照波形に条件付けられたオーディオのバリエーションを生成します。 例: ```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/main/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)` テンソル。 duration の値をグローバルな条件付けベクトルに埋め込みます。 #### 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/main/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/main/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 は、`seconds_total` のコンディショナーを、グローバル（AdaLN）入力とクロスアテンションのコンテキスト（`cross_attention_cond_ids = ["prompt", "seconds_total"]`）の*両方*にルーティングします。期間の埋め込みはテキストトークンの後に連結され、アテンションマスクには1つの有効なエントリが追加されます。 ## 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/main/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L43) **パラメータ:** output_dim (*int*、デフォルトは 768) : 出力埋め込みの次元数。DiT の `global_cond_dim` と一致する必要があります。 fourier_dim (*int*、デフォルトは 256) : 内部 Fourier 特徴の次元（偶数である必要があります）。 min_val (*float*、デフォルト値は 0.0) : 正規化クランプ用の最小持続時間値。 max_val (*float*、デフォルト値は 384.0) : 正規化クランプ用の最大持続時間値。この値を超える場合はクランプされます。384 秒は、`seconds_total` コンディショナーにおける本番環境 SA3 Medium の上限値です。 min_freq (*float*、デフォルト値は 0.5) : 指数関数型フーリエ基底の最小周波数。 max_freq (*float*、デフォルト値は 10000.0) : 指数関数型フーリエ基底の最大周波数。 Stable Audio 3 DiT（`global_hidden_states` AdaLN 入力として使用）のグローバル条件付けベクトルに、時間値（秒）を埋め込みます。 SA3の参照実装にある`NumberConditioner(fourier_features_type="expo")`を再現します。 #### forward[[diffusers.StableAudio3DurationEmbedder.forward]] ```python forward(seconds: Tensor) ``` [ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L90) **パラメータ:** seconds (`torch.Tensor`、shape `(batch,)`) : 秒単位の所要時間。 **戻り値:** `torch.Tensor`、形状 `(batch, output_dim)` — 期間の埋め込み。