sOURnd Docs Vos moteurs
Sur cette page
  1. Ce que vous obtenez
  2. 1. Ajouter le module et la bibliothèque
  3. 2. Créer le moteur, ses paramètres et le bridge
  4. 3. Choisir un moteur
  5. Règles à connaître
  6. Limites
  7. Plateformes
  8. Licences

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.

  1. Téléchargerle module JUCE et la bibliothèque de votre moteur
  2. CMaketrois lignes
  3. Trois objets C++moteur, paramètres, bridge
  4. Votre plugincompilé par JUCE comme d'habitude

Ce que vous obtenez

  • sournd_engine, un module JUCE standard qui ne dépend que de juce_audio_processors et juce_dsp (Apache-2.0). Téléchargez-le : sournd-engine-juce-module.zip.
  • Une bibliothèque statique pour votre plateforme (libsournd_cabi.a, ou sournd_cabi.lib sous Windows) et l'en-tête sournd_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émente juce::dsp::ProcessorBase, et SourndEngineParameters, 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.

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)

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 :

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. Créer le moteur, ses paramètres et le bridge

Construisez-les dans cet ordre, sur le thread de messages :

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

Ce qui se passe à l'exécution :

À chaque bloc

  1. Hôteboutons et automation
  2. APVTSles paramètres de votre plugin
  3. bridge.applyvaleurs modifiées, une fois par bloc
  4. engine.processlisse échantillon par échantillon
  5. Sortie audio

Enregistrement

  1. L'hôte demande l'état
  2. getCallbackLock()tient processBlock à l'écart
  3. bridge.syncToEngine()
  4. engine.saveState()un blob opaque

Chargement

  1. L'hôte rend l'état
  2. getCallbackLock()
  3. engine.loadState()associé par identifiant de paramètre
  4. bridge.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, passez createLayout (engine, false) pour les conserver, car les hôtes enregistrent l'automation sous forme de valeurs de 0 à 1.
  • bridge.apply transmet 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) prend getCallbackLock(), 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. Laissez supportsDoublePrecisionProcessing() à 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 isBusesLayoutSupported plutôt que de le supposer (voir plus bas). supportsChannels pré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.
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);

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.