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

Эта модель была опубликована в HF papers 24.10.2022 и добавлена в Hugging Face Transformers 14.06.2023.

EnCodec

Обзор

Модель нейронного кодека EnCodec была предложена в работе High Fidelity Neural Audio Compression авторами Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

Аннотация из статьи следующая:

Мы представляем аудиокодек последнего поколения для работы в реальном времени с высокой точностью, использующий нейронные сети. Он построен на основе потоковой архитектуры «кодировщик-декодер» с квантованным латентным пространством, обучаемой в режиме end-to-end. Мы упрощаем и ускоряем процесс обучения, применяя единый мультимасштабный спектрограммный adversary, который эффективно снижает артефакты и позволяет получать образцы высокого качества. Мы предлагаем новый механизм балансировки потерь для стабилизации обучения: вес потери теперь определяет долю общего градиента, которую она должна составлять, что позволяет отделить выбор этого гиперпараметра от типичного масштаба потери. Наконец, мы исследуем, как лёгкие модели Transformer можно использовать для дополнительного сжатия полученного представления до 40%, сохраняя при этом скорость выше реального времени. Мы приводим подробное описание ключевых проектных решений предложенной модели, включая: целевую функцию обучения, архитектурные изменения и анализ различных функций перцептивных потерь. Мы представляем обширную субъективную оценку (тесты MUSHRA) вместе с ablation study для ряда полос пропускания и областей применения аудио, включая речь, речь в условиях шума и реверберации, а также музыку. Наш подход превосходит базовые методы во всех рассмотренных условиях, как для монофонического аудио 24 кГц, так и для стереофонического аудио 48 кГц.

Эта модель была предоставлена 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_values

EncodecConfig

класс 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 )

Параметры

  • target_bandwidths (list[float], необязательный, по умолчанию [1.5, 3.0, 6.0, 12.0, 24.0]) — Диапазон различных пропускных способностей, с которыми модель может кодировать аудио.
  • sampling_rate (int, необязательный, по умолчанию 24000) — Частота дискретизации, с которой аудиофайлы должны быть оцифрованы, выраженная в герцах (Гц).
  • 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) — Во сколько раз увеличивать дилатацию на каждом слое.
  • 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. Если 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.config

EncodecFeatureExtractor

класс transformers.EncodecFeatureExtractor

< >

( 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) — Частота дискретизации, с которой аудиосигнал должен быть оцифрован, выраженная в герцах (Гц).
  • padding_value (float, необязательный, по умолчанию 0.0) — Значение, используемое для заполнения позиций, отведённых под padding.
  • chunk_length_s (float, необязательный) — Если задано, аудио предварительно обрабатывается, разбиваясь на фрагменты длиной chunk_length_s, а затем кодируется.
  • overlap (float, необязательный) — Определяет перекрытие между каждым фрагментом. Используется для вычисления chunk_stride по следующей формуле: int((1.0 - self.overlap) * self.chunk_length).

Создаёт экстрактор признаков EnCodec.

Этот экстрактор признаков наследуется от SequenceFeatureExtractor, который содержит большинство основных методов. За дополнительной информацией о них следует обращаться к этому суперклассу.

Создание экземпляра feature extractor с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации архитектуры 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 )

Параметры

  • raw_audio (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — Последовательность или батч последовательностей для обработки. Каждая последовательность может быть массивом numpy, списком значений float, списком массивов numpy или списком списков значений float. Массив numpy должен иметь форму (num_samples,) для моноаудио (feature_size = 1) или (2, num_samples) для стереоаудио (feature_size = 2).
  • 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': возвращает объекты torch.Tensor PyTorch.
    • 'np': возвращает объекты Numpy np.ndarray.
  • sampling_rate (int, необязательный) — Частота дискретизации, с которой была оцифрована входная audio. Настоятельно рекомендуется передавать sampling_rate при вызове forward, чтобы избежать скрытых ошибок.

Основной метод для создания признаков и подготовки одной или нескольких последовательностей для модели.

EncodecModel

класс transformers.EncodecModel

< >

( config: EncodecConfig )

Параметры

  • config (EncodecConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().

Модель нейросетевого аудиокодера EnCodec.

Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)

Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

decode

< >

( 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

< >

( 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)) — Значения типа float для входной аудиоволны.
  • padding_mask (torch.Tensor формы (batch_size, channels, sequence_length)) — Маска отступов, используемая для дополнения input_values.
  • bandwidth (float, необязательный) — Целевая пропускная способность. Должно быть одним из значений config.target_bandwidths. Если None, используется минимально возможная пропускная способность. bandwidth выражается в тысячных долях от фактического значения, например, пропускная способность 6 кбит/с представляется как bandwidth == 6.0

Возвращает

EncodecEncoderOutput словарь или кортеж, содержащий

  • 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 (так как энкодер применяется к полному аудио), что характерно для модели 24 кГц. В противном случае nb_frames=ceil(input_length/self.config.chunk_stride), что характерно для модели 48 кГц.
  • frame_len — это длина каждого кадра, которая равна ceil(input_length/self.config.hop_length), если self.config.chunk_length=None (например, для модели 24 кГц). В противном случае, если self.config.chunk_length задано, то frame_len=self.config.chunk_length/self.config.hop_length, например, для модели 48 кГц с 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)

Параметры

  • input_values (torch.Tensor формы (batch_size, channels, sequence_length), необязательный) — Сырые аудиоданные, преобразованные в Float и дополненные нулями до нужной длины для кодирования с использованием блоков длины self.chunk_length и шага config.chunk_stride.
  • padding_mask (torch.BoolTensor формы (batch_size, channels, sequence_length), , необязательный) — Маска для исключения индексов токенов заполнителя из вычисления коэффициентов масштабирования (можно ли избежать вычисления свёртки для них+). Значения маски выбираются из диапазона [0, 1]: 1 для токенов, не скрытых маской, 0 для скрытых. padding_mask следует передавать всегда, если вход не был усечён или не был дополнен. Это необходимо для эффективной обработки тензоров: входной аудиосигнал должен быть дополнен так, чтобы input_length % stride = step, где step = chunk_length - stride. Это гарантирует, что все фрагменты имеют одинаковую форму [0, 1]:
    • 1 для токенов, которые не замаскированы,
    • 0 для токенов, которые замаскированы.

    padding_mask следует передавать всегда, если входные данные не были усечены или не требуют выравнивания. Это необходимо, чтобы эффективно обрабатывать тензоры: входной аудиосигнал должен быть дополнен нулями так, чтобы выполнялось условие input_length % stride = step, где step = chunk_length-stride. Это гарантирует, что все фрагменты имеют одинаковую форму.

  • bandwidth (float, необязательный) — Целевая пропускная способность. Должно быть одним из значений config.target_bandwidths. Если None, используется минимально возможная пропускная способность. bandwidth выражается в тысячных долях от фактического значения, например, пропускная способность 6 кбит/с задается как bandwidth == 6.0
  • audio_codes (torch.LongTensor формы (nb_frames, batch_size, nb_quantizers, frame_len), необязательный) — Дискретные кодовые эмбеддинги, вычисленные с помощью model.encode.
  • audio_scales (list длины nb_frames, состоящий из torch.Tensor формы (batch_size, 1), необязательный) — Коэффициент масштабирования для каждого входа audio_codes.
  • return_dict (bool, необязательный) — Указывает, следует ли возвращать выходные данные в виде словаря.
  • last_frame_pad_length (int, необязательный) — Длина отступов в последнем кадре, если они есть. Это значение используется для того, чтобы закодированные кадры можно было вывести в виде тензора. При декодировании это значение следует передать, чтобы отступы были удалены из закодированных кадров.

Возвращает

EncodecOutput или tuple(torch.Tensor)

EncodecOutput или кортеж из torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные элементы в зависимости от конфигурации (EncodecConfig) и входных данных.

Метод forward модели EncodecModel переопределяет специальный метод __call__.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.

  • audio_codes (torch.LongTensor формы (nb_frames, batch_size, nb_quantizers, frame_len), необязательный) — Вложения дискретных кодов, вычисленные с помощью model.encode.
  • audio_values (torch.Tensor формы (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
Update on GitHub

←Dia FastSpeech2Conformer→