Hugging Face's logo

Diffusers documentation

Stable Audio

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

and get access to the augmented documentation experience

to get started

Stable Audio

Stable Audio は、Zach Evans らによって Stable Audio Open で提案されました。テキストプロンプトを入力として受け取り、それに対応するサウンドまたは音楽サンプルを予測します。

Stable Audio Open は、テキストプロンプトから最大 47 秒の可変長ステレオオーディオを 44.1kHz で生成します。このモデルは 3 つのコンポーネントで構成されています。波形を扱いやすいシーケンス長に圧縮するオートエンコーダー、テキスト条件付けのための T5 ベースのテキスト埋め込み、そしてオートエンコーダーの潜在空間で動作する Transformer ベースの拡散（DiT）モデルです。

Stable Audioは、約48,000件の音声録音からなるコーパスで学習されています。そのうち約47,000件はFreesoundから、残りはFree Music Archive (FMA)から提供されています。すべての音声ファイルは、CC0、CC BY、またはCC Sampling+のライセンスの下で利用可能です。このデータは、autoencoderとDiTの学習に使用されます。

本論文の抄録は以下の通りです：オープンな生成モデルはコミュニティにとって極めて重要であり、ファインチューニングを可能にし、新モデルを提示する際のベースラインとして機能します。しかし、現在のテキストからオーディオを生成するモデルの多くは非公開であり、アーティストや研究者がその上に構築することができません。ここでは、クリエイティブ・コモンズデータで学習された新しいオープンウェイトのテキストからオーディオを生成するモデルのアーキテクチャと学習プロセスについて説明します。評価の結果、本モデルの性能は、さまざまな指標において最先端のモデルと競争力があることが示されました。特に、FDopenl3の結果（生成物のリアリズムを測定する）は、44.1kHzでの高品質ステレオサウンド合成の可能性を示しています。

このパイプラインはYoach Lacombeによって提供されました。元のコードベースはStability-AI/stable-audio-toolsで確認できます。

ヒント

プロンプトを構築する際は、以下の点に注意してください。

  • 説明的なプロンプト入力が最も効果的です。形容詞を使用して音の特徴を記述し（例：「高品質」や「クリア」）、可能な限りプロンプトの文脈を具体的に指定してください（例：「高速ビートとシンセを備えたメロディックテクノ」は「テクノ」よりも効果的です）。
  • ネガティブプロンプトを使用すると、生成されるオーディオの品質を大幅に向上させることができます。「low quality, average quality」をネガティブプロンプトとして使用してみてください。

推論中:

  • 生成されたオーディオサンプルの品質は、num_inference_steps引数によって制御できます。ステップ数を増やすと品質の高いオーディオが得られますが、推論速度は低下します。
  • 一度に複数の波形を生成できます。num_waveforms_per_promptを1より大きい値に設定すると、この機能が有効になります。生成された波形とプロンプトテキストの間に自動スコアリングが実行され、オーディオはそれに応じて最良から最悪の順にランキングされます。

量子化

Quantizationは、モデルの重みを低精度のデータ型で保存することで、非常に大規模なモデルのメモリ要件を軽減するのに役立ちます。ただし、動画モデルによって、Quantizationが動画の品質に与える影響は異なります。

サポートされている量子化バックエンドと、ユースケースに対応する量子化バックエンドの選択について詳しくは、Quantizationの概要を参照してください。以下の例では、bitsandbytesを使用して量子化されたStableAudioPipelineを読み込み、推論を実行する方法を示しています。

import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, StableAudioDiTModel, StableAudioPipeline
from diffusers.utils import export_to_video
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    subfolder="text_encoder",
    quantization_config=quant_config,
    dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = StableAudioDiTModel.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = StableAudioPipeline.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = "The sound of a hammer hitting a wooden surface."
negative_prompt = "Low quality."
audio = pipeline(
    prompt,
    negative_prompt=negative_prompt,
    num_inference_steps=200,
    audio_end_in_s=10.0,
    num_waveforms_per_prompt=3,
    generator=generator,
).audios

output = audio[0].T.float().cpu().numpy()
sf.write("hammer.wav", output, pipeline.vae.sampling_rate)

StableAudioPipeline

class diffusers.StableAudioPipeline

< >

( vae: AutoencoderOoblecktext_encoder: T5EncoderModelprojection_model: StableAudioProjectionModeltokenizer: T5Tokenizertransformer: StableAudioDiTModelscheduler: EDMDPMSolverMultistepScheduler )

パラメータ

  • vae (AutoencoderOobleck) — 画像を潜在表現にエンコードし、潜在表現からデコードするための Variational Auto-Encoder (VAE) モデル。
  • text_encoder (T5EncoderModel) — 凍結されたテキストエンコーダー。StableAudio は T5 のエンコーダーを使用しており、具体的には google-t5/t5-base バリアントです。
  • projection_model (StableAudioProjectionModel) — テキストエンコーダーモデルの隠れ状態と開始秒・終了秒を線形射影するために使用される学習済みモデルです。エンコーダーからの射影された隠れ状態と条件付きの秒数が連結され、transformerモデルへの入力となります。
  • tokenizer (T5Tokenizer) — 凍結されたテキストエンコーダー用のテキストをトークン化するためのトークナイザー。
  • transformer (StableAudioDiTModel) — エンコードされたオーディオの潜在変数をノイズ除去するためのStableAudioDiTModel。
  • scheduler (EDMDPMSolverMultistepScheduler) — エンコードされたオーディオの潜在変数をノイズ除去するために、transformer と組み合わせて使用するスケジューラ。

StableAudio を使用したテキストからオーディオへの生成を行う Pipeline です。

このモデルは DiffusionPipeline を継承しています。すべてのパイプラインに実装されている汎用的なメソッド（ダウンロード、保存、特定のデバイスでの実行など）については、スーパークラスのドキュメントを参照してください。

__call__

< >

( prompt: str | list[str] = Noneaudio_end_in_s: float | None = Noneaudio_start_in_s: float | None = 0.0num_inference_steps: int = 100guidance_scale: float = 7.0negative_prompt: str | list[str] | None = Nonenum_waveforms_per_prompt: int | None = 1eta: float = 0.0generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneinitial_audio_waveforms: typing.Optional[torch.Tensor] = Noneinitial_audio_sampling_rate: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.LongTensor] = Nonenegative_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = Nonecallback_steps: int | None = 1output_type: str | None = 'pt' ) → StableDiffusionPipelineOutput or tuple

パラメータ

  • prompt (str または list[str]、省略可) — 音声生成をガイドするためのプロンプトです。未定義の場合、prompt_embeds を渡す必要があります。
  • audio_end_in_s (float、任意、デフォルト値は 47.55) — 秒単位のオーディオ終了インデックス。
  • audio_start_in_s (float、任意、デフォルト値は 0) — 秒単位のオーディオ開始インデックス。
  • num_inference_steps (int, 任意、デフォルト値は 100) — デノイジングのステップ数です。デノイジングのステップ数を増やすと、推論速度が遅くなる代わりに、より高品質なオーディオが得られる傾向があります。
  • guidance_scale (float、任意、デフォルト値は 7.0) — guidance scale の値を高くすると、prompt と密接に関連する音声を生成するようモデルに促されますが、その代わり音質が低下します。guidance scale は guidance_scale > 1 の場合に有効になります。
  • negative_prompt (str または list[str]、省略可) — 音声生成において含めるべきでない内容を指示するためのプロンプトです。未定義の場合、代わりに negative_prompt_embeds を渡す必要があります。ガイダンスを使用していない場合（guidance_scale < 1）は無視されます。
  • num_waveforms_per_prompt (int、省略可、デフォルト値は 1)— プロンプトごとに生成する波形の数を指定します。
  • eta (float、省略可、デフォルト値は 0.0) — DDIM論文のパラメータ eta (η) に対応します。DDIMSchedulerでのみ適用され、他のスケジューラーでは無視されます。
  • generator (torch.Generator または list[torch.Generator]、省略可) — 生成を決定論的にするための torch.Generator。
  • latents (torch.Tensor, 任意) — ガウス分布からサンプリングされた事前生成されたノイズ付き潜変数で、音声生成の入力として使用されます。異なるプロンプトで同じ生成を調整するために使用できます。指定されない場合、指定されたランダムgeneratorを使用してサンプリングを行い、潜変数テンソルが生成されます。
  • initial_audio_waveforms (torch.Tensor, 任意) — 生成の初期音声波形として使用する、任意の初期音声波形です。形状は (batch_size, num_channels, audio_length) または (batch_size, audio_length) である必要があります。ここで batch_size は、モデルに渡されるプロンプトの数に対応します。
  • initial_audio_sampling_rate (int, 任意) — initial_audio_waveforms が提供される場合のサンプリングレートです。モデルのものと一致する必要があります。
  • prompt_embeds (torch.Tensor, 任意) — テキストエンコーダーモデルによって事前計算されたテキスト埋め込みです。テキスト入力の調整、例えばプロンプトの重み付けなどを容易に行うために使用できます。指定されない場合、prompt 入力引数からテキスト埋め込みが計算されます。
  • negative_prompt_embeds (torch.Tensor, 任意) — テキストエンコーダーモデルから事前計算されたネガティブなテキスト埋め込みです。プロンプトの重み付けなど、例えばテキスト入力の調整を簡単に実行できます。指定されない場合、negative_prompt 入力引数から negative_prompt_embeds が計算されます。
  • attention_mask (torch.LongTensor, 任意) — prompt_embeds に適用する事前計算済みのアテンションマスクです。指定しない場合、prompt 入力引数からアテンションマスクが計算されます。
  • negative_attention_mask (torch.LongTensor, 任意) — negative_text_audio_duration_embeds に適用する事前計算済みのアテンションマスク。
  • return_dict (bool、任意、デフォルトは True) — プレーンなタプルではなく StableDiffusionPipelineOutput を返すかどうかを指定します。
  • callback (Callable, 省略可) — 推論中に callback_steps ステップごとに呼び出される関数です。この関数は、以下の引数とともに呼び出されます: callback(step: int, timestep: int, latents: torch.Tensor)。
  • callback_steps (int、任意、デフォルトは 1) — callback 関数が呼び出される頻度です。指定しない場合、callback はすべてのステップで呼び出されます。
  • output_type (str、任意、デフォルトは "pt") — 生成されたオーディオの出力形式です。"np" を指定すると NumPy の np.ndarray が、"pt" を指定すると PyTorch の torch.Tensor オブジェクトが返されます。"latent" を指定すると、潜在拡散モデル (LDM) の出力が返されます。

戻り値

StableDiffusionPipelineOutput または tuple

return_dict が True の場合、StableDiffusionPipelineOutput が返され、それ以外の場合は、最初の要素が生成されたオーディオのリストである tuple が返されます。

生成用の pipeline への呼び出し関数。

例:

>>> import scipy
>>> import torch
>>> import soundfile as sf
>>> from diffusers import StableAudioPipeline

>>> repo_id = "stabilityai/stable-audio-open-1.0"
>>> pipe = StableAudioPipeline.from_pretrained(repo_id, torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")

>>> # define the prompts
>>> prompt = "The sound of a hammer hitting a wooden surface."
>>> negative_prompt = "Low quality."

>>> # set the seed for generator
>>> generator = torch.Generator("cuda").manual_seed(0)

>>> # run the generation
>>> audio = pipe(
...     prompt,
...     negative_prompt=negative_prompt,
...     num_inference_steps=200,
...     audio_end_in_s=10.0,
...     num_waveforms_per_prompt=3,
...     generator=generator,
... ).audios

>>> output = audio[0].T.float().cpu().numpy()
>>> sf.write("hammer.wav", output, pipe.vae.sampling_rate)
Update on GitHub

←LongCat-AudioDiT Stable Audio 3→