sOURnd Dokumentace Vaše enginy
Na této stránce
  1. Co dostanete
  2. 1. Přidejte modul a knihovnu
  3. 2. Vytvořte engine, jeho parametry a most
  4. 3. Vyberte engine
  5. Pravidla, která stojí za znalost
  6. Omezení
  7. Platformy
  8. Licencování

Rychlý start s JUCE

Přidejte engine sournd do pluginu JUCE 8. Tři řádky CMake, tři objekty C++, na vašem počítači žádný toolchain Rustu.

  1. Stáhnoutmodul JUCE a knihovna vašeho enginu
  2. CMaketři řádky
  3. Tři objekty C++engine, parametry, most
  4. Váš pluginsestavený JUCE jako obvykle

Co dostanete

  • sournd_engine, standardní modul JUCE, který závisí jen na juce_audio_processors a juce_dsp (Apache-2.0). Stáhněte si ho: sournd-engine-juce-module.zip.
  • Statická knihovna pro vaši platformu (libsournd_cabi.a, ve Windows sournd_cabi.lib) a hlavička sournd_engine.h: enginy zdarma ze stránky libovolného enginu zdarma (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), placené z části Vaše enginy.
  • SourndEngine, který implementuje juce::dsp::ProcessorBase, a SourndEngineParameters, který z enginu sestaví rozložení APVTS a udržuje je v souladu.

1. Přidejte modul a knihovnu

Rozbalte modul tak, aby vznikla složka sournd_engine, a vedle ní rozbalte stažený engine.

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)

Pro univerzální plugin pro macOS sestavte s -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' a linkujte univerzální archiv.

V Linuxu obsahuje stažení jeden archiv pro každou architekturu. Vyberte ten pro počítač, pro který sestavujete, a přidejte systémové knihovny, které potřebuje:

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. Vytvořte engine, jeho parametry a most

Vytvořte je v tomto pořadí, ve vlákně zpráv:

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;
};

Co se děje za běhu:

Každý blok

  1. Hostitelknoflíky a automatizace
  2. APVTSparametry vašeho pluginu
  3. bridge.applyzměněné hodnoty, jednou za blok
  4. engine.processvyhlazuje vzorek po vzorku
  5. Audio výstup

Ukládání

  1. Hostitel žádá o stav
  2. getCallbackLock()drží processBlock stranou
  3. bridge.syncToEngine()
  4. engine.saveState()neprůhledný blob

Načítání

  1. Hostitel vrací stav
  2. getCallbackLock()
  3. engine.loadState()párováno podle id parametru
  4. bridge.syncFromEngine()

3. Vyberte engine

Vyberte libovolné id z katalogu nebo catalog.json. Neznámé id vytvoří neplatný engine, který vydává ticho, proto zkontrolujte isValid() a lastError().

Pravidla, která stojí za znalost

  • Id parametrů jsou stabilní desítkové řetězce: pozice parametru v manifestu enginu, uvedená na stránce každého enginu. Parametry se vždy jen přidávají, nikdy se nepřečíslovávají.
  • Rozsahy v hostiteli sledují průběh každého parametru. Logaritmický parametr (cutoff, čas, poměr) mapuje hostitelův rozsah 0 až 1 jako min * (max / min)^p, takže automatizační stopy a obecné editory se pohybují v stejných poměrech, jako vlastní knoflíky enginu. Pokud jste už vydali plugin s lineárními rozsahy, předejte createLayout (engine, false), abyste je zachovali, protože hostitelé ukládají automatizaci jako hodnoty 0 až 1.
  • bridge.apply předá enginu každou změněnou hodnotu na začátku bloku. Engine plynulé ovladače vyhlazuje sám, vzorek po vzorku, takže zvuk nezávisí na velikosti bloku hostitele (testováno bit po bitu při 1, 32, 64 a 512 snímcích). Skokové a booleovské ovladače přeskočí okamžitě.
  • Počet snímků na volání se musí vejít do maxima předaného prepare. Obal bloky hostitele nedělí.
  • Stav je neprůhledný a vázaný na id enginu. Ukládá nastavení, ne historii delaye nebo filtru. Přenáší se mezi verzemi enginu: hodnoty se párují podle id parametru, parametry přidané od uložení session dostanou výchozí hodnoty a hodnoty z novějšího enginu, které tento nemá, se ignorují (lastStateReport() počítá obojí). Stav je odmítnut, a nic se nezmění, jen když patří jinému enginu nebo je poškozený.
  • Audio vlákno nikdy nealokuje, nezamyká ani nevolá správce zpráv. Na každé zpracovávací vlákno použijte jednu instanci enginu.
  • Volání jednoho enginu se nesmí překrývat. Cokoli mimo processBlock, co se enginu dotýká (ukládání nebo načítání stavu, prepare, reset), drží getCallbackLock(), jak je uvedeno výše, takže nikdy neběží během zpracování zvuku.

Omezení

Toto jsou dnešní hranice mostu.

  • Zvuk je 32bitový float. Most zpracovává jen buffery float. Nechte supportsDoublePrecisionProcessing() na výchozí hodnotě (false), aby hostitelé předávali vašemu pluginu zvuk ve float.
  • Mono nebo stereo, stejně na vstupu i výstupu. Jeden nebo dva hlavní kanály; mono na stereo, stereo na mono a prostorová rozložení nejsou podporována. Některé enginy běží jen ve stereu, proto se zeptejte enginu v isBusesLayoutSupported, místo abyste to předpokládali (níže). supportsChannels připraví pracovní instanci, takže odpověď uložte do mezipaměti a nevolejte ji v audio vlákně.
  • Enginy se sidechainem přijímají nepřipojený, mono nebo stereo pomocný vstup.
  • MIDI. Efekty ignorují buffer MIDI a most MIDI nikdy nevytváří. Nástrojové enginy čtou note on, note off a all notes off (CC 120 a 123) na jejich pozicích vzorků, na každém kanálu; pitch bend, aftertouch, další ovladače a MPE se nepředávají.
  • Vzorkovací frekvence od 8 kHz do 768 kHz a až 1,048,576 snímků na blok.
  • Skryté parametry enginu zůstávají uvnitř stavu enginu a nejsou ovládacími prvky hostitele.
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);

Platformy

Stažení jsou sestavena pro macOS universal (arm64 a x86_64), Linux (x86_64 a aarch64, glibc 2.36 nebo novější) a Windows x64 (MSVC). Platformu zvolíte při stahování na stránce Vaše enginy; agent o ni žádá pomocí platform=linux nebo platform=windows-x64.

Ve Windows obsahuje zip dvě kopie sournd_cabi.lib: lib/windows-x64/ pro projekty s dynamickým C runtime (/MD, výchozí v MSVC) a lib/windows-x64-static-crt/ pro statický (/MT). Linkujte tu, která odpovídá vašemu pluginu, následovanou kernel32 ntdll userenv ws2_32 dbghelp. README v zipu obsahuje řádky CMake.

Licencování

Modul JUCE a hlavička C jsou pod Apache-2.0, takže se linkují do projektů JUCE pod GPL i komerčních. JUCE samo má vlastní licenci a plány, které licence sournd nepokrývá: řiďte se licencí JUCE 8 a zvolte plán JUCE, který odpovídá tomu, co vydáváte. Placené enginy se dodávají jako uzavřené statické knihovny. Viz licencování.