JUCE クイックスタート
JUCE 8 のプラグインに sournd エンジンを追加します。CMake は 3 行、C++ オブジェクトは 3 つで、お使いのマシンに Rust ツールチェーンは必要ありません。
- ダウンロードJUCE モジュールとエンジンライブラリ
- CMake3 行
- C++ オブジェクト 3 つエンジン、パラメーター、ブリッジ
- あなたのプラグイン通常どおり 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 フォルダーを作り、その隣にエンジンのダウンロードも解凍します。
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 つずつ含まれます。ビルド対象のマシンに合うものを選び、必要なシステムライブラリを追加してください。
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変化した値を、ブロックごとに 1 回engine.processサンプル単位でスムージング- オーディオ出力
保存
- ホストがステートを要求
getCallbackLock()processBlockを待機させるbridge.syncToEngine()engine.saveState()不透明なブロブ
読み込み
- ホストがステートを返す
getCallbackLock()engine.loadState()パラメーター ID で対応付け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 フレームです。
- 非表示のエンジンパラメーターはエンジンのステート内に保持され、ホストのコントロールにはなりません。
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 プランを選んでください。有料エンジンはクローズドなスタティックライブラリとして提供されます。ライセンスをご覧ください。