sOURnd Docs Jouw engines
Op deze pagina
  1. Wat je krijgt
  2. 1. Voeg de module en de bibliotheek toe
  3. 2. Maak de engine, zijn parameters en de bridge aan
  4. 3. Kies een engine
  5. Regels die je moet kennen
  6. Beperkingen
  7. Platforms
  8. Licenties

JUCE quick start

Voeg een sournd-engine toe aan een JUCE 8-plugin. Drie CMake-regels, drie C++-objecten, geen Rust-toolchain op je machine.

  1. Downloadende JUCE-module en jouw enginebibliotheek
  2. CMakedrie regels
  3. Drie C++-objectenengine, parameters, bridge
  4. Jouw plugindoor JUCE gebouwd zoals gewoonlijk

Wat je krijgt

  • sournd_engine, een standaard JUCE-module die alleen afhangt van juce_audio_processors en juce_dsp (Apache-2.0). Download hem: sournd-engine-juce-module.zip.
  • Een static library voor jouw platform (libsournd_cabi.a, of sournd_cabi.lib op Windows) en de header sournd_engine.h: de gratis engines vind je op de pagina van elke gratis engine (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), betaalde engines onder Jouw engines.
  • SourndEngine, die juce::dsp::ProcessorBase implementeert, en SourndEngineParameters, die een APVTS-layout bouwt uit de engine en beide gelijk houdt.

1. Voeg de module en de bibliotheek toe

Pak de module uit zodat je een map sournd_engine hebt, en pak je engine-download ernaast uit.

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)

Bouw voor een universal macOS-plugin met -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' en link het universal archief.

Op Linux bevat de download één archief per architectuur. Kies het archief voor de machine waarvoor je bouwt en voeg de systeembibliotheken toe die het nodig heeft:

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. Maak de engine, zijn parameters en de bridge aan

Maak ze in deze volgorde aan, op de 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;
};

Wat er tijdens het draaien gebeurt:

Elk blok

  1. Hostknoppen en automatisering
  2. APVTSde parameters van je plugin
  3. bridge.applygewijzigde waarden, één keer per blok
  4. engine.processsmoothet sample voor sample
  5. Audio uit

Opslaan

  1. Host vraagt om de state
  2. getCallbackLock()houdt processBlock buiten
  3. bridge.syncToEngine()
  4. engine.saveState()een ondoorzichtige blob

Laden

  1. Host geeft de state terug
  2. getCallbackLock()
  3. engine.loadState()gekoppeld op parameter-id
  4. bridge.syncFromEngine()

3. Kies een engine

Kies een willekeurige id uit de catalogus of catalog.json. Een onbekende id levert een ongeldige engine op die stilte uitvoert, dus controleer isValid() en lastError().

Regels die je moet kennen

  • Parameter-id's zijn stabiele decimale strings: de positie van de parameter in de manifest van de engine, te zien op elke enginepagina. Parameters worden alleen toegevoegd, nooit hernummerd.
  • Hostbereiken volgen de curve van elke parameter. Een logaritmische parameter (cutoff, tijd, ratio) koppelt de 0 tot 1 van de host aan min * (max / min)^p, zodat automatiseringslanes en generieke editors in gelijke verhoudingen bewegen, net als de eigen knoppen van de engine. Heb je al een plugin met lineaire bereiken uitgebracht, geef dan createLayout (engine, false) mee om die te behouden, want hosts slaan automatisering op als waarden van 0 tot 1.
  • bridge.apply geeft elke gewijzigde waarde aan het begin van het blok door aan de engine. De engine smoothet continue regelaars zelf, sample voor sample, zodat het geluid niet afhangt van de bloklengte van de host (bit voor bit getest bij 1, 32, 64 en 512 frames). Stapsgewijze en booleaanse regelaars springen direct.
  • Frames per aanroep moeten passen binnen het maximum dat aan prepare is meegegeven. De wrapper splitst hostblokken niet op.
  • State is ondoorzichtig en gebonden aan de engine-id. Hij bewaart instellingen, geen delay- of filtergeschiedenis. Hij migreert tussen engineversies: waarden worden gekoppeld op parameter-id, parameters die zijn toegevoegd nadat de sessie werd opgeslagen krijgen hun standaardwaarde, en waarden van een nieuwere engine die deze mist worden genegeerd (lastStateReport() telt beide). Een state wordt alleen geweigerd, zonder dat er iets verandert, als hij bij een andere engine hoort of beschadigd is.
  • De audio thread alloceert nooit, lockt nooit en roept de message manager nooit aan. Gebruik één engine-instantie per verwerkingsthread.
  • Aanroepen naar één engine mogen niet overlappen. Alles buiten processBlock dat de engine raakt (state opslaan of laden, prepare, reset) houdt getCallbackLock() vast, zoals hierboven, zodat het nooit draait terwijl audio wordt verwerkt.

Beperkingen

Dit zijn nu de grenzen van de bridge.

  • Audio is 32-bit float. De bridge verwerkt alleen float-buffers. Laat supportsDoublePrecisionProcessing() op de standaardwaarde (false), zodat hosts je plugin float-audio geven.
  • Mono of stereo, hetzelfde op ingang en uitgang. Eén of twee hoofdkanalen; mono naar stereo, stereo naar mono en surround-layouts worden niet ondersteund. Sommige engines draaien alleen in stereo, dus vraag het de engine in isBusesLayoutSupported in plaats van het aan te nemen (zie hieronder). supportsChannels bereidt een tijdelijke instantie voor, dus cache het antwoord in plaats van het op de audio thread aan te roepen.
  • Sidechain-engines accepteren een niet-aangesloten, mono of stereo extra ingang.
  • MIDI. Effecten negeren de MIDI-buffer en de bridge produceert nooit MIDI. Instrumentengines lezen note on, note off en all notes off (CC 120 en 123) op hun samplepositie, op elk kanaal; pitch bend, aftertouch, andere controllers en MPE worden niet doorgegeven.
  • Samplerates van 8 kHz tot 768 kHz, en tot 1,048,576 frames per blok.
  • Verborgen engineparameters blijven in de state van de engine en zijn geen hostregelaars.
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);

Platforms

Downloads zijn gebouwd voor macOS universal (arm64 en x86_64), Linux (x86_64 en aarch64, glibc 2.36 of nieuwer) en Windows x64 (MSVC). Kies het platform wanneer je downloadt vanaf je enginepagina; een agent vraagt erom met platform=linux of platform=windows-x64.

Op Windows bevat de zip twee kopieën van sournd_cabi.lib: lib/windows-x64/ voor projecten met de dynamische C-runtime (/MD, de MSVC-standaard) en lib/windows-x64-static-crt/ voor de statische (/MT). Link degene die bij je plugin past, gevolgd door kernel32 ntdll userenv ws2_32 dbghelp. De README in de zip bevat de CMake-regels.

Licenties

De JUCE-module en de C-header zijn Apache-2.0, dus ze kunnen worden gelinkt in GPL- of commerciële JUCE-projecten. JUCE zelf heeft een eigen licentie en eigen abonnementen, die een sournd-licentie niet dekt: volg de JUCE 8-licentie en kies het JUCE-abonnement dat past bij wat je uitbrengt. Betaalde engines worden geleverd als closed static libraries. Zie licenties.