Diffusers documentation
ACE-Step 1.5
ACE-Step 1.5
ACE-Step 1.5는 ACE-Step 팀(ACE Studio 및 StepFun)의 ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation에서 소개되었습니다. 텍스트 프롬프트에서 가사가 포함된 상업용 수준의 스테레오 음악을 생성하는 오픈소스 음악 파운데이션 모델입니다.
ACE-Step 1.5는 텍스트 프롬프트와 선택적인 가사로부터 48 kHz의 가변 길이 스테레오 오디오(10초에서 10분)를 생성합니다. 전체 시스템은 Language Model 플래너와 Diffusion Transformer(DiT) 합성기를 결합하며, 이 파이프라인은 해당 스택의 DiT 부분을 래핑합니다. 이 파이프라인은 세 가지 구성 요소로 이루어져 있습니다. 웨이브폼을 25 Hz 스테레오 라텐트로 압축하는 AutoencoderOobleck VAE, 프롬프트 및 가사 조건화에 사용되는 Qwen3 기반 텍스트 인코더, 그리고 flow matching을 사용하여 VAE 라텐트 공간에서 작동하는 AceStepTransformer1DModel DiT입니다.
모델은 영어, 중국어, 일본어, 한국어, 프랑스어, 독일어, 스페인어, 이탈리아어, 포르투갈어, 러시아어를 포함한 50개 이상의 언어의 가사를 지원하며, 오프로드 시 4GB 미만의 VRAM으로 소비자용 GPU에서 실행됩니다.
이 파이프라인은 ACE-Step Team이 기여했습니다. 원본 코드베이스는 ace-step/ACE-Step-1.5에서 찾을 수 있습니다.
변형
ACE-Step 1.5에는 동일한 transformer 아키텍처를 공유하지만 guidance 동작이 다른 세 가지 DiT checkpoint가 포함되어 있습니다. 해당 파이프라인은 로드된 transformer config에서 turbo checkpoint를 자동으로 감지하며, guidance-distilled weights의 경우 CFG guidance를 무시합니다.
| 변형 | CFG | 기본 단계 | 기본 guidance_scale | 기본 shift | HF 저장소 |
|---|---|---|---|---|---|
turbo (가이던스 증류) | off | 8 | 무시됨 | 3.0 | ACE-Step/acestep-v15-xl-turbo-diffusers |
base | on | 8 | 7.0 | 3.0 | ACE-Step/acestep-v15-base |
sft | on | 8 | 7.0 | 3.0 | ACE-Step/acestep-v15-sft |
Base와 SFT는 classifier-free guidance(APG, vanilla CFG가 아님)에 학습된 null_condition_emb를 사용합니다. 사용자는 일반적으로 base/sft에서 더 높은 품질을 얻기 위해 num_inference_steps를 30~60으로 재정의합니다.
팁
프롬프트를 구성할 때 다음 사항을 기억하세요:
- 설명적인 프롬프트 입력이 가장 효과적입니다. 형용사를 사용하여 음악 스타일, 악기, 무드, 템포를 설명하세요.
- 는 전체적인 음악적 특성(예: “일렉트릭 기타와 드럼이 있는 업비트 팝 노래”)을 설명해야 합니다.
- 가사는
[verse],[chorus],[bridge]등의 태그로 구조화되어야 합니다.
추론 중:
num_inference_steps,guidance_scale,shift의 기본값은 위에서 표시된 값입니다. Turbo 체크포인트의 경우, 가이던스가 가중치에 증류되어 있으므로guidance_scale > 1.0은 경고와 함께 무시됩니다.audio_duration매개변수는 생성된 음악의 길이를 초 단위로 제어합니다.vocal_language매개변수는 가사의 언어와 일치해야 합니다.pipe.sample_rate와pipe.latents_per_second는 VAE 설정에서 가져오며(발행된 체크포인트의 경우 48000 Hz, 25 fps)- 오디오-오디오 작업의 경우,
src_audio와reference_audio를pipe.sample_rate에서 전처리된 스테레오 텐서로 전달합니다. flash와flash_hub는 ACE-Step의 self-attention에 대해 FlashAttention의 네이티브 sliding-window 지원을 사용하며, 패딩이 없는 텍스트 배치(batch)를 가정합니다. 배치된 프롬프트에 패딩이 포함된 경우, 대신flash_varlen또는flash_varlen_hub를 사용하세요.padding="longest"를 사용한 단일 프롬프트 추론은 일반적으로 패딩이 없습니다.
import torch
import soundfile as sf
from diffusers import AceStepPipeline
pipe = AceStepPipeline.from_pretrained("ACE-Step/acestep-v15-xl-turbo-diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda") # or "mps", "xpu", "cpu"
audio = pipe(
prompt="A beautiful piano piece with soft melodies and gentle rhythm",
lyrics="[verse]\nSoft notes in the morning light\nDancing through the air so bright\n[chorus]\nMusic fills the air tonight\nEvery note feels just right",
audio_duration=30.0,
).audios
sf.write("output.wav", audio[0].T.cpu().float().numpy(), pipe.sample_rate)AceStepPipeline
클래스 diffusers.AceStepPipeline
< source >( vae: AutoencoderOoblecktext_encoder: PreTrainedModeltokenizer: TokenizersBackendtransformer: AceStepTransformer1DModelcondition_encoder: AceStepConditionEncoderscheduler: FlowMatchEulerDiscreteScheduleraudio_tokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenizer] = Noneaudio_token_detokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenDetokenizer] = None )
매개변수
- vae (AutoencoderOobleck) — 음성 웨이브폼을 잠재 표현으로 인코딩하고 디코딩하는 Variational Auto-Encoder (VAE) 모델.
- text_encoder (AutoModel) — 텍스트 프롬프트와 가사를 인코딩하는 텍스트 인코더 모델 (예: Qwen3-Embedding-0.6B).
- tokenizer (AutoTokenizer) — 텍스트 인코더용 토크나이저.
- transformer (AceStepTransformer1DModel) — 오디오 잠재 변수의 노이즈 제거를 위한 Diffusion Transformer (DiT) 모델.
- condition_encoder (
AceStepConditionEncoder) — 크로스 어텐션을 위해 텍스트, 가사, 음색 임베딩을 결합하는 조건 인코더입니다. - scheduler (FlowMatchEulerDiscreteScheduler) —
Flow-matching Euler 스케줄러입니다. ACE-Step은 DiT에
[0, 1]범위의 timesteps를 전달하므로, 스케줄러는num_train_timesteps=1과shift=1.0로 구성됩니다. 파이프라인은 자체적으로 shifted / turbo sigma 스케줄을 계산하고set_timesteps(sigmas=...)를 통해 전달합니다.
ACE-Step 1.5를 사용한 텍스트-음악 생성을 위한 Pipeline입니다.
이 모델은 DiffusionPipeline에서 상속됩니다. 모든 파이프라인에 대해 구현된 일반적 메서드(다운로드, 저장, 특정 디바이스에서 실행 등)에 대해서는 상위 클래스 문서를 확인하세요.
pipeline은 diffusion 프로세스를 위해 커스텀 timestep schedule을 사용하는 flow matching을 사용합니다. turbo 모델 변형은 기본적으로 8개의 추론 단계를 사용합니다.
지원하는 작업 유형:
"text2music": 텍스트 프롬프트와 가사에서 음악을 생성합니다."cover": 소스 오디오/시맨틱 코드를 기반으로 참조 오디오의 음색을 이식하여 오디오를 생성합니다."repaint": 기존 오디오의 일부만 재생성하고 나머지는 유지합니다."extract": 오디오에서 특정 트랙(예: 보컬, 드럼)을 추출합니다."lego": 오디오 컨텍스트에 기반하여 특정 트랙을 생성합니다."complete": 추가 트랙을 사용하여 입력 오디오를 완성합니다.
__call__
< source >( prompt: typing.Union[str, typing.List[str]] = Nonelyrics: typing.Union[str, typing.List[str]] = ''audio_duration: float = 60.0vocal_language: typing.Union[str, typing.List[str]] = 'en'num_inference_steps: int = 8guidance_scale: float = 7.0shift: float = 3.0generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pt'return_dict: bool = Truecallback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = Nonecallback_steps: typing.Optional[int] = 1callback_on_step_end: typing.Optional[typing.Callable[..., dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ('latents',)instruction: typing.Optional[str] = Nonemax_text_length: int = 256max_lyric_length: int = 2048bpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonetask_type: str = 'text2music'track_name: typing.Optional[str] = Nonecomplete_track_classes: typing.Optional[typing.List[str]] = Nonesrc_audio: typing.Optional[torch.Tensor] = Nonereference_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonerepainting_start: typing.Optional[float] = Nonerepainting_end: typing.Optional[float] = Noneaudio_cover_strength: float = 1.0cfg_interval_start: float = 0.0cfg_interval_end: float = 1.0timesteps: typing.Optional[typing.List[float]] = Noneattention_kwargs: typing.Optional[dict] = None ) → AudioPipelineOutput or tuple
매개변수
- prompt (
str또는List[str], 선택 사항) — 음악 생성을 안내하는 프롬프트입니다. 스타일, 장르, 악기 등을 설명합니다. - lyrics (
str또는List[str], 선택 사항, 기본값"") — 음악의 가사 텍스트입니다.[verse],[chorus]와 같은 태그를 사용한 구조화된 가사를 지원합니다. - audio_duration (
float, 선택 사항, 기본값 60.0) — 생성된 오디오의 길이(초). - vocal_language (
str또는List[str], 선택 사항, 기본값"en") — 가사의 언어 코드(예:"en","zh","ja"). - num_inference_steps (
int, 선택 사항, 기본값 8) — 디노이징 단계 수입니다. 터보 모델은 8단계를 위해 설계되었습니다. - guidance_scale (
float, 선택 사항, 기본값 7.0) — Classifier-free guidance의 guidance scale입니다. 1.0으로 설정하면 CFG가 비활성화됩니다. - shift (
float, 선택 사항, 기본값 3.0) — 타임스텝 스케줄의 Shift 파라미터 (1.0, 2.0 또는 3.0). - generator (
torch.Generator또는List[torch.Generator], 선택) — 생성을 결정적으로 만들기 위한 생성기입니다. - latents (
torch.Tensor, 선택 사항) —(batch_size, latent_length, acoustic_dim)형태의 사전 생성된 노이즈 latents입니다. - output_type (
str, 선택 사항, 기본값"pt") — 출력 형식입니다. PyTorch 텐서는"pt", NumPy 배열은"np", 원시 잠재 변수는"latent"를 사용합니다. - return_dict (
bool, 선택 사항, 기본값True) —AudioPipelineOutput을 반환할지, 아니면 일반 튜플을 반환할지를 결정합니다. - callback (
Callable, 선택 사항) —(step, timestep, latents)인수를 받아callback_steps스텝마다 호출되는 함수입니다. - callback_steps (
int, 선택 사항, 기본값 1) — 콜백 함수의 실행 주기. - callback_on_step_end (
Callable, 선택 사항) — 추론 중 각 디노이징 단계의 끝에서 호출되는 함수입니다. 이 함수는 다음 인수를 받아 호출됩니다:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargs에는callback_on_step_end_tensor_inputs로 지정된 모든 텐서 목록이 포함됩니다. - callback_on_step_end_tensor_inputs (
List, 선택 사항) —callback_on_step_end함수의 텐서 입력 목록입니다. 목록에 지정된 텐서는callback_kwargs인수로 전달됩니다. 파이프라인 클래스의._callback_tensor_inputs속성에 나열된 변수만 포함할 수 있습니다. - instruction (
str, 선택 사항) — 생성 작업에 사용할 사용자 지정 지시문입니다. 제공되지 않으면task_type에 기반하여 자동으로 생성됩니다. - max_text_length (
int, 선택 사항, 기본값 256) — 텍스트 프롬프트 인코딩을 위한 최대 토큰 길이입니다. - max_lyric_length (
int, 선택 사항, 기본값 2048) — 가사 인코딩을 위한 최대 토큰 길이입니다. - bpm (
int, 선택 사항) — 음악 메타데이터의 BPM(분당 박수).None인 경우 모델이 추정합니다. - keyscale (
str, 선택 사항) — 음악의 킷(예:"C major","A minor").None인 경우 모델이 추정합니다. - timesignature (
str, 선택 사항) — 박자표 (예: 4/4는"4", 3/4는"3").None인 경우 모델이 추정합니다. - task_type (
str, 선택 사항, 기본값"text2music") — 생성 작업 유형입니다."text2music","cover","repaint","extract","lego","complete"중 하나입니다. - track_name (
str, 선택 사항) —"extract"또는"lego"작업에 사용할 트랙 이름 (예:"vocals","drums"). - complete_track_classes (
List[str], 선택 사항) —"complete"작업에 대한 트랙 클래스입니다. - src_audio (
torch.Tensor, 선택 사항) — 오디오-투-오디오 작업(Repaint, Lego, Cover, Extract, Complete)을 위한 48kHz의[channels, samples]형식 소스 오디오 텐서입니다. 오디오는 VAE를 통해 인코딩되어 소스 라텐트를 생성합니다. - reference_audio (
torch.Tensor, 선택 사항) — 음색 조건화를 위한 48kHz의[channels, samples]형식 참조 오디오 텐서. 스타일 전이를 위해 음색 특성을 추출하는 데 사용됩니다. - audio_codes (
str또는List[str], 선택 사항) — 오디오 의미론 코드 문자열(예:"<|audio_code_123|><|audio_code_456|>..."). 이 값이 제공되면 작업이 자동으로"cover"모드로 전환되며, 등록된 ACE-Step 오디오 토크나이저/디토크나이저 모듈이 5 Hz 코드를 25 Hz 음향 조건으로 디코딩합니다. - repainting_start (
float, 선택 사항) —"repaint"및"lego"작업의 경우, 재도색 영역의 시작 시간(초 단위). - repainting_end (
float, 선택 사항) — 재도색 영역의 종료 시간(초). 끝까지 적용하려면-1또는None을 사용하세요. - audio_cover_strength (
float, 선택 사항, 기본값 1.0) — 오디오 커버 블렌딩의 강도(0.0~1.0). 1.0 미만이면 커버 조건부 출력과 텍스트만 조건부 출력을 혼합합니다. 값이 낮을수록 스타일 전이 효과가 더 강해집니다. - cfg_interval_start (
float, 선택 사항, 기본값 0.0) — CFG가 적용되는 타임스텝 범위의 시작 비율(0.0-1.0). - cfg_interval_end (
float, 선택 사항, 기본값 1.0) — CFG가 적용되는 타임스텝 범위의 끝 비율(0.0-1.0). - timesteps (
List[float], 선택 사항) — 사용자 정의 timestep 스케줄입니다. 제공되면num_inference_steps와shift를 덮어씁니다. - attention_kwargs (
dict, 선택 사항) —AttentionProcessor에 전달되는 kwargs 사전입니다.{"scale": float}를 통해 LoRA scale을 전달하는 데 사용됩니다.
반환값
AudioPipelineOutput 또는 tuple
return_dict가 True인 경우 AudioPipelineOutput가 반환되고, 그렇지 않으면 생성된 오디오가 포함된 튜플이 반환됩니다.
음악 생성을 위한 pipeline의 호출 함수.
예:
>>> import torch
>>> import soundfile as sf
>>> from diffusers import AceStepPipeline
>>> pipe = AceStepPipeline.from_pretrained(
... "ACE-Step/acestep-v15-xl-turbo-diffusers", torch_dtype=torch.bfloat16
... )
>>> pipe = pipe.to("cuda")
>>> # Text-to-music generation with metadata
>>> audio = pipe(
... prompt="A beautiful piano piece with soft melodies",
... lyrics="[verse]\nSoft notes in the morning light\n[chorus]\nMusic fills the air tonight",
... audio_duration=30.0,
... num_inference_steps=8,
... bpm=120,
... keyscale="C major",
... timesignature="4",
... ).audios
>>> # Save the generated audio
>>> sf.write("output.wav", audio[0, 0].cpu().numpy(), 48000)
>>> # Repaint task: regenerate a section of existing stereo 48kHz audio
>>> src_audio, sr = sf.read("input.wav")
>>> src_audio = torch.from_numpy(src_audio).float().T
>>> audio = pipe(
... prompt="Epic rock guitar solo",
... lyrics="",
... task_type="repaint",
... src_audio=src_audio,
... repainting_start=10.0,
... repainting_end=20.0,
... ).audios
>>> # Cover task with reference audio for timbre transfer
>>> ref_audio, sr = sf.read("reference.wav")
>>> ref_audio = torch.from_numpy(ref_audio).float().T
>>> audio = pipe(
... prompt="Pop song with bright vocals",
... lyrics="[verse]\nHello world",
... task_type="cover",
... reference_audio=ref_audio,
... audio_cover_strength=0.8,
... ).audioscheck_inputs
< source >( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]task_type: strnum_inference_steps: intguidance_scale: floatshift: floataudio_cover_strength: floatcfg_interval_start: floatcfg_interval_end: floatrepainting_start: typing.Optional[float]repainting_end: typing.Optional[float] )
noise 텐서를 할당하기 전에 사용자 대상 인수를 검증합니다.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]device: devicevocal_language: typing.Union[str, typing.List[str]] = 'en'audio_duration: float = 60.0instruction: typing.Optional[str] = Nonebpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonemax_text_length: int = 256max_lyric_length: int = 2048 )
매개변수
- prompt (
str또는List[str]) — 음악을 설명하는 텍스트 캡션입니다. - lyrics (
str또는List[str]) — 가사 텍스트. - device (
torch.device) — 텐서를 위한 장치. - vocal_language (
str또는List[str], 선택 사항, 기본값"en") — 가사의 언어 코드입니다. - audio_duration (
float, 선택 사항, 기본값 60.0) — 초 단위의 오디오 길이입니다. - instruction (
str, 선택 사항) — 생성을 위한 지시 텍스트. - bpm (
int, 선택 사항) — 메타데이터에 사용할 BPM(분당 박수). - keyscale (
str, 선택 사항) — 음악의 킷(예:"C major"). - timesignature (
str, 선택 사항) — 박자표 (예: 4/4의 경우"4"). - max_text_length (
int, 선택 사항, 기본값 256) — 텍스트 프롬프트의 최대 토큰 길이입니다. - max_lyric_length (
int, 선택 사항, 기본값 2048) — 가사의 최대 토큰 길이입니다.
텍스트 프롬프트와 가사를 임베딩으로 인코딩합니다.
Text prompts는 전체 text encoder 모델을 통해 인코딩되어 컨텍스트 hidden states를 생성합니다. 가사(Lyrics)는 condition encoder의 lyric encoder가 컨텍스트 인코딩을 담당하므로, text encoder의 embedding layer(token lookup)만 통과합니다.
prepare_latents
< source >( batch_size: intaudio_duration: floatdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = None )
Flow matching 프로세스를 위한 초기 노이즈 latents를 준비합니다.
prepare_reference_audio_latents
< source >( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )
음색 인코더를 위해 참조 오디오를 음향 잠재 변수로 처리합니다.
참조 오디오는 30초(앞, 중간, 뒤에서 각각 10초씩 3개 세그먼트)로 반복/잘린 후 VAE를 통해 인코딩되고, 그 다음 음색 인코더를 위해 전치됩니다.
prepare_src_latents
< source >( device: devicedtype: dtypebatch_size: int = 1src_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonelatent_length: typing.Optional[int] = Nonetask_type: str = 'text2music' )
매개변수
- src_audio (
torch.Tensor, 선택 사항) —self.sample_rate에서[channels, samples]모양의 소스 오디오 텐서 - audio_codes (
str또는List[str], 선택 사항) — 오디오 의미론 코드 문자열. - latent_length (
int, 선택 사항) — 소스 오디오 또는 오디오 코드가 제공되지 않은 경우의 대상 latent 길이입니다. - device (
torch.device) — 대상 디바이스. - dtype (
torch.dtype) — 대상 dtype. - batch_size (
int) — 배치 크기. - task_type (
str) — 현재 작업 유형.
텍스트-음악 및 오디오-오디오 작업을 위한 소스 latents를 준비합니다.