sOURnd Docs Dine engines
På denne side
  1. Det får du
  2. 1. Tilføj modulet og biblioteket
  3. 2. Opret enginen, dens parametre og broen
  4. 3. Vælg en engine
  5. Regler, det er godt at kende
  6. Begrænsninger
  7. Platforme
  8. Licenser

JUCE-kom godt i gang

Føj en sournd-engine til et JUCE 8-plugin. Tre CMake-linjer, tre C++-objekter, ingen Rust-toolchain på din maskine.

  1. DownloadJUCE-modulet og dit engine-bibliotek
  2. CMaketre linjer
  3. Tre C++-objekterengine, parametre, bro
  4. Dit pluginbygget af JUCE som sædvanlig

Det får du

  • sournd_engine, et standard JUCE-modul, der kun afhænger af juce_audio_processors og juce_dsp (Apache-2.0). Download det: sournd-engine-juce-module.zip.
  • Et statisk bibliotek til din platform (libsournd_cabi.a, eller sournd_cabi.lib på Windows) og headeren sournd_engine.h: de gratis engines fra en hvilken som helst gratis engines side (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), de betalte fra Dine engines.
  • SourndEngine, som implementerer juce::dsp::ProcessorBase, og SourndEngineParameters, som bygger et APVTS-layout ud fra enginen og holder dem synkroniseret.

1. Tilføj modulet og biblioteket

Udpak modulet, så du har en sournd_engine-mappe, og udpak din engine-download ved siden af.

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)

Til et universelt macOS-plugin skal du bygge med -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' og linke det universelle arkiv.

På Linux har downloaden ét arkiv pr. arkitektur. Vælg det til den maskine, du bygger til, og tilføj de systembiblioteker, det kræver:

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. Opret enginen, dens parametre og broen

Konstruér dem i denne rækkefølge på message-trå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;
};

Hvad der sker under kørsel:

Hver blok

  1. Værtknapper og automation
  2. APVTSdit plugins parametre
  3. bridge.applyændrede værdier, én gang pr. blok
  4. engine.processudjævner sample for sample
  5. Lyd ud

Gemmer

  1. Værten beder om tilstand
  2. getCallbackLock()holder processBlock ude
  3. bridge.syncToEngine()
  4. engine.saveState()en uigennemsigtig blob

Indlæser

  1. Værten giver tilstanden tilbage
  2. getCallbackLock()
  3. engine.loadState()matches på parameter-id
  4. bridge.syncFromEngine()

3. Vælg en engine

Vælg et vilkårligt id fra kataloget eller catalog.json. Et ukendt id giver en ugyldig engine, der afgiver stilhed, så tjek isValid() og lastError().

Regler, det er godt at kende

  • Parameter-id'er er stabile decimale strenge: parameterens placering i enginens manifest, vist på hver engines side. Parametre tilføjes kun, de omnummereres aldrig.
  • Værtens intervaller følger hver parameters kurve. En log-parameter (cutoff, tid, ratio) afbilder værtens 0 til 1 som min * (max / min)^p, så automationsspor og generiske editorer bevæger sig i lige store forhold, som enginens egne knapper gør. Hvis du allerede har udgivet et plugin med lineære intervaller, så send createLayout (engine, false) for at beholde dem, fordi værter gemmer automation som værdier fra 0 til 1.
  • bridge.apply giver hver ændret værdi videre til enginen i begyndelsen af blokken. Enginen udjævner selv kontinuerlige kontroller, sample for sample, så lyden ikke afhænger af værtens blokstørrelse (testet bit for bit ved 1, 32, 64 og 512 frames). Trinvise og booleske kontroller springer direkte.
  • Frames pr. kald skal holde sig inden for det maksimum, der blev givet til prepare. Wrapperen opdeler ikke værtens blokke.
  • Tilstanden er uigennemsigtig og knyttet til engine-id'et. Den gemmer indstillinger, ikke delay- eller filterhistorik. Den migrerer på tværs af engine-versioner: værdier matches på parameter-id, parametre, der er tilføjet, siden sessionen blev gemt, får deres standardværdier, og værdier fra en nyere engine, som denne mangler, ignoreres (lastStateReport() tæller begge dele). En tilstand afvises, uden at noget ændres, kun hvis den tilhører en anden engine eller er beskadiget.
  • Lydtråden allokerer, låser eller kalder aldrig message manageren. Brug én engine-instans pr. processeringstråd.
  • Kald til én engine må ikke overlappe. Alt uden for processBlock, der rører enginen (gemme eller indlæse tilstand, prepare, reset), holder getCallbackLock(), som ovenfor, så det aldrig kører, mens lyd processeres.

Begrænsninger

Det er brofunktionens kanter i dag.

  • Lyd er 32-bit float. Broen processerer kun float-buffere. Lad supportsDoublePrecisionProcessing() stå på standardværdien (false), så værter giver dit plugin float-lyd.
  • Mono eller stereo, ens på input og output. En eller to hovedkanaler; mono til stereo, stereo til mono og surround-layouts understøttes ikke. Nogle engines kører kun i stereo, så spørg enginen i isBusesLayoutSupported i stedet for at antage det (nedenfor). supportsChannels forbereder en midlertidig instans, så gem svaret i stedet for at kalde den på lydtråden.
  • Sidechain-engines accepterer en frakoblet, mono- eller stereo-hjælpeindgang.
  • MIDI. Effekter ignorerer MIDI-bufferen, og broen producerer aldrig MIDI. Instrument-engines læser note on, note off og all notes off (CC 120 og 123) ved deres sampleplaceringer, på hver kanal; pitch bend, aftertouch, andre controllere og MPE videregives ikke.
  • Samplerater fra 8 kHz til 768 kHz og op til 1.048.576 frames pr. blok.
  • Skjulte engine-parametre bliver i enginens tilstand og er ikke værtskontroller.
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);

Platforme

Downloads bygges til macOS universal (arm64 og x86_64), Linux (x86_64 og aarch64, glibc 2.36 eller nyere) og Windows x64 (MSVC). Vælg platformen, når du downloader fra siden Dine engines; en agent beder om den med platform=linux eller platform=windows-x64.

På Windows indeholder zip-filen to kopier af sournd_cabi.lib: lib/windows-x64/ til projekter med den dynamiske C-runtime (/MD, MSVC-standarden) og lib/windows-x64-static-crt/ til den statiske (/MT). Link den, der passer til dit plugin, efterfulgt af kernel32 ntdll userenv ws2_32 dbghelp. README'en i zip-filen har CMake-linjerne.

Licenser

JUCE-modulet og C-headeren er Apache-2.0, så de kan linkes ind i GPL- eller kommercielle JUCE-projekter. JUCE har selv sin egen licens og sine egne abonnementer, som en sournd-licens ikke dækker: følg JUCE 8-licensen, og vælg det JUCE-abonnement, der passer til det, du udgiver. Betalte engines leveres som lukkede statiske biblioteker. Se licenser.