Neutone SDK

Neutone SDK 是一个开源框架，旨在简化基于 PyTorch 的神经音频模型在实时和离线应用中的部署。它使研究人员能够封装自己的 PyTorch 音频模型，并通过我们免费的宿主插件 Neutone FX 和 Neutone Gen 在数字音频工作站中运行这些模型。我们不仅支持本地加载模型，还允许将模型贡献到插件用户均可使用的模型库中。通过在一个统一且与模型无关的接口中封装常见的挑战，如可变缓冲区大小、采样率转换、延迟补偿以及控制参数处理，我们的框架实现了神经模型与宿主插件之间的无缝互操作性，同时让用户完全使用 Python 进行开发。迄今为止，该 SDK 已被应用于音频效果仿真、音色迁移和样本生成等多种场景，并得到了研究人员、教育工作者、企业和艺术家的广泛认可。

目前我们提供两款免费的宿主插件：

• Neutone FX：用于实时模型
• Neutone Gen：用于非实时模型，目前处于测试阶段。

为什么使用 Neutone SDK

JUCE 是构建音频插件的行业标准。因此，即使要构建非常简单的音频插件，也需要掌握 C++ 编程语言。然而，AI 音频研究者通常并不具备丰富的 C++ 经验，难以独立完成此类插件的开发。此外，投入大量时间开发插件也会占用本可用于改进算法的时间。Neutone 让研究人员可以使用熟悉的工具（如 PyTorch），并仅用少量 Python 代码即可封装模型，使其能够由 Neutone 插件执行。无需任何 C++ 代码或相关知识，便可在一天之内将模型部署到 DAW 中并正常运行。

SDK 提供对模型输入和输出的自动缓冲支持，以及实时的采样率和立体声/单声道转换功能。它使得只能以预定义样本数运行的模型能够在 DAW 中以任意采样率和缓冲区大小无缝使用。此外，SDK 内置了基准测试和性能分析工具，方便用户调试和评估模型的性能。

引用

已被 2025 年 9 月 8 日至 10 日在英国伦敦举行的 AES 国际人工智能与机器学习音频会议接受。

@inproceedings{mitcheltree2025neutone,
    title={Neutone {SDK}: An Open Source Framework for Neural Audio Processing},
    author={Christopher Mitcheltree and Bogdan Teleaga and Andrew Fyfe and Naotake Masuda and Matthias Schäfer and Alfie Bradic and Nao Tokui},
    booktitle={AES International Conference on Artificial Intelligence and Machine Learning for Audio},
    year={2025},
    url={https://doi.org/10.48550/arXiv.2508.09126}
}

目录

• 安装 SDK
• 下载 Neutone 插件
• 示例
• SDK 说明
• SDK 使用
• 基准测试与性能分析
• 已知问题
• 参与 SDK 贡献
• 致谢

安装 SDK

pip install neutone_sdk

Neutone FX 插件可在 https://neutone.ai/fx 获取。我们目前提供 VST3 和 AU 格式的插件，可用于加载使用此 SDK 创建的模型。更多信息请访问官网。

Gen

Neutone Gen 插件仍处于测试阶段，可从以下链接直接下载：

• MacOS ARM
• Windows

目前 Gen 插件尚未提供与 FX 插件类似的模型商店功能。在开发过程中，只需将导出的 .nm 模型文件放入 UI 可访问的 models 文件夹中即可。

我们提供了以下预封装模型：

• Nao Tokui 基于专有数据集训练的 LoopGAN - 下载 .nm 模型
• 基于 WaivOps EDM-HSE 数据集训练的 LoopGAN - 下载 .nm 模型
• Stable Audio Open Small - 下载 .nm 模型
• HT Demucs - 下载 .nm 模型

• Clipper 示例展示了如何封装一个非常简单的 PyTorch 模块，该模块不包含任何 AI 模型。请查看此示例，以了解封装模型所需的高层次概览。它位于 examples/neutone_fx/example_clipper.py。
• 基于 Randomized Overdrive Neural Networks 的简单卷积模型示例可在 examples/neutone_fx/example_overdrive-random.py 中找到。
• 我们还提供了针对更复杂模型的 Notebook，展示了从训练到使用 Neutone 导出的完整工作流程：
  • TCN FX 仿真
  • DDSP 音色迁移
  • RAVE 音色迁移
  • NoiseBandNet 音频重建
  • GCN FX 仿真

Gen

• 我们提供了与上述相同的简单 clipper 示例，但使用 NonRealtime Gen 封装器，位于 examples/neutone_gen/example_clipper.py。
• 更为复杂的文本转音频模型封装示例可在 examples/neutone_gen/example_musicgen_load.py 中找到。此示例展示了如何使用分词器，并且需要一个已追踪或脚本化的 MusicGen 模型。

我们在 examples 目录中提供了多个示例模型。我们将以其中一个最简单的模型——失真效果模型为例进行说明。

假设我们有如下 PyTorch 模型。参数将在后面介绍，目前我们先关注输入和输出。假设该模型接收形状为 (2, buffer_size) 的张量作为输入，其中 buffer_size 是可指定的参数。

class ClipperModel(nn.Module):
    def forward(self, x: Tensor, min_val: float, max_val: float, gain: float) -> Tensor:
        return torch.clip(x, min=min_val * gain, max=max_val * gain)

要在 VST 中运行此模型，我们可以编写的最简单的封装类是继承 WaveformToWaveformBase 基类。

class ClipperModelWrapper(WaveformToWaveformBase):
    @torch.jit.export  
    def is_input_mono(self) -> bool:
        return False
    
    @torch.jit.export
    def is_output_mono(self) -> bool:
        return False
    
    @torch.jit.export
    def get_native_sample_rates(self) -> List[int]:
        return []  # 支持所有采样率
    
    @torch.jit.export
    def get_native_buffer_sizes(self) -> List[int]:
        return []  # 支持所有缓冲区大小

    def do_forward_pass(self, x: Tensor, params: Dict[str, Tensor]) -> Tensor:
        # ... 参数解包逻辑
        x = self.model.forward(x, min_val, max_val, gain)
        return x

负责大部分工作的方法是 do_forward_pass。在本例中它只是一个简单的直通操作，但我们稍后会利用它来处理参数。

默认情况下，VST 以立体声模式运行，但如果模型需要单声道输入，可以通过 is_input_mono 和 is_output_mono 告知 SDK，从而自动转换输入和输出。如果启用 is_input_mono，则会传递一个平均后的形状为 (1, buffer_size) 的张量作为输入，而不是 (2, buffer_size)。如果启用 is_output_mono，则预计 do_forward_pass 会返回一个单声道张量（形状为 (1, buffer_size)），随后在 VST 的输出端将其复制到两个声道。这一过程由 SDK 自动完成，以避免每次传递时产生不必要的内存分配。

get_native_sample_rates 和 get_native_buffer_sizes 可用于指定偏好的采样率或缓冲区大小。大多数情况下，这些列表通常只有一个元素，但对于更复杂的模型，则提供了额外的灵活性。如果提供了多个选项，SDK 会尝试为当前 DAW 的设置找到最佳匹配。每当采样率或缓冲区大小与 DAW 不一致时，系统会自动触发封装层，以转换为正确的采样率，或为请求的缓冲区大小实现 FIFO 队列，甚至两者兼施。这会导致轻微的性能损失并增加一定的延迟。如果模型兼容任意采样率和/或缓冲区大小，则可以将这些列表留空。

这意味着，在 do_forward_pass 方法中，张量 x 的形状将保证为 (1 如果是单声道输入，否则为 2, buffer_size)，其中 buffer_size 将在运行时从 get_native_buffer_sizes 方法提供的列表中选择。张量 x 也将处于 get_native_sample_rates 方法提供的采样率列表中的某一个采样率下。

模型导出与插件加载

我们提供了一个 save_neutone_model 辅助函数，用于将模型保存到磁盘。默认情况下，此函数会将模型转换为 TorchScript 格式，并运行一系列检查，以确保模型可以被插件加载。生成的 model.nm 文件可以通过插件中的“加载自定义”按钮加载。有关如何将模型提交到对所有使用插件的用户可见的默认库，请参阅下文。

参数

对于可以使用条件信号的模型，我们目前提供了四个可配置的旋钮参数。在上面定义的 ClipperModelWrapper 中，我们可以包含以下内容：

class ClipperModelWrapper(WaveformToWaveformBase):
    ...
    
    def get_neutone_parameters(self) -> List[NeutoneParameter]:
        return [NeutoneParameter(name="min", description="最小削波阈值", default_value=0.5),
                NeutoneParameter(name="max", description="最大削波阈值", default_value=1.0),
                NeutoneParameter(name="gain", description="削波阈值缩放因子", default_value=1.0)]
         
    def do_forward_pass(self, x: Tensor, params: Dict[str, Tensor]) -> Tensor:
        min_val, max_val, gain = params["min"], params["max"], params["gain"]
        x = self.model.forward(x, min_val, max_val, gain)
        return x

在前向传播过程中，params 变量将是一个如下所示的字典：

{
    "min": torch.Tensor([0.5] * buffer_size),
    "max": torch.Tensor([1.0] * buffer_size),
    "gain": torch.Tensor([1.0] * buffer_size)
}

字典的键由 get_parameters 函数中指定。

这些参数的取值范围始终在 0 到 1 之间，do_forward_pass 函数可以在调用模型内部的前向方法之前，对参数进行必要的重新缩放。

此外，插件发送的参数是以采样点为粒度的。默认情况下，我们会对每个缓冲区取平均值并返回一个单精度浮点数（作为张量），但也可以通过 aggregate_param 方法来覆盖聚合方式。有关如何保留这一粒度的示例，请参阅完整的削波器导出文件。

某些音频模型会在输出音频时引入一定数量的采样延迟。这取决于具体模型的架构。为了使通过插件的干声和湿声信号能够对齐，用户需要报告其模型所引入的延迟样本数。可以通过 calc_model_delay_samples 方法来指定延迟样本数。RAVE 模型平均会有一个缓冲区的延迟（2048 个采样点），这一信息会在 calc_model_delay_samples 方法中静态声明，并可在示例中查看。而采用重叠相加实现的模型，其延迟将等于用于交叉淡入淡出的采样点数，如 Demucs 模型封装 或 频谱滤波器示例 所示。

计算模型引入的延迟可能较为复杂，尤其是当存在多种不同的延迟来源需要综合考虑时（例如，交叉淡入淡出延迟、滤波器延迟、前瞻缓冲区延迟，以及/或神经网络是在未对齐的干声和湿声数据上训练的）。因此，建议在宿主 DAW 中多花些时间测试模型，以确保正确报告了延迟。

后视缓冲区

为模型添加后视缓冲区对于那些需要额外上下文才能生成有用结果的模型非常有帮助。只需在 get_look_behind_samples 方法中指明所需的后视采样点数，即可轻松启用后视缓冲区。当该方法返回的数值大于零时，do_forward_pass 方法将始终接收到形状为 (in_n_ch, look_behind_samples + buffer_size) 的张量，但仍需返回形状为 (out_n_ch, buffer_size) 的最新采样张量。

我们建议尽可能避免使用后视缓冲区，因为它会降低模型效率，并可能导致每次前向传播时产生不必要的计算开销。如果使用纯卷积模型，可以尝试将所有卷积层替换为缓存卷积层。

滤波器

当 AI 模型接收到与其训练分布不符的输入时，往往会出现意想不到的行为。我们在 neutone_sdk/filters.py 文件中提供了一系列常用滤波器（低音滤波器、高通滤波器、带通滤波器、带阻滤波器）。这些滤波器可以在前向传播过程中使用，以限制输入信号的频率范围。其中部分滤波器可能会引入少量延迟，有关如何设置滤波器的简单示例，请参阅 examples/example_clipper_prefilter.py 文件。

提交模型

该插件包含一个默认的模型列表，旨在供创作者在其创作过程中使用。我们鼓励用户在对模型效果满意后提交自己的模型，以便更广泛的社区成员也能使用。提交时，我们需要一些额外的元数据，这些数据将用于展示关于模型的信息，面向创作者和其他研究人员。这些信息将在Neutone官网以及插件内部显示。

跳过之前的裁剪器模型，这里提供一个更真实的示例，基于受micro-tcn启发的随机TCN失真模型。

class OverdriveModelWrapper(WaveformToWaveformBase):
    def get_model_name(self) -> str:
        return "conv1d-overdrive.random"

    def get_model_authors(self) -> List[str]:
        return ["Nao Tokui"]

    def get_model_short_description(self) -> str:
        return "神经网络失真/过载效果"

    def get_model_long_description(self) -> str:
        return "通过随机初始化的卷积神经网络实现的神经网络失真/过载效果"

    def get_technical_description(self) -> str:
        return "通过随机初始化的时序一维卷积层实现的随机失真/过载效果。重新初始化权重或更改激活函数会得到不同类型的失真效果。基于Steinmetz等人提出的想法。"

    def get_tags(self) -> List[str]:
        return ["失真", "过载"]

    def get_model_version(self) -> str:
        return "1.0.0"

    def is_experimental(self) -> bool:
        return False

    def get_technical_links(self) -> Dict[str, str]:
        return {
            "论文": "https://arxiv.org/abs/2010.04237",
            "代码": "https://github.com/csteinmetz1/ronn"
        }

    def get_citation(self) -> str:
        return "Steinmetz, C. J., & Reiss, J. D. (2020). Randomized overdrive neural networks. arXiv preprint arXiv:2010.04237."

请查阅core.py中各方法的文档，以及网站和插件中的随机过载模型，以了解每个字段将在何处显示。

要提交模型，请在GitHub仓库中打开一个问题。目前我们需要以下内容：

• 模型功能的简短描述及其如何为社区做出贡献
• 由save_neutone_model辅助函数输出的model.nm文件链接

$ python -m neutone_sdk.benchmark benchmark-speed --model_file model.nm
INFO:__main__:正在运行缓冲区大小（128、256、512、1024、2048）和采样率（48000）的基准测试。异常值将从均值和标准差的计算中移除，并在存在时单独显示。
INFO:__main__:采样率：48000 | 缓冲区大小：128 | 持续时间：0.014±0.002 | 1/RTF：5.520 | 异常值：[0.008]
INFO:__main__:采样率：48000 | 缓冲区大小：256 | 持续时间：0.028±0.003 | 1/RTF：5.817 | 异常值：[]
INFO:__main__:采样率：48000 | 缓冲区大小：512 | 持续时间：0.053±0.003 | 1/RTF：6.024 | 异常值：[]
INFO:__main__:采样率：48000 | 缓冲区大小：1024 | 持续时间：0.106±0.000 | 1/RTF：6.056 | 异常值：[]
INFO:__main__:采样率：48000 | 缓冲区大小：2048 | 持续时间：0.212±0.000 | 1/RTF：6.035 | 异常值：[0.213]

$ python -m neutone_sdk.benchmark benchmark-latency model.nm                    
INFO:__main__:原生缓冲区大小：[2048]，原生采样率：[48000]
INFO:__main__:模型导出文件 exports/ravemodel/model.nm 对于每种采样率/缓冲区大小组合具有以下延迟（按最低延迟排序）：
INFO:__main__:采样率： 48000 | 缓冲区大小：   2048 | 总延迟：      0 | (缓冲延迟：      0 | 模型延迟：      0)
INFO:__main__:采样率： 48000 | 缓冲区大小：   1024 | 总延迟：   1024 | (缓冲延迟：   1024 | 模型延迟：      0)
INFO:__main__:采样率： 48000 | 缓冲区大小：    512 | 总延迟：   1536 | (缓冲延迟：   1536 | 模型延迟：      0)
INFO:__main__:采样率： 48000 | 缓冲区大小：    256 | 总延迟：   1792 | (缓冲延迟：   1792 | 模型延迟：      0)
INFO:__main__:采样率： 44100 | 缓冲区大小：    128 | 总延迟：   1920 | (缓冲延迟：   1920 | 模型延迟：      0)
INFO:__main__:采样率： 48000 | 缓冲区大小：    128 | 总延迟：   1920 | (缓冲延迟：   1920 | 模型延迟：      0)
INFO:__main__:采样率： 44100 | 缓冲区大小：    256 | 总延迟：   2048 | (缓冲延迟：   2048 | 模型延迟：      0)
INFO:__main__:采样率： 44100 | 缓冲区大小：    512 | 总延迟：   2048 | (缓冲延迟：   2048 | 模型延迟：      0)
INFO:__main__:采样率： 44100 | 缓冲区大小：   1024 | 总延迟：   2048 | (缓冲延迟：   2048 | 模型延迟：      0)
INFO:__main__:采样率： 44100 | 缓冲区大小：   2048 | 总延迟：   2048 | (缓冲延迟：   2048 | 模型延迟：      0)

运行速度基准测试会自动计算模型在 sample_rate=(44100, 48000) 和 buffer_size=(128, 256, 512, 1024, 2048) 组合下的延迟。这可以大致了解常见 DAW 设置下会发生什么情况。总延迟分为缓冲延迟和模型延迟。模型延迟由模型创建者在模型封装中报告，如 上述 所述。缓冲延迟则由 SDK 自动计算，考虑封装中指定的原生 (sample_rate, buffer_size) 组合以及 DAW 运行时指定的组合。在模型的原生 (sample_rate, buffer_size) 组合下运行模型将产生最小延迟。

与上述速度基准测试类似，可以通过命令行指定要测试的 (sample_rate, buffer_size) 组合。运行 python -m neutone_sdk.benchmark benchmark-latency --help 可获取更多信息。

性能分析

$ python -m neutone_sdk.benchmark profile --model_file exports/ravemodel/model.nm
INFO:__main__:正在对模型 exports/ravemodel/model.nm 在采样率 48000 和缓冲区大小 128 下进行性能分析
STAGE:2023-09-28 14:34:53 96328:4714960 ActivityProfilerController.cpp:311] 阶段完成：预热
30it [00:00, 37.32it/s]
STAGE:2023-09-28 14:34:54 96328:4714960 ActivityProfilerController.cpp:317] 阶段完成：数据收集
STAGE:2023-09-28 14:34:54 96328:4714960 ActivityProfilerController.cpp:321] 阶段完成：后处理
INFO:__main__:显示总 CPU 时间
INFO:__main__:--------------------------------  ------------  ------------  ------------  ------------  ------------  ------------  ------------  ------------  
                            名称    自身 CPU 百分比      自身 CPU   总 CPU 百分比     总 CPU  平均 CPU 时间       CPU 内存  自身 CPU 内存    调用次数  
--------------------------------  ------------  ------------  ------------  ------------  ------------  ------------  ------------  ------------  
                         forward        98.54%     799.982ms       102.06%     828.603ms      26.729ms           0 b    -918.17 Kb            31  
               aten::convolution         0.12%     963.000us         0.95%       7.739ms     175.886us     530.62 Kb    -143.50 Kb            44
...
...
完整输出已从 GitHub 上移除。

性能分析工具将在 PyTorch 性能分析器下以 48000 的采样率和 128 的缓冲区大小运行模型，并输出一系列洞察信息，例如总 CPU 时间、每个函数的总 CPU 内存使用量以及按函数调用组划分的 CPU 内存使用量。这可用于识别模型代码中的瓶颈（甚至是在 do_forward_pass 调用内的模型调用中）。

与基准测试类似，也可以在不同的采样率和缓冲区大小组合以及不同线程数下运行。运行 python -m neutone_sdk.benchmark profile --help 可获取更多信息。

• 在保存时冻结模型可能导致不稳定，因此默认情况下禁用了冻结功能。我们建议尝试在启用和禁用冻结的情况下分别保存模型。
• 当前 SDK 中未包含前瞻缓冲区（仅支持后瞻缓冲区），但可以通过额外的代码实现。示例可在 此文件 中找到。
• 目前不支持 M1 加速。
• 包装更复杂的模型可能会导致难以理解的 TorchScript 错误。

audacitorch 项目是 SDK 开发的重要灵感来源。请在此处查看

Neutone SDK 快速上手指南

Neutone SDK 是一个开源框架，旨在简化基于 PyTorch 的神经音频模型部署。它允许研究人员仅使用 Python 代码将模型封装，并直接在数字音频工作站（DAW）中通过免费的宿主插件（Neutone FX 或 Neutone Gen）运行，无需编写 C++ 代码。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Windows, macOS 或 Linux。
• Python 版本: 建议 Python 3.8 及以上版本。
• 核心依赖:
  • PyTorch: 用于构建和运行神经网络模型。
  • neutone_sdk: 核心封装库。
• 宿主软件 (DAW): 任意支持 VST3 或 AU (macOS) 插件的 DAW（如 Ableton Live, FL Studio, Logic Pro 等）。
• 宿主插件:
  • Neutone FX: 用于实时音频效果模型（推荐大多数用户）。
  • Neutone Gen: 用于非实时生成模型（目前处于 Beta 阶段）。

2. 安装步骤

2.1 安装 Python SDK

使用 pip 安装 Neutone SDK。国内用户建议使用清华或阿里镜像源以加速下载：

pip install neutone_sdk -i https://pypi.tuna.tsinghua.edu.cn/simple

注意：如果尚未安装 PyTorch，请先根据您的需求访问 pytorch.org 安装对应版本的 PyTorch。

2.2 下载宿主插件

您需要下载对应的插件文件并将其放入 DAW 的插件扫描目录中。

• Neutone FX (实时模型):
  • 访问官网下载 VST3 或 AU 版本：https://neutone.ai/fx
• Neutone Gen (非实时模型 - Beta):
  • macOS (ARM): 下载链接
  • Windows: 下载链接

3. 基本使用

以下是将一个简单的 PyTorch 模型封装并在 DAW 中运行的最小化流程。

3.1 定义并封装模型

创建一个 Python 文件（例如 my_model.py），继承 WaveformToWaveformBase 基类。以下示例展示了一个简单的限幅器（Clipper）模型封装：

import torch
from torch import Tensor, nn
from typing import List, Dict
from neutone_sdk import WaveformToWaveformBase

# 1. 定义您的原始 PyTorch 模型逻辑
class ClipperModel(nn.Module):
    def forward(self, x: Tensor, min_val: float, max_val: float, gain: float) -> Tensor:
        return torch.clip(x, min=min_val * gain, max=max_val * gain)

# 2. 创建 SDK 包装类
class ClipperModelWrapper(WaveformToWaveformBase):
    def __init__(self):
        super().__init__()
        self.model = ClipperModel()

    @torch.jit.export
    def is_input_mono(self) -> bool:
        # 返回 True 表示模型需要单声道输入，SDK 会自动转换
        return False
    
    @torch.jit.export
    def is_output_mono(self) -> bool:
        # 返回 True 表示模型输出单声道，SDK 会自动复制为立体声
        return False
    
    @torch.jit.export
    def get_native_sample_rates(self) -> List[int]:
        # 返回模型最佳支持的采样率列表。返回空列表表示支持所有采样率
        return []  
    
    @torch.jit.export
    def get_native_buffer_sizes(self) -> List[int]:
        # 返回模型最佳支持的缓冲区大小列表。返回空列表表示支持所有大小
        return []

    def do_forward_pass(self, x: Tensor, params: Dict[str, Tensor]) -> Tensor:
        # 在此处执行模型推理
        # x 的形状保证为 (通道数，buffer_size)
        
        # 示例：从 params 中提取控制参数 (需在导出时定义映射)
        # 这里为了演示简单直接硬编码参数，实际使用中可通过 SDK 参数系统动态传入
        min_val = -1.0
        max_val = 1.0
        gain = 1.0
        
        return self.model.forward(x, min_val, max_val, gain)

if __name__ == "__main__":
    # 3. 导出模型
    # 这将运行测试并生成 .nm 模型文件，可直接拖入 Neutone 插件使用
    wrapper = ClipperModelWrapper()
    wrapper.save_to_neutone_bundle("clipper_model.nm")
    print("模型导出成功：clipper_model.nm")

3.2 在 DAW 中使用

1. 运行上述脚本，生成 clipper_model.nm 文件。
2. 打开您的 DAW，加载 Neutone FX 插件。
3. 在插件界面中，点击加载按钮，选择生成的 clipper_model.nm 文件（或者如果已发布，可直接在内置商店搜索）。
4. 现在，您的 PyTorch 模型已经作为原生音频效果器在 DAW 中运行了。

3.3 进阶提示

• 参数控制: SDK 支持最多 4 个旋钮参数，可在 do_forward_pass 中通过 params 字典接收，并在 DAW 中自动化控制。
• 采样率适配: 如果您的模型仅在特定采样率下训练，请在 get_native_sample_rates 中指定，SDK 会自动处理重采样。
• 更多示例: 请参考官方仓库中的 examples 目录，包含过驱效果、音色转换等复杂模型的完整实现。