# Pop2Piano

## Обзор

Модель Pop2Piano была предложена в работе [Pop2Piano : Pop Audio-based Piano Cover Generation](https://huggingface.co/papers/2211.00895) авторами Jongho Choi и Kyogu Lee.

Популярные фортепианные каверы широко востребованы, но их генерация из музыки — задача не из простых. Она требует высокого уровня владения фортепиано, а также знания различных характеристик и мелодий песни. С помощью Pop2Piano можно напрямую генерировать кавер из аудиоволны песни. Это первая модель, которая генерирует фортепианный кавер из поп-музыки напрямую, без модулей извлечения мелодии и аккордов.

Pop2Piano — это модель Transformer с архитектурой «кодировщик-декодер», основанная на [T5](https://huggingface.co/papers/1910.10683). Входной аудиосигнал преобразуется в его волновую форму и передаётся в кодировщик, который преобразует её в латентное представление. Декодер использует эти латентные представления для генерации идентификаторов токенов в авторегрессионном режиме. Каждый идентификатор токена соответствует одному из четырёх различных типов токенов: time, velocity, note и 'special'. Затем идентификаторы токенов декодируются в эквивалентный MIDI-файл.

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

*Пiano-версии поп-музыки пользуются большой популярностью. Однако задача автоматической генерации piano-версий поп-музыки остаётся недостаточно изученной. Это отчасти связано с отсутствием синхронизированных пар данных {Pop, Piano Cover}, что затрудняло применение новейших методов глубокого обучения, требующих больших объёмов данных. Чтобы использовать потенциал data-driven подхода, мы создали большой объём парных и синхронизированных данных {Pop, Piano Cover} с помощью автоматизированного конвейера. В данной статье мы представляем Pop2Piano — Transformer-сеть, которая генерирует piano-версии по волновым формам поп-музыки. По нашему мнению, это первая модель, генерирующая piano-версию напрямую из поп-аудио без использования модулей извлечения мелодии и аккордов. Мы показываем, что Pop2Piano, обученный на нашем наборе данных, способен создавать правдоподобные piano-версии.*

Эта модель была предоставлена [Susnato Dhar](https://huggingface.co/susnato). Исходный код можно найти [здесь](https://github.com/sweetcocoa/pop2piano).

## Советы по использованию

* Для использования Pop2Piano необходимо установить библиотеку 🤗 Transformers, а также следующие сторонние модули:

```bash
pip install pretty-midi==0.2.9 essentia==2.1b6.dev1034 librosa scipy
```

Обратите внимание, что после установки может потребоваться перезапустить среду выполнения.

* Pop2Piano — это модель с архитектурой «кодировщик-декодировщик», подобная T5.
* Pop2Piano можно использовать для генерации midi-аудиофайлов для заданной аудиоследовательности.
* Выбор разных композиторов в `Pop2PianoForConditionalGeneration.generate()` может привести к разнообразию результатов.
* Установка частоты дискретизации 44,1 кГц при загрузке аудиофайла может обеспечить хорошее качество.
* Хотя Pop2Piano обучался преимущественно на корейской поп-музыке, он также хорошо справляется с другими западными поп- или хип-хоп-треками.

## Примеры

- Пример с использованием набора данных HuggingFace:

```python
from datasets import load_dataset

from transformers import Pop2PianoForConditionalGeneration, Pop2PianoProcessor

model = Pop2PianoForConditionalGeneration.from_pretrained("sweetcocoa/pop2piano", device_map="auto")
processor = Pop2PianoProcessor.from_pretrained("sweetcocoa/pop2piano")
ds = load_dataset("sweetcocoa/pop2piano_ci", split="test")

inputs = processor(
    audio=ds["audio"][0]["array"], sampling_rate=ds["audio"][0]["sampling_rate"], return_tensors="pt"
)
model_output = model.generate(input_features=inputs["input_features"], composer="composer1")
tokenizer_output = processor.batch_decode(
    token_ids=model_output, feature_extractor_output=inputs
)["pretty_midi_objects"][0]
tokenizer_output.write("./Outputs/midi_output.mid")
```

- Пример с использованием собственного аудиофайла:

```python
import librosa

from transformers import Pop2PianoForConditionalGeneration, Pop2PianoProcessor

audio, sr = librosa.load("<your_audio_file_here>", sr=44100)  # feel free to change the sr to a suitable value.
model = Pop2PianoForConditionalGeneration.from_pretrained("sweetcocoa/pop2piano", device_map="auto")
processor = Pop2PianoProcessor.from_pretrained("sweetcocoa/pop2piano")

inputs = processor(audio=audio, sampling_rate=sr, return_tensors="pt").to(model.device)
model_output = model.generate(input_features=inputs["input_features"], composer="composer1")
tokenizer_output = processor.batch_decode(
    token_ids=model_output, feature_extractor_output=inputs
)["pretty_midi_objects"][0]
tokenizer_output.write("./Outputs/midi_output.mid")
```

- Пример обработки нескольких аудиофайлов в батче:

```python
import librosa

from transformers import Pop2PianoForConditionalGeneration, Pop2PianoProcessor

# feel free to change the sr to a suitable value.
audio1, sr1 = librosa.load("<your_first_audio_file_here>", sr=44100)
audio2, sr2 = librosa.load("<your_second_audio_file_here>", sr=44100)
model = Pop2PianoForConditionalGeneration.from_pretrained("sweetcocoa/pop2piano", device_map="auto")
processor = Pop2PianoProcessor.from_pretrained("sweetcocoa/pop2piano")

inputs = processor(audio=[audio1, audio2], sampling_rate=[sr1, sr2], return_attention_mask=True, return_tensors="pt").to(model.device)
# Since we now generating in batch(2 audios) we must pass the attention_mask
model_output = model.generate(
    input_features=inputs["input_features"],
    attention_mask=inputs["attention_mask"],
    composer="composer1",
)
tokenizer_output = processor.batch_decode(
    token_ids=model_output, feature_extractor_output=inputs
)["pretty_midi_objects"]

# Since we now have 2 generated MIDI files
tokenizer_output[0].write("./Outputs/midi_output1.mid")
tokenizer_output[1].write("./Outputs/midi_output2.mid")
```

- Пример обработки нескольких аудиофайлов в батче (с использованием `Pop2PianoFeatureExtractor` и `Pop2PianoTokenizer`):

```python
import librosa

from transformers import Pop2PianoFeatureExtractor, Pop2PianoForConditionalGeneration, Pop2PianoTokenizer

# feel free to change the sr to a suitable value.
audio1, sr1 = librosa.load("<your_first_audio_file_here>", sr=44100)
audio2, sr2 = librosa.load("<your_second_audio_file_here>", sr=44100)
model = Pop2PianoForConditionalGeneration.from_pretrained("sweetcocoa/pop2piano", device_map="auto")
feature_extractor = Pop2PianoFeatureExtractor.from_pretrained("sweetcocoa/pop2piano")
tokenizer = Pop2PianoTokenizer.from_pretrained("sweetcocoa/pop2piano")

inputs = feature_extractor(
    audio=[audio1, audio2],
    sampling_rate=[sr1, sr2],
    return_attention_mask=True,
    return_tensors="pt",
)
# Since we now generating in batch(2 audios) we must pass the attention_mask
model_output = model.generate(
    input_features=inputs["input_features"],
    attention_mask=inputs["attention_mask"],
    composer="composer1",
)
tokenizer_output = tokenizer.batch_decode(
    token_ids=model_output, feature_extractor_output=inputs
)["pretty_midi_objects"]

# Since we now have 2 generated MIDI files
tokenizer_output[0].write("./Outputs/midi_output1.mid")
tokenizer_output[1].write("./Outputs/midi_output2.mid")
```

## Pop2PianoConfig[[transformers.Pop2PianoConfig]]

#### transformers.Pop2PianoConfig[[transformers.Pop2PianoConfig]]

```python
transformers.Pop2PianoConfig(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, 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, is_encoder_decoder: bool = True, vocab_size: int = 2400, composer_vocab_size: int = 21, d_model: int = 512, d_kv: int = 64, d_ff: int = 2048, num_layers: int = 6, num_decoder_layers: int | None = None, num_heads: int = 8, relative_attention_num_buckets: int = 32, relative_attention_max_distance: int = 128, dropout_rate: float | int = 0.1, layer_norm_epsilon: float = 1e-06, initializer_factor: float = 1.0, feed_forward_proj: str = 'gated-gelu', use_cache: bool = True, pad_token_id: int | None = 0, eos_token_id: int | list[int] | None = 1, dense_act_fn: str = 'relu', is_decoder: bool = False, tie_word_embeddings: bool = True)
```

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

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

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

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

composer_vocab_size (`int`, *optional*, по умолчанию 21) : Указывает количество композиторов.

d_model (`int`, *необязательный*, по умолчанию `512`) : Размер слоев кодировщика и пулера.

d_kv (`int`, *необязательный*, по умолчанию `64`) : Размер проекций ключа, запроса и значения на каждую голову внимания. `inner_dim` слоя проекции определяется как `num_heads * d_kv`.

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

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

num_decoder_layers (`int`, *optional*) : Количество скрытых слоев в декодере Transformer. Если не задано, будет использовано то же значение, что и у `num_layers`.

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

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

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

dropout_rate (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Доля для всех слоёв dropout.

layer_norm_epsilon (`float`, *необязательный*, по умолчанию `1e-06`) : Значение epsilon, используемое слоями нормализации.

initializer_factor (`float`, *необязательный*, по умолчанию `1.0`) : Коэффициент для инициализации всех матриц весов (должен оставаться равным 1, используется внутренне для тестирования инициализации).

feed_forward_proj (`string`, *необязательный*, по умолчанию `"gated-gelu"`) : Тип слоя feed forward, который будет использоваться. Должно быть одним из `"relu"` или `"gated-gelu"`.

use_cache (`bool`, *необязательный*, по умолчанию `True`) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только при `config.is_decoder=True` или если модель является генеративной моделью только с декодером.

pad_token_id (`int`, *необязательный*, по умолчанию `0`) : Идентификатор токена, используемый для выравнивания в словаре.

eos_token_id (`Union[int, list[int]]`, *необязательный*, по умолчанию `1`) : Идентификатор токена, используемого для обозначения конца потока в словаре.

dense_act_fn (`string`, *необязательный*, по умолчанию `"relu"`) : Тип функции активации, используемой в `Pop2PianoDenseActDense` и в `Pop2PianoDenseGatedActDense`.

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

tie_word_embeddings (`bool`, *необязательный*, по умолчанию `True`) : Связывать ли веса эмбеддингов согласно отображению `tied_weights_keys` модели.

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

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

## Pop2PianoFeatureExtractor[[transformers.Pop2PianoFeatureExtractor]]

#### transformers.Pop2PianoFeatureExtractor[[transformers.Pop2PianoFeatureExtractor]]

```python
transformers.Pop2PianoFeatureExtractor(sampling_rate: int = 22050, padding_value: int = 0, window_size: int = 4096, hop_length: int = 1024, min_frequency: float = 10.0, feature_size: int = 512, num_bars: int = 2, **kwargs)
```

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

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

sampling_rate (`int`, *optional*, по умолчанию 22050) : Целевая частота дискретизации аудиосигнала. Это частота дискретизации, которую мы передаём в модель.

padding_value (`int`, *optional*, по умолчанию 0) : Значение, используемое для дополнения аудио. Должно соответствовать тишине.

window_size (`int`, *optional*, по умолчанию 4096) : Длина окна в сэмплах, к которому применяется преобразование Фурье.

hop_length (`int`, *optional*, по умолчанию 1024) : Шаг между окнами волнового сигнала, в отсчетах.

min_frequency (`float`, *optional*, по умолчанию 10.0) : Минимальная частота, используемая в лог-мел-спектрограмме.

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

num_bars (`int`, *необязательный*, по умолчанию 2) : Определяет интервал между каждой последовательностью.

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

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

Этот класс извлекает ритм и выполняет предобработку аудио перед передачей в модель. Сначала аудио передаётся в алгоритм `RhythmExtractor2013`, который извлекает beat_times, позиции битов, оценивает их уверенность, а также темп в bpm. Затем beat_times интерполируется для получения beatsteps. Позже из них вычисляются extrapolated_beatsteps, которые используются в токенизаторе. С другой стороны, аудио ресемплируется до self.sampling_rate и предобрабатывается, после чего из него вычисляется логарифмическая мел-спектрограмма для использования в нашей трансформерной модели.

#### __call__[[transformers.Pop2PianoFeatureExtractor.__call__]]

```python
__call__(audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], sampling_rate: int | list[int], steps_per_beat: int = 2, resample: bool | None = True, return_attention_mask: bool | None = False, return_tensors: str | transformers.utils.generic.TensorType | None = None, **kwargs)
```

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

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

audio (`np.ndarray`, `List`) : Аудио или пакет аудио для обработки. Каждое аудио может быть массивом numpy, списком значений float, списком массивов numpy или списком списков значений float.

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

steps_per_beat (`int`, *необязательный*, по умолчанию 2) : Используется при интерполяции `beat_times`.

resample (`bool`, *необязательный*, по умолчанию `True`) : Определяет, нужно ли перед обработкой пересэмплировать аудио до `sampling_rate`. Во время инференса должно быть True.

return_attention_mask (`bool` *optional*, по умолчанию `False`) : Указывает, будет ли attention_mask для input_features, beatsteps и extrapolated_beatstep возвращаться в качестве вывода. Автоматически устанавливается в True для пакетных входных данных.

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

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

## Pop2PianoForConditionalGeneration[[transformers.Pop2PianoForConditionalGeneration]]

#### transformers.Pop2PianoForConditionalGeneration[[transformers.Pop2PianoForConditionalGeneration]]

```python
transformers.Pop2PianoForConditionalGeneration(config: Pop2PianoConfig)
```

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

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

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

Модель Pop2Piano с головкой `language modeling` наверху.

Эта модель наследуется от [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 по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.Pop2PianoForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, input_features: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`) : Индексы токенов входной последовательности в словаре. Pop2Piano — модель с относительными позиционными эмбеддингами, поэтому вы можете дополнять (padding) входные данные как справа, так и слева. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое input IDs?](../glossary#input-ids) Чтобы узнать, как подготовить `input_ids` для предварительного обучения, ознакомьтесь с разделом [Pop2Piano Training](./Pop2Piano#training).

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательно*) : Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы декодера?](../glossary#decoder-input-ids) Pop2Piano использует `pad_token_id` в качестве начального токена для генерации `decoder_input_ids`. Если используется `past_key_values`, необязательно вводить только последние `decoder_input_ids` (см. `past_key_values`). Чтобы узнать больше о том, как подготовить

decoder_attention_mask (`torch.BoolTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Поведение по умолчанию: генерировать тензор, игнорирующий токены заполнения в `decoder_input_ids`. Маска причинности также будет использоваться по умолчанию.

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *необязательный*) : Кортеж состоит из (`last_hidden_state`, *необязательный*: `hidden_states`, *необязательный*: `attentions`) `last_hidden_state` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) представляет собой последовательность скрытых состояний на выходе последнего слоя кодировщика. Используется в кросс-внимании декодера.

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

input_features (`torch.Tensor` формы `(batch_size, sequence_length, feature_dim)`, *необязательно*) : Тензоры, соответствующие входным аудиособытиям. Аудиособытия можно получить с помощью [Pop2PianoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor). Подробности см. в [Pop2PianoFeatureExtractor.__call__()](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor.__call__) ([Pop2PianoProcessor](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoProcessor) использует [Pop2PianoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor) для обработки аудио).

decoder_inputs_embeds (`torch.Tensor` формы `(batch_size, target_sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `decoder_input_ids` можно напрямую передать встроенное представление. Если используется `past_key_values`, по желанию на вход нужно передавать только последние `decoder_inputs_embeds` (см. `past_key_values`). Это полезно, если требуется больший контроль над тем, как индексы `decoder_input_ids` преобразуются в соответствующие векторы, чем это делает внутренняя матрица поиска встраиваний модели. Если `decoder_input_ids` и `decoder_inputs_embeds` не заданы, `decoder_inputs_embeds` принимает значение `inputs_embeds`.

labels (`torch.LongTensor` формы `(batch_size,)`, *необязательный*) : Метки для вычисления функции потерь классификации/регрессии последовательности. Индексы должны находиться в диапазоне `[-100, 0, ..., config.vocab_size - 1]`. Все метки, установленные в `-100`, игнорируются (маскируются); потери вычисляются только для меток в диапазоне `[0, ..., config.vocab_size]`

use_cache (`bool`, *необязательный*) : Если установлено в `True`, состояния ключей и значений `past_key_values` возвращаются и могут использоваться для ускорения декодирования (см. `past_key_values`).

**Возвращает:** [Seq2SeqLMOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) или `tuple(torch.Tensor)`

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

Метод forward класса [Pop2PianoForConditionalGeneration](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoForConditionalGeneration) переопределяет специальный метод `__call__`.

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели.
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **past_key_values** (`EncoderDecoderCache`, *необязательный*, возвращается при передаче `use_cache=True` или при `config.use_cache=True`) -- это экземпляр [EncoderDecoderCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.EncoderDecoderCache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
- **decoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **cross_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) — Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кросс-внимания декодера, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах кросс-внимания.
- **encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя энкодера модели.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **encoder_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

Пример:

```python
>>> from transformers import AutoProcessor, Pop2PianoForConditionalGeneration
>>> from datasets import load_dataset
>>> import torch

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation")
>>> dataset = dataset.sort("id")
>>> sampling_rate = dataset.features["audio"].sampling_rate

>>> processor = AutoProcessor.from_pretrained("sweetcocoa/pop2piano")
>>> model = Pop2PianoForConditionalGeneration.from_pretrained("sweetcocoa/pop2piano")

>>> # audio file is decoded on the fly
>>> inputs = processor(dataset[0]["audio"]["array"], sampling_rate=sampling_rate, return_tensors="pt")
>>> with torch.no_grad():
...     logits = model(**inputs).logits
>>> predicted_ids = torch.argmax(logits, dim=-1)

>>> # transcribe speech
>>> transcription = processor.batch_decode(predicted_ids)
>>> transcription[0]
...

>>> inputs["labels"] = processor(text=dataset[0]["text"], return_tensors="pt").input_ids

>>> # compute loss
>>> loss = model(**inputs).loss
>>> round(loss.item(), 2)
...
```

#### generate[[transformers.Pop2PianoForConditionalGeneration.generate]]

```python
generate(input_features, attention_mask = None, composer = 'composer1', generation_config = None, **kwargs)
```

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

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

input_features (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) : Это версионизированное представление аудио, сгенерированное `Pop2PianoFeatureExtractor`.

attention_mask : При пакетной генерации `input_features` дополняются нулями, чтобы иметь одинаковую форму во всех примерах. `attention_mask` помогает определить, какие области были дополнены, а какие — нет. - 1 для токенов, которые **не дополнены**, - 0 для токенов, которые **дополнены**.

composer (`str`, *необязательный*, по умолчанию `"composer1"`) : Это значение передаётся в `Pop2PianoConcatEmbeddingToMel` для генерации различных эмбеддингов для каждого `"composer"`. Убедитесь, что значение composer присутствует в `composer_to_feature_token` в `generation_config`. Пример см. по адресу https://huggingface.co/sweetcocoa/pop2piano/blob/main/generation_config.json .

generation_config (`~generation.GenerationConfig`, *optional*) : Конфигурация генерации, используемая в качестве базовой параметризации для вызова генерации. Аргументы `**kwargs`, переданные в generate и совпадающие с атрибутами `generation_config`, переопределяют их. Если `generation_config` не предоставлен, будет использован вариант по умолчанию, который имеет следующий приоритет загрузки: 1) из файла модели `generation_config.json`, если он существует; 2) из конфигурации модели. Обратите внимание, что не указанные параметры наследуют значения по умолчанию [GenerationConfig](/docs/transformers/v5.23.0/ru/main_classes/text_generation#transformers.GenerationConfig), документация по которым должна быть проверена для параметризации генерации.

kwargs : Параметризация ad hoc для `generate_config` и/или дополнительные аргументы kwargs, специфичные для модели, которые будут переданы в функцию `forward` модели. Если модель является моделью типа encoder-decoder, аргументы kwargs, специфичные для энкодера, не должны иметь префикса, а аргументы kwargs, специфичные для декодера, должны иметь префикс *decoder_*.

**Возвращает:** [ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) или `torch.LongTensor`

[ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput) (если `return_dict_in_generate=True` или когда `config.return_dict_in_generate=True`) или `torch.Tensor`. Поскольку Pop2Piano является моделью с кодировщиком-декодировщиком (`model.config.is_encoder_decoder=True`), возможные типы [ModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.utils.ModelOutput):
- [GenerateEncoderDecoderOutput](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.generation.GenerateEncoderDecoderOutput),
- [GenerateBeamEncoderDecoderOutput](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.generation.GenerateBeamEncoderDecoderOutput)

Генерирует идентификаторы токенов для MIDI-выходов.

Большинство параметров, управляющих генерацией, задаются в `generation_config`, который, если не передан явно, принимает значение конфигурации генерации по умолчанию для модели. Вы можете переопределить любые параметры `generation_config`, передав соответствующие аргументы в generate(), например, `.generate(inputs, num_beams=4, do_sample=True)`. С обзором стратегий генерации и примерами кода можно ознакомиться в [следующем руководстве](./generation_strategies).

## Pop2PianoTokenizer[[transformers.Pop2PianoTokenizer]]

#### transformers.Pop2PianoTokenizer[[transformers.Pop2PianoTokenizer]]

```python
transformers.Pop2PianoTokenizer(vocab, default_velocity = 77, num_bars = 2, unk_token = '-1', eos_token = '1', pad_token = '0', bos_token = '2', **kwargs)
```

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

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

vocab (`str`) : Путь к файлу словаря, содержащему словарь.

default_velocity (`int`, *optional*, по умолчанию 77) : Определяет скорость по умолчанию, используемую при создании нот MIDI.

num_bars (`int`, *optional*, по умолчанию 2) : Определяет cutoff_time_idx для каждого токена.

unk_token (`str` или `tokenizers.AddedToken`, *необязательный*, по умолчанию `"-1"`) : Неизвестный токен. Токен, отсутствующий в словаре, не может быть преобразован в идентификатор и вместо этого заменяется этим токеном.

eos_token (`str` или `tokenizers.AddedToken`, *необязательный*, по умолчанию 1) : Токен конца последовательности.

pad_token (`str` или `tokenizers.AddedToken`, *необязательный*, по умолчанию 0) : Специальный токен, используемый для приведения массивов токенов к одинаковому размеру в целях батчинга. В дальнейшем он игнорируется механизмами внимания или при вычислении функции потерь.

bos_token (`str` или `tokenizers.AddedToken`, *optional*, по умолчанию 2) : Токен начала последовательности, который использовался во время предварительного обучения. Может использоваться в качестве токена классификатора последовательности.

Создаёт токенизатор Pop2Piano. Этот токенизатор не требует обучения.

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

#### __call__[[transformers.Pop2PianoTokenizer.__call__]]

```python
__call__(notes: numpy.ndarray | list[pretty_midi.Note] | list[list[pretty_midi.Note]], padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy | None = None, max_length: int | None = None, pad_to_multiple_of: int | None = None, return_attention_mask: bool | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, verbose: bool = True, **kwargs)
```

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

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

notes (`numpy.ndarray` формы `[batch_size, max_sequence_length, 4]` или `list` объектов `pretty_midi.Note`) : Представляет MIDI-ноты. Если `notes` — это `numpy.ndarray`: - Каждая последовательность должна содержать 4 значения: `onset idx`, `offset idx`, `pitch` и `velocity`. Если `notes` — это `list`, содержащий объекты `pretty_midi.Note`: - Каждая последовательность должна иметь 4 атрибута: `start`, `end`, `pitch` и `velocity`.

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

truncation (`bool`, `str` или [TruncationStrategy](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *необязательный*, по умолчанию `False`) : Включает и управляет усечением. Принимает следующие значения:  - `True` или `'longest_first'`: Усечение до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Усечение выполняется посимвольно: если предоставлена пара последовательностей (или пакет пар), то символ удаляется из самой длинной последовательности в паре. - `'only_first'`: Усечение до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или пакет пар), усечение выполняется только для первой последовательности в паре. - `'only_second'`: Усечение до максимальной длины, указанной в аргументе `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или пакет пар), усечение выполняется только для второй последовательности в паре. - `False` или `'do_not_truncate'` (по умолчанию): Усечение не выполняется (т. е. на выходе может быть пакет с длинами последовательностей, превышающими максимально допустимый размер входных данных модели).

max_length (`int`, *optional*) : Управляет максимальной длиной, используемой одним из параметров усечения/дополнения. Если значение не задано или равно `None`, будет использована предопределённая максимальная длина модели, если один из параметров усечения/дополнения требует указания максимальной длины. Если у модели нет конкретной максимальной длины входных данных (как у XLNet), усечение/дополнение до максимальной длины будет отключено.

pad_to_multiple_of (`int`, *optional*) : Если задано, последовательность будет дополнена нулями до кратного указанного значения. Это особенно полезно для использования Tensor Cores на аппаратных платформах NVIDIA с вычислительной способностью `>= 7.5` (Volta).

return_attention_mask (`bool`, *необязательный*) : Указывает, следует ли возвращать маску внимания. Если значение не задано, маска внимания будет возвращена в соответствии со значением по умолчанию конкретного токенизатора, определяемым атрибутом `return_outputs`.  [Что такое маски внимания?](../glossary#attention-mask)

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.

verbose (`bool`, *необязательный*, по умолчанию `True`) : Выводить ли дополнительную информацию и предупреждения.

**Возвращаемое значение:**

`BatchEncoding`, содержащий token_ids.

Это метод `__call__` для `Pop2PianoTokenizer`. Он преобразует ноты MIDI в идентификаторы токенов, сгенерированные трансформером.

## Pop2PianoProcessor[[transformers.Pop2PianoProcessor]]

#### transformers.Pop2PianoProcessor[[transformers.Pop2PianoProcessor]]

```python
transformers.Pop2PianoProcessor(feature_extractor, tokenizer)
```

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

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

feature_extractor (`Pop2PianoFeatureExtractor`) : Извлекатель признаков является обязательным входом.

tokenizer (`tokenizer_class`) : Токенизатор является обязательным входным параметром.

Создаёт объект Pop2PianoProcessor, который объединяет экстрактор признаков и токенизатор в единый процессор.

[Pop2PianoProcessor](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoProcessor) предоставляет все возможности [Pop2PianoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor) и `tokenizer_class`. Подробнее см. в [~Pop2PianoFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor) и `~tokenizer_class`.

#### __call__[[transformers.Pop2PianoProcessor.__call__]]

```python
__call__(audio: numpy.ndarray | list[float] | list[numpy.ndarray] = None, sampling_rate: int | list[int] | None = None, steps_per_beat: int = 2, resample: bool | None = True, notes: list | transformers.utils.generic.TensorType = None, padding: bool | str | transformers.utils.generic.PaddingStrategy = False, truncation: bool | str | transformers.tokenization_utils_base.TruncationStrategy = None, max_length: int | None = None, pad_to_multiple_of: int | None = None, verbose: bool = True, **kwargs)
```

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

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

audio (`Union[numpy.ndarray, list[float], list[numpy.ndarray]]`, *необязательный*) : Аудио или пакет аудио для подготовки. Каждое аудио может быть массивом NumPy или тензором PyTorch. В случае массива NumPy/тензора PyTorch каждое аудио должно иметь форму (C, T), где C — количество каналов, а T — длина выборки аудио.

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

steps_per_beat (`int`, *optional*, по умолчанию `2`) : Количество шагов времени на музыкальный бит. Этот параметр управляет временным разрешением музыкального представления. Более высокое значение обеспечивает более мелкую временную детализацию, но увеличивает длину последовательности. Используется при обработке аудио для извлечения музыкальных признаков.

resample (`bool`, *необязательный*, по умолчанию `True`) : Фильтр ресемплинга, используемый при изменении размера изображения. Может принимать одно из значений перечисления `PILImageResampling`. Влияет только в том случае, если `do_resize` установлено в `True`.

notes (`list` или `TensorType`, *optional*) : Предварительно извлечённые музыкальные ноты в формате MIDI. Если этот параметр указан, процессор пропускает этап извлечения аудиопризнаков и передаёт ноты напрямую в токенизатор. Каждая нота должна быть представлена в виде списка или тензора, содержащего информацию о высоте, громкости и времени.

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

truncation (bool, str or [TruncationStrategy](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*) : Включает и управляет усечением. Принимает следующие значения:  - `True` или `'longest_first'`: Усечение до максимальной длины, указанной аргументом `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Усечение выполняется посимвольно: если предоставлена пара последовательностей (или батч пар), то токен удаляется из самой длинной последовательности в паре. - `'only_first'`: Усечение до максимальной длины, указанной аргументом `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или батч пар), усечение применяется только к первой последовательности пары. - `'only_second'`: Усечение до максимальной длины, указанной аргументом `max_length`, или до максимально допустимой входной длины для модели, если этот аргумент не указан. Если предоставлена пара последовательностей (или батч пар), усечение применяется только ко второй последовательности пары. - `False` или `'do_not_truncate'` (по умолчанию): Усечение не выполняется (т.е. на выходе может быть батч с длинами последовательностей, превышающими максимально допустимый размер входа модели).

max_length (`int`, *optional*) : Управляет максимальной длиной, используемой одним из параметров усечения/дополнения. Если значение не задано или равно `None`, будет использована предопределённая максимальная длина модели, если один из параметров усечения/дополнения требует указания максимальной длины. Если у модели нет конкретной максимальной длины входных данных (как у XLNet), усечение/дополнение до максимальной длины будет отключено.

pad_to_multiple_of (`int`, *optional*) : Если задано, последовательность будет дополнена до кратного указанного значения. Требуется активация `padding`. Это особенно полезно для использования Tensor Cores на аппаратных средствах NVIDIA с вычислительной способностью `>= 7.5` (Volta).

verbose (`bool`, *необязательный*, по умолчанию `True`) : Выводить ли дополнительную информацию и предупреждения.

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

**Возвращаемое значение:**

`Union[~feature_extraction_utils.BatchFeature, ~tokenization_utils_base.BatchEncoding]`

