Basic Pitch 是一个用于自动音乐转录（Automatic Music Transcription，简称 AMT）的 Python 库，采用由 Spotify 音频智能实验室 开发的轻量级神经网络。它小巧、易用，可以通过其 兄弟仓库 使用 pip install 或 npm install 进行安装。

Basic Pitch 或许看似简单，但它绝非“基础”！basic-pitch 高效且易于使用，其多音高（multipitch）支持、跨乐器的泛化能力以及音符准确性可与更大、更消耗资源的 AMT 系统相媲美。

提供兼容的音频文件，basic-pitch 将生成一个包含弯音（pitch bends）的 MIDI 文件。Basic Pitch 是乐器无关的（instrument-agnostic），支持复调（polyphonic）乐器，因此无论使用何种乐器，您都可以自由享受所有喜爱音乐的转录。Basic Pitch 在每次处理一种乐器时效果最佳。

Research Paper

本库随 Spotify 在 ICASSP 2022 上的发布一同推出。您可以在论文中阅读更多关于此研究的信息：A Lightweight Instrument-Agnostic Model for Polyphonic Note Transcription and Multipitch Estimation。

如果您在学术研究中使用此库，请考虑引用它：

@inproceedings{2022_BittnerBRME_LightweightNoteTranscription_ICASSP,
  author= {Bittner, Rachel M. and Bosch, Juan Jos\'e and Rubinstein, David and Meseguer-Brocal, Gabriel and Ewert, Sebastian},
  title= {A Lightweight Instrument-Agnostic Model for Polyphonic Note Transcription and Multipitch Estimation},
  booktitle= {Proceedings of the IEEE International Conference on Acoustics, Speech, and Signal Processing (ICASSP)},
  address= {Singapore},
  year= 2022,
}

请注意，我们已对 Basic Pitch 进行了改进，超出了本文档中的展示范围。因此，如果您在学术研究中使用 Basic Pitch 的输出结果，我们建议您引用所使用的代码版本。

Demo

如果您出于任何原因尚未完全获得灵感，或者只是想体验一下整体效果，不妨查看我们轻快的演示网站 basicpitch.io，在您提供的任何音乐音频上体验我们的模型！

Installation

basic-pitch 可通过 PyPI 获取。要安装当前版本：

pip install basic-pitch

要将 Basic Pitch 更新到最新版本，请在上述命令中添加 --upgrade。

Compatible Environments:

• MacOS、Windows 和 Ubuntu 操作系统
• Python 版本 3.7, 3.8, 3.9, 3.10, 3.11
• 对于 Mac M1 硬件，我们目前仅支持 Python 版本 3.10。否则，建议使用虚拟机。

Model Runtime

Basic Pitch 附带原始 TensorFlow 模型，以及转换为 CoreML、TensorFlowLite 和 ONNX 的 TensorFlow 模型。默认情况下，除非您使用 Python>=3.11，否则 Basic Pitch 不会将 TensorFlow 作为依赖项安装。相反，默认情况下，MacOS 上将安装 CoreML，Linux 上将安装 TensorFlowLite，Windows 上将安装 ONNX。如果您希望与默认模型推理运行时一起安装 TensorFlow，可以通过 pip install basic-pitch[tf] 安装 TensorFlow。

Usage

Model Prediction

模型运行时

默认情况下，Basic Pitch 将按以下顺序尝试加载模型：

1. TensorFlow（一种深度学习框架）
2. CoreML（苹果机器学习框架）
3. TensorFlowLite（轻量级移动和嵌入式机器学习框架）
4. ONNX（开放神经网络交换格式）

此外，模块变量 ICASSP_2022_MODEL_PATH 将默认为列表中第一个可用的版本。

我们将在此处解释如何覆盖此优先级列表。由于所有其他模型序列化格式均是从 TensorFlow（一种深度学习框架）转换而来的，我们建议在可能的情况下使用 TensorFlow。注意：Basic Pitch 默认不安装 TensorFlow，以节省用户安装和运行 Basic Pitch 的时间。

命令行工具

本库提供了一个命令行工具接口。一条基本的预测命令将在 <output-directory> 生成并保存位于 <input-audio-path> 的音频的 MIDI（乐器数字接口）文件转录结果：

basic-pitch <output-directory> <input-audio-path>

例如：

basic-pitch /output/directory/path /input/audio/path

要同时处理多个音频文件：

basic-pitch <output-directory> <input-audio-path-1> <input-audio-path-2> <input-audio-path-3>

可选地，您可以在预测命令后附加以下任意标志，以便将预测输出的其他格式保存到 <output-directory>：

• --sonify-midi 另外保存 MIDI 文件的 .wav（波形音频文件格式）音频渲染。
• --save-model-outputs 另外保存原始模型输出为 NPZ（NumPy 压缩文件格式）文件。
• --save-note-events 另外保存预测的音符事件为 CSV（逗号分隔值文件）文件。

如果您想使用非默认模型类型（例如，使用 CoreML 而不是 TF），请使用 --model-serialization 参数。CLI（命令行界面）将更改加载的模型为您首选的类型。

若要发现更多参数控制，请运行：

basic-pitch --help

编程方式

predict()

将 basic-pitch 导入您自己的 Python（编程语言）代码中，并直接运行 predict 函数，提供 <input-audio-path> 并返回模型的预测结果：

from basic_pitch.inference import predict
from basic_pitch import ICASSP_2022_MODEL_PATH

model_output, midi_data, note_events = predict(<input-audio-path>)

• <minimum-frequency> & <maximum-frequency> (floats) 设置模型返回的最大和最小允许音符频率，单位为 Hz。超出此范围的音高事件将从预测结果中排除。
• model_output 是原始模型推理输出
• midi_data 是由 model_output 派生的转录 MIDI 数据
• note_events 是由 model_output 派生的音符事件列表

注意：如前所述，ICASSP_2022_MODEL_PATH 将默认为列表中首先支持运行的 TensorFlow、CoreML、TensorFlowLite、ONNX。

predict() 在循环中

要在循环中运行预测，您需要自己加载模型，并向 predict() 提供加载的模型对象本身以供重复预测调用使用，以避免冗余且缓慢的模型加载。

import tensorflow as tf

from basic_pitch.inference import predict, Model
from basic_pitch import ICASSP_2022_MODEL_PATH

basic_pitch_model = Model(ICASSP_2022_MODEL_PATH))

for x in range():
    ...
    model_output, midi_data, note_events = predict(
        <loop-x-input-audio-path>,
        basic_pitch_model,
    )
    ...

predict_and_save()

如果您希望 basic-pitch 编排生成和保存我们各种支持的输出文件类型，您可以使用 predict_and_save 代替直接使用 predict：

from basic_pitch.inference import predict_and_save

predict_and_save(
    <input-audio-path-list>,
    <output-directory>,
    <save-midi>,
    <sonify-midi>,
    <save-model-outputs>,
    <save-notes>,
    <model-path>
)

其中：

• <input-audio-path-list> & <output-directory>
  • basic-pitch 用于读取/写入的目录路径。
• <save-midi>
  • bool 控制生成并将 MIDI 文件保存到 <output-directory>
• <sonify-midi>
  • bool 控制将 MIDI 文件的 WAV（波形音频文件格式）音频渲染保存到 <output-directory>
• <save-model-outputs>
  • bool 控制将原始模型输出保存为 NPZ（NumPy 压缩文件格式）文件到 <output-directory>
• <save-notes>
  • bool 控制将预测的音符事件保存为 CSV（逗号分隔值文件）到 <output-directory>
• <model-path>
  • str 或 pathlib.Path（Python 路径对象类）本地路径，从中加载模型，例如：可以使用 from basic_pitch import ICASSP_2022_MODEL_PATH 获得的路径

模型输入

支持的音频编解码器

basic-pitch 接受与其版本的 librosa（Python 音频处理库）兼容的所有声音文件，包括：

• .mp3
• .ogg
• .wav
• .flac
• .m4a

仅单声道音频

虽然您可以使用立体声音频作为模型的输入，但在预测时，输入的通道将被混音为单声道，然后进行分析并转录。

文件大小/音频长度

该模型可以处理任何大小或长度的音频，但较大/较长音频文件的处理可能受限于您机器上可用的磁盘空间。要处理这些文件，我们建议流式传输文件的音频，一次处理音频窗口。

采样率

输入音频可以是任何采样率，但是，所有音频在处理之前都将重采样至 22050 Hz。

VST

感谢 DamRsn 开发了此基本 pitch 的可用 VST（虚拟乐器插件标准）版本！- https://github.com/DamRsn/NeuralNote

贡献

欢迎对 basic-pitch 做出贡献！有关详细信息，请参阅 CONTRIBUTING.md。

版权与许可

basic-pitch 版权所有 2022 Spotify AB。

本软件根据 Apache License, Version 2.0（“Apache License"）（Apache 许可证）进行许可。您可以选择任一许可证来规范您对软件的使用，前提是您接受 Apache License 的所有条款。

您可以在以下位置获取 Apache License 副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据 Apache License 或 GPL License 分发的软件是按“原样”分发的，没有任何形式的担保或条件，无论是明示的还是暗示的。请参见 Apache License 以了解特定语言下的权限和限制。

basic-pitch 快速上手指南

basic-pitch 是由 Spotify 音频智能实验室开发的轻量级自动音乐转录（AMT）Python 库。它能够将音频文件高效地转换为包含音高变化的 MIDI 文件，支持多种乐器和复调音乐，无需依赖庞大的资源即可实现高精度转录。

1. 环境准备

• 操作系统: macOS, Windows, Linux (Ubuntu)
• Python 版本: 3.7, 3.8, 3.9, 3.10, 3.11
  • 注意: Mac M1 硬件目前仅支持 Python 3.10 版本，其他版本建议使用虚拟机。
• 输入格式: 支持 .mp3, .ogg, .wav, .flac, .m4a 等常见音频格式。
• 音频要求: 支持立体声（会自动混音为单声道），采样率不限（处理前会重采样至 22050 Hz）。

2. 安装步骤

通过 PyPI 直接安装当前发布版本：

pip install basic-pitch

如需升级到最新版本，添加 --upgrade 参数：

pip install --upgrade basic-pitch

运行时说明： 默认情况下，basic-pitch 会根据操作系统自动选择模型推理后端（Mac 使用 CoreML，Linux 使用 TensorFlowLite，Windows 使用 ONNX），不会强制安装 TensorFlow。如果您需要显式安装 TensorFlow 作为依赖，可运行：

pip install basic-pitch[tf]

3. 基本使用

命令行工具

最快捷的方式是通过命令行将音频转录为 MIDI 文件。

单个文件转录：

basic-pitch <output-directory> <input-audio-path>

示例：

basic-pitch /output/directory/path /input/audio/path

批量处理：

basic-pitch <output-directory> <input-audio-path-1> <input-audio-path-2> <input-audio-path-3>

可选输出参数：

• --sonify-midi: 额外保存 MIDI 的 .wav 渲染音频。
• --save-model-outputs: 额外保存原始模型输出为 NPZ 文件。
• --save-note-events: 额外保存预测音符事件为 CSV 文件。
• --model-serialization: 指定非默认的模型类型（如 CoreML）。

查看完整帮助：

basic-pitch --help

Python 代码调用

在您的 Python 脚本中直接导入并使用 predict 函数进行转录。

基础预测：

from basic_pitch.inference import predict
from basic_pitch import ICASSP_2022_MODEL_PATH

model_output, midi_data, note_events = predict(<input-audio-path>)

• model_output: 原始模型推理输出
• midi_data: 转录生成的 MIDI 数据
• note_events: 预测的音符事件列表

循环预测优化： 为避免重复加载模型导致速度变慢，建议在循环外加载模型对象：

import tensorflow as tf

from basic_pitch.inference import predict, Model
from basic_pitch import ICASSP_2022_MODEL_PATH

basic_pitch_model = Model(ICASSP_2022_MODEL_PATH))

for x in range():
    ...
    model_output, midi_data, note_events = predict(
        <loop-x-input-audio-path>,
        basic_pitch_model,
    )
    ...

一键保存所有格式： 使用 predict_and_save 函数可自动管理输出文件的生成与保存：

from basic_pitch.inference import predict_and_save

predict_and_save(
    <input-audio-path-list>,
    <output-directory>,
    <save-midi>,
    <sonify-midi>,
    <save-model-outputs>,
    <save-notes>,
    <model-path>
)