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.
- Scaricail modulo JUCE e la libreria del tuo engine
- CMaketre righe
- Tre oggetti C++engine, parametri, bridge
- Il tuo plugincompilato da JUCE come al solito
Cosa ottieni
sournd_engine, un modulo JUCE standard che dipende solo dajuce_audio_processorsejuce_dsp(Apache-2.0). Scaricalo: sournd-engine-juce-module.zip.- Una libreria statica per la tua piattaforma (
libsournd_cabi.a, oppuresournd_cabi.libsu Windows) e l'headersournd_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 implementajuce::dsp::ProcessorBase, eSourndEngineParameters, 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.
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:
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:
#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
- Hostmanopole e automazione
- APVTSi parametri del tuo plugin
bridge.applyvalori modificati, una volta a bloccoengine.processsmussa campione per campione- Audio in uscita
Salvataggio
- L'host chiede lo stato
getCallbackLock()tiene fuoriprocessBlockbridge.syncToEngine()engine.saveState()un blob opaco
Caricamento
- L'host restituisce lo stato
getCallbackLock()engine.loadState()abbinato per id del parametrobridge.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, passacreateLayout (engine, false)per mantenerli, perché gli host salvano l'automazione come valori da 0 a 1. bridge.applypassa 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) tienegetCallbackLock(), 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. LasciasupportsDoublePrecisionProcessing()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
isBusesLayoutSupportedinvece di dare per scontato (sotto).supportsChannelsprepara 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.
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.