sOURnd 文档 我的引擎
本页内容
  1. 你将得到什么
  2. 1. 添加模块和库
  3. 2. 创建引擎、其参数和桥接器
  4. 3. 选择引擎
  5. 值得了解的规则
  6. 限制
  7. 平台
  8. 授权许可

JUCE 快速入门

把 sournd 引擎加入 JUCE 8 插件。三行 CMake,三个 C++ 对象,你的机器上无需 Rust 工具链。

  1. 下载JUCE 模块和你的引擎库
  2. CMake三行
  3. 三个 C++ 对象引擎、参数、桥接器
  4. 你的插件照常由 JUCE 构建

你将得到什么

  • sournd_engine:标准 JUCE 模块,仅依赖 juce_audio_processors 和 juce_dsp(Apache-2.0)。下载:sournd-engine-juce-module.zip。
  • 适用于你的平台的静态库(libsournd_cabi.a,Windows 上为 sournd_cabi.lib)和头文件 sournd_engine.h:免费引擎可在任一免费引擎的页面下载(https://sournd.com/download/free/macos、https://sournd.com/download/free/linux、https://sournd.com/download/free/windows),付费引擎可在“我的引擎”页面下载。
  • SourndEngine 实现了 juce::dsp::ProcessorBase;SourndEngineParameters 则根据引擎生成 APVTS 布局,并让两者保持同步。

1. 添加模块和库

解压模块,得到一个 sournd_engine 文件夹,再把你的引擎下载包解压到它旁边。

cmake
juce_add_module(path/to/sournd_engine)
target_include_directories(MyPlugin PRIVATE path/to/include)            # sournd_engine.h
target_link_libraries(MyPlugin PRIVATE sournd_engine path/to/libsournd_cabi.a)

要构建通用版 macOS 插件,请使用 -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' 构建,并链接通用归档。

在 Linux 上,下载包里每种架构有一个归档。选择与你构建目标机器相符的那个,并加上它所需的系统库:

cmake
if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
  set(SOURND_ARCH linux-aarch64)
else()
  set(SOURND_ARCH linux-x86_64)
endif()
target_link_libraries(MyPlugin PRIVATE sournd_engine
    path/to/lib/${SOURND_ARCH}/libsournd_cabi.a pthread dl m)

2. 创建引擎、其参数和桥接器

请在消息线程上按以下顺序构造它们:

cpp
#include <sournd_engine/sournd_engine.h>

class MyPlugin final : public juce::AudioProcessor
{
public:
    MyPlugin()
        : AudioProcessor (BusesProperties().withInput ("Input", juce::AudioChannelSet::stereo())
                                           .withOutput ("Output", juce::AudioChannelSet::stereo())),
          engine ("org.sournd.reverb.roomette"),
          parameters (*this, nullptr, "Parameters", sournd::SourndEngineParameters::createLayout (engine)),
          bridge (engine, parameters)
    { jassert (engine.isValid()); }

    void prepareToPlay (double rate, int maximumBlock) override
    {
        engine.prepare ({ rate, (juce::uint32) maximumBlock, (juce::uint32) getTotalNumOutputChannels() });
        bridge.prepare (rate);
        setLatencySamples ((int) engine.latency());
    }

    void processBlock (juce::AudioBuffer<float>& buffer, juce::MidiBuffer&) override
    {
        bridge.apply ((uint32_t) buffer.getNumSamples());
        juce::dsp::AudioBlock<float> block { buffer };
        engine.process (juce::dsp::ProcessContextReplacing<float> { block });
    }

    void getStateInformation (juce::MemoryBlock& destination) override
    {
        // Hosts can ask for state during playback: JUCE's callback lock keeps processBlock out
        // while the engine is read (the C ABI allows one call at a time per engine).
        const juce::ScopedLock lock (getCallbackLock());
        bridge.syncToEngine();
        destination = engine.saveState();
    }

    void setStateInformation (const void* data, int bytes) override
    {
        if (bytes < 0) return;
        const juce::ScopedLock lock (getCallbackLock());
        if (engine.loadState (data, (size_t) bytes)) bridge.syncFromEngine();
    }

    double getTailLengthSeconds() const override { return engine.tailSeconds(); }

private:
    sournd::SourndEngine engine;
    juce::AudioProcessorValueTreeState parameters;
    sournd::SourndEngineParameters bridge;
};

运行时会发生什么:

每个处理块

  1. 宿主旋钮和自动化
  2. APVTS你插件的参数
  3. bridge.apply有变化的值,每块一次
  4. engine.process逐采样平滑
  5. 音频输出

保存

  1. 宿主请求状态
  2. getCallbackLock()让 processBlock 无法同时运行
  3. bridge.syncToEngine()
  4. engine.saveState()一个不透明的数据块

加载

  1. 宿主交回状态
  2. getCallbackLock()
  3. engine.loadState()按参数 id 匹配
  4. bridge.syncFromEngine()

3. 选择引擎

从目录或 catalog.json 中任选一个 id。未知的 id 会产生一个无效引擎,它只输出静音,所以请检查 isValid() 和 lastError()。

值得了解的规则

  • 参数 id 是稳定的十进制字符串:即该参数在引擎清单中的位置,每个引擎页面上都会显示。参数只会增加,绝不会重新编号。
  • 宿主范围遵循每个参数的曲线。对数参数(截止频率、时间、比率)会把宿主的 0 到 1 映射为 min * (max / min)^p,因此自动化轨道和通用编辑器会按相同比例变化,与引擎自己的旋钮一致。如果你已经发布了使用线性范围的插件,请传入 createLayout (engine, false) 以保持原样,因为宿主把自动化存为 0 到 1 的值。
  • bridge.apply 在每个处理块开始时把每个有变化的值交给引擎。引擎自己逐采样平滑连续控制,因此声音不取决于宿主的块大小(已在 1、32、64 和 512 帧下逐位测试)。步进和布尔控制会直接跳变。
  • 每次调用的帧数必须在传给 prepare 的最大值以内。封装层不会拆分宿主的处理块。
  • 状态是不透明的,并绑定到引擎 id。它保存的是设置,而不是延迟或滤波器的历史。它可跨引擎版本迁移:值按参数 id 匹配,会话保存之后新增的参数使用默认值,来自更新版本引擎、而此版本没有的值会被忽略(lastStateReport() 会统计这两类)。只有当状态属于另一个引擎或已损坏时才会被拒绝,此时不会有任何改动。
  • 音频线程绝不分配内存、加锁,也不调用消息管理器。每个处理线程使用一个引擎实例。
  • 对同一个引擎的调用不得重叠。processBlock 之外任何会接触引擎的操作(保存或加载状态、prepare、reset)都要持有 getCallbackLock(),如上所述,这样它就不会在处理音频时运行。

限制

这些是目前桥接器的边界。

  • 音频为 32 位浮点。桥接器只处理 float 缓冲区。请让 supportsDoublePrecisionProcessing() 保持默认值(false),这样宿主会向你的插件传入 float 音频。
  • 单声道或立体声,输入输出一致。一个或两个主声道;不支持单声道转立体声、立体声转单声道,也不支持环绕声布局。有些引擎只能以立体声运行,所以请在 isBusesLayoutSupported 中询问引擎,而不要自行假设(见下文)。supportsChannels 会准备一个临时实例,所以请缓存结果,不要在音频线程上调用它。
  • 侧链引擎接受未连接、单声道或立体声的辅助输入。
  • MIDI。效果器会忽略 MIDI 缓冲区,桥接器也从不产生 MIDI。乐器引擎会在各自的采样位置读取所有声道上的 note on、note off 和 all notes off(CC 120 和 123);弯音、触后、其他控制器和 MPE 不会传递。
  • 采样率从 8 kHz 到 768 kHz,每块最多 1,048,576 帧。
  • 引擎的隐藏参数保留在引擎的状态内部,不是宿主控制项。
cpp
bool isBusesLayoutSupported (const BusesLayout& layout) const override
{
    const auto& in = layout.getMainInputChannelSet();
    return in == layout.getMainOutputChannelSet()
        && ((in == juce::AudioChannelSet::mono() && mono) || (in == juce::AudioChannelSet::stereo() && stereo));
}
// members, after engine:
const bool mono = engine.supportsChannels (1), stereo = engine.supportsChannels (2);

平台

下载包针对 macOS 通用版(arm64 和 x86_64)、Linux(x86_64 和 aarch64,glibc 2.36 或更高)和 Windows x64(MSVC)构建。请在“我的引擎”页面下载时选择平台;智能体则用 platform=linux 或 platform=windows-x64 请求。

在 Windows 上,压缩包里有两份 sournd_cabi.lib:lib/windows-x64/ 用于使用动态 C 运行库(/MD,MSVC 默认)的项目,lib/windows-x64-static-crt/ 用于静态运行库(/MT)。请链接与你的插件相符的那一份,后面接上 kernel32 ntdll userenv ws2_32 dbghelp。压缩包里的 README 有 CMake 代码行。

授权许可

JUCE 模块和 C 头文件采用 Apache-2.0,因此可以链接进 GPL 或商业 JUCE 项目。JUCE 本身有自己的许可证和方案,sournd 的授权并不涵盖:请遵守 JUCE 8 许可证,并选择适合你所发布产品的 JUCE 方案。付费引擎以闭源静态库形式提供。参见授权许可。