Hugging Face's logo

Transformers documentation

EnCodec

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

and get access to the augmented documentation experience

to get started

Model ini dipublikasikan di HF papers pada 2022-10-24 dan disumbangkan ke Hugging Face Transformers pada 2023-06-14.

EnCodec

Ikhtisar

Model codec saraf EnCodec diusulkan dalam High Fidelity Neural Audio Compression oleh Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

Abstrak dari makalah tersebut adalah sebagai berikut:

Kami memperkenalkan codec audio real-time berkeandalan tinggi terkini yang memanfaatkan jaringan saraf. Codec ini terdiri dari arsitektur encoder-decoder streaming dengan ruang laten terkuantisasi yang dilatih secara end-to-end. Kami menyederhanakan dan mempercepat pelatihan dengan menggunakan adversary spektrogram multiscale tunggal yang secara efisien mengurangi artefak dan menghasilkan sampel berkualitas tinggi. Kami memperkenalkan mekanisme loss balancer baru untuk menstabilkan pelatihan: bobot dari sebuah loss kini mendefinisikan fraksi dari keseluruhan gradien yang seharusnya diwakilinya, sehingga memisahkan pemilihan hiperparameter ini dari skala tipikal dari loss tersebut. Terakhir, kami mempelajari bagaimana model Transformer ringan dapat digunakan untuk lebih mengompresi representasi yang diperoleh hingga 40%, sambil tetap lebih cepat dari real-time. Kami menyediakan deskripsi rinci tentang pilihan desain utama dari model yang diusulkan, termasuk: tujuan pelatihan, perubahan arsitektur, dan studi tentang berbagai fungsi loss perseptual. Kami menyajikan evaluasi subjektif yang luas (tes MUSHRA) bersama dengan studi ablation untuk berbagai rentang bandwidth dan domain audio, termasuk ucapan, ucapan yang bising dan bergema, serta musik. Pendekatan kami unggul dibandingkan metode baseline di semua pengaturan yang dievaluasi, dengan mempertimbangkan audio monofonik 24 kHz dan stereofonik 48 kHz.

Model ini disumbangkan oleh Matthijs, Patrick Von Platen dan Arthur Zucker. Kode aslinya dapat ditemukan di sini.

Contoh penggunaan

Berikut adalah contoh singkat tentang cara mengkodekan dan mendekodekan audio menggunakan model ini:

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_values

EncodecConfig

kelas transformers.EncodecConfig

< >

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

Parameter

  • target_bandwidths (list[float], opsional, defaultnya [1.5, 3.0, 6.0, 12.0, 24.0]) — Rentang berbagai bandwidth yang dapat digunakan model untuk mengkodekan audio.
  • sampling_rate (int, opsional, default 24000) — Laju sampling di mana file audio harus didigitalisasi, dinyatakan dalam hertz (Hz).
  • audio_channels (int, opsional, defaultnya 1) — Jumlah saluran input.
  • normalize (bool, opsional, default False) — Apakah audio akan dinormalisasi saat diteruskan.
  • chunk_length_s (float, opsional) — Jika didefinisikan, audio diproses terlebih dahulu menjadi potongan-potongan dengan panjang chunk_length_s dan kemudian dikodekan.
  • overlap (float, opsional) — Menentukan tumpang tindih antar setiap chunk. Digunakan untuk menghitung chunk_stride menggunakan rumus berikut: int((1.0 - self.overlap) * self.chunk_length).
  • hidden_size (int, opsional, default 128) — Dimensi dari representasi tersembunyi.
  • num_filters (int, opsional, default 32) — Jumlah kernel konvolusi dari lapisan down sampling pertama EncodecConv1d.
  • num_residual_layers (int, opsional, default 1) — Jumlah lapisan residual.
  • upsampling_ratios (Sequence[int] , opsional, defaultnya [8, 5, 4, 2]) — Rasio ukuran kernel dan stride. Encoder menggunakan rasio downsampling alih-alih rasio upsampling, sehingga ia akan menggunakan rasio dalam urutan terbalik dari yang ditentukan di sini, yang harus sesuai dengan urutan decoder.
  • norm_type (str, opsional, default "weight_norm") — Metode normalisasi. Harus berupa ["weight_norm", "time_group_norm"]
  • kernel_size (int, opsional, default 7) — Ukuran kernel untuk konvolusi awal.
  • last_kernel_size (int, opsional, default 7) — Ukuran kernel untuk lapisan konvolusi terakhir.
  • residual_kernel_size (int, opsional, default 3) — Ukuran kernel untuk lapisan residual.
  • dilation_growth_rate (int, opsional, defaultnya 2) — Seberapa besar peningkatan dilation pada setiap layer.
  • use_causal_conv (bool, opsional, default True) — Apakah akan menggunakan konvolusi kausal penuh.
  • pad_mode (str, opsional, defaultnya "reflect") — Mode padding untuk konvolusi.
  • compress (int, opsional, default 2) — Dimensi yang dikurangi pada cabang residual (dari Demucs v3).
  • num_lstm_layers (int, opsional, default 2) — Jumlah lapisan LSTM di akhir encoder.
  • trim_right_ratio (float, opsional, default 1.0) — Rasio untuk pemotongan di sisi kanan dari transposed convolution di bawah setup use_causal_conv = True. Jika sama dengan 1.0, artinya semua pemotongan dilakukan di sisi kanan.
  • codebook_size (int, opsional, defaultnya 1024) — Jumlah codebook paralel yang digunakan oleh model.
  • codebook_dim (int, opsional) — Dimensi dari setiap vektor embedding codebook.
  • use_conv_shortcut (bool, opsional, default True) — Apakah akan menggunakan lapisan konvolusi sebagai koneksi ‘skip’ pada blok EncodecResnetBlock. Jika False, fungsi identitas akan digunakan, menghasilkan koneksi residual generik.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari EncodecModel. Kelas ini digunakan untuk membuat instance model Encodec sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instance konfigurasi dengan nilai default akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari facebook/encodec_24khz

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

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

EncodecFeatureExtractor

kelas transformers.EncodecFeatureExtractor

< >

( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0chunk_length_s: float | None = Noneoverlap: float | None = None**kwargs )

Parameter

  • feature_size (int, opsional, default 1) — Dimensi fitur dari fitur yang diekstrak. Gunakan 1 untuk mono, 2 untuk stereo.
  • sampling_rate (int, opsional, default 24000) — Laju sampling di mana gelombang audio harus didigitalisasi, dinyatakan dalam hertz (Hz).
  • padding_value (float, opsional, default 0.0) — Nilai yang digunakan untuk mengisi nilai padding.
  • chunk_length_s (float, opsional) — Jika didefinisikan, audio diproses terlebih dahulu menjadi potongan-potongan dengan panjang chunk_length_s dan kemudian dikodekan.
  • overlap (float, opsional) — Menentukan tumpang tindih antar setiap chunk. Digunakan untuk menghitung chunk_stride menggunakan rumus berikut: int((1.0 - self.overlap) * self.chunk_length).

Membangun ekstraktor fitur EnCodec.

Feature extractor ini mewarisi dari SequenceFeatureExtractor yang berisi sebagian besar metode utama. Pengguna harus merujuk ke superclass ini untuk informasi lebih lanjut mengenai metode-metode tersebut.

Membuat instans feature extractor dengan nilai default akan menghasilkan konfigurasi yang serupa dengan arsitektur facebook/encodec_24khz.

__call__

< >

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

Parameter

  • raw_audio (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — Sequens atau batch dari sequens yang akan diproses. Setiap sequens dapat berupa array numpy, daftar nilai float, daftar array numpy, atau daftar dari daftar nilai float. Array numpy harus memiliki bentuk (num_samples,) untuk audio mono (feature_size = 1), atau (2, num_samples) untuk audio stereo (feature_size = 2).
  • padding (bool, str atau PaddingStrategy, opsional, defaultnya True) — Pilih strategi untuk melakukan padding pada urutan yang dikembalikan (sesuai sisi padding dan indeks padding model) di antara:
    • True atau 'longest': Pad hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan).
    • 'max_length': Pad hingga panjang maksimum yang ditentukan dengan argumen max_length atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan.
    • False atau 'do_not_pad' (default): Tidak ada padding (yaitu, dapat menghasilkan batch dengan urutan yang panjangnya berbeda).
  • truncation (bool, opsional, default False) — Mengaktifkan pemotongan untuk memotong urutan input yang lebih panjang dari max_length menjadi max_length.
  • max_length (int, opsional) — Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).
  • return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor alih-alih daftar integer Python. Nilai yang dapat diterima adalah:
    • 'pt': Mengembalikan objek PyTorch torch.Tensor.
    • 'np': Mengembalikan objek Numpy np.ndarray.
  • sampling_rate (int, opsional) — Laju sampling di mana input audio disampelkan. Sangat disarankan untuk meneruskan sampling_rate pada panggilan forward untuk mencegah kesalahan yang tidak terdeteksi.

Metode utama untuk melakukan featurisasi dan persiapan satu atau beberapa sekuens untuk model.

EncodecModel

kelas transformers.EncodecModel

< >

( config: EncodecConfig )

Parameter

  • config (EncodecConfig) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Model codec audio neural EnCodec.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

decode

< >

( audio_codes: LongTensoraudio_scales: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 )

Parameter

  • audio_codes (torch.LongTensor dengan bentuk (nb_frames, batch_size, nb_quantizers, frame_len), opsional) — Embedding kode diskrit yang dihitung menggunakan model.encode.
  • audio_scales (daftar dengan panjang nb_frames berisi torch.Tensor dengan bentuk (batch_size, 1), opsional) — Faktor penskalaan untuk setiap input audio_codes.
  • padding_mask (torch.Tensor dengan bentuk (channels, sequence_length)) — Mask padding yang digunakan untuk mengisi input_values.
  • return_dict (bool, opsional) — Apakah akan mengembalikan ModelOutput alih-alih tuple biasa.
  • last_frame_pad_length (int, opsional) — Bilangan bulat yang merepresentasikan panjang padding pada frame terakhir, yang dihapus selama decoding.

Mendekodekan frame yang diberikan menjadi waveform audio keluaran.

Perhatikan bahwa output mungkin sedikit lebih besar daripada input. Dalam hal itu, langkah-langkah tambahan di akhir dapat dipangkas.

encode

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = Nonereturn_dict: bool | None = None ) → EncodecEncoderOutput dict or a tuple containing

Parameter

  • input_values (torch.Tensor dengan bentuk (batch_size, channels, sequence_length)) — Nilai float dari waveform audio input.
  • padding_mask (torch.Tensor dengan bentuk (batch_size, channels, sequence_length)) — Mask padding yang digunakan untuk mengisi input_values.
  • bandwidth (float, opsional) — Bandwidth target. Harus salah satu dari config.target_bandwidths. Jika None, menggunakan bandwidth terkecil yang mungkin. bandwidth direpresentasikan sebagai sepersepuluh ribu dari nilai aslinya, misalnya bandwidth 6kbps direpresentasikan sebagai bandwidth == 6.0

Mengembalikan

EncodecEncoderOutput dict atau tuple yang berisi

  • audio_codes (torch.LongTensor dengan bentuk (nb_frames, batch_size, nb_quantizers, frame_len), opsional),
  • audio_scales (list dengan panjang nb_frames berisi torch.Tensor dengan bentuk (batch_size, 1), opsional),
  • last_frame_pad_length (int, opsional).

Mengkodekan gelombang audio input menjadi kode diskrit dengan bentuk (nb_frames, batch_size, nb_quantizers, frame_len).

  • nb_frames=1 jika self.config.chunk_length=None (karena encoder diterapkan pada audio penuh), yang merupakan kasus untuk model 24kHz. Sebaliknya, nb_frames=ceil(input_length/self.config.chunk_stride), yang merupakan kasus untuk model 48kHz.
  • frame_len adalah panjang setiap frame, yang sama dengan ceil(input_length/self.config.hop_length) jika self.config.chunk_length=None (misalnya, untuk model 24kHz). Sebaliknya, jika self.config.chunk_length didefinisikan, maka frame_len=self.config.chunk_length/self.config.hop_length, misalnya kasus untuk model 48kHz dengan frame_len=150.

forward

< >

( input_values: Tensorpadding_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.Tensor)

Parameter

  • input_values (torch.Tensor dengan bentuk (batch_size, channels, sequence_length), opsional) — Input audio mentah yang dikonversi ke Float dan di-pad hingga panjang yang sesuai agar dapat dikodekan menggunakan chunk dengan panjang self.chunk_length dan stride config.chunk_stride.
  • padding_mask (torch.BoolTensor dengan bentuk (batch_size, channels, sequence_length), opsional) — Mask untuk menghindari perhitungan faktor skala pada indeks token padding (apakah kita bisa menghindari perhitungan conv pada token-token ini+). Nilai mask yang dipilih dalam [0, 1]: 1 untuk token yang tidak di-mask, 0 untuk token yang di-mask. padding_mask harus selalu diberikan, kecuali jika input dipangkas atau tidak di-pad. Hal ini karena untuk memproses tensor secara efektif, audio input harus di-pad sehingga input_length % stride = step dengan step = chunk_length-stride. Ini memastikan bahwa semua chunk memiliki bentuk yang sama [0, 1]:
    • 1 untuk token yang tidak dimasker,
    • 0 untuk token yang dimasker.

    padding_mask harus selalu diteruskan, kecuali jika input dipangkas atau tidak di-pad. Hal ini karena untuk memproses tensor secara efektif, audio input harus di-pad sehingga input_length % stride = step dengan step = chunk_length-stride. Ini memastikan bahwa semua chunk memiliki bentuk yang sama

  • bandwidth (float, opsional) — Bandwidth target. Harus salah satu dari config.target_bandwidths. Jika None, menggunakan bandwidth terkecil yang mungkin. bandwidth direpresentasikan sebagai sepersepuluh ribu dari nilainya, misalnya bandwidth 6kbps direpresentasikan sebagai bandwidth == 6.0
  • audio_codes (torch.LongTensor dengan bentuk (nb_frames, batch_size, nb_quantizers, frame_len), opsional) — Embedding kode diskrit yang dihitung menggunakan model.encode.
  • audio_scales (list dengan panjang nb_frames berisi torch.Tensor dengan bentuk (batch_size, 1), opsional) — Faktor penskalaan untuk setiap input audio_codes.
  • return_dict (bool, opsional) — Apakah akan mengembalikan output sebagai dict.
  • last_frame_pad_length (int, opsional) — Panjang padding pada frame terakhir, jika ada. Nilai ini digunakan untuk memastikan bahwa frame yang telah di-encode dapat dioutputkan sebagai tensor. Nilai ini harus diteruskan saat decoding untuk memastikan padding dihapus dari frame yang telah di-encode.

Mengembalikan

EncodecOutput atau tuple(torch.Tensor)

EncodecOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (EncodecConfig) dan input.

Metode forward dari EncodecModel menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • audio_codes (torch.LongTensor dengan bentuk (nb_frames, batch_size, nb_quantizers, frame_len), opsional) — Embedding kode diskrit yang dihitung menggunakan model.encode.
  • audio_values (torch.Tensor dengan bentuk (batch_size, segment_length), opsional) — Nilai audio yang telah didekodekan, diperoleh menggunakan bagian decoder dari Encodec.

Contoh:

>>> 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
Update on GitHub

←Dia FastSpeech2Conformer→