sOURnd Documentação Suas engines
Nesta página
  1. O que você recebe
  2. 1. Adicione o módulo e a biblioteca
  3. 2. Crie a engine, os parâmetros e a bridge
  4. 3. Escolha uma engine
  5. Regras que vale conhecer
  6. Limites
  7. Plataformas
  8. Licenciamento

Início rápido com JUCE

Adicione uma engine do sournd a um plugin JUCE 8. Três linhas de CMake, três objetos C++, nenhuma toolchain Rust na sua máquina.

  1. Baixaro módulo JUCE e a biblioteca da sua engine
  2. CMaketrês linhas
  3. Três objetos C++engine, parâmetros, bridge
  4. Seu plugincompilado pelo JUCE como de costume

O que você recebe

  • sournd_engine, um módulo JUCE padrão que depende apenas de juce_audio_processors e juce_dsp (Apache-2.0). Baixe-o: sournd-engine-juce-module.zip.
  • Uma biblioteca estática para a sua plataforma (libsournd_cabi.a, ou sournd_cabi.lib no Windows) e o header sournd_engine.h: as engines gratuitas, na página de qualquer engine gratuita (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows); as pagas, em Suas engines.
  • SourndEngine, que implementa juce::dsp::ProcessorBase, e SourndEngineParameters, que monta um layout APVTS a partir da engine e mantém os dois em sincronia.

1. Adicione o módulo e a biblioteca

Descompacte o módulo para ter uma pasta sournd_engine e descompacte o download da sua engine ao lado dela.

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)

Para um plugin universal de macOS, compile com -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' e faça o link com o arquivo universal.

No Linux, o download traz um arquivo por arquitetura. Escolha o da máquina para a qual você compila e adicione as bibliotecas do sistema de que ele precisa:

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. Crie a engine, os parâmetros e a bridge

Construa-os nesta ordem, na thread de mensagens:

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

O que acontece em tempo de execução:

A cada bloco

  1. Hostknobs e automação
  2. APVTSos parâmetros do seu plugin
  3. bridge.applyvalores alterados, uma vez por bloco
  4. engine.processsuaviza sample a sample
  5. Saída de áudio

Salvando

  1. O host pede o estado
  2. getCallbackLock()mantém o processBlock de fora
  3. bridge.syncToEngine()
  4. engine.saveState()um blob opaco

Carregando

  1. O host devolve o estado
  2. getCallbackLock()
  3. engine.loadState()associado pelo id do parâmetro
  4. bridge.syncFromEngine()

3. Escolha uma engine

Escolha qualquer id do catálogo ou do catalog.json. Um id desconhecido produz uma engine inválida que emite silêncio, então verifique isValid() e lastError().

Regras que vale conhecer

  • Os ids de parâmetro são strings decimais estáveis: a posição do parâmetro no manifest da engine, exibida em toda página de engine. Parâmetros só são acrescentados, nunca renumerados.
  • As faixas do host seguem a curva de cada parâmetro. Um parâmetro logarítmico (cutoff, tempo, ratio) mapeia o 0 a 1 do host como min * (max / min)^p, de modo que as pistas de automação e os editores genéricos se movem em razões iguais, como os knobs da própria engine. Se você já lançou um plugin com faixas lineares, passe createLayout (engine, false) para mantê-las, porque os hosts guardam a automação como valores de 0 a 1.
  • bridge.apply entrega cada valor alterado à engine no início do bloco. A própria engine suaviza os controles contínuos, sample a sample, então o som não depende do tamanho de bloco do host (testado bit a bit com 1, 32, 64 e 512 frames). Os controles discretos e booleanos mudam de uma vez.
  • Os frames por chamada têm de caber no máximo passado a prepare. O wrapper não divide os blocos do host.
  • O estado é opaco e ligado ao id da engine. Ele guarda ajustes, não o histórico de delay ou de filtro. Ele migra entre versões da engine: os valores são associados pelo id do parâmetro, os parâmetros acrescentados depois que a sessão foi salva assumem seus padrões, e os valores de uma engine mais nova que esta não tem são ignorados (lastStateReport() conta os dois casos). Um estado só é recusado, sem alterar nada, quando pertence a outra engine ou está danificado.
  • A thread de áudio nunca aloca memória, usa locks nem chama o message manager. Use uma instância de engine por thread de processamento.
  • As chamadas a uma mesma engine não podem se sobrepor. Tudo fora de processBlock que toque a engine (salvar ou carregar o estado, prepare, reset) segura o getCallbackLock(), como acima, para nunca rodar enquanto o áudio é processado.

Limites

Estes são os limites da bridge hoje.

  • O áudio é float de 32 bits. A bridge processa apenas buffers float. Deixe supportsDoublePrecisionProcessing() no padrão (false), para que os hosts entreguem ao seu plugin áudio em float.
  • Mono ou estéreo, igual na entrada e na saída. Um ou dois canais principais; mono para estéreo, estéreo para mono e layouts surround não são suportados. Algumas engines só funcionam em estéreo, então pergunte à engine em isBusesLayoutSupported em vez de presumir (abaixo). supportsChannels prepara uma instância temporária, então guarde a resposta em cache em vez de chamá-la na thread de áudio.
  • As engines com sidechain aceitam uma entrada auxiliar desconectada, mono ou estéreo.
  • MIDI. Os efeitos ignoram o buffer MIDI, e a bridge nunca produz MIDI. As engines de instrumento leem note on, note off e all notes off (CC 120 e 123) nas posições de sample, em todos os canais; pitch bend, aftertouch, outros controladores e MPE não são repassados.
  • Taxas de amostragem de 8 kHz a 768 kHz e até 1,048,576 frames por bloco.
  • Os parâmetros ocultos da engine ficam dentro do estado dela e não são controles do host.
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);

Plataformas

Os downloads são compilados para macOS universal (arm64 e x86_64), Linux (x86_64 e aarch64, glibc 2.36 ou mais recente) e Windows x64 (MSVC). Escolha a plataforma ao baixar na página Suas engines; um agente a pede com platform=linux ou platform=windows-x64.

No Windows, o zip traz duas cópias de sournd_cabi.lib: lib/windows-x64/ para projetos com o runtime C dinâmico (/MD, o padrão do MSVC) e lib/windows-x64-static-crt/ para o estático (/MT). Faça o link com a que combina com o seu plugin, seguida de kernel32 ntdll userenv ws2_32 dbghelp. O README do zip traz as linhas de CMake.

Licenciamento

O módulo JUCE e o header C são Apache-2.0, então podem ser ligados a projetos JUCE GPL ou comerciais. O JUCE em si tem licença e planos próprios, que uma licença do sournd não cobre: siga a licença do JUCE 8 e escolha o plano do JUCE que combina com o que você lança. As engines pagas vêm como bibliotecas estáticas fechadas. Veja licenciamento.