reaper-rs

Rust绑定REAPER C++ API。

简介

reaper-rs 允许程序员使用 Rust 编程语言编写 REAPER DAW (数字音频工作站) 插件。它通过提供原始Rust绑定和更便捷的API来实现这一点。

基础

reaper-rs 由4个生产crate组成

• reaper-macros
• reaper-low
• reaper-medium
• reaper-high (尚未发布)

reaper-macros 提供一个简单的属性宏来简化REAPER扩展插件的初始化。

其余的crate代表 reaper-rs 的3种不同API。

1. 低级API

此API包含原始绑定，没有其他内容。它在很大程度上是不安全的，不建议直接使用。然而，它为所有其他API提供了基础，并且由于它主要从 reaper_plugin_functions.h 自动生成，因此易于保持最新。它还可以在中等API尚未实现函数的情况下作为最后的手段使用（尽管我更愿意鼓励在这种情况下为中等API做出贡献）。

状态

• crates.io：已发布
• API稳定性：接近稳定（已经很完善，可能会有破坏性更改，但未计划）
• 完成度：约95%（仍有一些虚拟函数调用未实现）

示例

unsafe {
    reaper.ShowConsoleMsg(c_str!("Hello world from reaper-rs low-level API!").as_ptr());
    let track = reaper.GetTrack(null_mut(), 0);
    reaper.DeleteTrack(track);
}

2. 中级API

此API基于底层API构建。它几乎一对一地暴露了原始REAPER C++ API函数，但以惯用和类型安全的方式。与原始绑定相比，这是一大进步，使用起来更加方便。它的重点是稳定性而不是探索新的范式。由于高级API仍然非常不稳定，因此这是推荐的API。

状态

• crates.io：已发布
• API稳定性：接近稳定（已经很完善，可能会有破坏性更改，但未计划）
• 完成度：约13%（基础扎实，大约实现了800个函数中的100个）

示例

let functions = reaper.functions();
functions.show_console_msg("Hello world from reaper-rs medium-level API!");
let track = functions.get_track(CurrentProject, 0).ok_or("no tracks")?;
unsafe { functions.delete_track(track); }

3. 高级API

此API基于中级API构建。它打破了原始REAPER C++ API“平面函数”的特性，并替换为使用反应性和面向对象范式的API。这种突破使得提供直观的API成为可能，可以完全无安全地使用。

状态

• crates.io：尚未发布
• API稳定性：不稳定（处于变化状态，但正在工作）
• 完成度：约13%（与中级API相当）

示例

reaper.show_console_msg("Hello world from reaper-rs high-level API!");
reaper.track_removed().subscribe(|t| println!("Track {:?} removed", t));
let project = reaper.get_current_project();
let track = project.get_track_by_index(0).ok_or("no tracks")?;
project.remove_track(&track);

使用方法

具体步骤取决于所需的类型的插件。除了编写REAPER扩展插件外，reaper-rs还可以用于开发使用REAPER函数的VST插件。无论您选择哪种方式，与REAPER交互的可能性基本上是相同的。两者的区别在于您的插件将在哪种环境下运行。

扩展插件在REAPER启动时加载，并在REAPER退出前保持活动状态，因此非常适合向REAPER添加一些全局可用的功能。常见的例子有SWS和ReaPack（两者均用C++编写）。

REAPER VST插件作为特定REAPER项目中的轨道、音轨或监听FX加载，就像任何乐器或效果插件一样。这也意味着它可以实例化多次。例如，有Playtime（用C++编写）和ReaLearn（用C++编写，但正在移植到Rust）。

在这两种情况下，您都需要创建一个类型为cdylib的库crate。

REAPER扩展插件

使用reaper_extension_plugin宏是快速开始的最佳方式。

将其添加到您的Cargo.toml

[dependencies]
reaper-low = "0.1.0"
reaper-medium = "0.1.0"
reaper-macros = "0.1.0"

[lib]
name = "my_reaper_extension_plugin"
crate-type = ["cdylib"]

然后在您的lib.rs

use std::error::Error;
use reaper_macros::reaper_extension_plugin;
use reaper_low::ReaperPluginContext;
use reaper_medium::Reaper;

#[reaper_extension_plugin]
fn plugin_main(context: &ReaperPluginContext) -> Result<(), Box<dyn Error>> {
    let reaper = Reaper::load(context);
    reaper.functions().show_console_msg("Hello world from reaper-rs medium-level API!");
    Ok(())
}

这个宏所做的不仅仅是暴露一个调用reaper_low::bootstrap_extension_plugin()函数的extern "C" ReaperPluginEntry()函数。因此，如果您出于某种原因不想使用宏，请查看宏的实现。那里没有魔法。

REAPER VST插件

REAPER VST插件实际上是一个普通的VST插件，它获得了访问REAPER C++ API函数的权限。幸运的是，已经有一个用于创建VST插件的Rust crate：vst-rs。所以您只需要通过vst-rs编写一个VST插件，并通过让reaper-rs访问HostCallback函数来访问REAPER函数。

将其添加到您的Cargo.toml

[dependencies]
reaper-low = "0.1.0"
reaper-medium = "0.1.0"
vst = "0.2.0"

[lib]
name = "my_reaper_vst_plugin"
crate-type = ["cdylib"]

然后在您的lib.rs

use vst::plugin::{Info, Plugin, HostCallback};
use reaper_low::ReaperPluginContext;
use reaper_medium::Reaper;

#[derive(Default)]
struct MyReaperVstPlugin {
    host: HostCallback,
};

impl Plugin for MyReaperVstPlugin {
    fn new(host: HostCallback) -> Self {
        Self { host }
    }

    fn get_info(&self) -> Info {
        Info {
            name: "My REAPER VST plug-in".to_string(),
            unique_id: 6830,
            ..Default::default()
        }
    }

    fn init(&mut self) {
        if let Ok(context) = ReaperPluginContext::from_vst_plugin(self.host) {
            let reaper = Reaper::load(&context);
            reaper
                .functions()
                .show_console_msg("Hello world from reaper-rs medium-level API!");
        }
    }
}

vst::plugin_main!(MyReaperVstPlugin);

贡献

贡献非常欢迎！特别是中级API。

目录结构

低级API代码生成

reaper-low有几个生成的文件，即bindings.rs和reaper.rs。尽管这些文件不是每次构建都生成，但为了减少构建时间和提高IDE调试支持，它们像其他Rust源代码一样包含在Git仓库中。

您可以根据需要生成这些文件（见构建部分），例如在您调整了reaper_plugin_functions.h之后。根据您在哪个操作系统上生成这些文件，bindings.rs可能看起来相当不同（而reaper.rs应该相同）。原因是reaper_plugin.h在Windows上仅包含windows.h。在Linux和Mac OS X上，它使用swell.h（简单的Windows仿真层）作为替代。

bindings.rs的大部分用于生成reaper.rs，其他部分被忽略，但少数结构、类型和常量作为raw模块的一部分发布。为了实现确定性的构建，目前约定只提交在Linux上生成的文件。理由是：swell.h是windows.h的子集，所以如果子集工作正常，那么超集也应该工作。反之则不一定成立。目前尚不清楚这种策略是否完全正确，但暂时看来似乎是正确的。此外，在Linux上生成文件对持续集成也有好处。

构建

感谢Cargo，构建reaper-rs并不复杂。

Windows

以下是在Windows 10上的说明。需要考虑目标架构（REAPER 32位与64位）的点用⭐标记（说明假设64位）。

1. 设置“Visual Studio 2019构建工具”
   • Rust使用本地构建工具链。在Windows上，必须使用MSVC（Microsoft Visual Studio C++）工具链，因为REAPER插件只能与该工具链一起工作。
   • Visual Studio下载 → 所有下载 → Visual Studio 2019工具 → Visual Studio 2019构建工具
   • 启动它并按照安装程序的说明操作
   • 所需组件
     • 工作负载选项卡
       • “C++构建工具”（左侧的大框）
       • 确保右侧已勾选“Windows 10 SDK”（通常是这样）
     • 语言包
       • 英语
2. 设置Rust
   • 下载并执行rustup-init.exe
   • 接受默认设置
   • 设置正确的工具链默认值（如果只想构建reaper-low和reaper-medium，则不需要nightly工具链）⭐

     rustup default nightly-x86_64-pc-windows-msvc
     

3. 下载并安装Git for Windows
4. 克隆reaper-rs Git仓库

   git clone --recurse-submodules https://github.com/helgoboss/reaper-rs.git`
   

5. 构建reaper-rs

   cd reaper-rs
   cargo build
   

重新生成低级API（生成的代码不应推送！）

1. 下载并安装64位Windows版本的LLVM⭐
2. 启用generate功能进行构建

   cd main\low
   cargo build --features generate
   cargo fmt
   

Linux

从全新的Ubuntu 18.04.3 LTS安装中构建reaper-rs的完整说明

# Install basic stuff
sudo apt update
sudo apt install curl git build-essential -y

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # choose 1 (default)
source $HOME/.cargo/env
# Using nightly is not necessary if you want to build just the low-level or medium-level API!
rustup default nightly

# Clone reaper-rs
cd Downloads
git clone --recurse-submodules https://github.com/helgoboss/reaper-rs.git
cd reaper-rs
cargo build

在REAPER中使测试插件可用

1. 下载Linux版本的REAPER并至少启动一次。
2. 创建符号链接

   ln -s $HOME/Downloads/reaper-rs/target/debug/libreaper_test_extension_plugin.so $HOME/.config/REAPER/UserPlugins/reaper_test_extension_plugin.so
   mkdir -p $HOME/.config/REAPER/UserPlugins/FX
   ln -s $HOME/Downloads/reaper-rs/target/debug/libreaper_test_vst_plugin.so $HOME/.config/REAPER/UserPlugins/FX/reaper_test_extension_plugin.so
   

重新生成低级API

cd main/low
cargo build --features generate
cargo fmt

Mac OS X

待完成

测试

在构建完整的reaper-rs工作空间时，将生成3个测试crate

• reaper-test
• reaper-test-extension-plugin
• reaper-test-vst-plugin

reaper-test提供了一种集成测试，该测试应在REAPER本身中运行。这是reaper-rs的主要测试机制。reaper-test-extension-plugin和reaper-test-vst-plugin都是测试插件，它们将集成测试注册为REAPER动作。

运行集成测试不仅是一种发现reaper-rs回归错误的好方法，还可以帮助揭示REAPER C++ API本身的微妙变化。目前，测试断言非常严格，以便揭示即使是微小的偏差。

项目背景

reaper-rs诞生于将REAPER VST插件ReaLearn移植到Rust并将其作为开源项目发布的努力的一部分。高级API深受ReaPlus的启发，ReaPlus是REAPER原生C++ API的C++门面，这是原始ReaLearn的基本构建块。