sOURnd Dokumentacja Twoje silniki
Na tej stronie
  1. Co dostajesz
  2. 1. Dodaj moduł i bibliotekę
  3. 2. Utwórz silnik, jego parametry i most
  4. 3. Wybierz silnik
  5. Reguły, które warto znać
  6. Ograniczenia
  7. Platformy
  8. Licencje

Szybki start z JUCE

Dodaj silnik sournd do wtyczki JUCE 8. Trzy linie CMake, trzy obiekty C++, bez toolchaina Rust na twoim komputerze.

  1. Pobierzmoduł JUCE i biblioteka twojego silnika
  2. CMaketrzy linie
  3. Trzy obiekty C++silnik, parametry, most
  4. Twoja wtyczkabudowana przez JUCE jak zwykle

Co dostajesz

  • sournd_engine, standardowy moduł JUCE zależny tylko od juce_audio_processors i juce_dsp (Apache-2.0). Pobierz go: sournd-engine-juce-module.zip.
  • Biblioteka statyczna dla twojej platformy (libsournd_cabi.a lub sournd_cabi.lib w Windows) i nagłówek sournd_engine.h: darmowe silniki ze strony dowolnego darmowego silnika (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), płatne z Twoich silników.
  • SourndEngine, który implementuje juce::dsp::ProcessorBase, oraz SourndEngineParameters, który buduje układ APVTS z silnika i utrzymuje je zsynchronizowane.

1. Dodaj moduł i bibliotekę

Rozpakuj moduł tak, aby powstał folder sournd_engine, a pobrany silnik rozpakuj obok niego.

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)

Dla uniwersalnej wtyczki macOS buduj z -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' i podlinkuj archiwum uniwersalne.

W Linuksie pobranie zawiera jedno archiwum na architekturę. Wybierz to dla maszyny, na którą budujesz, i dodaj potrzebne biblioteki systemowe:

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. Utwórz silnik, jego parametry i most

Twórz je w tej kolejności, w wątku komunikatów:

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 dzieje się w czasie działania:

Każdy blok

  1. Hostpokrętła i automatyka
  2. APVTSparametry twojej wtyczki
  3. bridge.applyzmienione wartości, raz na blok
  4. engine.processwygładza próbka po próbce
  5. Wyjście audio

Zapis

  1. Host prosi o stan
  2. getCallbackLock()blokuje wejście processBlock
  3. bridge.syncToEngine()
  4. engine.saveState()nieprzezroczysty blob

Wczytywanie

  1. Host oddaje stan
  2. getCallbackLock()
  3. engine.loadState()dopasowanie po identyfikatorze parametru
  4. bridge.syncFromEngine()

3. Wybierz silnik

Wybierz dowolny identyfikator z katalogu lub catalog.json. Nieznany identyfikator tworzy nieprawidłowy silnik, który wyprowadza ciszę, więc sprawdzaj isValid() i lastError().

Reguły, które warto znać

  • Identyfikatory parametrów to stałe ciągi dziesiętne: pozycja parametru w manifeście silnika, widoczna na stronie każdego silnika. Parametry są tylko dodawane, nigdy renumerowane.
  • Zakresy hosta podążają za skalą każdego parametru. Parametr logarytmiczny (cutoff, czas, ratio) odwzorowuje zakres hosta od 0 do 1 jako min * (max / min)^p, więc ścieżki automatyki i ogólne edytory poruszają się w równych proporcjach, tak jak własne pokrętła silnika. Jeśli wydałeś już wtyczkę z zakresami liniowymi, przekaż createLayout (engine, false), aby je zachować, ponieważ hosty przechowują automatykę jako wartości od 0 do 1.
  • bridge.apply przekazuje każdą zmienioną wartość silnikowi na początku bloku. Silnik sam wygładza regulatory ciągłe, próbka po próbce, więc brzmienie nie zależy od rozmiaru bloku hosta (przetestowano bit w bit przy 1, 32, 64 i 512 próbkach). Regulatory skokowe i logiczne przeskakują.
  • Liczba próbek na wywołanie musi mieścić się w maksimum przekazanym do prepare. Nakładka nie dzieli bloków hosta.
  • Stan jest nieprzezroczysty i powiązany z identyfikatorem silnika. Przechowuje ustawienia, a nie historię delaya czy filtra. Przenosi się między wersjami silnika: wartości są dopasowywane po identyfikatorze parametru, parametry dodane po zapisaniu sesji dostają wartości domyślne, a wartości z nowszego silnika, których ten nie ma, są pomijane (lastStateReport() liczy jedne i drugie). Stan jest odrzucany, bez żadnych zmian, tylko gdy należy do innego silnika lub jest uszkodzony.
  • Wątek audio nigdy nie alokuje, nie blokuje ani nie wywołuje menedżera komunikatów. Używaj jednej instancji silnika na wątek przetwarzania.
  • Wywołania jednego silnika nie mogą się nakładać. Wszystko poza processBlock, co dotyka silnika (zapis lub wczytanie stanu, prepare, reset), trzyma getCallbackLock(), jak wyżej, więc nigdy nie działa w trakcie przetwarzania audio.

Ograniczenia

Tak dziś wyglądają granice mostu.

  • Audio jest 32-bitowe zmiennoprzecinkowe. Most przetwarza tylko bufory float. Zostaw supportsDoublePrecisionProcessing() przy wartości domyślnej (false), aby hosty przekazywały wtyczce audio float.
  • Mono lub stereo, tak samo na wejściu i wyjściu. Jeden lub dwa kanały główne; mono na stereo, stereo na mono i układy surround nie są obsługiwane. Niektóre silniki działają tylko w stereo, więc zapytaj silnik w isBusesLayoutSupported, zamiast zakładać (niżej). supportsChannels przygotowuje instancję roboczą, więc zapamiętaj odpowiedź, zamiast wywoływać ją w wątku audio.
  • Silniki sidechain przyjmują wejście pomocnicze: odłączone, mono lub stereo.
  • MIDI. Efekty ignorują bufor MIDI, a most nigdy nie wytwarza MIDI. Silniki instrumentów czytają note on, note off i all notes off (CC 120 i 123) na właściwych pozycjach próbek, na każdym kanale; pitch bend, aftertouch, inne kontrolery i MPE nie są przekazywane.
  • Częstotliwości próbkowania od 8 kHz do 768 kHz i do 1 048 576 próbek na blok.
  • Ukryte parametry silnika zostają w jego stanie i nie są regulatorami hosta.
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

Pobrania są budowane dla macOS uniwersalnego (arm64 i x86_64), Linuksa (x86_64 i aarch64, glibc 2.36 lub nowszy) i Windows x64 (MSVC). Platformę wybierasz przy pobieraniu ze strony Twoich silników; agent prosi o nią przez platform=linux lub platform=windows-x64.

W Windows archiwum zip zawiera dwie kopie sournd_cabi.lib: lib/windows-x64/ dla projektów z dynamicznym środowiskiem uruchomieniowym C (/MD, domyślne w MSVC) i lib/windows-x64-static-crt/ dla statycznego (/MT). Podlinkuj tę, która pasuje do twojej wtyczki, a po niej kernel32 ntdll userenv ws2_32 dbghelp. README w archiwum zawiera linie CMake.

Licencje

Moduł JUCE i nagłówek C są na licencji Apache-2.0, więc podlinkujesz je do projektów JUCE na GPL lub komercyjnych. Sam JUCE ma własną licencję i plany, których licencja sournd nie obejmuje: stosuj się do licencji JUCE 8 i wybierz plan JUCE pasujący do tego, co wydajesz. Płatne silniki trafiają do ciebie jako zamknięte biblioteki statyczne. Zobacz licencje.