JUCE-Schnellstart
Binde eine sournd-Engine in ein JUCE-8-Plugin ein. Drei CMake-Zeilen, drei C++-Objekte, keine Rust-Toolchain auf deinem Rechner.
- Herunterladendas JUCE-Modul und deine Engine-Bibliothek
- CMakedrei Zeilen
- Drei C++-ObjekteEngine, Parameter, Bridge
- Dein Pluginvon JUCE wie gewohnt gebaut
Was du bekommst
sournd_engine, ein normales JUCE-Modul, das nur vonjuce_audio_processorsundjuce_dspabhängt (Apache-2.0). Lade es herunter: sournd-engine-juce-module.zip.- Eine statische Bibliothek für deine Plattform (
libsournd_cabi.a, unter Windowssournd_cabi.lib) und der Headersournd_engine.h: die kostenlosen Engines auf der Seite jeder kostenlosen Engine (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), die kostenpflichtigen unter Deine Engines. SourndEngine, dasjuce::dsp::ProcessorBaseimplementiert, undSourndEngineParameters, das aus der Engine ein APVTS-Layout baut und beide synchron hält.
1. Modul und Bibliothek hinzufügen
Entpacke das Modul, sodass du einen Ordner sournd_engine hast, und entpacke deinen Engine-Download daneben.
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)Für ein Universal-Plugin unter macOS baust du mit -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' und bindest das Universal-Archiv ein.
Unter Linux enthält der Download ein Archiv pro Architektur. Wähle das für den Rechner, für den du baust, und füge die Systembibliotheken hinzu, die es braucht:
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. Engine, Parameter und Bridge erzeugen
Erzeuge sie in dieser Reihenfolge im Message-Thread:
#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;
};Was zur Laufzeit passiert:
Jeder Block
- HostRegler und Automation
- APVTSdie Parameter deines Plugins
bridge.applygeänderte Werte, einmal pro Blockengine.processglättet Sample für Sample- Audio-Ausgang
Speichern
- Host fragt den Zustand ab
getCallbackLock()hältprocessBlockfernbridge.syncToEngine()engine.saveState()ein undurchsichtiger Blob
Laden
- Host gibt den Zustand zurück
getCallbackLock()engine.loadState()zugeordnet über die Parameter-IDbridge.syncFromEngine()
3. Eine Engine auswählen
Wähle eine beliebige ID aus dem Katalog oder aus catalog.json. Eine unbekannte ID erzeugt eine ungültige Engine, die Stille ausgibt, also prüfe isValid() und lastError().
Regeln, die du kennen solltest
- Parameter-IDs sind stabile Dezimal-Strings: die Position des Parameters im Manifest der Engine, angezeigt auf jeder Engine-Seite. Parameter werden nur hinzugefügt, nie neu nummeriert.
- Host-Bereiche folgen der Kennlinie jedes Parameters. Ein logarithmischer Parameter (Cutoff, Zeit, Ratio) bildet das 0 bis 1 des Hosts als
min * (max / min)^pab, sodass sich Automationsspuren und generische Editoren in gleichen Verhältnissen bewegen, so wie die Regler der Engine selbst. Wenn du bereits ein Plugin mit linearen Bereichen ausgeliefert hast, übergibcreateLayout (engine, false), um sie beizubehalten, denn Hosts speichern Automation als Werte von 0 bis 1. bridge.applygibt jeden geänderten Wert zu Beginn des Blocks an die Engine weiter. Die Engine glättet kontinuierliche Regler selbst, Sample für Sample, sodass der Klang nicht von der Blockgröße des Hosts abhängt (bitgenau getestet bei 1, 32, 64 und 512 Frames). Gestufte und boolesche Regler springen.- Die Frames pro Aufruf müssen in das Maximum passen, das an
prepareübergeben wurde. Der Wrapper teilt Host-Blöcke nicht auf. - Der Zustand ist undurchsichtig und an die Engine-ID gebunden. Er speichert Einstellungen, keine Delay- oder Filterhistorie. Er migriert über Engine-Versionen hinweg: Werte werden über die Parameter-ID zugeordnet, Parameter, die seit dem Speichern der Session hinzugekommen sind, nehmen ihre Standardwerte an, und Werte einer neueren Engine, die diese nicht kennt, werden ignoriert (
lastStateReport()zählt beides). Ein Zustand wird nur abgelehnt, ohne dass sich etwas ändert, wenn er zu einer anderen Engine gehört oder beschädigt ist. - Der Audio-Thread alloziert nie, sperrt nie und ruft nie den Message Manager auf. Nutze eine Engine-Instanz pro Verarbeitungs-Thread.
- Aufrufe in eine Engine dürfen sich nicht überlappen. Alles außerhalb von
processBlock, das die Engine berührt (Zustand speichern oder laden,prepare,reset), hält wie obengetCallbackLock(), damit es nie läuft, während Audio verarbeitet wird.
Grenzen
Das sind heute die Grenzen der Bridge.
- Audio ist 32-Bit-Float. Die Bridge verarbeitet nur
float-Puffer. LasssupportsDoublePrecisionProcessing()auf dem Standardwert (false), damit Hosts deinem Plugin Float-Audio liefern. - Mono oder Stereo, am Eingang und Ausgang gleich. Ein oder zwei Hauptkanäle; Mono zu Stereo, Stereo zu Mono und Surround-Layouts werden nicht unterstützt. Manche Engines laufen nur in Stereo, also frage die Engine in
isBusesLayoutSupported, statt etwas anzunehmen (siehe unten).supportsChannelsbereitet eine Hilfsinstanz vor, also speichere die Antwort zwischen, statt sie im Audio-Thread aufzurufen. - Sidechain-Engines akzeptieren einen nicht verbundenen, einen Mono- oder einen Stereo-Zusatzeingang.
- MIDI. Effekte ignorieren den MIDI-Puffer, und die Bridge erzeugt nie MIDI. Instrument-Engines lesen Note-on, Note-off und All-Notes-off (CC 120 und 123) an ihren Sample-Positionen auf jedem Kanal; Pitch-Bend, Aftertouch, andere Controller und MPE werden nicht weitergegeben.
- Samplerates von 8 kHz bis 768 kHz und bis zu 1,048,576 Frames pro Block.
- Versteckte Engine-Parameter bleiben im Zustand der Engine und sind keine Host-Regler.
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);Plattformen
Die Downloads sind gebaut für macOS Universal (arm64 und x86_64), Linux (x86_64 und aarch64, glibc 2.36 oder neuer) und Windows x64 (MSVC). Wähle die Plattform beim Download auf der Seite Deine Engines; ein Agent fordert sie mit platform=linux oder platform=windows-x64 an.
Unter Windows enthält das Zip zwei Kopien von sournd_cabi.lib: lib/windows-x64/ für Projekte mit der dynamischen C-Runtime (/MD, der MSVC-Standard) und lib/windows-x64-static-crt/ für die statische (/MT). Binde die passende zu deinem Plugin ein, gefolgt von kernel32 ntdll userenv ws2_32 dbghelp. Die README im Zip enthält die CMake-Zeilen.
Lizenzierung
Das JUCE-Modul und der C-Header stehen unter Apache-2.0, daher lassen sie sich in GPL- oder kommerzielle JUCE-Projekte einbinden. JUCE selbst hat eine eigene Lizenz und eigene Tarife, die eine sournd-Lizenz nicht abdeckt: Halte dich an die JUCE-8-Lizenz und wähle den JUCE-Tarif, der zu dem passt, was du auslieferst. Kostenpflichtige Engines kommen als geschlossene statische Bibliotheken. Siehe Lizenzierung.