# EnCodec

## Обзор

Модель нейронного кодека EnCodec была предложена в работе [High Fidelity Neural Audio Compression](https://huggingface.co/papers/2210.13438) авторами Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

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

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

Эта модель была предоставлена [Matthijs](https://huggingface.co/Matthijs), [Patrick Von Platen](https://huggingface.co/patrickvonplaten) и [Arthur Zucker](https://huggingface.co/ArthurZ). Исходный код можно найти [здесь](https://github.com/facebookresearch/encodec).

## Пример использования

Вот краткий пример того, как закодировать и декодировать аудио с помощью этой модели:

```python
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.EncodecConfig[[transformers.EncodecConfig]]

```python
transformers.EncodecConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, target_bandwidths: list[float] | tuple[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: int | float | None = None, overlap: float | None = None, hidden_size: int = 128, num_filters: int = 32, num_residual_layers: int = 1, upsampling_ratios: list[int] | tuple[int, ...] = (8, 5, 4, 2), norm_type: str = 'weight_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, num_lstm_layers: int = 2, trim_right_ratio: float = 1.0, codebook_size: int = 1024, codebook_dim: int | None = None, use_conv_shortcut: bool = True)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/configuration_encodec.py#L27)

**Параметры:**

target_bandwidths (`list[float]`, *необязательный*, по умолчанию `[1.5, 3.0, 6.0, 12.0, 24.0]`) : Диапазон различных полос пропускания, с которыми модель может кодировать аудио.

sampling_rate (`int`, *optional*, по умолчанию `24000`) : Частота дискретизации, с которой аудиофайлы должны быть оцифрованы, выраженная в герцах (Гц).

audio_channels (`int`, *необязательный*, по умолчанию `1`) : Количество входных каналов.

normalize (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли нормализовать аудио при передаче.

chunk_length_s (`float`, *optional*) : Если определено, аудио предварительно обрабатывается в блоки длины `chunk_length_s`, а затем кодируется.

overlap (`float`, *optional*) : Определяет перекрытие между каждым фрагментом. Используется для вычисления `chunk_stride` по следующей формуле: `int((1.0 - self.overlap) * self.chunk_length)`.

hidden_size (`int`, *optional*, по умолчанию `128`) : Размерность скрытых представлений.

num_filters (`int`, *optional*, по умолчанию 32) : Количество свёрточных ядер первого слоя понижающей дискретизации `EncodecConv1d`.

num_residual_layers (`int`,  *необязательный*, по умолчанию 1) : Количество остаточных слоёв.

upsampling_ratios (`Sequence[int]` , *optional*, по умолчанию `[8, 5, 4, 2]`) : Соотношения размера и шага ядра. Кодировщик использует соотношения даунсемплинга вместо апсемплинга, поэтому он применяет соотношения в обратном порядке по сравнению с указанными здесь, которые должны соответствовать порядку декодера.

norm_type (`str`, *необязательный*, по умолчанию `"weight_norm"`) : Метод нормализации. Должен быть из `["weight_norm", "time_group_norm"]`

kernel_size (`int`, *optional*, по умолчанию 7) : Размер ядра для начальной свёртки.

last_kernel_size (`int`, *необязательный*, по умолчанию 7) : Размер ядра для последнего свёрточного слоя.

residual_kernel_size (`int`, *optional*, по умолчанию 3) : Размер ядра для остаточных слоёв.

dilation_growth_rate (`int`, *optional*, по умолчанию 2) : Насколько увеличивать дилатацию на каждом слое.

use_causal_conv (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли полностью каузальную свёртку.

pad_mode (`str`, *необязательный*, по умолчанию `"reflect"`) : Режим дополнения для свёрток.

compress (`int`, *optional*, по умолчанию 2) : Сокращённая размерность в остаточных ветках (из Demucs v3).

num_lstm_layers (`int`, *optional*, по умолчанию 2) : Количество слоёв LSTM в конце кодировщика.

trim_right_ratio (`float`, *optional*, по умолчанию 1.0) : Коэффициент обрезки справа для транспонированной свёртки при настройке `use_causal_conv = True`. Если значение равно 1.0, это означает, что вся обрезка выполняется справа.

codebook_size (`int`, *необязательный*, по умолчанию `1024`) : Количество параллельных кодовых книг, используемых моделью.

codebook_dim (`int`, *optional*) : Размерность каждого вектора встраивания из книги кодов.

use_conv_shortcut (`bool`, *необязательный*, по умолчанию `True`) : Использовать ли свёрточный слой в качестве соединения 'skip' в блоке `EncodecResnetBlock`. Если False, будет использована тождественная функция, что даст обычное остаточное соединение.

Это класс конфигурации для хранения настроек модели EncodecModel. Он используется для создания модели Encodec в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:

```python
>>> 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]]

#### transformers.EncodecFeatureExtractor[[transformers.EncodecFeatureExtractor]]

```python
transformers.EncodecFeatureExtractor(feature_size: int = 1, sampling_rate: int = 24000, padding_value: float = 0.0, chunk_length_s: float | None = None, overlap: float | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/feature_extraction_encodec.py#L26)

**Параметры:**

feature_size (`int`, *optional*, по умолчанию 1) : Размерность признаков извлекаемых фич. Используйте 1 для моно, 2 для стерео.

sampling_rate (`int`, *optional*, по умолчанию 24000) : Частота дискретизации, с которой аудиоволна должна быть оцифрована, выраженная в герцах (Гц).

padding_value (`float`, *необязательный*, по умолчанию 0.0) : Значение, используемое для заполнения позиций с заполнителем (padding).

chunk_length_s (`float`, *optional*) : Если определено, аудио предварительно обрабатывается в блоки длины `chunk_length_s`, а затем кодируется.

overlap (`float`, *optional*) : Определяет перекрытие между каждым фрагментом. Используется для вычисления `chunk_stride` по следующей формуле: `int((1.0 - self.overlap) * self.chunk_length)`.

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

Этот экстрактор признаков наследуется от [SequenceFeatureExtractor](/docs/transformers/v5.23.0/ru/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), который содержит большинство основных методов. За дополнительной информацией о них следует обращаться к этому суперклассу.

Создание экземпляра feature extractor с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации архитектуры [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz).

#### __call__[[transformers.EncodecFeatureExtractor.__call__]]

```python
__call__(raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], padding: bool | str | transformers.utils.generic.PaddingStrategy | None = None, truncation: bool | None = False, max_length: int | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/feature_extraction_encodec.py#L81)

**Параметры:**

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](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.utils.PaddingStrategy), *необязательный*, по умолчанию `True`) : Выбор стратегии выравнивания возвращаемых последовательностей (с учётом стороны выравнивания и индекса padding модели) из следующих вариантов:  - `True` или `'longest'`: Выравнивание до самой длинной последовательности в батче (или без выравнивания, если предоставлена только одна последовательность). - `'max_length'`: Выравнивание до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. - `False` или `'do_not_pad'` (по умолчанию): Без выравнивания (т. е. на выходе может быть батч с последовательностями разной длины).

truncation (`bool`, *необязательный*, по умолчанию `False`) : Включает усечение, чтобы сократить входные последовательности длиннее `max_length` до `max_length`.

max_length (`int`, *optional*) : Максимальная длина возвращаемого списка и, при необходимости, длина отступов (см. выше).

return_tensors (`str` или [TensorType](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры вместо списка целых чисел Python. Допустимые значения:  - `'pt'`: Возвращает объекты `torch.Tensor` PyTorch. - `'np'`: Возвращает объекты `np.ndarray` Numpy.

sampling_rate (`int`, *optional*) : Частота дискретизации, с которой была оцифрована входная `audio`. Настоятельно рекомендуется передавать `sampling_rate` при вызове forward, чтобы избежать скрытых ошибок.

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

## EncodecModel[[transformers.EncodecModel]]

#### transformers.EncodecModel[[transformers.EncodecModel]]

```python
transformers.EncodecModel(config: EncodecConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L485)

**Параметры:**

config ([EncodecConfig](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

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

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### decode[[transformers.EncodecModel.decode]]

```python
decode(audio_codes: LongTensor, audio_scales: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, last_frame_pad_length: int | None = 0)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L661)

**Параметры:**

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](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) вместо обычного кортежа.

last_frame_pad_length (`int`, *optional*) : целое число, обозначающее длину отступов в последнем кадре, которые удаляются при декодировании.

Декодирует указанные кадры в выходную аудиоволну.

Обратите внимание, что выходной результат может быть немного больше входного. В этом случае лишние шаги в конце можно отбросить.

#### encode[[transformers.EncodecModel.encode]]

```python
encode(input_values: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, bandwidth: float | None = None, return_dict: bool | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L525)

**Параметры:**

input_values (`torch.Tensor` формы `(batch_size, channels, sequence_length)`) : Значения типа Float входной аудиоволны.

padding_mask (`torch.Tensor` формы `(batch_size, channels, sequence_length)`) : Маска отступов, используемая для дополнения `input_values`.

bandwidth (`float`, *optional*) : Целевая пропускная способность. Должна быть одним из значений `config.target_bandwidths`. Если `None`, используется минимально возможная пропускная способность. bandwidth выражается в тысячных долях от фактического значения, например, пропускная способность 6 кбит/с задается как bandwidth == 6.0

**Возвращает:** `EncodecEncoderOutput dict or a tuple containing`

- 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[[transformers.EncodecModel.forward]]

```python
forward(input_values: Tensor, padding_mask: typing.Optional[torch.BoolTensor] = None, bandwidth: float | None = None, audio_codes: typing.Optional[torch.LongTensor] = None, audio_scales: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, last_frame_pad_length: int | None = 0)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L716)

**Параметры:**

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`. Это гарантирует, что все фрагменты имеют одинаковую форму

bandwidth (`float`, *optional*) : Целевая пропускная способность. Должна быть одним из значений `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`, *optional*) : Длина отступов в последнем кадре, если они есть. Это значение используется для того, чтобы закодированные кадры можно было вывести в виде тензора. Это значение следует передавать при декодировании, чтобы отступы были удалены из закодированных кадров.

**Возвращает:** `EncodecOutput` или `tuple(torch.Tensor)`

Объект `EncodecOutput` или кортеж из `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([EncodecConfig](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecConfig)) и входных данных.

Метод forward модели [EncodecModel](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.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.

Примеры:

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

