sOURnd Documentazione I tuoi engine
In questa pagina
  1. Cosa ottieni
  2. 1. Aggiungi il modulo e la libreria
  3. 2. Crea l'engine, i suoi parametri e il bridge
  4. 3. Scegli un engine
  5. Regole da conoscere
  6. Limiti
  7. Piattaforme
  8. Licenze

Guida rapida JUCE

Aggiungi un engine sournd a un plugin JUCE 8. Tre righe di CMake, tre oggetti C++, nessuna toolchain Rust sul tuo computer.

  1. Scaricail modulo JUCE e la libreria del tuo engine
  2. CMaketre righe
  3. Tre oggetti C++engine, parametri, bridge
  4. Il tuo plugincompilato da JUCE come al solito

Cosa ottieni

  • sournd_engine, un modulo JUCE standard che dipende solo da juce_audio_processors e juce_dsp (Apache-2.0). Scaricalo: sournd-engine-juce-module.zip.
  • Una libreria statica per la tua piattaforma (libsournd_cabi.a, oppure sournd_cabi.lib su Windows) e l'header sournd_engine.h: gli engine gratuiti dalla pagina di qualsiasi engine gratuito (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), quelli a pagamento da I tuoi engine.
  • SourndEngine, che implementa juce::dsp::ProcessorBase, e SourndEngineParameters, che costruisce un layout APVTS dall'engine e li mantiene allineati.

1. Aggiungi il modulo e la libreria

Decomprimi il modulo in modo da avere una cartella sournd_engine e decomprimi accanto il download del tuo 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)

Per un plugin macOS universal, compila con -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' e collega l'archivio universal.

Su Linux il download ha un archivio per ogni architettura. Scegli quello della macchina per cui compili e aggiungi le librerie di sistema che richiede:

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. Crea l'engine, i suoi parametri e il bridge

Costruiscili in quest'ordine, sul 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;
};

Cosa succede a runtime:

Ogni blocco

  1. Hostmanopole e automazione
  2. APVTSi parametri del tuo plugin
  3. bridge.applyvalori modificati, una volta a blocco
  4. engine.processsmussa campione per campione
  5. Audio in uscita

Salvataggio

  1. L'host chiede lo stato
  2. getCallbackLock()tiene fuori processBlock
  3. bridge.syncToEngine()
  4. engine.saveState()un blob opaco

Caricamento

  1. L'host restituisce lo stato
  2. getCallbackLock()
  3. engine.loadState()abbinato per id del parametro
  4. bridge.syncFromEngine()

3. Scegli un engine

Scegli un id qualsiasi dal catalogo o da catalog.json. Un id sconosciuto produce un engine non valido che emette silenzio, quindi controlla isValid() e lastError().

Regole da conoscere

  • Gli id dei parametri sono stringhe decimali stabili: la posizione del parametro nel manifest dell'engine, mostrata in ogni pagina di engine. I parametri vengono solo aggiunti, mai rinumerati.
  • Gli intervalli dell'host seguono la curva di ogni parametro. Un parametro logaritmico (cutoff, tempo, rapporto) mappa lo 0-1 dell'host come min * (max / min)^p, così le corsie di automazione e gli editor generici si muovono per rapporti uguali, come le manopole dell'engine. Se hai già distribuito un plugin con intervalli lineari, passa createLayout (engine, false) per mantenerli, perché gli host salvano l'automazione come valori da 0 a 1.
  • bridge.apply passa all'engine ogni valore modificato all'inizio del blocco. L'engine smussa da sé i controlli continui, campione per campione, quindi il suono non dipende dalla dimensione del blocco dell'host (verificato bit per bit a 1, 32, 64 e 512 frame). I controlli a gradini e booleani scattano.
  • I frame per chiamata devono rientrare nel massimo passato a prepare. Il wrapper non divide i blocchi dell'host.
  • Lo stato è opaco e legato all'id dell'engine. Salva le impostazioni, non la storia di delay o filtri. Migra tra le versioni dell'engine: i valori sono abbinati per id del parametro, i parametri aggiunti dopo il salvataggio della sessione prendono i valori predefiniti e i valori di un engine più recente che questo non ha vengono ignorati (lastStateReport() conta entrambi). Uno stato viene rifiutato, senza cambiare nulla, solo se appartiene a un altro engine o è danneggiato.
  • Il thread audio non alloca, non blocca e non chiama il message manager. Usa un'istanza dell'engine per ogni thread di elaborazione.
  • Le chiamate a un engine non devono sovrapporsi. Tutto ciò che tocca l'engine fuori da processBlock (salvare o caricare lo stato, prepare, reset) tiene getCallbackLock(), come sopra, così non gira mai mentre si elabora l'audio.

Limiti

Questi sono i confini attuali del bridge.

  • L'audio è float a 32 bit. Il bridge elabora solo buffer float. Lascia supportsDoublePrecisionProcessing() al valore predefinito (false), così gli host passano al tuo plugin audio float.
  • Mono o stereo, uguale in ingresso e in uscita. Uno o due canali principali; mono verso stereo, stereo verso mono e layout surround non sono supportati. Alcuni engine girano solo in stereo, quindi chiedi all'engine in isBusesLayoutSupported invece di dare per scontato (sotto). supportsChannels prepara un'istanza temporanea, quindi memorizza la risposta invece di chiamarla sul thread audio.
  • Gli engine sidechain accettano un ingresso ausiliario scollegato, mono o stereo.
  • MIDI. Gli effetti ignorano il buffer MIDI e il bridge non produce mai MIDI. Gli engine strumento leggono note on, note off e all notes off (CC 120 e 123) alle loro posizioni di campione, su ogni canale; pitch bend, aftertouch, altri controller e MPE non vengono inoltrati.
  • Frequenze di campionamento da 8 kHz a 768 kHz e fino a 1.048.576 frame per blocco.
  • I parametri nascosti dell'engine restano nello stato dell'engine e non sono controlli dell'host.
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);

Piattaforme

I download sono compilati per macOS universal (arm64 e x86_64), Linux (x86_64 e aarch64, glibc 2.36 o successiva) e Windows x64 (MSVC). Scegli la piattaforma quando scarichi dalla pagina dei tuoi engine; un agente la richiede con platform=linux o platform=windows-x64.

Su Windows lo zip contiene due copie di sournd_cabi.lib: lib/windows-x64/ per i progetti con runtime C dinamico (/MD, il predefinito di MSVC) e lib/windows-x64-static-crt/ per quello statico (/MT). Collega quella che corrisponde al tuo plugin, seguita da kernel32 ntdll userenv ws2_32 dbghelp. Il README nello zip contiene le righe CMake.

Licenze

Il modulo JUCE e l'header C sono Apache-2.0, quindi si collegano a progetti JUCE GPL o commerciali. JUCE ha la sua licenza e i suoi piani, che una licenza sournd non copre: segui la licenza JUCE 8 e scegli il piano JUCE adatto a ciò che distribuisci. Gli engine a pagamento sono librerie statiche chiuse. Vedi licenze.