Diffusers documentation
Stable Audio 3
Stable Audio 3
Stable Audio 3 (SA3) は、Stability AI によるテキストからオーディオを生成するモデルで、44.1 kHz の高品質ステレオオーディオを生成します。2つのシグナルで条件付けられた rectified-flow DiT を使用しています。
- Text — 凍結された T5Gemma エンコーダーでエンコードされ、クロスアテンションを介して注入されます。
- Duration — StableAudio3DurationEmbedderによって埋め込まれる float（秒）で、適応型レイヤーノーマライゼーションのグローバル条件付けベクトルとして使用されます。
Audioは、SAME（Semantically-Aligned Music Encoder）オートエンコーダー、AutoencoderSAMEによってデコードされます。
両方のチェックポイントは、log-SNR 一様シグマスケジュールを用いた 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。
元のチェックポイントの変換
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 エラーで失敗します。
使用例
ローカル出力ディレクトリから変換済みチェックポイントをロードします（pip install soundfile で 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 形式で公開されていないため（リポジトリ 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
class diffusers.StableAudio3Pipeline
< source >( 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（秒）を、各 DiT ブロックの AdaLN 用のグローバル条件付けベクトルにマッピングします。 - transformer ([StableAudio3DiTModel]) — Rectified-flow 速度予測 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 チェックポイントでは、これらの設定が意味を持ちます。
このモデルは [DiffusionPipeline] を継承しています。すべてのパイプラインに実装されている汎用的なメソッドについては、スーパークラスのドキュメントを参照してください。
__call__
< source >( 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 設定に基づいてステップ数が決定されます。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 を無効にします（デフォルトであり、distilled SA3 Medium チェックポイントでは CFG が重みに組み込まれているため、唯一の妥当な値です）。> 1.0の値は、非 distilled な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]、省略可) — ピンポンループにおける決定論的な生成と再現可能な再ノイズ化のために使用します。
- latents (torch.Tensor, optional) —
事前生成された初期 latents です。
Noneの場合、新しいガウス分布のテンソルがサンプリングされます。 - prompt_embeds (torch.Tensor, optional) —
事前計算されたテキスト埋め込み
(batch, seq_len, 768)。 - encoder_attention_mask (torch.LongTensor, optional) — 事前計算済みエンベディング用のブールマスク。
- negative_prompt_embeds (torch.Tensor、任意) — negative_prompt の代わりに使用する、事前計算済みのネガティブテキスト埋め込み。
- negative_encoder_attention_mask (torch.LongTensor、任意) — 事前計算されたネガティブ埋め込み用のブールマスクです。
- 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 に列挙されたテンソルが含まれます。ループの残りの部分で使用するための（変更された場合のある）テンソルを dict として返す必要があります。
- 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
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
duration の値をグローバルな条件付けベクトルに埋め込みます。
encode_prompt
< source >( 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 — 事前計算済みエンベディング用の Boolean マスク
(batch, seq_len)。1= 実トークン、0= パディング。
テキストプロンプトをクロスアテンションの条件付けテンソルにエンコードします。
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
長さの埋め込みを追加トークンとして付加することで、クロスアテンションのコンテキストを構築します。
SA3 は seconds_total 条件を、グローバル (AdaLN) 入力とクロスアテンションコンテキストの両方にルーティングします (cross_attention_cond_ids = ["prompt", "seconds_total"])。期間の埋め込みはテキストトークンの後に連結され、アテンションマスクには 1 つの有効エントリが追加されます。
StableAudio3InpaintPipeline
class diffusers.StableAudio3InpaintPipeline
< source >( 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（秒）を、各 DiT ブロックの AdaLN 用のグローバル条件付けベクトルにマッピングします。 - transformer ([StableAudio3DiTModel]) — Rectified-flow 速度予測 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 の拡張（__call__）を参照してください:
audio (torch.Tensor、shape (batch, channels, samples)):
vae.config.sampling_rate Hz の参照オーディオ波形。
mask (torch.Tensor、shape (batch, 1, latent_length)):
潜在空間におけるフレームごとのバイナリマスク。 1 = 元のオーディオを保持; 0 = インペイント対象の領域。
__call__
< source >( 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) —
インペインティングに必要です。
vae.config.sampling_rateHz の参照波形(batch, channels, samples)。 - 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]、任意) —
インペイント領域の終了時刻（
mask_start_secondsと対で指定する必要があります）。 - num_inference_steps (int、任意) —
デノイジングのステップ数。
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"。
テキストプロンプトと参照に基づいて、インペイントされたオーディオを生成します。
例:
>>> 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
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
duration の値をグローバルな条件付けベクトルに埋め込みます。
encode_prompt
< source >( 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 — 事前計算済みエンベディング用の Boolean マスク
(batch, seq_len)。1= 実トークン、0= パディング。
テキストプロンプトをクロスアテンションの条件付けテンソルにエンコードします。
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
長さの埋め込みを追加トークンとして付加することで、クロスアテンションのコンテキストを構築します。
SA3 は seconds_total 条件を、グローバル (AdaLN) 入力とクロスアテンションコンテキストの両方にルーティングします (cross_attention_cond_ids = ["prompt", "seconds_total"])。期間の埋め込みはテキストトークンの後に連結され、アテンションマスクには 1 つの有効エントリが追加されます。
StableAudio3AudioToAudioPipeline
参照オーディオクリップのバリエーションを生成します。参照全体をinit_noise_levelまでノイズ化してからデノイズする方式であり、StableAudio3InpaintPipelineのフレームごとの局所的な加法的条件付け（特定のフレームを正確に保持する方式）とは異なります。
class diffusers.StableAudio3AudioToAudioPipeline
< source >( 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（秒）を、各 DiT ブロックの AdaLN 用のグローバル条件付けベクトルにマッピングします。 - transformer ([StableAudio3DiTModel]) — Rectified-flow 速度予測 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 signature extension (see __call__):
audio (torch.Tensor of shape (batch, channels, samples)):
Reference audio waveform at vae.config.sampling_rate Hz.
init_noise_level (float):
How much noise to mix into the reference before denoising. 1.0 = full noise (equivalent to
text-to-audio); lower values retain more of the reference.
__call__
< source >( 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) —
vae.config.sampling_rateHz の参照波形(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、任意) —
デノイジングのステップ数。
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"。
テキストプロンプトと参照波形に条件付けられたオーディオのバリエーションを生成します。
例:
>>> 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
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
duration の値をグローバルな条件付けベクトルに埋め込みます。
encode_prompt
< source >( 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 — 事前計算済みエンベディング用の Boolean マスク
(batch, seq_len)。1= 実トークン、0= パディング。
テキストプロンプトをクロスアテンションの条件付けテンソルにエンコードします。
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
長さの埋め込みを追加トークンとして付加することで、クロスアテンションのコンテキストを構築します。
SA3 は seconds_total 条件を、グローバル (AdaLN) 入力とクロスアテンションコンテキストの両方にルーティングします (cross_attention_cond_ids = ["prompt", "seconds_total"])。期間の埋め込みはテキストトークンの後に連結され、アテンションマスクには 1 つの有効エントリが追加されます。
StableAudio3DurationEmbedder
class diffusers.StableAudio3DurationEmbedder
< source >( 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) —
出力埋め込みの次元数。DiT の
global_cond_dimと一致する必要があります。 - fourier_dim (int、デフォルト値は 256) — 内部フーリエ特徴の次元（偶数である必要があります）。
- min_val (float、デフォルト値は 0.0) — 正規化クランプ用の最小時間値。
- max_val (float、デフォルト値は 384.0) —
正規化クランプ用の最大持続時間値です。この値を超える場合はクランプされます。384 秒は、
seconds_totalコンディショナーにおける本番環境 SA3 Medium の上限値です。 - min_freq (float、デフォルト値: 0.5) — 指数Fourier基底の最小周波数。
- max_freq (float、デフォルト値: 10000.0) — 指数関数型フーリエ基底の最大周波数。
Stable Audio 3 DiT（global_hidden_states AdaLN 入力として使用）のグローバル条件付けベクトルに、時間値（秒）を埋め込みます。
SA3の参照実装にあるNumberConditioner(fourier_features_type="expo")を再現します。