Transformers documentation
WavTokenizer
このモデルは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
< 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 )
パラメータ
- 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.configWavTokenizerEncoderConfig
クラス 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 )
WavTokenizerのエンコーダーおよび量子化器であるWavTokenizerEncoderModelの設定です。すべてのフィールドをWavTokenizerConfigと共有しています(引数についてはそのドキュメントを参照してください)。そのため、完全なWavTokenizerチェックポイントから読み込むことができます。デコーダー固有のフィールドは、エンコーダーモデルでは使用されません。
WavTokenizerFeatureExtractor
class 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 )
パラメータ
- 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__
< 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
パラメータ
- 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:
- 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
< source >( config: WavTokenizerEncoderConfig )
パラメータ
- config (WavTokenizerEncoderConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
WavTokenizerのエンコーダーと量子化器。音声波形を離散コードに変換するために使用されます。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド(ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど)については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
encode
< source >( 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
< source >( 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
< source >( config: WavTokenizerConfig )
パラメータ
- config (WavTokenizerConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
推論専用、単一コードブックのWavTokenizerニューラルオーディオコーデック。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド(ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど)については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
decode
< source >( 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
< source >( 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
< source >( 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。