sOURnd Dokumentation Dina motorer
På den här sidan
  1. Det här får du
  2. 1. Lägg till modulen och biblioteket
  3. 2. Skapa motorn, dess parametrar och bryggan
  4. 3. Välj en motor
  5. Regler värda att känna till
  6. Begränsningar
  7. Plattformar
  8. Licenser

Snabbstart för JUCE

Lägg till en sournd-motor i ett JUCE 8-plugin. Tre CMake-rader, tre C++-objekt, ingen Rust-verktygskedja på din dator.

  1. Ladda nerJUCE-modulen och ditt motorbibliotek
  2. CMaketre rader
  3. Tre C++-objektmotor, parametrar, brygga
  4. Ditt pluginbyggs av JUCE som vanligt

Det här får du

  • sournd_engine, en vanlig JUCE-modul som bara är beroende av juce_audio_processors och juce_dsp (Apache-2.0). Ladda ner den: sournd-engine-juce-module.zip.
  • Ett statiskt bibliotek för din plattform (libsournd_cabi.a, eller sournd_cabi.lib på Windows) och headern sournd_engine.h: gratismotorerna från vilken gratismotors sida som helst (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), de betalda från Dina motorer.
  • SourndEngine, som implementerar juce::dsp::ProcessorBase, och SourndEngineParameters, som bygger en APVTS-layout från motorn och håller dem synkade.

1. Lägg till modulen och biblioteket

Packa upp modulen så att du får en mapp sournd_engine, och packa upp din motornedladdning bredvid den.

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)

För ett universellt macOS-plugin bygger du med -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' och länkar det universella arkivet.

På Linux har nedladdningen ett arkiv per arkitektur. Välj det för maskinen du bygger för och lägg till de systembibliotek det behö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. Skapa motorn, dess parametrar och bryggan

Skapa dem i den här ordningen, på meddelandetrå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;
};

Vad som händer under körning:

Varje block

  1. Värdrattar och automation
  2. APVTSditt plugins parametrar
  3. bridge.applyändrade värden, en gång per block
  4. engine.processjämnar ut sampel för sampel
  5. Ljud ut

Spara

  1. Värden frågar efter tillstånd
  2. getCallbackLock()håller processBlock utanför
  3. bridge.syncToEngine()
  4. engine.saveState()en ogenomskinlig blob

Ladda

  1. Värden lämnar tillbaka tillståndet
  2. getCallbackLock()
  3. engine.loadState()matchas på parameter-id
  4. bridge.syncFromEngine()

3. Välj en motor

Välj vilket id som helst från katalogen eller catalog.json. Ett okänt id ger en ogiltig motor som matar ut tystnad, så kontrollera isValid() och lastError().

Regler värda att känna till

  • Parameter-id:n är stabila decimala strängar: parameterns position i motorns manifest, som visas på varje motorsida. Parametrar läggs bara till, de numreras aldrig om.
  • Värdens intervall följer varje parameters kurva. En logaritmisk parameter (cutoff, tid, ratio) mappar värdens 0 till 1 som min * (max / min)^p, så automationsspår och generiska redigerare rör sig i lika stora förhållanden, precis som motorns egna rattar. Om du redan har släppt ett plugin med linjära intervall, skicka createLayout (engine, false) för att behålla dem, eftersom värdar lagrar automation som värden mellan 0 och 1.
  • bridge.apply lämnar varje ändrat värde till motorn i början av blocket. Motorn jämnar själv ut kontinuerliga reglage, sampel för sampel, så ljudet beror inte på värdens blockstorlek (testat bit för bit vid 1, 32, 64 och 512 frames). Stegade och booleska reglage hoppar direkt.
  • Antalet frames per anrop måste rymmas inom det maximum som skickades till prepare. Omslaget delar inte upp värdens block.
  • Tillstånd är ogenomskinligt och knutet till motorns id. Det lagrar inställningar, inte delay- eller filterhistorik. Det migrerar mellan motorversioner: värden matchas på parameter-id, parametrar som lagts till sedan sessionen sparades får sina standardvärden, och värden från en nyare motor som den här saknar ignoreras (lastStateReport() räknar båda). Ett tillstånd avvisas, utan att något ändras, bara när det hör till en annan motor eller är skadat.
  • Ljudtråden allokerar, låser eller anropar aldrig meddelandehanteraren. Använd en motorinstans per bearbetningstråd.
  • Anrop till en motor får inte överlappa. Allt utanför processBlock som rör motorn (spara eller ladda tillstånd, prepare, reset) håller getCallbackLock(), som ovan, så att det aldrig körs medan ljud bearbetas.

Begränsningar

Det här är bryggans gränser i dag.

  • Ljudet är 32-bitars float. Bryggan bearbetar bara float-buffertar. Låt supportsDoublePrecisionProcessing() stå kvar på standardvärdet (false), så att värdar ger ditt plugin float-ljud.
  • Mono eller stereo, samma på in och ut. En eller två huvudkanaler; mono till stereo, stereo till mono och surroundlayouter stöds inte. Vissa motorer körs bara i stereo, så fråga motorn i isBusesLayoutSupported i stället för att anta (nedan). supportsChannels förbereder en tillfällig instans, så spara svaret i stället för att anropa den på ljudtråden.
  • Sidechain-motorer accepterar en frånkopplad, mono- eller stereoextraingång.
  • MIDI. Effekter ignorerar MIDI-bufferten, och bryggan skapar aldrig MIDI. Instrumentmotorer läser note on, note off och all notes off (CC 120 och 123) vid sina samplepositioner, på varje kanal; pitch bend, aftertouch, andra kontroller och MPE skickas inte vidare.
  • Samplingsfrekvenser från 8 kHz till 768 kHz, och upp till 1,048,576 frames per block.
  • Dolda motorparametrar stannar inne i motorns tillstånd och är inte värdreglage.
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);

Plattformar

Nedladdningarna byggs för macOS universal (arm64 och x86_64), Linux (x86_64 och aarch64, glibc 2.36 eller nyare) och Windows x64 (MSVC). Välj plattform när du laddar ner från sidan Dina motorer; en agent ber om den med platform=linux eller platform=windows-x64.

På Windows innehåller zipfilen två kopior av sournd_cabi.lib: lib/windows-x64/ för projekt med den dynamiska C-runtimen (/MD, MSVC:s standard) och lib/windows-x64-static-crt/ för den statiska (/MT). Länka den som passar ditt plugin, följt av kernel32 ntdll userenv ws2_32 dbghelp. README i zipfilen har CMake-raderna.

Licenser

JUCE-modulen och C-headern är Apache-2.0, så de kan länkas in i GPL- eller kommersiella JUCE-projekt. JUCE har sin egen licens och sina egna abonnemang, som en sournd-licens inte täcker: följ JUCE 8-licensen och välj det JUCE-abonnemang som passar det du släpper. Betalda motorer levereras som slutna statiska bibliotek. Se licenser.