Szybki start z JUCE
Dodaj silnik sournd do wtyczki JUCE 8. Trzy linie CMake, trzy obiekty C++, bez toolchaina Rust na twoim komputerze.
- Pobierzmoduł JUCE i biblioteka twojego silnika
- CMaketrzy linie
- Trzy obiekty C++silnik, parametry, most
- Twoja wtyczkabudowana przez JUCE jak zwykle
Co dostajesz
sournd_engine, standardowy moduł JUCE zależny tylko odjuce_audio_processorsijuce_dsp(Apache-2.0). Pobierz go: sournd-engine-juce-module.zip.- Biblioteka statyczna dla twojej platformy (
libsournd_cabi.alubsournd_cabi.libw Windows) i nagłóweksournd_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 implementujejuce::dsp::ProcessorBase, orazSourndEngineParameters, 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.
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:
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:
#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
- Hostpokrętła i automatyka
- APVTSparametry twojej wtyczki
bridge.applyzmienione wartości, raz na blokengine.processwygładza próbka po próbce- Wyjście audio
Zapis
- Host prosi o stan
getCallbackLock()blokuje wejścieprocessBlockbridge.syncToEngine()engine.saveState()nieprzezroczysty blob
Wczytywanie
- Host oddaje stan
getCallbackLock()engine.loadState()dopasowanie po identyfikatorze parametrubridge.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.applyprzekazuje 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), trzymagetCallbackLock(), 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. ZostawsupportsDoublePrecisionProcessing()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).supportsChannelsprzygotowuje 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.
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.