# Pop2Piano

## 概述

Pop2Piano 模型由 Jongho Choi 和 Kyogu Lee 在 [Pop2Piano : Pop Audio-based Piano Cover Generation](https://huggingface.co/papers/2211.00895) 中提出。

流行音乐的钢琴翻弹广受欢迎，但从音乐中生成钢琴翻弹并非易事。这需要高超的钢琴演奏技巧，以及对歌曲不同特征和旋律的深刻理解。借助 Pop2Piano，您可以直接从歌曲的音频波形生成翻弹。它是首个无需旋律和和弦提取模块即可直接从流行音乐音频生成钢琴翻弹的模型。

Pop2Piano 是一个基于 [T5](https://huggingface.co/papers/1910.10683) 的编码器-解码器 Transformer 模型。输入音频被转换为其波形并传入编码器，编码器将其转换为潜在表示。解码器利用这些潜在表示以自回归方式生成 token id。每个 token id 对应四种不同的 token 类型之一：时间、力度、音符和“特殊”。随后，这些 token id 被解码为等效的 MIDI 文件。

该论文的摘要如下：

*流行音乐钢琴改编曲深受许多人喜爱。然而，自动生成流行音乐钢琴改编曲的任务仍缺乏深入研究。这在一定程度上是由于缺乏同步的 {Pop, Piano Cover} 数据对，使得难以应用最新的数据密集型基于深度学习的方法。为了利用数据驱动方法的优势，我们使用自动化流程生成了大量配对且同步的 {Pop, Piano Cover} 数据。在本文中，我们提出了 Pop2Piano，这是一个 Transformer 网络，能够根据流行音乐的波形生成钢琴改编曲。据我们所知，这是首个无需使用旋律和和弦提取模块即可直接从流行音频生成钢琴改编曲的模型。我们展示了使用我们的数据集训练的 Pop2Piano 能够生成合理的钢琴改编曲。*

该模型由 [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 是一个基于 Encoder-Decoder 的模型，类似于 T5。
* Pop2Piano 可用于为给定的音频序列生成 midi-audio 文件。
* 在 `Pop2PianoForConditionalGeneration.generate()` 中选择不同的作曲家，可能会产生多种不同的结果。
* 在加载音频文件时将采样率设置为 44.1 kHz 可以获得良好的性能。
* 尽管 Pop2Piano 主要基于韩国流行音乐进行训练，但它在其他西方流行或嘻哈歌曲上的表现也相当不错。

## 示例

- 使用 HuggingFace Dataset 的示例：

```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` 可以表示的不同 token 数量。

composer_vocab_size (`int`，*可选*，默认为 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`, *可选*) : Transformer 解码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。

num_heads (`int`，*可选*，默认为 `8`)：Transformer 解码器中每个注意力层的注意力头数量。

relative_attention_num_buckets (`int`，*可选*，默认为 32)：每个注意力层使用的桶数。

relative_attention_max_distance (`int`，*可选*，默认为 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"`)：要使用的前馈层类型。应为 `"relu"` 或 `"gated-gelu"` 之一。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

pad_token_id (`int`，*可选*，默认为 `0`)：词表中用于填充的 Token ID。

eos_token_id (`Union[int, list[int]]`，*可选*，默认为 `1`)：词汇表中用于表示流结束（end-of-stream）的 Token ID。

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/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/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`，*可选*，默认为 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)：确定每个序列之间的间隔。

构建一个 Pop2Piano 特征提取器。

此特征提取器继承自 [SequenceFeatureExtractor](/docs/transformers/v5.23.0/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)，后者包含了大部分主要方法。有关这些方法的更多信息，请参阅该父类。

该类负责提取节奏并在音频传入模型之前对其进行预处理。首先，音频会被传入`RhythmExtractor2013`算法，该算法会提取 beat_times、节拍位置，并估计其置信度以及以 bpm 为单位的 tempo。随后，对 beat_times 进行插值以获取 beatsteps。之后，我们从中计算 extrapolated_beatsteps，供 tokenizer 使用。另一方面，音频会被重采样至 self.sampling_rate 并进行预处理，然后基于此计算对数梅尔频谱图，供我们的 transformer 模型使用。

#### __调用__[[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 数组、浮点值列表、numpy 数组列表或浮点值列表的列表。

sampling_rate (`int`) : `audio` 输入的采样率。强烈建议在 forward 调用时传入 `sampling_rate`，以避免静默错误。

steps_per_beat (`int`，*可选*，默认为 2)：用于对 `beat_times` 进行插值。

resample (`bool`，*可选*，默认为 `True`)：确定在处理之前是否将音频重采样为 `sampling_rate`。在推理期间必须为 True。

return_attention_mask (`bool` *可选*，默认为 `False`)：指示是否将 input_features、beatsteps 和 extrapolated_beatstep 的 attention_mask 作为输出返回。对于批量输入，会自动设置为 True。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为：- `'pt'`：返回 PyTorch `torch.Tensor` 对象。- `'np'`：返回 Numpy `np.ndarray` 对象。如果未指定任何值，将返回 `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/zh/model_doc/pop2piano#transformers.Pop2PianoConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

在顶部带有`language modeling`头的Pop2Piano模型。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 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 是一个具有相对位置嵌入的模型，因此您应该可以在右侧和左侧填充输入。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids) 要了解如何为预训练准备 `input_ids`，请查看 [Pop2Piano Training](./Pop2Piano#training)。

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：解码器输入序列中各个 token 在词汇表中的索引。可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取这些索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是解码器输入 ID？](../glossary#decoder-input-ids) Pop2Piano 使用 `pad_token_id` 作为 `decoder_input_ids` 生成的起始 token。如果使用了 `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/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

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/zh/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor) 获取音频特征。有关详细信息，请参阅 [Pop2PianoFeatureExtractor.__call__()](/docs/transformers/v5.23.0/zh/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor.__call__)（[Pop2PianoProcessor](/docs/transformers/v5.23.0/zh/model_doc/pop2piano#transformers.Pop2PianoProcessor) 使用 [Pop2PianoFeatureExtractor](/docs/transformers/v5.23.0/zh/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/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `tuple(torch.Tensor)`

一个 [Seq2SeqLMOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) 或 `torch.Tensor` 元组（如果传入了 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[Pop2PianoConfig](/docs/transformers/v5.23.0/zh/model_doc/pop2piano#transformers.Pop2PianoConfig)）和输入。

[Pop2PianoForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/pop2piano#transformers.Pop2PianoForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 语言建模损失。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](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**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。
- **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` 用于确定哪些区域被填充，哪些未被填充。- 对于**未填充**的 token，值为 1；- 对于**已填充**的 token，值为 0。

composer (`str`，*可选*，默认为 `"composer1"`)：该值会传递给 `Pop2PianoConcatEmbeddingToMel`，以根据每个 `"composer"` 生成不同的嵌入。请确保该 composer 值存在于 `generation_config` 中的 `composer_to_feature_token` 里。示例请参见 https://huggingface.co/sweetcocoa/pop2piano/blob/main/generation_config.json 。

generation_config (`~generation.GenerationConfig`, *可选*) : 用作生成调用基础参数化的生成配置。传递给 generate 且与 `generation_config` 属性匹配的 `**kwargs` 将覆盖这些属性。如果未提供 `generation_config`，则使用默认值，其加载优先级如下：1) 如果存在，则从 `generation_config.json` 模型文件加载；2) 从模型配置加载。请注意，未指定的参数将继承 [GenerationConfig](/docs/transformers/v5.23.0/zh/main_classes/text_generation#transformers.GenerationConfig) 的默认值，应查阅其文档以参数化生成。

kwargs : 对 `generate_config` 和/或额外模型特定 kwargs 的临时参数化，这些参数将被转发到模型的 `forward` 函数。如果模型是编码器-解码器模型，编码器特定的 kwargs 不应添加前缀，而解码器特定的 kwargs 应以 *decoder_* 作为前缀。

**返回：** [ModelOutput](/docs/transformers/v5.23.0/zh/main_classes/output#transformers.utils.ModelOutput) 或 `torch.LongTensor`

[ModelOutput](/docs/transformers/v5.23.0/zh/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/zh/main_classes/output#transformers.utils.ModelOutput) 类型为：
- [GenerateEncoderDecoderOutput](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.generation.GenerateEncoderDecoderOutput)，
- [GenerateBeamEncoderDecoderOutput](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.generation.GenerateBeamEncoderDecoderOutput)

生成用于 MIDI 输出的 token ID。

大多数生成控制参数都在 `generation_config` 中设置，如果未传入该参数，则会使用模型的默认生成配置。你可以通过向 generate() 传入相应参数来覆盖 `generation_config` 中的任意设置，例如 `.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`，*可选*，默认值为 77)：确定创建 midi 音符时使用的默认速度。

num_bars (`int`，*可选*，默认为 2)：确定每个 token 的 cutoff_time_idx。

unk_token (`str` 或 `tokenizers.AddedToken`，*可选*，默认为 `"-1"`)：未知标记。不在词汇表中的标记无法转换为 ID，将被设置为该标记。

eos_token (`str` 或 `tokenizers.AddedToken`，*可选*，默认为 1)：序列结束标记。

pad_token (`str` 或 `tokenizers.AddedToken`，*可选*，默认为 0)：一种特殊标记，用于将标记数组调整为相同大小以便进行批处理。随后，注意力机制或损失计算将忽略该标记。

bos_token (`str` 或 `tokenizers.AddedToken`，*可选*，默认为 2)：预训练期间使用的序列起始标记。可用作序列分类标记。

构建一个 Pop2Piano 分词器。该分词器无需训练。

该分词器继承自 [PreTrainedTokenizer](/docs/transformers/v5.23.0/zh/main_classes/tokenizer#transformers.PythonBackend)，后者包含了大部分主要方法。用户应参考该父类以获取有关这些方法的更多信息。

#### __调用__[[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/zh/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/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy)，*optional*，默认为 `False`)：启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，若未提供该参数，则截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认）：不截断（即，可以输出序列长度大于模型最大允许输入大小的批次）。

max_length (`int`, *optional*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

pad_to_multiple_of (`int`，*可选*)：如果设置，则将序列填充为所提供值的倍数。这对于在计算能力 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 的使用特别有用。

return_attention_mask (`bool`，*可选*)：是否返回注意力掩码。如果保持默认值，将根据特定分词器的默认设置返回注意力掩码，该设置由 `return_outputs` 属性定义。[什么是注意力掩码？](../glossary#attention-mask)

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。

**返回值：**

包含 token_ids 的 `BatchEncoding`。

这是 `Pop2PianoTokenizer` 的 `__call__` 方法。它将 midi 音符转换为 transformer 生成的 token ids。

## 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/zh/model_doc/pop2piano#transformers.Pop2PianoProcessor) 提供了 [Pop2PianoFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor) 和 `tokenizer_class` 的所有功能。有关更多信息，请参阅 [~Pop2PianoFeatureExtractor](/docs/transformers/v5.23.0/zh/model_doc/pop2piano#transformers.Pop2PianoFeatureExtractor) 和 `~tokenizer_class`。

#### __调用__[[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]`，*可选*)：输入音频的采样率，单位为 Hz。此值应与特征提取器使用的采样率一致。如果未提供，则使用处理器配置中的默认采样率。

steps_per_beat (`int`, *可选*，默认为 `2`)：每个音乐节拍的时间步数。该参数控制音乐表示的时间分辨率。较高的值提供更细的时间粒度，但会增加序列长度。在处理音频以提取音乐特征时使用。

resample (`bool`，*可选*，默认为 `True`)：如果调整图像大小，则使用的重采样滤波器。它可以是枚举 `PILImageResampling` 中的一个值。仅当 `do_resize` 设置为 `True` 时才会生效。

notes (`list` 或 `TensorType`，*可选*)：以 MIDI 格式预提取的音符。提供时，处理器将跳过音频特征提取，并直接通过分词器处理这些音符。每个音符应表示为包含音高、力度和时序信息的列表或张量。

padding (bool, str 或 [PaddingStrategy](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.utils.PaddingStrategy), *optional*, 默认为 `False`) : 启用并控制填充。接受以下值： - `True` 或 `'longest'`：填充到批次中最长的序列（如果只提供单个序列，则不进行填充）。 - `'max_length'`：填充到由参数 `max_length` 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。 - `False` 或 `'do_not_pad'`（默认）：不进行填充（即，可以输出包含不同长度序列的批次）。

truncation (bool, str 或 [TruncationStrategy](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.tokenization_utils_base.TruncationStrategy), *optional*) : 启用并控制截断。接受以下值： - `True` 或 `'longest_first'`：截断至参数 `max_length` 指定的最大长度，或者在未提供该参数时截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将逐个 token 进行截断，从该对中最长的序列中移除一个 token。 - `'only_first'`：截断至参数 `max_length` 指定的最大长度，或者在未提供该参数时截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第一个序列。 - `'only_second'`：截断至参数 `max_length` 指定的最大长度，或者在未提供该参数时截断至模型可接受的最大输入长度。如果提供了一对序列（或一批序列对），这将仅截断该对中的第二个序列。 - `False` 或 `'do_not_truncate'`（默认值）：不截断（即，可以输出序列长度大于模型最大可接受输入大小的批次）。

max_length (`int`, *可选*) : 控制截断/填充参数之一所使用的最大长度。如果未设置或设置为 `None`，当截断/填充参数需要最大长度时，将使用预定义的最大模型长度。如果模型没有特定的最大输入长度（例如 XLNet），则禁用截断/填充至最大长度的功能。

pad_to_multiple_of (`int`, *可选*) : 如果设置，则将序列填充为所提供值的倍数。需要启用 `padding`。这对于在计算能力为 `>= 7.5`（Volta）的 NVIDIA 硬件上启用 Tensor Cores 特别有用。

verbose (`bool`，*可选*，默认为 `True`)：是否打印更多信息和警告。

return_tensors (`str` 或 [TensorType](/docs/transformers/v5.23.0/zh/internal/file_utils#transformers.TensorType)，*可选*)：如果设置，将返回特定框架的张量。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 NumPy `np.ndarray` 对象。

**返回值：**

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

