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 是穩定的十進位字串:即該參數在引擎資訊清單中的位置,每個引擎頁面都有列出。參數只會新增,絕不重新編號。
  • 主機端的範圍依各參數的曲線而定。對數參數(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 影格。
  • 隱藏的引擎參數保留在引擎的狀態裡,不是主機控制項。
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 上,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 方案。付費引擎以閉源靜態函式庫提供。見授權。