sOURnd ドキュメント マイエンジン
このページの内容
  1. できること
  2. 1. モジュールとライブラリを追加する
  3. 2. エンジン、パラメーター、ブリッジを作成する
  4. 3. エンジンを選ぶ
  5. 知っておきたいルール
  6. 制限
  7. 対応プラットフォーム
  8. ライセンス

JUCE クイックスタート

JUCE 8 のプラグインに sournd エンジンを追加します。CMake は 3 行、C++ オブジェクトは 3 つで、お使いのマシンに Rust ツールチェーンは必要ありません。

  1. ダウンロードJUCE モジュールとエンジンライブラリ
  2. CMake3 行
  3. C++ オブジェクト 3 つエンジン、パラメーター、ブリッジ
  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)。有料エンジンは「マイエンジン」から入手できます。
  • juce::dsp::ProcessorBase を実装する SourndEngine と、エンジンから APVTS レイアウトを作って同期を保つ SourndEngineParameters。

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 では、ダウンロードにアーキテクチャーごとのアーカイブが 1 つずつ含まれます。ビルド対象のマシンに合うものを選び、必要なシステムライブラリを追加してください。

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変化した値を、ブロックごとに 1 回
  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 は安定した 10 進数の文字列で、エンジンのマニフェストにおけるそのパラメーターの位置です。各エンジンのページに表示されています。パラメーターは追加されるだけで、番号が振り直されることはありません。
  • ホスト側の範囲は、各パラメーターのテーパーに従います。ログのパラメーター(カットオフ、タイム、レシオ)では、ホストの 0 から 1 が min * (max / min)^p に対応するので、オートメーションレーンや汎用エディターも、エンジン自身のノブと同じく等比で動きます。すでにリニアな範囲でプラグインを出荷している場合は、createLayout (engine, false) を渡してそれを維持してください。ホストはオートメーションを 0 から 1 の値で保存するためです。
  • bridge.apply は、変化した値をブロックの先頭でエンジンに渡します。連続値のコントロールはエンジン側でサンプル単位にスムージングされるので、サウンドはホストのブロックサイズに左右されません(1、32、64、512 フレームでビット単位に検証済み)。ステップ式とブール値のコントロールは即座に切り替わります。
  • 1 回の呼び出しのフレーム数は、prepare に渡した最大値に収まる必要があります。ラッパーはホストのブロックを分割しません。
  • ステートは不透明で、エンジン ID に結び付いています。保存されるのは設定で、ディレイやフィルターの履歴ではありません。ステートはエンジンのバージョン間で移行されます。値はパラメーター ID で対応付けられ、セッションの保存後に追加されたパラメーターは初期値になり、新しいエンジンの値でこちらにないものは無視されます(lastStateReport() が両方の数を返します)。ステートが拒否されるのは、別のエンジンのものか破損している場合だけで、その場合は何も変更されません。
  • オーディオスレッドでは、メモリ確保、ロック、メッセージマネージャーの呼び出しを行いません。処理スレッドごとにエンジンのインスタンスを 1 つ使ってください。
  • 1 つのエンジンへの呼び出しは重なってはいけません。processBlock の外でエンジンに触れる処理(ステートの保存や読み込み、prepare、reset)は、上記のとおり getCallbackLock() を保持して行い、オーディオ処理中には実行されないようにします。

制限

現時点でのブリッジの制限は次のとおりです。

  • オーディオは 32 ビット浮動小数点です。ブリッジが処理するのは float バッファーだけです。supportsDoublePrecisionProcessing() は既定値(false)のままにして、ホストが float のオーディオを渡すようにしてください。
  • モノラルまたはステレオで、入力と出力は同じ構成です。メインチャンネルは 1 つまたは 2 つで、モノラルからステレオ、ステレオからモノラル、サラウンドのレイアウトには対応していません。ステレオ専用のエンジンもあるので、想定せずに isBusesLayoutSupported でエンジンに問い合わせてください(後述)。supportsChannels は作業用のインスタンスを準備するため、オーディオスレッドで呼ばず、結果をキャッシュしてください。
  • サイドチェイン対応のエンジンは、未接続、モノラル、ステレオの補助入力を受け付けます。
  • MIDI。エフェクトは MIDI バッファーを無視し、ブリッジが MIDI を生成することはありません。インストゥルメントのエンジンは、すべてのチャンネルでノートオン、ノートオフ、オールノートオフ(CC 120 と 123)をサンプル位置どおりに読み取ります。ピッチベンド、アフタータッチ、その他のコントローラー、MPE は渡されません。
  • サンプルレートは 8 kHz から 768 kHz、1 ブロックあたり最大 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 が 2 つ入っています。動的 C ランタイム(/MD、MSVC の既定)のプロジェクト向けが lib/windows-x64/、静的ランタイム(/MT)向けが lib/windows-x64-static-crt/ です。プラグインに合うほうをリンクし、続けて kernel32 ntdll userenv ws2_32 dbghelp をリンクします。zip 内の README に CMake の記述があります。

ライセンス

JUCE モジュールと C ヘッダーは Apache-2.0 なので、GPL や商用の JUCE プロジェクトにリンクできます。JUCE 自体には独自のライセンスとプランがあり、sournd のライセンスでは対象になりません。JUCE 8 ライセンスに従い、出荷するものに合った JUCE プランを選んでください。有料エンジンはクローズドなスタティックライブラリとして提供されます。ライセンスをご覧ください。