Prise en main JUCE
Ajoutez un moteur sournd à un plugin JUCE 8. Trois lignes CMake, trois objets C++, aucune chaîne d'outils Rust sur votre machine.
- Téléchargerle module JUCE et la bibliothèque de votre moteur
- CMaketrois lignes
- Trois objets C++moteur, paramètres, bridge
- Votre plugincompilé par JUCE comme d'habitude
Ce que vous obtenez
sournd_engine, un module JUCE standard qui ne dépend que dejuce_audio_processorsetjuce_dsp(Apache-2.0). Téléchargez-le : sournd-engine-juce-module.zip.- Une bibliothèque statique pour votre plateforme (
libsournd_cabi.a, ousournd_cabi.libsous Windows) et l'en-têtesournd_engine.h: les moteurs gratuits depuis la page de n'importe quel moteur gratuit (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), les moteurs payants depuis Vos moteurs. SourndEngine, qui implémentejuce::dsp::ProcessorBase, etSourndEngineParameters, qui construit une disposition APVTS à partir du moteur et les garde synchronisés.
1. Ajouter le module et la bibliothèque
Décompressez le module pour obtenir un dossier sournd_engine, et décompressez à côté le téléchargement de votre moteur.
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)Pour un plugin macOS universel, compilez avec -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' et liez l'archive universelle.
Sous Linux, le téléchargement contient une archive par architecture. Choisissez celle de la machine pour laquelle vous compilez et ajoutez les bibliothèques système dont elle a besoin :
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. Créer le moteur, ses paramètres et le bridge
Construisez-les dans cet ordre, sur le thread de messages :
#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;
};Ce qui se passe à l'exécution :
À chaque bloc
- Hôteboutons et automation
- APVTSles paramètres de votre plugin
bridge.applyvaleurs modifiées, une fois par blocengine.processlisse échantillon par échantillon- Sortie audio
Enregistrement
- L'hôte demande l'état
getCallbackLock()tientprocessBlockà l'écartbridge.syncToEngine()engine.saveState()un blob opaque
Chargement
- L'hôte rend l'état
getCallbackLock()engine.loadState()associé par identifiant de paramètrebridge.syncFromEngine()
3. Choisir un moteur
Choisissez n'importe quel identifiant dans le catalogue ou catalog.json. Un identifiant inconnu produit un moteur invalide qui sort du silence : vérifiez donc isValid() et lastError().
Règles à connaître
- Les identifiants de paramètre sont des chaînes décimales stables : la position du paramètre dans le manifeste du moteur, affichée sur chaque page de moteur. Les paramètres ne font qu'être ajoutés, jamais renumérotés.
- Les plages côté hôte suivent la courbe de chaque paramètre. Un paramètre logarithmique (cutoff, temps, ratio) fait correspondre le 0 à 1 de l'hôte à
min * (max / min)^p, de sorte que les pistes d'automation et les éditeurs génériques se déplacent par rapports égaux, comme les boutons du moteur lui-même. Si vous avez déjà publié un plugin avec des plages linéaires, passezcreateLayout (engine, false)pour les conserver, car les hôtes enregistrent l'automation sous forme de valeurs de 0 à 1. bridge.applytransmet chaque valeur modifiée au moteur au début du bloc. Le moteur lisse lui-même les commandes continues, échantillon par échantillon, si bien que le son ne dépend pas de la taille de bloc de l'hôte (testé bit à bit à 1, 32, 64 et 512 frames). Les commandes par paliers et booléennes basculent d'un coup.- Le nombre de frames par appel doit respecter le maximum passé à
prepare. Le wrapper ne découpe pas les blocs de l'hôte. - L'état est opaque et lié à l'identifiant du moteur. Il enregistre les réglages, pas l'historique des delays ou des filtres. Il migre d'une version du moteur à l'autre : les valeurs sont associées par identifiant de paramètre, les paramètres ajoutés depuis l'enregistrement de la session prennent leur valeur par défaut, et les valeurs d'un moteur plus récent que celui-ci n'a pas sont ignorées (
lastStateReport()compte les deux cas). Un état n'est refusé, sans rien modifier, que s'il appartient à un autre moteur ou s'il est endommagé. - Le thread audio n'alloue jamais, ne verrouille jamais et n'appelle jamais le gestionnaire de messages. Utilisez une instance de moteur par thread de traitement.
- Les appels vers un même moteur ne doivent pas se chevaucher. Tout ce qui touche le moteur en dehors de
processBlock(enregistrer ou charger l'état,prepare,reset) prendgetCallbackLock(), comme ci-dessus, et ne s'exécute donc jamais pendant le traitement de l'audio.
Limites
Voici les limites actuelles du bridge.
- L'audio est en float 32 bits. Le bridge ne traite que des tampons
float. LaissezsupportsDoublePrecisionProcessing()à sa valeur par défaut (false), pour que les hôtes fournissent à votre plugin de l'audio en float. - Mono ou stéréo, à l'identique en entrée et en sortie. Un ou deux canaux principaux ; le mono vers stéréo, le stéréo vers mono et les configurations surround ne sont pas pris en charge. Certains moteurs ne fonctionnent qu'en stéréo : interrogez donc le moteur dans
isBusesLayoutSupportedplutôt que de le supposer (voir plus bas).supportsChannelsprépare une instance temporaire : mettez la réponse en cache au lieu de l'appeler sur le thread audio. - Les moteurs sidechain acceptent une entrée auxiliaire déconnectée, mono ou stéréo.
- MIDI. Les effets ignorent le tampon MIDI, et le bridge ne produit jamais de MIDI. Les moteurs d'instrument lisent note on, note off et all notes off (CC 120 et 123) à leur position en échantillons, sur tous les canaux ; le pitch bend, l'aftertouch, les autres contrôleurs et le MPE ne sont pas transmis.
- Fréquences d'échantillonnage de 8 kHz à 768 kHz, et jusqu'à 1,048,576 frames par bloc.
- Les paramètres masqués d'un moteur restent dans l'état du moteur et ne sont pas des commandes de l'hôte.
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);Plateformes
Les téléchargements sont compilés pour macOS universel (arm64 et x86_64), Linux (x86_64 et aarch64, glibc 2.36 ou plus récente) et Windows x64 (MSVC). Choisissez la plateforme au moment du téléchargement depuis la page de vos moteurs ; un agent la demande avec platform=linux ou platform=windows-x64.
Sous Windows, le zip contient deux copies de sournd_cabi.lib : lib/windows-x64/ pour les projets avec le runtime C dynamique (/MD, le réglage par défaut de MSVC) et lib/windows-x64-static-crt/ pour le runtime statique (/MT). Liez celle qui correspond à votre plugin, suivie de kernel32 ntdll userenv ws2_32 dbghelp. Le README du zip contient les lignes CMake.
Licences
Le module JUCE et l'en-tête C sont sous Apache-2.0 : ils se lient donc à des projets JUCE sous GPL ou commerciaux. JUCE a sa propre licence et ses propres formules, que la licence sournd ne couvre pas : respectez la licence JUCE 8 et choisissez la formule JUCE adaptée à ce que vous publiez. Les moteurs payants sont livrés en bibliothèques statiques fermées. Voir licences.