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

このモデルは2024年8月29日にHF papersで公開され、2026年11月16日にHugging Face Transformersに貢献されました。

WavTokenizer

概要

WavTokenizerは、単一のコードブックを使用して、24 kHzのモノラルオーディオを離散トークンにエンコードします。チェックポイントによって1秒あたり40トークンまたは75トークンになります。また、これらのトークンからオーディオを再構成することもできます。

この実装は、エンコードおよびデコードを行うWavTokenizerModel、またはエンコードのみを行うWavTokenizerEncoderModelによる推論をサポートしています。1秒あたり40トークンのバリアントは、Apertus 1.5用のオーディオトークナイザを提供します。コーデックの学習はサポートされていません。

このモデルはSwiss AI Initiativeによって提供されました。 元の実装はGitHubで利用できます。

利用可能なチェックポイント

これらのチェックポイントは、from_pretrainedで読み込む準備ができています:

チェックポイントドメイン1秒あたりのトークン数
Small、40トークン/秒音声40
小型、75トークン/秒音声75
中程度音声75
Medium v2音声75
中程度音楽/オーディオ75
Medium v2音楽/オーディオ75
大規模統合統合40
Large v2音声75

使用例

音声クリップを読み込み、チェックポイントのサンプリングレートにリサンプリングし、エンコードして再構成します:

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)]

使用上の注意

  • オーディオ入力: 特徴抽出器は、設定されたサンプリングレートでのモノラルオーディオを期待します。リサンプリングやダウンミックスは行いません。例では、load_audio を使用してこれら両方を処理しています。デコード時に内部パディングにより末尾にサンプルが追加されることがあるため、例では再構成されたオーディオを元の長さにトリミングしています。
  • バッチ処理: 長さが異なるクリップのパディングは、そのコードを変更する可能性があります。各クリップを個別に処理した場合と同一のコードが必要な場合は、クリップを個別にエンコードしてください。
  • 精度: トークナイザーをfloat32(デフォルト)で読み込み、実行します。精度を下げると、コードの割り当てが変わる可能性があります。

WavTokenizerConfig

クラス 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 )

パラメータ

  • sampling_rate (int、任意、デフォルトは 24000) — オーディオファイルをデジタル化するためのサンプリングレート(ヘルツ (Hz) 表記)。
  • audio_channels (int、任意、デフォルトは 1) — オーディオデータのチャンネル数です。モノラル(1)のみサポートされています。
  • num_filters (int、任意、デフォルトは 32) — 最初の WavTokenizerConv1d ダウンサンプリング層の畳み込みカーネルの数。
  • upsampling_ratios (list[int]、任意、デフォルトは [6, 5, 5, 4]) — カーネルサイズとストライドの比率です。エンコーダーはアップサンプリング比率ではなくダウンサンプリング比率を使用するため、ここで指定した比率とは逆の順序で比率を使用します。この順序はデコーダーの順序と一致する必要があります。これらの積(デフォルトでは 600)はホップ長、つまり 1 つのコードが表すオーディオサンプルの数です。
  • num_residual_layers (int, 任意, デフォルトは 1) — 各エンコーダステージにおける残差層の数。
  • dilation_growth_rate (int、任意、デフォルト値は 2) — エンコーダーの各残差層で、dilation をどの程度増加させるかを指定します。
  • compress (int、任意、デフォルトは 2) — 残差ブランチの次元削減数。
  • use_conv_shortcut (bool、任意、デフォルトはTrue) — 残差ブロック内の(スキップ)ショートカットとして畳み込み層を使用するかどうか。False の場合、恒等関数が使用され、一般的な残差接続になります。
  • use_causal_conv (bool、任意、デフォルトは False) — 完全に因果的な畳み込みを使用するかどうか。
  • pad_mode (str、任意、デフォルトは "reflect") — 畳み込みのパディングモードです。
  • norm_type (str、任意、デフォルトは"weight_norm") — エンコーダーの畳み込み層に適用する正規化手法。["weight_norm", "time_group_norm"] のいずれかである必要があります。
  • kernel_size (int, 任意, デフォルトは 7) — 初期エンコーダ畳み込みのカーネルサイズ。
  • last_kernel_size (int, 任意, デフォルトは 7) — 最後のエンコーダ畳み込みのカーネルサイズ。
  • residual_kernel_size (int、任意、デフォルトは 3) — エンコーダーの残差層のカーネルサイズです。
  • num_lstm_layers (int、任意、デフォルトは 2) — エンコーダーの末尾にある LSTM レイヤーの数。
  • hidden_size (int, 任意、デフォルトは 512) — エンコーダー出力の次元数(量子化器の潜在空間)。
  • codebook_size (int, 任意、デフォルトは 4096) — 単一の VQ コードブックを構成する離散コードの数。
  • codebook_dim (int、任意、デフォルトは 512) — コードブックベクトルの次元数。hidden_size と一致する必要があります(射影は使用されません)。
  • decoder_hidden_size (int、任意、デフォルトは 768) — Vocos 形式のデコーダーバックボーンの次元数。
  • decoder_intermediate_size (int, 任意, デフォルトは 2304) — デコーダーの ConvNeXt ブロック内の pointwise 畳み込みの次元数。
  • decoder_num_layers (int、任意、デフォルトは 12) — デコーダーのバックボーンに含まれる ConvNeXt ブロックの数。
  • adanorm_num_embeddings (int、任意、デフォルト値は 4) — デコーダーの適応型レイヤーノルムの条件埋め込みの数です。条件付けは学習時の機能であり(バンド幅ごとに 1 つの埋め込み)、推論時には常に埋め込み 0 が使用されます。
  • decoder_attention_num_groups (int、任意、デフォルトは 32) — デコーダーの GroupNorm 層のグループ数です。
  • norm_eps (float, 任意、デフォルトは 1e-06) — デコーダーの正規化レイヤーの epsilon。

これはWavTokenizerModelの設定を保存するための設定クラスです。指定された引数に基づいてWavtokenizerモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、swiss-ai/wavtokenizer-large-unify-40tokenと類似した設定が得られます。

設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。

例:

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

クラス 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 )

WavTokenizerのエンコーダーおよび量子化器であるWavTokenizerEncoderModelの設定です。すべてのフィールドをWavTokenizerConfigと共有しています(引数についてはそのドキュメントを参照してください)。そのため、完全なWavTokenizerチェックポイントから読み込むことができます。デコーダー固有のフィールドは、エンコーダーモデルでは使用されません。

WavTokenizerFeatureExtractor

class 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 )

パラメータ

  • feature_size (int、任意、デフォルトは 1) — 抽出された特徴量の次元です。モノ(1)のみサポートされています。
  • sampling_rate (int, 任意、デフォルトは 24000) — オーディオ波形をデジタル化するためのサンプリングレート (Hz)。
  • padding_value (float、任意、デフォルトは 0.0) — パディングに使用される値です。
  • hop_length (int、任意、デフォルトは 600) — 1 つのオーディオコードが表すオーディオサンプルの数。
  • normalize_audio (bool、省略可能、デフォルトはFalse) — パディングの前に、各クリップをtarget_peak_dB_FSにピーク正規化するかどうかです。元のWavTokenizerでは正規化を行いませんが、Apertus 1.5ではこれを有効にしています。
  • target_peak_dB_FS (float, 省略可能、デフォルトは -3.0) — normalize_audio が True の場合に使用される、dB FS でのターゲットピークレベル。

設定されたサンプリングレートでのモノラル音声用のWavTokenizer特徴抽出器を構築します。音声はリサンプリングされず、ダウンミックスもされません。

__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

パラメータ

  • audio (np.ndarray、torch.Tensor、list[float]、list[np.ndarray]、list[torch.Tensor]、list[list[float]]) — 処理対象のシーケンスまたはシーケンスのバッチです。各シーケンスは、このフィーチャーエクストラクターのsampling_rateでサンプリング済みの、形状(num_samples,)のモノラルオーディオである必要があります。オーディオはリサンプリングやダウンミックスは行われません。
  • padding (bool、strまたはPaddingStrategy、省略可能、デフォルトはTrue) — パディング戦略: Trueまたは'longest'はバッチをその中で最も長いシーケンスの長さにパディングします(単一の入力の場合はパディングされません)、'max_length'はmax_lengthまでパディングします、Falseまたは'do_not_pad'はパディングを無効にします。
  • truncation (bool、省略可、デフォルトはFalse) — max_lengthを超える長さのシーケンスをmax_lengthに切り詰めるかどうかを指定します。
  • max_length (int、任意) — 'max_length'のパディングおよびtruncationの目標長。
  • return_tensors (str または TensorType、optional) — 設定されている場合、NumPy 配列のリストではなくテンソルを返します: PyTorch の torch.Tensor には 'pt'、NumPy の np.ndarray には 'np'。
  • sampling_rate (int, 任意) — audio 入力のサンプリングレートです。設定済みの sampling_rate と不一致の場合に、サイレントに失敗するのではなくエラーを発生させるために、この値を渡してください。

戻り値

BatchFeature

以下のフィールドを持つBatchFeature:

  • input_values — モデルに与える音声波形。形状が(1, num_samples)の配列のリスト、またはreturn_tensorsが設定されている場合は形状(batch_size, 1, num_samples)のテンソル。
  • padding_mask — 有効なオーディオサンプル(1)とパディング(0)を示すマスク。形状は(batch_size, num_samples)です。

モデル用に1つ以上のオーディオシーケンスを特徴化して準備します。

WavTokenizerEncoderModel

class transformers.WavTokenizerEncoderModel

< >

( config: WavTokenizerEncoderConfig )

パラメータ

  • config (WavTokenizerEncoderConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

WavTokenizerのエンコーダーと量子化器。音声波形を離散コードに変換するために使用されます。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド(ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど)については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

encode

< >

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

パラメータ

  • input_values (torch.Tensor、形状 (batch_size, 1, sequence_length)) — 入力音声波形です。任意の非ゼロ長をサポートしており、エンコーダーは内部でパディングを行い、ceil(sequence_length / hop_length) 個のコードを出力します。
  • padding_mask (torch.Tensor、形状 (batch_size, sequence_length) または (batch_size, 1, sequence_length)、任意) — input_values におけるパディングを記述するマスク。audio_codes_mask の計算に使用されます。

戻り値

WavTokenizerEncoderOutputまたはtuple(torch.Tensor)

WavTokenizerEncoderOutput、またはtorch.Tensorのタプル(return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合)。設定(None)や入力に応じて、さまざまな要素で構成されます。

  • audio_codes (torch.LongTensor、形状 (batch_size, 1, codes_length)、任意) — model.encode を使用して計算された離散コードのインデックスです。これらは、入力音声信号の圧縮・量子化された形式を表します(1つのコードブック、ceil(num_samples / hop_length) 個のコード)。
  • audio_codes_mask (torch.Tensor、形状 (batch_size, 1, codes_length)、任意) — audio_codes 内の有効なオーディオコードを示す、ダウンサンプリングされた padding_mask。

forward

< >

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

パラメータ

  • input_values (torch.Tensor、形状 (batch_size, 1, sequence_length)) — 入力音声波形。
  • padding_mask (torch.Tensor、形状 (batch_size, sequence_length) または (batch_size, 1, sequence_length)、任意) — audio_codes_mask を計算するために使用されるパディングマスク。

戻り値

WavTokenizerEncoderOutputまたはtuple(torch.Tensor)

WavTokenizerEncoderOutput、またはtorch.Tensorのタプル(return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合)。設定(WavTokenizerConfig)と入力に応じて、さまざまな要素で構成されます。

WavTokenizerEncoderModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

  • audio_codes (torch.LongTensor、形状 (batch_size, 1, codes_length)、任意) — model.encode を使用して計算された離散コードのインデックスです。これらは、入力音声信号の圧縮・量子化された形式を表します(1つのコードブック、ceil(num_samples / hop_length) 個のコード)。
  • audio_codes_mask (torch.Tensor、形状 (batch_size, 1, codes_length)、任意) — audio_codes 内の有効なオーディオコードを示す、ダウンサンプリングされた padding_mask。

WavTokenizerModel

クラス transformers.WavTokenizerModel

< >

( config: WavTokenizerConfig )

パラメータ

  • config (WavTokenizerConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

推論専用、単一コードブックのWavTokenizerニューラルオーディオコーデック。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド(ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど)については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

decode

< >

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

パラメータ

  • audio_codes (torch.LongTensor、形状 (batch_size, 1, codes_length)) — model.encode を使用して計算された離散コードのインデックスです。1 つ以上のコードをサポートしており、各コードは hop_length 個のオーディオサンプルにデコードされます。
  • bandwidth_id (int、任意、デフォルトは 0) — デコーダーの適応型レイヤーノルムの条件埋め込み ID。推論時には常に 0 です。

戻り値

WavTokenizerDecoderOutput または tuple(torch.Tensor)

WavTokenizerDecoderOutput、またはtorch.Tensorのタプル(return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合)。設定(None)や入力に応じて、さまざまな要素で構成されます。

  • audio_values (torch.Tensor、形状 (batch_size, 1, sequence_length)、任意) — 時間領域におけるデコードされた音声波形の値(codes_length * hop_length サンプル)。

encode

< >

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

パラメータ

  • input_values (torch.Tensor、形状 (batch_size, 1, sequence_length)) — 入力音声波形です。任意の非ゼロ長をサポートしており、エンコーダーは内部でパディングを行い、ceil(sequence_length / hop_length) 個のコードを出力します。
  • padding_mask (torch.Tensor、形状 (batch_size, sequence_length) または (batch_size, 1, sequence_length)、任意) — input_values におけるパディングを記述するマスク。audio_codes_mask の計算に使用されます。

戻り値

WavTokenizerEncoderOutputまたはtuple(torch.Tensor)

WavTokenizerEncoderOutput、またはtorch.Tensorのタプル(return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合)。設定(None)や入力に応じて、さまざまな要素で構成されます。

  • audio_codes (torch.LongTensor、形状 (batch_size, 1, codes_length)、任意) — model.encode を使用して計算された離散コードのインデックスです。これらは、入力音声信号の圧縮・量子化された形式を表します(1つのコードブック、ceil(num_samples / hop_length) 個のコード)。
  • audio_codes_mask (torch.Tensor、形状 (batch_size, 1, codes_length)、任意) — audio_codes 内の有効なオーディオコードを示す、ダウンサンプリングされた padding_mask。

forward

< >

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

パラメータ

  • input_values (torch.Tensor、形状 (batch_size, 1, sequence_length)) — 入力音声波形。
  • padding_mask (torch.Tensor、形状 (batch_size, sequence_length) または (batch_size, 1, sequence_length)、任意) — 有効な音声サンプル (1) とパディング (0) を示すマスク。audio_codes_mask の計算に使用されます。

戻り値

WavTokenizerOutputまたはtuple(torch.Tensor)

WavTokenizerOutput、またはtorch.Tensorのタプル(return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合)。設定(None)や入力に応じて、さまざまな要素で構成されます。

WavTokenizerModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

  • audio_values (torch.Tensor、形状 (batch_size, 1, sequence_length)、任意) — WavTokenizer のデコーダー部分を使用して取得した、時間領域におけるデコード済みオーディオ波形の値。
  • audio_codes(torch.LongTensor、形状 (batch_size, 1, codes_length)、任意)— model.encode を使用して計算された離散コードのインデックス。
  • audio_codes_mask (torch.Tensor、形状 (batch_size, 1, codes_length)、任意) — audio_codes 内の有効なオーディオコードを示す、ダウンサンプリングされた padding_mask。
Update on GitHub