Transformers documentation

VibeVoice Acoustic Tokenizer

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

이 모델은 2025-08-26에 HF papers에 게시되었으며, 2026-02-06에 Hugging Face Transformers에 기여되었습니다.

VibeVoice Acoustic Tokenizer

개요

VibeVoice는 Large Language Model(LLM) 구조 내에서 next-token diffusion 방식을 활용하여 다수의 화자가 포함된 고해상도 장문 음성 합성을 위한 새로운 프레임워크입니다. 자연스러운 대화의 'vibe'를 포착하도록 설계되었으며, 팟캐스트나 다중 참여자 오디오북과 같은 오디오 콘텐츠 생성에 특히 적합합니다.

VibeVoice의 핵심 기능 중 하나는 연속 오디오 토크나이저 두 개를 사용하는 것입니다. 하나는 음향 특징을 추출하고, 다른 하나는 의미론적 특징을 추출합니다.

모델 체크포인트는 microsoft/VibeVoice-AcousticTokenizer에서 사용할 수 있습니다.

이 모델은 Eric Bezzam이 기여했습니다.

아키텍처

아키텍처는 거울 대칭형 인코더-디코더 구조입니다. 인코더는 1D depth-wise causal convolution을 사용하여 효율적인 스트리밍 처리를 수행하는 ConvNeXt 유사 블록 7단계로 구성된 계층적 설계를 채택합니다. 6개의 다운샘플링 레이어를 통해 24kHz 입력에서 누적 3200X 다운샘플링 비율을 달성하여 초당 7.5개의 토큰/프레임을 생성합니다. 각 인코더/디코더 구성 요소에는 약 340M개의 매개변수가 포함되어 있으며, 전체 매개변수는 약 680M개입니다. 학습 목표는 DAC의 것을 따르며, 그 판별기 및 손실 설계도 포함합니다.

Acoustic Tokenizer는 Variational Autoencoder(VAE)의 원리를 채택합니다. 인코더는 입력 오디오를 잠재 분포의 매개변수, 즉 평균으로 매핑합니다. 고정된 표준편차와 함께, 재매개변수화 트릭을 사용하여 잠재 벡터를 샘플링합니다. 자세한 내용은 기술 보고서를 참조하세요.

사용

다음은 오디오를 인코딩하고 디코딩하는 사용 예시입니다:

import torch
from scipy.io import wavfile

from transformers import AutoFeatureExtractor, VibeVoiceAcousticTokenizerModel
from transformers.audio_utils import load_audio_librosa


model_id = "microsoft/VibeVoice-AcousticTokenizer"

# load model
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
model = VibeVoiceAcousticTokenizerModel.from_pretrained(model_id, device_map="auto")
print("Model loaded on device:", model.device)
print("Model dtype:", model.dtype)

# load audio
audio = load_audio_librosa(
    "https://huggingface.co/datasets/bezzam/vibevoice_samples/resolve/main/voices/en-Alice_woman.wav",
    sampling_rate=feature_extractor.sampling_rate,
)

# preprocess audio
inputs = feature_extractor(
    audio,
    sampling_rate=feature_extractor.sampling_rate,
    pad_to_multiple_of=3200,
).to(model.device, model.dtype)
print("Input audio shape:", inputs.input_values.shape)
# Input audio shape: torch.Size([1, 1, 224000])

with torch.no_grad():
    # set VAE sampling to False for deterministic output
    encoded_outputs = model.encode(inputs.input_values, sample=False)
    print("Latent shape:", encoded_outputs.latents.shape)
    # Latent shape: torch.Size([1, 70, 64])

    decoded_outputs = model.decode(**encoded_outputs)
    print("Reconstructed audio shape:", decoded_outputs.audio.shape)
    # Reconstructed audio shape: torch.Size([1, 1, 224000])

# Save audio
output_fp = "vibevoice_acoustic_tokenizer_reconstructed.wav"
wavfile.write(output_fp, feature_extractor.sampling_rate, decoded_outputs.audio.squeeze().float().cpu().numpy())
print(f"Reconstructed audio saved to : {output_fp}")

스트리밍

캐시된 상태를 추적해야 하는 스트리밍 ASR 또는 TTS의 경우, 오디오를 인코딩하거나 디코딩할 때 use_cache 매개변수를 사용할 수 있습니다:

import torch
from scipy.io import wavfile

from transformers import AutoFeatureExtractor, VibeVoiceAcousticTokenizerModel
from transformers.audio_utils import load_audio_librosa


model_id = "microsoft/VibeVoice-AcousticTokenizer"

# load model
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
model = VibeVoiceAcousticTokenizerModel.from_pretrained(model_id, device_map="auto")
print("Model loaded on device:", model.device)
print("Model dtype:", model.dtype)

# load audio
audio = load_audio_librosa(
    "https://huggingface.co/datasets/bezzam/vibevoice_samples/resolve/main/voices/en-Alice_woman.wav",
    sampling_rate=feature_extractor.sampling_rate,
)

# preprocess audio
inputs = feature_extractor(
    audio,
    sampling_rate=feature_extractor.sampling_rate,
    pad_to_multiple_of=3200,
).to(model.device, model.dtype)
print("Input audio shape:", inputs.input_values.shape)
# Input audio shape: torch.Size([1, 1, 224000])

# cache will be initialized after a first pass
encoder_cache = None
decoder_cache = None
with torch.no_grad():
    # set VAE sampling to False for deterministic output
    encoded_outputs = model.encode(inputs.input_values, sample=False, padding_cache=encoder_cache, use_cache=True)
    print("Latent shape:", encoded_outputs.latents.shape)
    # Latent shape: torch.Size([1, 70, 64])

    decoded_outputs = model.decode(encoded_outputs.latents, padding_cache=decoder_cache, use_cache=True)
    print("Reconstructed audio shape:", decoded_outputs.audio.shape)
    # Reconstructed audio shape: torch.Size([1, 1, 224000])

    # `padding_cache` can be extracted from the outputs for subsequent passes
    encoder_cache = encoded_outputs.padding_cache
    print("Number of cached encoder layers:", len(encoder_cache.per_layer_in_channels))
    # Number of cached encoder layers: 34
    decoder_cache = decoded_outputs.padding_cache
    print("Number of cached decoder layers:", len(decoder_cache.per_layer_in_channels))
    # Number of cached decoder layers: 34

# Save audio
output_fp = "vibevoice_acoustic_tokenizer_reconstructed.wav"
wavfile.write(output_fp, feature_extractor.sampling_rate, decoded_outputs.audio.squeeze().float().cpu().numpy())
print(f"Reconstructed audio saved to : {output_fp}")

VibeVoiceAcousticTokenizerConfig

클래스 transformers.VibeVoiceAcousticTokenizerConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonechannels: int = 1hidden_size: int = 64kernel_size: int = 7rms_norm_eps: float = 1e-05layer_scale_init_value: float = 1e-06initializer_range: float = 0.01num_filters: int = 32downsampling_ratios: list[int] | tuple[int, ...] = (2, 2, 4, 5, 5, 8)depths: list[int] | tuple[int, ...] = (3, 3, 3, 3, 3, 3, 8)hidden_act: str = 'gelu'ffn_expansion: int = 4vae_std: float = 0.625 )

매개변수

channels (int, 선택 사항, 기본값 1) — 입력 채널 수.
hidden_size (int, 선택 사항, 기본값 64) — 잠재 표현의 차원입니다.
kernel_size (int, 선택 사항, 기본값 7) — 합성곱 계층의 커널 크기.
rms_norm_eps (float, 선택 사항, 기본값 1e-05) — rms 정규화 레이어에서 사용되는 epsilon 값입니다.
layer_scale_init_value (float, 선택 사항, 기본값 1e-06) — 자기 주의(self-attention) 레이어에서 사용할 스케일 값입니다. base 모델에는 0.1, large 모델에는 1e-6을 사용합니다. 0으로 설정하면 layer scale을 비활성화합니다.
initializer_range (float, 선택 사항, 기본값 0.01) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.
num_filters (int, 선택 사항, 기본값 32) — 초기 합성곱 계층의 필터 수이며, 각 다운샘플링 이후에 두 배로 증가합니다.
downsampling_ratios (List[int], 선택 사항, 기본값 [2, 2, 4, 5, 5, 8]) — 각 레이어에 대한 다운샘플링 비율입니다.
depths (List[int], 선택 사항, 기본값 [3, 3, 3, 3, 3, 3, 8]) — 각 단계의 ConvNeXt 블록 수입니다.
hidden_act (str, 선택 사항, 기본값 gelu) — 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어, "gelu", "relu", "silu" 등이 있습니다.
ffn_expansion (int, 선택 사항, 기본값 4) — 피드포워드 네트워크의 확장 계수입니다.
vae_std (float, 선택 사항, 기본값 0.625) — 인코더 latents에 노이즈를 추가할 때(sample=True) 샘플별 노이즈 스케일을 추출하는 가우시안 분포의 표준 편차입니다.

이것은 VibeVoiceAcousticTokenizerModel의 설정을 저장하기 위한 설정 클래스입니다. 지정된 인자에 따라 Vibevoice Acoustic Tokenizer 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 설정을 인스턴스화하면 microsoft/VibeVoice-1.5B와 유사한 설정이 생성됩니다.

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

예:

>>> from transformers import VibeVoiceAcousticTokenizerModel, VibeVoiceAcousticTokenizerConfig

>>> # Initializing a VibeVoice Acoustic Tokenizer configuration
>>> configuration = VibeVoiceAcousticTokenizerConfig()

>>> # Initializing a model (with random weights)
>>> model = VibeVoiceAcousticTokenizerModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

VibeVoiceAcousticTokenizerEncoderConfig

클래스 transformers.VibeVoiceAcousticTokenizerEncoderConfig

< source >

매개변수

channels (int, 선택 사항, 기본값 1) — 입력 채널 수.
hidden_size (int, 선택 사항, 기본값 64) — 잠재 표현의 차원입니다.
kernel_size (int, 선택 사항, 기본값 7) — 합성곱 계층의 커널 크기.
rms_norm_eps (float, 선택 사항, 기본값 1e-05) — rms 정규화 레이어에서 사용되는 epsilon 값입니다.
layer_scale_init_value (float, 선택 사항, 기본값 1e-06) — 자기 주의(self-attention) 레이어에서 사용할 스케일 값입니다. base 모델에는 0.1, large 모델에는 1e-6을 사용합니다. 0으로 설정하면 layer scale을 비활성화합니다.
initializer_range (float, 선택 사항, 기본값 0.01) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.
num_filters (int, 선택 사항, 기본값 32) — 초기 합성곱 계층의 필터 수이며, 각 다운샘플링 이후에 두 배로 증가합니다.
downsampling_ratios (List[int], 선택 사항, 기본값 [2, 2, 4, 5, 5, 8]) — 각 레이어에 대한 다운샘플링 비율입니다.
depths (List[int], 선택 사항, 기본값 [3, 3, 3, 3, 3, 3, 8]) — 각 단계의 ConvNeXt 블록 수입니다.
hidden_act (str, 선택 사항, 기본값 gelu) — 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어, "gelu", "relu", "silu" 등이 있습니다.
ffn_expansion (int, 선택 사항, 기본값 4) — 피드포워드 네트워크의 확장 계수입니다.
vae_std (float, 선택 사항, 기본값 0.625) — 인코더 latents에 노이즈를 추가할 때(sample=True) 샘플별 노이즈 스케일을 추출하는 가우시안 분포의 표준 편차입니다.

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

VibeVoiceAcousticTokenizerDecoderConfig

클래스 transformers.VibeVoiceAcousticTokenizerDecoderConfig

< source >

매개변수

channels (int, 선택 사항, 기본값 1) — 입력 채널 수.
hidden_size (int, 선택 사항, 기본값 64) — 잠재 표현의 차원입니다.
kernel_size (int, 선택 사항, 기본값 7) — 합성곱 계층의 커널 크기.
rms_norm_eps (float, 선택 사항, 기본값 1e-05) — rms 정규화 레이어에서 사용되는 epsilon 값입니다.
layer_scale_init_value (float, 선택 사항, 기본값 1e-06) — 자기 주의(self-attention) 레이어에서 사용할 스케일 값입니다. base 모델에는 0.1, large 모델에는 1e-6을 사용합니다. 0으로 설정하면 layer scale을 비활성화합니다.
initializer_range (float, 선택 사항, 기본값 0.01) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.
num_filters (int, 선택 사항, 기본값 32) — 초기 합성곱 계층의 필터 수이며, 각 다운샘플링 이후에 두 배로 증가합니다.
downsampling_ratios (List[int], 선택 사항, 기본값 [2, 2, 4, 5, 5, 8]) — 각 레이어에 대한 다운샘플링 비율입니다.
depths (List[int], 선택 사항, 기본값 [3, 3, 3, 3, 3, 3, 8]) — 각 단계의 ConvNeXt 블록 수입니다.
hidden_act (str, 선택 사항, 기본값 gelu) — 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어, "gelu", "relu", "silu" 등이 있습니다.
ffn_expansion (int, 선택 사항, 기본값 4) — 피드포워드 네트워크의 확장 계수입니다.
vae_std (float, 선택 사항, 기본값 0.625) — 인코더 latents에 노이즈를 추가할 때(sample=True) 샘플별 노이즈 스케일을 추출하는 가우시안 분포의 표준 편차입니다.

Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.

VibeVoiceAcousticTokenizerFeatureExtractor

class transformers.VibeVoiceAcousticTokenizerFeatureExtractor

< source >

( feature_size = 1sampling_rate = 24000padding_value = 0.0normalize_audio = Truetarget_dB_FS = -25eps = 1e-06pad_to_multiple_of = 3200**kwargs )

매개변수

feature_size (int, 선택 사항, 기본값 1) — 채널 수입니다.
sampling_rate (int, 선택 사항, 기본값 24000) — 오디오 웨이브포름을 디지털화할 때 사용할 샘플링 레이트(헤르츠(Hz) 단위).
padding_value (float, 선택 사항, 기본값 0.0) — 패딩에 사용되는 값입니다.
normalize_audio (bool, 선택 사항, 기본값 True) — 오디오를 목표 dB FS로 정규화할지 여부.
target_dB_FS (float, 선택 사항, 기본값 -25) — 정규화에 사용할 목표 dB FS.
eps (float, 선택 사항, 기본값 1e-06) — 정규화 시 0으로 나누는 것을 방지하기 위한 작은 값입니다.
pad_to_multiple_of (int, 선택, 기본값 3200) — 음성을 이 값의 배수로 패딩합니다. 이 값은 음향 토크나이저의 hop length, 즉 인코더의 다운샘플링 계수에 해당해야 합니다.

VibeVoiceAcousticTokenizer feature extractor를 생성합니다.

call

< source >

( audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']]sampling_rate: int | None = Nonepadding: bool | str | transformers.utils.generic.PaddingStrategy | None = Truepad_to_multiple_of: int | None = Nonemax_length: int | None = Nonereturn_attention_mask: bool | None = Truereturn_tensors: str | None = 'pt'**kwargs )

매개변수

audio (np.ndarray, torch.Tensor, list[np.ndarray], list[torch.Tensor] — 처리할 시퀀스 또는 시퀀스 배치입니다. 각 시퀀스는 numpy 배열, torch 텐서, numpy 배열의 리스트, 또는 torch 텐서의 리스트일 수 있습니다.
sampling_rate (int, 선택 사항) — audio 입력이 샘플링된 샘플링 레이트입니다. 조용한 오류를 방지하려면 forward 호출 시 sampling_rate를 전달하는 것이 강력히 권장됩니다.
padding (bool, str 또는 PaddingStrategy, 선택 사항, 기본값은 True) — 모델의 패딩 방향과 패딩 인덱스에 따라 반환된 시퀀스에 적용할 패딩 전략을 다음 중 선택합니다:
- True 또는 'longest': 배치 내 가장 긴 시퀀스 길이에 맞게 패딩을 수행합니다(단일 시퀀스만 제공된 경우 패딩을 하지 않음).
- 'max_length': max_length 인수로 지정된 최대 길이로 패딩하거나, 해당 인수가 제공되지 않으면 모델이 허용하는 최대 입력 길이로 패딩합니다.
- False 또는 'do_not_pad' (기본값): 패딩을 하지 않습니다(즉, 서로 다른 길이의 시퀀스로 구성된 배치로 출력할 수 있습니다).
pad_to_multiple_of (int, 선택 사항) — 설정된 경우, 제공된 값의 배수로 시퀀스를 패딩합니다. 제공되지 않으면 기본값은 self.pad_to_multiple_of입니다.

VibeVoiceAcousticTokenizerModel

class transformers.VibeVoiceAcousticTokenizerModel

< source >

( config: VibeVoiceAcousticTokenizerConfig )

매개변수

config (VibeVoiceAcousticTokenizerConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

인코더와 디코더를 갖춘 연속 음향 토큰용 VibeVoice 음향 토크나이저.

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.

encode

< source >

( input_valuespadding_cache = Noneuse_cache = Nonesample = True )

매개변수

input_values (torch.Tensor, shape (batch_size, channels, sequence_length)) — 잠재 표현으로 인코딩할 입력 오디오 웨이브폼입니다.
padding_cache (VibeVoiceAcousticTokenizerConv1dPaddingCache, 선택) — 스트리밍 모드에서 레이어 간 컨볼루션 상태를 유지하기 위한 캐시 객체.
use_cache (bool, 선택 사항) — 컨볼루션 상태를 캐싱할지 여부.
sample (bool, 선택 사항) — latents에 가우시안 노이즈를 추가할지 여부입니다 (σ-VAE: 노이즈 스케일은 배치 항목별로 N(0, config.vae_std)에서 추출됩니다). False인 경우 인코더 출력이 그대로 반환됩니다.

decode

< source >

( latentspadding_cache = Noneuse_cache = False )

매개변수

latents (torch.Tensor, shape (batch_size, channels, sequence_length)) — 음성으로 복원될 입력 latent 표현입니다.
padding_cache (VibeVoiceAcousticTokenizerConv1dPaddingCache, 선택) — 스트리밍 모드에서 레이어 간 컨볼루션 상태를 유지하기 위한 캐시 객체.
use_cache (bool, 선택 사항) — 컨볼루션 상태를 캐싱할지 여부.

forward

< source >

( input_valuespadding_cache = Noneuse_cache = Falsesample = True**kwargs )

매개변수

input_values (torch.Tensor, shape (batch_size, channels, sequence_length)) — 잠재 표현으로 인코딩할 입력 오디오 웨이브폼입니다.
padding_cache (VibeVoiceAcousticTokenizerConv1dPaddingCache, 선택 사항) — 스트리밍 모드에서 레이어 간 컨볼루션 상태를 유지하기 위한 캐시 객체. 디코더에서만 사용됩니다.
use_cache (bool, 선택 사항) — 컨볼루션 상태를 캐싱할지 여부.
sample (bool, 선택 사항) — latents에 가우시안 노이즈를 추가할지 여부입니다 (σ-VAE: 노이즈 스케일은 배치 항목별로 N(0, config.vae_std)에서 추출됩니다). False인 경우 인코더 출력이 그대로 반환됩니다.