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.
- Last nedJUCE-modulen og motorbiblioteket ditt
- CMaketre linjer
- Tre C++-objektermotor, parametere, bro
- Pluginen dinbygget av JUCE som vanlig
Dette får du
sournd_engine, en standard JUCE-modul som bare avhenger avjuce_audio_processorsogjuce_dsp(Apache-2.0). Last den ned: sournd-engine-juce-module.zip.- Et statisk bibliotek for plattformen din (
libsournd_cabi.a, ellersournd_cabi.libpå Windows) og headerensournd_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 implementererjuce::dsp::ProcessorBase, ogSourndEngineParameters, 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.
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:
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:
#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
- Vertknotter og automatisering
- APVTSpluginens parametere
bridge.applyendrede verdier, én gang per blokkengine.processglatter sample for sample- Lyd ut
Lagring
- Verten ber om tilstand
getCallbackLock()holderprocessBlockutebridge.syncToEngine()engine.saveState()en ugjennomsiktig blob
Innlasting
- Verten gir tilstanden tilbake
getCallbackLock()engine.loadState()matchet på parameter-idbridge.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, sendcreateLayout (engine, false)for å beholde dem, fordi verter lagrer automasjon som verdier fra 0 til 1. bridge.applygir 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
processBlocksom berører motoren (lagring eller innlasting av tilstand,prepare,reset) holdergetCallbackLock(), 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. LasupportsDoublePrecisionProcessing()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
isBusesLayoutSupportedi stedet for å anta (se nedenfor).supportsChannelsforbereder 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.
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.