Transformers documentation
EnCodec
このモデルは2022年10月24日にHF papersで公開され、2023年6月14日にHugging Face Transformersに貢献されました。
EnCodec
概要
EnCodecニューラルコーデックモデルは、Alexandre Défossez、Jade Copet、Gabriel Synnaeve、Yossi Adi によって High Fidelity Neural Audio Compression で提案されました。
論文の抄録は以下の通りです。
ニューラルネットワークを活用した、最先端のリアルタイムかつ高忠実度のオーディオコーデックを提案します。本コーデックは、量子化された潜在空間をエンドツーエンドで学習した、ストリーミング型のエンコーダ・デコーダアーキテクチャから構成されています。単一のマルチスケールスペクトログラム敵対的損失関数を用いることで、アーティファクトを効率的に低減し、高品質なサンプルを生成しながら、学習を簡素化かつ高速化しています。学習を安定させるための新しい損失バランサー機構を導入しました。この機構により、損失の重みが、全体の勾配に対して占めるべき割合を定義するものとなり、このハイパーパラメータの選択が損失の典型的なスケールから切り離されます。さらに、リアルタイムより速い処理速度を維持したまま、得られた表現を最大40%まで圧縮できる軽量なTransformerモデルの活用方法を検討しました。提案するモデルの主要な設計判断、すなわち学習目的、アーキテクチャの変更、および様々な知覚損失関数に関する検討について、詳細な説明を提供します。音声、ノイズ・残響の多い音声、音楽といった幅広い帯域幅とオーディオドメインを対象に、広範な主観的評価（MUSHRAテスト）とアブレーションスタディを提示します。24 kHzモノラルおよび48 kHzステレオオーディオの両方を対象としたすべての評価設定において、当社のアプローチはベースライン手法を上回ります。
このモデルは、Matthijs、Patrick Von Platen、Arthur Zucker によって提供されました。 元のコードはこちらで確認できます。
使用例
このモデルを使用してオーディオをエンコードおよびデコードする簡単な例を以下に示します。
from datasets import Audio, load_dataset
from transformers import AutoProcessor, EncodecModel
librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
model = EncodecModel.from_pretrained("facebook/encodec_24khz", device_map="auto")
processor = AutoProcessor.from_pretrained("facebook/encodec_24khz")
librispeech_dummy = librispeech_dummy.cast_column("audio", Audio(sampling_rate=processor.sampling_rate))
audio_sample = librispeech_dummy[-1]["audio"]["array"]
inputs = processor(raw_audio=audio_sample, sampling_rate=processor.sampling_rate, return_tensors="pt").to(model.device)
encoder_outputs = model.encode(inputs["input_values"], inputs["padding_mask"])
# `encoder_outputs.audio_codes` contains discrete codes
audio_values = model.decode(**encoder_outputs, padding_mask=inputs["padding_mask"])[0]
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"], inputs["padding_mask"]).audio_valuesEncodecConfig
class transformers.EncodecConfig
< 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 = Nonetarget_bandwidths: list[float] | tuple[float, ...] = (1.5, 3.0, 6.0, 12.0, 24.0)sampling_rate: int = 24000audio_channels: int = 1normalize: bool = Falsechunk_length_s: int | float | None = Noneoverlap: float | None = Nonehidden_size: int = 128num_filters: int = 32num_residual_layers: int = 1upsampling_ratios: list[int] | tuple[int, ...] = (8, 5, 4, 2)norm_type: str = 'weight_norm'kernel_size: int = 7last_kernel_size: int = 7residual_kernel_size: int = 3dilation_growth_rate: int = 2use_causal_conv: bool = Truepad_mode: str = 'reflect'compress: int = 2num_lstm_layers: int = 2trim_right_ratio: float = 1.0codebook_size: int = 1024codebook_dim: int | None = Noneuse_conv_shortcut: bool = True )
パラメータ
- target_bandwidths (
list[float]、任意、デフォルトは[1.5, 3.0, 6.0, 12.0, 24.0]) — モデルが音声エンコードに使用できる帯域幅の範囲です。 - sampling_rate (
int、任意、デフォルトは24000) — オーディオファイルをデジタル化するためのサンプリングレート（ヘルツ (Hz) 表記）。 - audio_channels (
int、任意、デフォルトは1) — 入力チャネル数です。 - normalize (
bool、省略可能、デフォルトはFalse) — 渡されたオーディオを正規化するか否かを指定します。 - chunk_length_s (
float, 任意) — 定義されている場合、音声は長さchunk_length_sのチャンクに事前処理され、その後エンコードされます。 - overlap (
float, 任意) — 各チャンク間の重複を定義します。chunk_strideを計算するために、以下の式が使用されます:int((1.0 - self.overlap) * self.chunk_length)。 - hidden_size (
int、任意、デフォルトは128) — 隠れ表現の次元数。 - num_filters (
int、任意、デフォルトは 32) — 最初のEncodecConv1dダウンサンプリング層の畳み込みカーネルの数。 - num_residual_layers (
int, 省略可, デフォルト値は 1) — 残差層の数。 - upsampling_ratios (
Sequence[int], 任意、デフォルトは[8, 5, 4, 2]) — カーネルサイズとストライドの比率です。エンコーダーはアップサンプリング比率ではなくダウンサンプリング比率を使用するため、ここで指定した比率とは逆の順序で比率を使用します。この順序はデコーダーの順序と一致する必要があります。 - norm_type (
str、任意、デフォルトは"weight_norm") — 正規化手法。["weight_norm", "time_group_norm"]のいずれかである必要があります。 - kernel_size (
int、任意、デフォルトは 7) — 初期畳み込みのカーネルサイズ。 - last_kernel_size (
int, 任意、デフォルトは 7) — 最後の畳み込み層のカーネルサイズ。 - residual_kernel_size (
int、任意、デフォルトは 3)— 残差層のカーネルサイズ。 - dilation_growth_rate (
int、任意、デフォルト値は 2)— 各レイヤーで dilation をどの程度増加させるかを指定します。 - use_causal_conv (
bool、任意、デフォルトはTrue) — 完全に因果的な畳み込みを使用するかどうか。 - pad_mode (
str、任意、デフォルトは"reflect") — 畳み込みのパディングモードです。 - compress (
int、任意、デフォルトは 2) — 残差ブランチの次元削減（Demucs v3 由来）。 - num_lstm_layers (
int、任意、デフォルトは 2) — エンコーダーの末尾にある LSTM レイヤーの数。 - trim_right_ratio (
float、任意、デフォルト値は 1.0)—use_causal_conv = Trueの設定下で、転置畳み込みの右側をトリムするための比率です。1.0 に等しい場合、すべてのトリムが右側で行われることを意味します。 - codebook_size (
int、任意、デフォルトは1024) — モデルが使用する並列コードブックの数です。 - codebook_dim (
int, 省略可) — 各コードブック埋め込みベクトルの次元数です。 - use_conv_shortcut (
bool、省略可、デフォルトはTrue) —EncodecResnetBlockブロック内で、'skip' 接続として畳み込み層を使用するかどうか。False の場合、恒等関数が使用され、一般的な残差接続になります。
これはEncodecModelの設定を保存するための設定クラスです。指定された引数に基づいてEncodecモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、facebook/encodec_24khzと類似した設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
例:
>>> from transformers import EncodecModel, EncodecConfig
>>> # Initializing a "facebook/encodec_24khz" style configuration
>>> configuration = EncodecConfig()
>>> # Initializing a model (with random weights) from the "facebook/encodec_24khz" style configuration
>>> model = EncodecModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configEncodecFeatureExtractor
class transformers.EncodecFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0chunk_length_s: float | None = Noneoverlap: float | None = None**kwargs )
パラメータ
- feature_size (
int、任意、デフォルトは 1)— 抽出された特徴量の次元です。モノラルの場合は 1、ステレオの場合は 2 を指定します。 - sampling_rate (
int、任意、デフォルトは 24000)— オーディオ波形をデジタル化するためのサンプリングレート (Hz)。 - padding_value (
float、任意、デフォルトは 0.0) — パディング値を埋めるために使用される値です。 - chunk_length_s (
float, 任意) — 定義されている場合、音声は長さchunk_length_sのチャンクに事前処理され、その後エンコードされます。 - overlap (
float, 任意) — 各チャンク間の重複を定義します。chunk_strideを計算するために、以下の式が使用されます:int((1.0 - self.overlap) * self.chunk_length)。
EnCodecのフィーチャーエクストラクターを構築します。
このフィーチャーエクストラクターは、主要なメソッドの大部分を含む SequenceFeatureExtractor を継承しています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。
デフォルト値でフィーチャーエクストラクターをインスタンス化すると、facebook/encodec_24khzアーキテクチャと類似した設定が得られます。
__call__
< source >( raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]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 )
パラメータ
- raw_audio (
np.ndarray、list[float]、list[np.ndarray]、list[list[float]]) — 処理対象のシーケンスまたはシーケンスのバッチです。各シーケンスは、numpy 配列、float 値のリスト、numpy 配列のリスト、または float 値のリストのリストであることができます。モノラル音声（feature_size = 1）の場合、numpy 配列の形状は(num_samples,)である必要があります。ステレオ音声（feature_size = 2）の場合、形状は(2, 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, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ（上記を参照）。 - return_tensors (
strまたは TensorType, 省略可) — 設定すると、Python の整数のリストではなくテンソルを返します。指定可能な値は以下の通りです:'pt': PyTorchのtorch.Tensorオブジェクトを返します。'np': Numpy のnp.ndarrayオブジェクトを返します。
- sampling_rate (
int, 任意) —audio入力がサンプリングされたレートです。サイレントエラーを防ぐため、forward 呼び出し時にsampling_rateを渡すことを強く推奨します。
1つ以上のシーケンスを特徴量化し、モデル用に準備するための主要なメソッド。
EncodecModel
class transformers.EncodecModel
< source >( config: EncodecConfig )
パラメータ
- config (EncodecConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
EnCodec ニューラルオーディオコーデックモデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
decode
< source >( audio_codes: LongTensoraudio_scales: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 )
パラメータ
- audio_codes (
torch.LongTensor、形状(nb_frames, batch_size, nb_quantizers, frame_len)、任意) —model.encodeを使用して計算された離散コード埋め込み。 - audio_scales (
nb_frames長さのtorch.Tensorのリスト、各要素の形状は(batch_size, 1)、任意) — 各audio_codes入力に対するスケーリング係数。 - padding_mask (
torch.Tensor、形状(channels, sequence_length)) —input_valuesをパディングするために使用されるパディングマスク。 - return_dict (
bool, 任意) — プレーンなタプルではなく ModelOutput を返すかどうか。 - last_frame_pad_length (
int, 省略可) — デコード時に除去される最後のフレームのパディングの長さを表す整数です。
与えられたフレームを出力音声波形にデコードします。
出力が入力よりやや大きくなる場合があります。その場合、末尾の余分なステップは切り捨てることができます。
encode
< source >( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = Nonereturn_dict: bool | None = None ) → EncodecEncoderOutput dict or a tuple containing
パラメータ
- input_values (
torch.Tensor、形状(batch_size, channels, sequence_length)) — 入力音声波形の浮動小数点値です。 - padding_mask (
torch.Tensor、shape(batch_size, channels, sequence_length)) —input_valuesをパディングするために使用されるパディングマスク。 - bandwidth (
float, 任意) — 目標帯域幅です。config.target_bandwidthsのいずれかの値である必要があります。Noneの場合、可能な最小の帯域幅が使用されます。bandwidth は実際の値の千分の一で表されます。例えば、6kbps の帯域幅は bandwidth == 6.0 と表されます。
戻り値
EncodecEncoderOutput dict または、それを含むタプル
- audio_codes(
torch.LongTensor、形状(nb_frames, batch_size, nb_quantizers, frame_len)、任意) - audio_scales（
nb_frames個のtorch.Tensorのリスト、各テンソルの形状は(batch_size, 1)、省略可）、 - last_frame_pad_length (
int, 任意)
入力オーディオ波形を、(nb_frames, batch_size, nb_quantizers, frame_len) の形状を持つ離散コードにエンコードします。
nb_frames=1となるのは、self.config.chunk_length=Noneの場合です（エンコーダーがオーディオ全体に適用されるため）。24kHz のモデルがこれに該当します。それ以外の場合は、nb_frames=ceil(input_length/self.config.chunk_stride)となり、48kHz のモデルがこれに該当します。frame_lenは各フレームの長さであり、self.config.chunk_length=Noneの場合（24kHz モデルなど）はceil(input_length/self.config.hop_length)に等しくなります。それ以外の場合、つまりself.config.chunk_lengthが定義されている場合は、frame_len=self.config.chunk_length/self.config.hop_lengthとなり、例えばframe_len=150の 48kHz モデルが該当します。
forward
< source >( input_values: FloatTensorpadding_mask: typing.Optional[torch.BoolTensor] = Nonebandwidth: float | None = Noneaudio_codes: typing.Optional[torch.LongTensor] = Noneaudio_scales: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 ) → EncodecOutput or tuple(torch.FloatTensor)
パラメータ
- input_values (
torch.FloatTensor、shape(batch_size, channels, sequence_length)、任意) — Float に変換され、長さ self.chunk_length のチャンクとconfig.chunk_strideのストライドでエンコードできるように、適切な長さにパディングされた生オーディオ入力。 - padding_mask (
torch.BoolTensor形状(batch_size, channels, sequence_length), 省略可) — padding トークンのインデックスでのスケーリング係数の計算を回避するためのマスク（これらのトークンでの conv の計算を回避できるか）。 マスクの値は[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0 です。
padding_maskは、入力が切り詰められた場合やパディングされていない場合を除き、常に渡す必要があります。これは、テンソルを効率的に処理するために、input_length % stride = step（step = chunk_length-stride）を満たすように入力オーディオをパディングする必要があるためです。これにより、すべてのチャンクが同じ形状になることが保証されます。 - bandwidth (
float, 省略可) — 目標帯域幅です。config.target_bandwidthsのいずれかの値である必要があります。Noneの場合、可能な最小の帯域幅が使用されます。bandwidth は実際の値の千分の一で表されます。例えば、6kbps の帯域幅はbandwidth == 6.0と表されます。 - audio_codes (
torch.LongTensor、形状(nb_frames, batch_size, nb_quantizers, frame_len)、任意) —model.encodeを使用して計算された離散コード埋め込み。 - audio_scales (
list、長さnb_frames、要素は形状(batch_size, 1)のtorch.Tensor、任意) — 各audio_codes入力に対するスケーリング係数。 - return_dict (
bool, 省略可) — 出力を辞書として返すかどうかを指定します。 - last_frame_pad_length (
int, 任意) — 最後のフレームにパディングがある場合、その長さです。エンコードされたフレームをテンソルとして出力できるようにするために使用されます。デコード時には、エンコードされたフレームからパディングを除去するために、この値を渡す必要があります。
戻り値
EncodecOutput または tuple(torch.FloatTensor)
EncodecOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（EncodecConfig）と入力に応じて、さまざまな要素で構成されます。
EncodecModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- audio_codes（
torch.LongTensor、形状(nb_frames, batch_size, nb_quantizers, frame_len)、任意）—model.encodeを使用して計算された離散コード埋め込み。 - audio_values (
torch.FloatTensor、shape(batch_size, segment_length)、任意) — Encodec のデコーダー部分を使用して取得したデコード済み音声値。
例:
>>> from datasets import load_dataset
>>> from transformers import AutoProcessor, EncodecModel
>>> dataset = load_dataset("hf-internal-testing/ashraq-esc50-1-dog-example")
>>> audio_sample = dataset["train"]["audio"][0]["array"]
>>> model_id = "facebook/encodec_24khz"
>>> model = EncodecModel.from_pretrained(model_id)
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> inputs = processor(raw_audio=audio_sample, return_tensors="pt")
>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values