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.
- Downloadende JUCE-module en jouw enginebibliotheek
- CMakedrie regels
- Drie C++-objectenengine, parameters, bridge
- Jouw plugindoor JUCE gebouwd zoals gewoonlijk
Wat je krijgt
sournd_engine, een standaard JUCE-module die alleen afhangt vanjuce_audio_processorsenjuce_dsp(Apache-2.0). Download hem: sournd-engine-juce-module.zip.- Een static library voor jouw platform (
libsournd_cabi.a, ofsournd_cabi.libop Windows) en de headersournd_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, diejuce::dsp::ProcessorBaseimplementeert, enSourndEngineParameters, 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.
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:
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:
#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
- Hostknoppen en automatisering
- APVTSde parameters van je plugin
bridge.applygewijzigde waarden, één keer per blokengine.processsmoothet sample voor sample- Audio uit
Opslaan
- Host vraagt om de state
getCallbackLock()houdtprocessBlockbuitenbridge.syncToEngine()engine.saveState()een ondoorzichtige blob
Laden
- Host geeft de state terug
getCallbackLock()engine.loadState()gekoppeld op parameter-idbridge.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 dancreateLayout (engine, false)mee om die te behouden, want hosts slaan automatisering op als waarden van 0 tot 1. bridge.applygeeft 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
prepareis 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
processBlockdat de engine raakt (state opslaan of laden,prepare,reset) houdtgetCallbackLock()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. LaatsupportsDoublePrecisionProcessing()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
isBusesLayoutSupportedin plaats van het aan te nemen (zie hieronder).supportsChannelsbereidt 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.
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.