JUCE 快速入门
把 sournd 引擎加入 JUCE 8 插件。三行 CMake,三个 C++ 对象,你的机器上无需 Rust 工具链。
- 下载JUCE 模块和你的引擎库
- CMake三行
- 三个 C++ 对象引擎、参数、桥接器
- 你的插件照常由 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 文件夹,再把你的引擎下载包解压到它旁边。
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 上,下载包里每种架构有一个归档。选择与你构建目标机器相符的那个,并加上它所需的系统库:
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. 创建引擎、其参数和桥接器
请在消息线程上按以下顺序构造它们:
#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;
};运行时会发生什么:
每个处理块
- 宿主旋钮和自动化
- APVTS你插件的参数
bridge.apply有变化的值,每块一次engine.process逐采样平滑- 音频输出
保存
- 宿主请求状态
getCallbackLock()让processBlock无法同时运行bridge.syncToEngine()engine.saveState()一个不透明的数据块
加载
- 宿主交回状态
getCallbackLock()engine.loadState()按参数 id 匹配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 帧。
- 引擎的隐藏参数保留在引擎的状态内部,不是宿主控制项。
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 方案。付费引擎以闭源静态库形式提供。参见授权许可。