Transformers documentation
WavTokenizer
Este modelo foi publicado em HF papers em 2024-08-29 e contribuído para Hugging Face Transformers em 2026-11-16.
WavTokenizer
Visão geral
WavTokenizer codifica áudio mono de 24 kHz em tokens discretos usando um único codebook, a 40 ou 75 tokens por segundo, dependendo do checkpoint. Ele também pode reconstruir áudio a partir desses tokens.
Esta implementação suporta inferência com WavTokenizerModel para codificação e decodificação, ou WavTokenizerEncoderModel apenas para codificação. A variante de 40 tokens por segundo fornece o tokenizador de áudio para o Apertus 1.5. O treinamento do codec não é suportado.
Este modelo foi contribuído pela Swiss AI Initiative. A implementação original está disponível no GitHub.
Checkpoints disponíveis
Esses checkpoints estão prontos para serem carregados com from_pretrained:
| Checkpoint | Domínio | Tokens por segundo |
|---|---|---|
| Pequeno, 40 tokens/s | Fala | 40 |
| Pequeno, 75 tokens/s | Fala | 75 |
| Médio | Fala | 75 |
| Médio v2 | Fala | 75 |
| Médio | Música/áudio | 75 |
| Médio v2 | Música/áudio | 75 |
| Unificado grande | Unificado | 40 |
| Large v2 | Fala | 75 |
Exemplo de uso
Carregue um trecho de fala, reamostra-o para a taxa de amostragem do checkpoint e codifique e reconstrua-o:
import torch
from transformers import AutoFeatureExtractor, WavTokenizerModel
from transformers.audio_utils import load_audio
model_id = "swiss-ai/wavtokenizer-large-unify-40token"
model = WavTokenizerModel.from_pretrained(model_id)
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
audio = load_audio(
"https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/belinda.wav",
sampling_rate=feature_extractor.sampling_rate,
)
inputs = feature_extractor(audio=audio, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt")
with torch.no_grad():
audio_codes = model.encode(**inputs).audio_codes
reconstruction = model.decode(audio_codes).audio_values[..., : len(audio)]Notas de uso
- Entradas de áudio: O extrator de características espera áudio mono na taxa de amostragem configurada; ele não realiza reamostragem nem downmix. O exemplo usa
load_audiopara lidar com ambos. A decodificação pode adicionar amostras finais devido ao padding interno, portanto o exemplo recorta a reconstrução para o comprimento original. - Loteamento: O preenchimento de clipes de diferentes comprimentos pode alterar seus códigos. Codifique os clipes separadamente quando precisar dos mesmos códigos que seriam obtidos ao processar cada clipe individualmente.
- Precisão: Carregue e execute o tokenizer em
float32(o padrão). Uma precisão menor pode alterar as atribuições de código.
WavTokenizerConfig
classe transformers.WavTokenizerConfig
< 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 = Nonesampling_rate: int = 24000audio_channels: int = 1num_filters: int = 32upsampling_ratios: list[int] | tuple[int, ...] = (6, 5, 5, 4)num_residual_layers: int = 1dilation_growth_rate: int = 2compress: int = 2use_conv_shortcut: bool = Trueuse_causal_conv: bool = Falsepad_mode: str = 'reflect'norm_type: str = 'weight_norm'kernel_size: int = 7last_kernel_size: int = 7residual_kernel_size: int = 3num_lstm_layers: int = 2hidden_size: int = 512codebook_size: int = 4096codebook_dim: int = 512decoder_hidden_size: int = 768decoder_intermediate_size: int = 2304decoder_num_layers: int = 12adanorm_num_embeddings: int = 4decoder_attention_num_groups: int = 32norm_eps: float = 1e-06 )
Parâmetros
- sampling_rate (
int, opcional, padrão24000) — A taxa de amostragem na qual os arquivos de áudio devem ser digitalizados, expressa em hertz (Hz). - audio_channels (
int, opcional, padrão 1) — Número de canais nos dados de áudio. Apenas mono (1) é suportado. - num_filters (
int, opcional, padrão 32) — Número de núcleos de convolução da primeira camada de redução de amostragemWavTokenizerConv1d. - upsampling_ratios (
list[int], opcional, padrão[6, 5, 5, 4]) — Razões de tamanho de kernel e stride. O codificador usa razões de downsampling em vez de razões de upsampling, portanto ele usará as razões na ordem inversa àquelas especificadas aqui, que devem corresponder à ordem do decodificador. O produto (600 por padrão) é o hop length: o número de amostras de áudio representadas por um único código. - num_residual_layers (
int, opcional, padrão 1) — Número de camadas residuais em cada estágio do codificador. - dilation_growth_rate (
int, opcional, padrão 2) — Quanto aumentar a dilatação em cada camada residual no codificador. - compress (
int, opcional, padrão 2) — Dimensão reduzida nos ramos residuais. - use_conv_shortcut (
bool, opcional, padrãoTrue) — Se deve usar uma camada convolucional como atalho (skip) nos blocos residuais. Se False, uma função identidade será usada, resultando em uma conexão residual genérica. - use_causal_conv (
bool, opcional, padrãoFalse) — Se deve usar convolução totalmente causal. - pad_mode (
str, opcional, padrão"reflect") — Modo de preenchimento para as convoluções. - norm_type (
str, opcional, padrão"weight_norm") — Método de normalização para as convoluções do codificador. Deve estar em["weight_norm", "time_group_norm"]. - kernel_size (
int, opcional, padrão 7) — Tamanho do kernel para a convolução inicial do codificador. - last_kernel_size (
int, opcional, padrão 7) — Tamanho do kernel para a última convolução do codificador. - residual_kernel_size (
int, opcional, padrão 3) — Tamanho do kernel para as camadas residuais do codificador. - num_lstm_layers (
int, opcional, padrão 2) — Número de camadas LSTM no final do codificador. - hidden_size (
int, opcional, padrão 512) — Dimensão da saída do codificador (o espaço latente do quantizador). - codebook_size (
int, opcional, padrão 4096) — Número de códigos discretos que compõem o único codebook VQ. - codebook_dim (
int, opcional, padrão 512) — Dimensão dos vetores do codebook. Deve corresponder ahidden_size(nenhuma projeção é utilizada). - decoder_hidden_size (
int, opcional, padrão 768) — Dimensão do backbone do decodificador no estilo Vocos. - decoder_intermediate_size (
int, opcional, padrão 2304) — Dimensão das convoluções pointwise dentro dos blocos ConvNeXt do decoder. - decoder_num_layers (
int, opcional, padrão 12) — Número de blocos ConvNeXt no backbone do decodificador. - adanorm_num_embeddings (
int, opcional, padrão 4) — Número de embeddings de condição das camadas de normalização adaptativas do decodificador. A condição é um recurso de tempo de treinamento (um embedding por largura de banda); a inferência sempre usa o embedding 0. - decoder_attention_num_groups (
int, opcional, padrão 32) — Número de grupos das camadas GroupNorm do decoder. - norm_eps (
float, opcional, padrão 1e-06) — Epsilon das camadas de normalização do decodificador.
Esta é a classe de configuração para armazenar a configuração de um WavTokenizerModel. Ela é usada para instanciar um modelo Wavtokenizer de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do swiss-ai/wavtokenizer-large-unify-40token
Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.
Exemplo:
>>> from transformers import WavTokenizerConfig, WavTokenizerModel
>>> # Initializing configuration
>>> configuration = WavTokenizerConfig()
>>> # Initializing a model (with random weights) from the configuration
>>> model = WavTokenizerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configWavTokenizerEncoderConfig
classe transformers.WavTokenizerEncoderConfig
< 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 = Nonesampling_rate: int = 24000audio_channels: int = 1num_filters: int = 32upsampling_ratios: list[int] | tuple[int, ...] = (6, 5, 5, 4)num_residual_layers: int = 1dilation_growth_rate: int = 2compress: int = 2use_conv_shortcut: bool = Trueuse_causal_conv: bool = Falsepad_mode: str = 'reflect'norm_type: str = 'weight_norm'kernel_size: int = 7last_kernel_size: int = 7residual_kernel_size: int = 3num_lstm_layers: int = 2hidden_size: int = 512codebook_size: int = 4096codebook_dim: int = 512decoder_hidden_size: int = 768decoder_intermediate_size: int = 2304decoder_num_layers: int = 12adanorm_num_embeddings: int = 4decoder_attention_num_groups: int = 32norm_eps: float = 1e-06 )
Configuração do WavTokenizerEncoderModel, o codificador e quantizador do WavTokenizer. Ele compartilha todos os campos com WavTokenizerConfig (consulte sua documentação para os argumentos), portanto, pode ser carregado de um checkpoint completo do WavTokenizer. Os campos específicos do decodificador não são usados pelo modelo de codificador.
WavTokenizerFeatureExtractor
classe transformers.WavTokenizerFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0hop_length: int = 600normalize_audio: bool = Falsetarget_peak_dB_FS: float = -3.0**kwargs )
Parâmetros
- feature_size (
int, opcional, padrão 1) — A dimensão da característica dos recursos extraídos. Apenas mono (1) é suportado. - sampling_rate (
int, opcional, padrão 24000) — A taxa de amostragem na qual a forma de onda de áudio deve ser digitalizada, expressa em hertz (Hz). - padding_value (
float, opcional, padrão 0.0) — O valor utilizado para preenchimento. - hop_length (
int, opcional, padrão 600) — Número de amostras de áudio representadas por um único código de áudio. - normalize_audio (
bool, opcional, padrãoFalse) — Se normalizar por pico cada clipe paratarget_peak_dB_FSantes do padding. O WavTokenizer original não normaliza; o Apertus 1.5 habilita isso. - target_peak_dB_FS (
float, opcional, padrão -3.0) — Nível de pico alvo em dB FS usado quandonormalize_audioéTrue.
Constrói um extrator de recursos WavTokenizer para áudio mono na taxa de amostragem configurada. O áudio não é reamostrado nem reduzido para mono.
__call__
< source >( audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']]padding: bool | str | transformers.utils.generic.PaddingStrategy | None = Nonetruncation: bool | None = Falsemax_length: int | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonesampling_rate: int | None = None ) → BatchFeature
Parâmetros
- audio (
np.ndarray,torch.Tensor,list[float],list[np.ndarray],list[torch.Tensor],list[list[float]]) — A sequência ou lote de sequências a ser processada. Cada sequência deve ser áudio mono de forma(num_samples,), já amostrada nasampling_ratedeste extrator de recursos. O áudio não é reamostrado nem reduzido para mono. - padding (
bool,strou PaddingStrategy, opcional, padrãoTrue) — Estratégia de preenchimento:Trueou'longest'preenche um lote até a sequência mais longa (entradas únicas permanecem sem preenchimento),'max_length'preenche atémax_length,Falseou'do_not_pad'desativa o preenchimento. - truncation (
bool, opcional, padrãoFalse) — Sequências mais longas quemax_lengthdevem ser truncadas paramax_length. - max_length (
int, opcional) — Comprimento alvo para o preenchimento de'max_length'e para atruncation. - return_tensors (
strou TensorType, opcional) — Se definido, retorna tensores em vez de uma lista de arrays numpy:'pt'para PyTorchtorch.Tensor,'np'para NumPynp.ndarray. - sampling_rate (
int, opcional) — Taxa de amostragem da entradaaudio; passe-a para que uma incompatibilidade com asampling_rateconfigurada gere um erro em vez de falhar silenciosamente.
Retorna
Um BatchFeature com os seguintes campos:
- input_values — Formas de onda de áudio a serem fornecidas ao modelo, como uma lista de arrays de forma
(1, num_samples), ou um tensor de forma(batch_size, 1, num_samples)quandoreturn_tensorsestá definido. - padding_mask — Máscara que indica amostras de áudio válidas (1) em relação ao preenchimento (0), com forma
(batch_size, num_samples).
Extraia recursos e prepare uma ou várias sequências de áudio para o modelo.
WavTokenizerEncoderModel
classe transformers.WavTokenizerEncoderModel
< source >( config: WavTokenizerEncoderConfig )
Parâmetros
- config (WavTokenizerEncoderConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
Codificador e quantizador do WavTokenizer para converter formas de onda de áudio em códigos discretos.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
encode
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerEncoderOutput or tuple(torch.Tensor)
Parâmetros
- input_values (
torch.Tensorde forma(batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada. Comprimentos não nulos arbitrários são suportados; o codificador faz o preenchimento internamente e emiteceil(sequence_length / hop_length)códigos. - padding_mask (
torch.Tensorde forma(batch_size, sequence_length)ou(batch_size, 1, sequence_length), opcional) — Máscara que descreve o preenchimento eminput_values; usada para calcularaudio_codes_mask.
Retorna
WavTokenizerEncoderOutput ou tuple(torch.Tensor)
Um WavTokenizerEncoderOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos dependendo da configuração (None) e das entradas.
- audio_codes (
torch.LongTensorde forma(batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usandomodel.encode. Esses representam a forma comprimida e quantizada do sinal de áudio de entrada (um codebook,ceil(num_samples / hop_length)códigos). - audio_codes_mask (
torch.Tensorde forma(batch_size, 1, codes_length), opcional) —padding_maskreduzido indicando os códigos de áudio válidos emaudio_codes.
forward
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerEncoderOutput or tuple(torch.Tensor)
Parâmetros
- input_values (
torch.Tensorde forma(batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada. - padding_mask (
torch.Tensorde forma(batch_size, sequence_length)ou(batch_size, 1, sequence_length), opcional) — Máscara de preenchimento usada para calcularaudio_codes_mask.
Retorna
WavTokenizerEncoderOutput ou tuple(torch.Tensor)
Um WavTokenizerEncoderOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos, dependendo da configuração (WavTokenizerConfig) e das entradas.
O método forward do WavTokenizerEncoderModel sobrescreve o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
- audio_codes (
torch.LongTensorde forma(batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usandomodel.encode. Esses representam a forma comprimida e quantizada do sinal de áudio de entrada (um codebook,ceil(num_samples / hop_length)códigos). - audio_codes_mask (
torch.Tensorde forma(batch_size, 1, codes_length), opcional) —padding_maskreduzido indicando os códigos de áudio válidos emaudio_codes.
WavTokenizerModel
classe transformers.WavTokenizerModel
< source >( config: WavTokenizerConfig )
Parâmetros
- config (WavTokenizerConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.
Codificador neural de áudio WavTokenizer com um único codebook, apenas para inferência.
Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)
Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.
decode
< source >( audio_codes: Tensorbandwidth_id: int = 0**kwargs ) → WavTokenizerDecoderOutput or tuple(torch.Tensor)
Parâmetros
- audio_codes (
torch.LongTensorde forma(batch_size, 1, codes_length)) — Índices de códigos discretos calculados usandomodel.encode. Um ou mais códigos são suportados; cada código decodifica parahop_lengthamostras de áudio. - bandwidth_id (
int, opcional, padrão 0) — ID do embedding de condição das camadas de normalização adaptativas do decodificador. Sempre 0 na inferência.
Retorna
WavTokenizerDecoderOutput ou tuple(torch.Tensor)
Um WavTokenizerDecoderOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos dependendo da configuração (None) e das entradas.
- audio_values (
torch.Tensorde forma(batch_size, 1, sequence_length), opcional) — Valores da forma de onda de áudio decodificados no domínio do tempo (codes_length * hop_lengthamostras).
encode
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerEncoderOutput or tuple(torch.Tensor)
Parâmetros
- input_values (
torch.Tensorde forma(batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada. Comprimentos não nulos arbitrários são suportados; o codificador faz o preenchimento internamente e emiteceil(sequence_length / hop_length)códigos. - padding_mask (
torch.Tensorde forma(batch_size, sequence_length)ou(batch_size, 1, sequence_length), opcional) — Máscara que descreve o preenchimento eminput_values; usada para calcularaudio_codes_mask.
Retorna
WavTokenizerEncoderOutput ou tuple(torch.Tensor)
Um WavTokenizerEncoderOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos dependendo da configuração (None) e das entradas.
- audio_codes (
torch.LongTensorde forma(batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usandomodel.encode. Esses representam a forma comprimida e quantizada do sinal de áudio de entrada (um codebook,ceil(num_samples / hop_length)códigos). - audio_codes_mask (
torch.Tensorde forma(batch_size, 1, codes_length), opcional) —padding_maskreduzido indicando os códigos de áudio válidos emaudio_codes.
forward
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerOutput or tuple(torch.Tensor)
Parâmetros
- input_values (
torch.Tensorde forma(batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada. - padding_mask (
torch.Tensorde forma(batch_size, sequence_length)ou(batch_size, 1, sequence_length), opcional) — Máscara que indica amostras de áudio válidas (1) em relação ao preenchimento (0), usada para calcularaudio_codes_mask.
Retorna
WavTokenizerOutput ou tuple(torch.Tensor)
Um WavTokenizerOutput ou uma tupla de
torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários
elementos dependendo da configuração (None) e das entradas.
O método forward do WavTokenizerModel substitui o método especial __call__.
Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de
Moduleem seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.
- audio_values (
torch.Tensorde forma(batch_size, 1, sequence_length), opcional) — Valores da forma de onda de áudio decodificados no domínio do tempo, obtidos usando a parte decodificadora do WavTokenizer. - audio_codes (
torch.LongTensorde forma(batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usandomodel.encode. - audio_codes_mask (
torch.Tensorde forma(batch_size, 1, codes_length), opcional) —padding_maskreduzido indicando os códigos de áudio válidos emaudio_codes.