sOURnd Doku Deine Engines
Auf dieser Seite
  1. Was du bekommst
  2. 1. Modul und Bibliothek hinzufügen
  3. 2. Engine, Parameter und Bridge erzeugen
  4. 3. Eine Engine auswählen
  5. Regeln, die du kennen solltest
  6. Grenzen
  7. Plattformen
  8. Lizenzierung

JUCE-Schnellstart

Binde eine sournd-Engine in ein JUCE-8-Plugin ein. Drei CMake-Zeilen, drei C++-Objekte, keine Rust-Toolchain auf deinem Rechner.

  1. Herunterladendas JUCE-Modul und deine Engine-Bibliothek
  2. CMakedrei Zeilen
  3. Drei C++-ObjekteEngine, Parameter, Bridge
  4. Dein Pluginvon JUCE wie gewohnt gebaut

Was du bekommst

  • sournd_engine, ein normales JUCE-Modul, das nur von juce_audio_processors und juce_dsp abhängt (Apache-2.0). Lade es herunter: sournd-engine-juce-module.zip.
  • Eine statische Bibliothek für deine Plattform (libsournd_cabi.a, unter Windows sournd_cabi.lib) und der Header sournd_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, das juce::dsp::ProcessorBase implementiert, und SourndEngineParameters, 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.

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)

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:

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. Engine, Parameter und Bridge erzeugen

Erzeuge sie in dieser Reihenfolge im Message-Thread:

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;
};

Was zur Laufzeit passiert:

Jeder Block

  1. HostRegler und Automation
  2. APVTSdie Parameter deines Plugins
  3. bridge.applygeänderte Werte, einmal pro Block
  4. engine.processglättet Sample für Sample
  5. Audio-Ausgang

Speichern

  1. Host fragt den Zustand ab
  2. getCallbackLock()hält processBlock fern
  3. bridge.syncToEngine()
  4. engine.saveState()ein undurchsichtiger Blob

Laden

  1. Host gibt den Zustand zurück
  2. getCallbackLock()
  3. engine.loadState()zugeordnet über die Parameter-ID
  4. bridge.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)^p ab, 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, übergib createLayout (engine, false), um sie beizubehalten, denn Hosts speichern Automation als Werte von 0 bis 1.
  • bridge.apply gibt 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 oben getCallbackLock(), 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. Lass supportsDoublePrecisionProcessing() 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). supportsChannels bereitet 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.
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);

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.