Inicio rápido con JUCE
Añade un motor de sournd a un plugin de JUCE 8. Tres líneas de CMake, tres objetos de C++ y ninguna cadena de herramientas de Rust en tu equipo.
- Descargarel módulo de JUCE y la biblioteca de tu motor
- CMaketres líneas
- Tres objetos de C++motor, parámetros, puente
- Tu plugincompilado por JUCE como siempre
Qué obtienes
sournd_engine, un módulo estándar de JUCE que solo depende dejuce_audio_processorsyjuce_dsp(Apache-2.0). Descárgalo: sournd-engine-juce-module.zip.- Una biblioteca estática para tu plataforma (
libsournd_cabi.a, osournd_cabi.liben Windows) y la cabecerasournd_engine.h: los motores gratuitos desde la página de cualquier motor gratuito (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), los de pago desde Tus motores. SourndEngine, que implementajuce::dsp::ProcessorBase, ySourndEngineParameters, que construye un diseño de APVTS a partir del motor y los mantiene sincronizados.
1. Añade el módulo y la biblioteca
Descomprime el módulo para tener una carpeta sournd_engine, y descomprime junto a ella la descarga de tu motor.
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)Para un plugin universal de macOS, compila con -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' y enlaza el archivo universal.
En Linux la descarga trae un archivo por arquitectura. Elige el de la máquina para la que compilas y añade las bibliotecas del sistema que necesita:
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. Crea el motor, sus parámetros y el puente
Constrúyelos en este orden, en el hilo de mensajes:
#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;
};Qué ocurre en tiempo de ejecución:
Cada bloque
- Hostmandos y automatización
- APVTSlos parámetros de tu plugin
bridge.applyvalores cambiados, una vez por bloqueengine.processsuaviza muestra a muestra- Salida de audio
Guardar
- El host pide el estado
getCallbackLock()mantiene fuera aprocessBlockbridge.syncToEngine()engine.saveState()un blob opaco
Cargar
- El host devuelve el estado
getCallbackLock()engine.loadState()emparejados por id de parámetrobridge.syncFromEngine()
3. Elige un motor
Elige cualquier id del catálogo o de catalog.json. Un id desconocido produce un motor no válido que emite silencio, así que comprueba isValid() y lastError().
Reglas que conviene conocer
- Los ids de parámetro son cadenas decimales estables: la posición del parámetro en el manifiesto del motor, que aparece en la página de cada motor. Los parámetros solo se añaden, nunca se renumeran.
- Los rangos del host siguen la curva de cada parámetro. Un parámetro logarítmico (cutoff, tiempo, ratio) traduce el rango de 0 a 1 del host como
min * (max / min)^p, de modo que las pistas de automatización y los editores genéricos se mueven en proporciones iguales, como los mandos del propio motor. Si ya publicaste un plugin con rangos lineales, pasacreateLayout (engine, false)para conservarlos, porque los hosts guardan la automatización como valores de 0 a 1. bridge.applyentrega al motor cada valor cambiado al principio del bloque. El motor suaviza por sí mismo los controles continuos, muestra a muestra, así que el sonido no depende del tamaño de bloque del host (probado bit a bit con 1, 32, 64 y 512 frames). Los controles por pasos y los booleanos saltan de golpe.- Los frames por llamada deben caber en el máximo que se pasó a
prepare. El envoltorio no divide los bloques del host. - El estado es opaco y está ligado al id del motor. Guarda ajustes, no el historial de delay ni de filtros. Migra entre versiones del motor: los valores se emparejan por id de parámetro, los parámetros añadidos desde que se guardó la sesión toman sus valores por defecto y los valores de un motor más nuevo que este no tiene se ignoran (
lastStateReport()cuenta ambos casos). Un estado solo se rechaza, sin cambiar nada, cuando pertenece a otro motor o está dañado. - El hilo de audio nunca reserva memoria, ni usa bloqueos, ni llama al gestor de mensajes. Usa una instancia del motor por hilo de procesamiento.
- Las llamadas a un mismo motor no deben solaparse. Todo lo que toque el motor fuera de
processBlock(guardar o cargar el estado,prepare,reset) mantienegetCallbackLock(), como se vio antes, de modo que nunca se ejecuta mientras se procesa audio.
Límites
Estos son hoy los límites del puente.
- El audio es float de 32 bits. El puente solo procesa búferes de
float. DejasupportsDoublePrecisionProcessing()en su valor por defecto (false) para que los hosts entreguen a tu plugin audio en float. - Mono o estéreo, igual en la entrada y en la salida. Uno o dos canales principales; no se admiten mono a estéreo, estéreo a mono ni formatos envolventes. Algunos motores solo funcionan en estéreo, así que pregunta al motor en
isBusesLayoutSupporteden lugar de suponerlo (más abajo).supportsChannelsprepara una instancia temporal, así que guarda la respuesta en caché en lugar de llamarla desde el hilo de audio. - Los motores de sidechain aceptan una entrada auxiliar desconectada, mono o estéreo.
- MIDI. Los efectos ignoran el búfer MIDI y el puente nunca produce MIDI. Los motores de instrumento leen note on, note off y all notes off (CC 120 y 123) en sus posiciones de muestra, en todos los canales; el pitch bend, el aftertouch, otros controladores y MPE no se transmiten.
- Frecuencias de muestreo de 8 kHz a 768 kHz, y hasta 1,048,576 frames por bloque.
- Los parámetros ocultos del motor permanecen dentro de su estado y no son controles del host.
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);Plataformas
Las descargas se compilan para macOS universal (arm64 y x86_64), Linux (x86_64 y aarch64, glibc 2.36 o posterior) y Windows x64 (MSVC). Elige la plataforma al descargar desde la página de tus motores; un agente la pide con platform=linux o platform=windows-x64.
En Windows el zip contiene dos copias de sournd_cabi.lib: lib/windows-x64/ para proyectos con el runtime de C dinámico (/MD, el valor por defecto de MSVC) y lib/windows-x64-static-crt/ para el estático (/MT). Enlaza la que coincida con tu plugin, seguida de kernel32 ntdll userenv ws2_32 dbghelp. El README del zip trae las líneas de CMake.
Licencias
El módulo de JUCE y la cabecera de C son Apache-2.0, así que se enlazan en proyectos de JUCE con GPL o comerciales. JUCE tiene su propia licencia y sus propios planes, que una licencia de sournd no cubre: sigue la licencia de JUCE 8 y elige el plan de JUCE que se ajuste a lo que publicas. Los motores de pago se entregan como bibliotecas estáticas cerradas. Consulta licencias.