Transformers documentation

WavTokenizer

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

and get access to the augmented documentation experience

to get started

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:

CheckpointDomínioTokens por segundo
Pequeno, 40 tokens/sFala40
Pequeno, 75 tokens/sFala75
MédioFala75
Médio v2Fala75
MédioMúsica/áudio75
Médio v2Música/áudio75
Unificado grandeUnificado40
Large v2Fala75

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_audio para 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

< >

( 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ão 24000) — 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 amostragem WavTokenizerConv1d.
  • 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ão True) — 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ão False) — 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 a hidden_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.config

WavTokenizerEncoderConfig

classe transformers.WavTokenizerEncoderConfig

< >

( 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

< >

( 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ão False) — Se normalizar por pico cada clipe para target_peak_dB_FS antes 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 quando normalize_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__

< >

( 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 na sampling_rate deste extrator de recursos. O áudio não é reamostrado nem reduzido para mono.
  • padding (bool, str ou PaddingStrategy, opcional, padrão True) — Estratégia de preenchimento: True ou 'longest' preenche um lote até a sequência mais longa (entradas únicas permanecem sem preenchimento), 'max_length' preenche até max_length, False ou 'do_not_pad' desativa o preenchimento.
  • truncation (bool, opcional, padrão False) — Sequências mais longas que max_length devem ser truncadas para max_length.
  • max_length (int, opcional) — Comprimento alvo para o preenchimento de 'max_length' e para a truncation.
  • return_tensors (str ou TensorType, opcional) — Se definido, retorna tensores em vez de uma lista de arrays numpy: 'pt' para PyTorch torch.Tensor, 'np' para NumPy np.ndarray.
  • sampling_rate (int, opcional) — Taxa de amostragem da entrada audio; passe-a para que uma incompatibilidade com a sampling_rate configurada gere um erro em vez de falhar silenciosamente.

Retorna

BatchFeature

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) quando return_tensors está 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

< >

( 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

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerEncoderOutput or tuple(torch.Tensor)

Parâmetros

  • input_values (torch.Tensor de 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 emite ceil(sequence_length / hop_length) códigos.
  • padding_mask (torch.Tensor de forma (batch_size, sequence_length) ou (batch_size, 1, sequence_length), opcional) — Máscara que descreve o preenchimento em input_values; usada para calcular audio_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.LongTensor de forma (batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usando model.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.Tensor de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido indicando os códigos de áudio válidos em audio_codes.

forward

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerEncoderOutput or tuple(torch.Tensor)

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada.
  • padding_mask (torch.Tensor de forma (batch_size, sequence_length) ou (batch_size, 1, sequence_length), opcional) — Máscara de preenchimento usada para calcular audio_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 Module em 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.LongTensor de forma (batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usando model.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.Tensor de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido indicando os códigos de áudio válidos em audio_codes.

WavTokenizerModel

classe transformers.WavTokenizerModel

< >

( 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

< >

( audio_codes: Tensorbandwidth_id: int = 0**kwargs ) → WavTokenizerDecoderOutput or tuple(torch.Tensor)

Parâmetros

  • audio_codes (torch.LongTensor de forma (batch_size, 1, codes_length)) — Índices de códigos discretos calculados usando model.encode. Um ou mais códigos são suportados; cada código decodifica para hop_length amostras 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.Tensor de forma (batch_size, 1, sequence_length), opcional) — Valores da forma de onda de áudio decodificados no domínio do tempo (codes_length * hop_length amostras).

encode

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerEncoderOutput or tuple(torch.Tensor)

Parâmetros

  • input_values (torch.Tensor de 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 emite ceil(sequence_length / hop_length) códigos.
  • padding_mask (torch.Tensor de forma (batch_size, sequence_length) ou (batch_size, 1, sequence_length), opcional) — Máscara que descreve o preenchimento em input_values; usada para calcular audio_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.LongTensor de forma (batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usando model.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.Tensor de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido indicando os códigos de áudio válidos em audio_codes.

forward

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = None**kwargs ) → WavTokenizerOutput or tuple(torch.Tensor)

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada.
  • padding_mask (torch.Tensor de 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 calcular audio_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 Module em 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.Tensor de 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.LongTensor de forma (batch_size, 1, codes_length), opcional) — Índices de códigos discretos calculados usando model.encode.
  • audio_codes_mask (torch.Tensor de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido indicando os códigos de áudio válidos em audio_codes.
Update on GitHub