sOURnd Dokumentasjon Dine motorer
På denne siden
  1. Dette får du
  2. 1. Legg til modulen og biblioteket
  3. 2. Opprett motoren, parameterne og broen
  4. 3. Velg en motor
  5. Regler det er greit å kunne
  6. Begrensninger
  7. Plattformer
  8. Lisensiering

Kom i gang med JUCE

Legg en sournd-motor til i en JUCE 8-plugin. Tre CMake-linjer, tre C++-objekter, ingen Rust-verktøykjede på maskinen din.

  1. Last nedJUCE-modulen og motorbiblioteket ditt
  2. CMaketre linjer
  3. Tre C++-objektermotor, parametere, bro
  4. Pluginen dinbygget av JUCE som vanlig

Dette får du

  • sournd_engine, en standard JUCE-modul som bare avhenger av juce_audio_processors og juce_dsp (Apache-2.0). Last den ned: sournd-engine-juce-module.zip.
  • Et statisk bibliotek for plattformen din (libsournd_cabi.a, eller sournd_cabi.lib på Windows) og headeren sournd_engine.h: de gratis motorene fra siden til en hvilken som helst gratis motor (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), de betalte fra Dine motorer.
  • SourndEngine, som implementerer juce::dsp::ProcessorBase, og SourndEngineParameters, som bygger et APVTS-oppsett fra motoren og holder dem synkronisert.

1. Legg til modulen og biblioteket

Pakk ut modulen slik at du har en sournd_engine-mappe, og pakk ut motornedlastingen din ved siden av.

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)

For en universell macOS-plugin bygger du med -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' og linker det universelle arkivet.

På Linux har nedlastingen ett arkiv per arkitektur. Velg det for maskinen du bygger for, og legg til systembibliotekene det trenger:

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. Opprett motoren, parameterne og broen

Konstruer dem i denne rekkefølgen, på meldingstråden:

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

Dette skjer under kjøring:

Hver blokk

  1. Vertknotter og automatisering
  2. APVTSpluginens parametere
  3. bridge.applyendrede verdier, én gang per blokk
  4. engine.processglatter sample for sample
  5. Lyd ut

Lagring

  1. Verten ber om tilstand
  2. getCallbackLock()holder processBlock ute
  3. bridge.syncToEngine()
  4. engine.saveState()en ugjennomsiktig blob

Innlasting

  1. Verten gir tilstanden tilbake
  2. getCallbackLock()
  3. engine.loadState()matchet på parameter-id
  4. bridge.syncFromEngine()

3. Velg en motor

Velg en hvilken som helst id fra katalogen eller catalog.json. En ukjent id gir en ugyldig motor som sender ut stillhet, så sjekk isValid() og lastError().

Regler det er greit å kunne

  • Parameter-id-er er stabile desimalstrenger: parameterens posisjon i motorens manifest, vist på hver motorside. Parametere legges bare til, aldri omnummereres.
  • Vertsområdene følger kurven til hver parameter. En logaritmisk parameter (cutoff, tid, ratio) avbilder vertens 0 til 1 som min * (max / min)^p, så automasjonsspor og generiske editorer beveger seg i like forhold, slik motorens egne knotter gjør. Hvis du allerede har utgitt en plugin med lineære områder, send createLayout (engine, false) for å beholde dem, fordi verter lagrer automasjon som verdier fra 0 til 1.
  • bridge.apply gir hver endrede verdi til motoren ved starten av blokken. Motoren glatter kontinuerlige kontroller selv, sample for sample, så lyden ikke avhenger av vertens blokkstørrelse (testet bit for bit ved 1, 32, 64 og 512 frames). Trinnvise og boolske kontroller hopper direkte.
  • Frames per kall må rommes av maksimum som ble sendt til prepare. Wrapperen deler ikke vertsblokker.
  • Tilstanden er ugjennomsiktig og knyttet til motor-id-en. Den lagrer innstillinger, ikke delay- eller filterhistorikk. Den migrerer mellom motorversjoner: verdier matches på parameter-id, parametere lagt til etter at økten ble lagret får standardverdiene sine, og verdier fra en nyere motor som denne mangler, ignoreres (lastStateReport() teller begge deler). En tilstand avvises, uten at noe endres, bare når den tilhører en annen motor eller er skadet.
  • Lydtråden alloker aldri, låser aldri og kaller aldri meldingshåndtereren. Bruk én motorinstans per prosesseringstråd.
  • Kall til én motor må ikke overlappe. Alt utenfor processBlock som berører motoren (lagring eller innlasting av tilstand, prepare, reset) holder getCallbackLock(), som vist over, så det aldri kjører mens lyd prosesseres.

Begrensninger

Dette er kantene på broen i dag.

  • Lyd er 32-bit float. Broen prosesserer bare float-buffere. La supportsDoublePrecisionProcessing() stå på standardverdien (false), så verter gir pluginen din float-lyd.
  • Mono eller stereo, likt på inngang og utgang. Én eller to hovedkanaler. Mono til stereo, stereo til mono og surround-oppsett støttes ikke. Noen motorer kjører bare i stereo, så spør motoren i isBusesLayoutSupported i stedet for å anta (se nedenfor). supportsChannels forbereder en midlertidig instans, så mellomlagre svaret i stedet for å kalle den på lydtråden.
  • Sidechain-motorer godtar en frakoblet, mono eller stereo ekstra inngang.
  • MIDI. Effekter ignorerer MIDI-bufferet, og broen produserer aldri MIDI. Instrumentmotorer leser note on, note off og all notes off (CC 120 og 123) på sample-posisjonene sine, på alle kanaler. Pitch bend, aftertouch, andre kontrollere og MPE sendes ikke videre.
  • Samplerater fra 8 kHz til 768 kHz, og opptil 1 048 576 frames per blokk.
  • Skjulte motorparametere blir værende i motorens tilstand og er ikke vertskontroller.
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);

Plattformer

Nedlastingene bygges for macOS universal (arm64 og x86_64), Linux (x86_64 og aarch64, glibc 2.36 eller nyere) og Windows x64 (MSVC). Velg plattform når du laster ned fra siden Dine motorer. En agent ber om den med platform=linux eller platform=windows-x64.

På Windows inneholder zip-filen to kopier av sournd_cabi.lib: lib/windows-x64/ for prosjekter med dynamisk C-runtime (/MD, MSVC-standarden) og lib/windows-x64-static-crt/ for den statiske (/MT). Link den som passer pluginen din, etterfulgt av kernel32 ntdll userenv ws2_32 dbghelp. README-filen i zip-en har CMake-linjene.

Lisensiering

JUCE-modulen og C-headeren er Apache-2.0, så de kan linkes inn i GPL- eller kommersielle JUCE-prosjekter. JUCE selv har sin egen lisens og egne abonnementer, som en sournd-lisens ikke dekker: følg JUCE 8-lisensen og velg det JUCE-abonnementet som passer det du leverer. Betalte motorer leveres som lukkede statiske biblioteker. Se lisensiering.