Diffusers documentation
Stable Audio 3
Stable Audio 3
Stable Audio 3(SA3)는 Stability AI의 텍스트-오디오 모델로, 44.1 kHz의 고품질 스테레오 오디오를 생성합니다. 두 개의 신호에 조건부화된 rectified-flow DiT를 사용합니다:
- Text — 동결된 T5Gemma 인코더로 인코딩된 후 크로스 어텐션을 통해 주입됩니다.
- Duration — StableAudio3DurationEmbedder에 의해 임베드된 float(초) 값으로, 적응형 레이어 정규화(global conditioning vector)의 전역 조건 벡터로 사용됩니다.
오디오는 SAME(Semantically-Aligned Music Encoder) 오토인코더인 AutoencoderSAME에 의해 디코딩됩니다.
두 체크포인트 모두 FlowMatchEulerDiscreteScheduler를 log-SNR-uniform sigma 스케줄과 함께 사용하며, 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 오류로 실패합니다.
사용 예시
로컬 출력 디렉터리에서 변환된 체크포인트를 로드합니다(soundfile은 pip install soundfile로 설치):
import torch
import soundfile as sf
from diffusers import StableAudio3Pipeline
pipe = StableAudio3Pipeline.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)
pipe = pipe.to("cuda") # or "mps", "xpu", "cpu"
generator = torch.Generator("cuda").manual_seed(0)
audio = pipe(
"A gentle piano melody with soft strings in a concert hall",
duration=10.0, # seconds; latent length is computed automatically
generator=generator,
).audios
sf.write("sa3_output.wav", audio[0].T.cpu().float().numpy(), samplerate=44100)파이프라인은 AutoPipelineForText2Audio에도 등록되어 있으며, 체크포인트를 자동으로 StableAudio3Pipeline으로 해석합니다:
from diffusers import AutoPipelineForText2Audio
pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)예제에서는
stabilityai/stable-audio-3-medium와stable-audio-3-medium-base가 아직 diffusers 형식으로 게시되지 않았기 때문에(리포지토리 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)는 latent 시퀀스 끝에 무음 여백을 추가합니다. 모델이 해당 패딩을 마스킹하도록 학습되지 않았다면0.0로 유지하세요. 그렇지 않으면 추가 프레임이 출력 에너지를 소모하여 결과가 조용해집니다.- 프롬프트당 여러 클립을 생성하려면
num_waveforms_per_prompt > 1을 설정하세요.
StableAudio3Pipeline
클래스 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번의 ping-pong 스텝을 위해 stochastic_sampling=True를 사용하며, 디스틸되지 않은 베이스 체크포인트는 약 100번의 결정론적 Euler 스텝을 위해 stochastic_sampling=False를 사용합니다.
Stable Audio 3을 사용한 텍스트-오디오 생성을 위한 Pipeline입니다.
SA3는 ping-pong 샘플링을 사용하는 증류된 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, 선택 사항) —
디노이징 단계 수입니다.
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 scale입니다.
1.0은 guidance를 비활성화합니다(기본값이며, CFG가 가중치에 이미 반영된 distilled SA3 Medium 체크포인트의 경우 유일한 합리적인 값입니다).> 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], 선택 사항) — ping-pong 루프에서 결정론적 생성 및 재노이즈의 재현성을 위해 사용합니다.
- latents (torch.Tensor, 선택 사항) —
미리 생성된 시작 latents입니다.
None인 경우 새로운 가우시안 텐서가 샘플링됩니다. - prompt_embeds (torch.Tensor, optional) —
사전 계산된 텍스트 임베딩
(batch, seq_len, 768). - encoder_attention_mask (torch.LongTensor, 선택 사항) — 사전 계산된 임베딩에 대한 불리언 마스크.
- negative_prompt_embeds (torch.Tensor, 선택) — negative_prompt의 대안으로 사용할 수 있는 사전 계산된 부정 텍스트 임베딩입니다.
- negative_encoder_attention_mask (torch.LongTensor, 선택 사항) — 사전 계산된 negative embeddings에 대한 Boolean mask입니다.
- 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") —"pt"는 PyTorch 텐서,"np"는 NumPy 배열,"latent"는 디코딩을 건너뛰고 원시 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 )
지속 시간 값을 전역 조건 벡터에 임베딩합니다.
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 )
텍스트 프롬프트를 크로스 어텐션 조건 텐서로 인코딩합니다.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
duration 임베딩을 추가 토큰으로 추가하여 크로스 어텐션 컨텍스트를 구성합니다.
SA3은 seconds_total 조건자를 전역(AdaLN) 입력과 크로스 어텐션 컨텍스트(cross_attention_cond_ids = ["prompt", "seconds_total"])에 모두 라우팅합니다. 지속 시간 임베딩은 텍스트 토큰 뒤에 연결되고, 어텐션 마스크에는 유효한 항목 하나가 확장됩니다.
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번의 ping-pong 스텝을 위해 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)):
latent space의 프레임별 바이너리 마스크. 1 = 원본 오디오 유지; 0 = inpaint할 영역.
__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) —
0 = inpaint 영역, 1 = 유지로 정의된 프레임별 latent-space mask
(batch, 1, L).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(기본값)인 경우, [StableAudio3Pipeline]과 일치하도록 스케줄러의 stochastic_sampling 설정에서 단계 수를 선택합니다. - 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 — 재현성을 위한 RNG.
- latents — 사전 생성된 시작 노이즈 (
None→ 새로 샘플링). - prompt_embeds — 사전 계산된 텍스트 임베딩.
- encoder_attention_mask — 사전 계산된 임베딩용 마스크.
- return_dict (bool, 기본값 True) — AudioPipelineOutput 또는 tuple을 반환합니다.
- 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".
텍스트 프롬프트와 참조에 조건부화된 인페인팅된 오디오를 생성합니다.
예:
>>> 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 )
지속 시간 값을 전역 조건 벡터에 임베딩합니다.
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 )
텍스트 프롬프트를 크로스 어텐션 조건 텐서로 인코딩합니다.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
duration 임베딩을 추가 토큰으로 추가하여 크로스 어텐션 컨텍스트를 구성합니다.
SA3은 seconds_total 조건자를 전역(AdaLN) 입력과 크로스 어텐션 컨텍스트(cross_attention_cond_ids = ["prompt", "seconds_total"])에 모두 라우팅합니다. 지속 시간 임베딩은 텍스트 토큰 뒤에 연결되고, 어텐션 마스크에는 유효한 항목 하나가 확장됩니다.
StableAudio3AudioToAudioPipeline
참조 오디오 클립의 변형을 생성합니다. StableAudio3InpaintPipeline의 프레임별 로컬 가산 조건화가 특정 프레임을 정확히 보존하는 것과 달리, 전체 참조 클립을 init_noise_level까지 노이즈화한 후 해당 상태에서 디노이즈합니다.
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번의 ping-pong 스텝을 위해 stochastic_sampling=True를 사용하며, 디스틸되지 않은 베이스 체크포인트는 약 100번의 결정론적 Euler 스텝을 위해 stochastic_sampling=False를 사용합니다.
Stable Audio 3용 오디오-오디오 변형 파이프라인.
[StableAudio3Pipeline]와 텍스트-오디오 로직을 공유합니다(# Copied from를 통해 동기화 유지). 동결된 SAME 인코더로 참조 오디오를 인코딩하고, init_noise_level에 따라 새로운 노이즈와 혼합한 뒤, 해당 지점부터 디노이즈합니다. [StableAudio3InpaintPipeline]의 프레임별 로컬 가산 조건화와 달리, 전체 신호가 전역적으로 노이즈/디노이즈됩니다.
Call signature 확장(자세한 내용은 __call__ 참조):
audio (torch.Tensor, shape (batch, channels, samples)):
vae.config.sampling_rate Hz의 참조 오디오 웨이브폼.
init_noise_level (float):
디노이징 전에 참조에 혼합할 노이즈의 양. 1.0 = 전체 노이즈(text-to-audio와 동일). 더 낮은 값은 참조의 더 많은 부분을 유지합니다.
__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(기본값)인 경우, [StableAudio3Pipeline]과 일치하도록 스케줄러의 stochastic_sampling 설정에서 단계 수를 선택합니다. - 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 — 재현성을 위한 RNG.
- latents — 사전 생성된 시작 노이즈 (
None→ 새로 샘플링). - prompt_embeds — 사전 계산된 텍스트 임베딩.
- encoder_attention_mask — 사전 계산된 임베딩용 마스크.
- return_dict (bool, 기본값 True) — AudioPipelineOutput 또는 tuple을 반환합니다.
- 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".
텍스트 프롬프트와 참조 웨이브폼에 조건부인 오디오 변형을 생성합니다.
예:
>>> 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 )
지속 시간 값을 전역 조건 벡터에 임베딩합니다.
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 )
텍스트 프롬프트를 크로스 어텐션 조건 텐서로 인코딩합니다.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
duration 임베딩을 추가 토큰으로 추가하여 크로스 어텐션 컨텍스트를 구성합니다.
SA3은 seconds_total 조건자를 전역(AdaLN) 입력과 크로스 어텐션 컨텍스트(cross_attention_cond_ids = ["prompt", "seconds_total"])에 모두 라우팅합니다. 지속 시간 임베딩은 텍스트 토큰 뒤에 연결되고, 어텐션 마스크에는 유효한 항목 하나가 확장됩니다.
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) — 내부 Fourier feature 차원(짝수여야 함).
- 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")를 재현합니다.