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 是穩定的十進位字串:即該參數在引擎資訊清單中的位置,每個引擎頁面都有列出。參數只會新增,絕不重新編號。
- 主機端的範圍依各參數的曲線而定。對數參數(cutoff、時間、比例)會把主機的 0 到 1 對應為
min * (max / min)^p,因此自動化軌與通用編輯器會以相同的比例移動,就像引擎自己的旋鈕一樣。如果你已經發行過使用線性範圍的外掛,請傳入createLayout (engine, false)來保留它們,因為主機是以 0 到 1 的值儲存自動化。 bridge.apply會在區塊開始時,把每個變動的值交給引擎。引擎自己逐取樣平滑連續控制項,所以聲音不受主機區塊大小影響(已以 1、32、64 與 512 影格逐位元測試)。步進式與布林控制項則直接跳到新值。- 每次呼叫的影格數必須符合傳給
prepare的最大值。封裝層不會切分主機的區塊。 - 狀態是不透明的,並綁定引擎 id。它儲存的是設定,不含 delay 或濾波器的歷史。它可跨引擎版本遷移:值依參數 id 對應,工作階段儲存之後才新增的參數使用預設值,來自較新引擎、本引擎沒有的值則忽略(
lastStateReport()會回報兩種數量)。只有狀態屬於另一個引擎或已損毀時才會被拒絕,且不會有任何變更。 - 音訊執行緒絕不配置記憶體、加鎖或呼叫訊息管理器。每個處理執行緒使用一個引擎實例。
- 對同一個引擎的呼叫不得重疊。
processBlock之外任何會碰到引擎的操作(儲存或載入狀態、prepare、reset),都要如上所述持有getCallbackLock(),這樣它就不會在處理音訊時執行。
限制
以下是目前橋接器的邊界。
- 音訊為 32 位元浮點數。橋接器只處理
float緩衝區。請讓supportsDoublePrecisionProcessing()維持預設值(false),這樣主機會給你的外掛浮點數音訊。 - 單聲道或立體聲,輸入與輸出相同。一或兩個主聲道;不支援單聲道轉立體聲、立體聲轉單聲道與環繞聲配置。有些引擎只能以立體聲運作,所以請在
isBusesLayoutSupported中詢問引擎,不要自行假設(見下方)。supportsChannels會準備一個暫用實例,所以請快取答案,不要在音訊執行緒上呼叫。 - Sidechain 引擎接受未連接、單聲道或立體聲的輔助輸入。
- MIDI。效果器會忽略 MIDI 緩衝區,橋接器也不會產生 MIDI。樂器引擎會在每個聲道上,依取樣位置讀取 note on、note off 與 all notes off(CC 120 與 123);彎音、aftertouch、其他控制器與 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 上,zip 內含兩份 sournd_cabi.lib:lib/windows-x64/ 給使用動態 C 執行階段(/MD,MSVC 預設)的專案,lib/windows-x64-static-crt/ 給使用靜態執行階段(/MT)的專案。請連結與你的外掛相符的那一份,後面接上 kernel32 ntdll userenv ws2_32 dbghelp。zip 內的 README 附有 CMake 設定行。
授權
JUCE 模組與 C 標頭檔採用 Apache-2.0,所以可以連結進 GPL 或商業的 JUCE 專案。JUCE 本身有自己的授權與方案,sournd 的授權並不涵蓋:請遵守 JUCE 8 授權,並選擇適合你所發行產品的 JUCE 方案。付費引擎以閉源靜態函式庫提供。見授權。