sOURnd Документація Ваші рушії
На цій сторінці
  1. Що ви отримуєте
  2. 1. Додайте модуль і бібліотеку
  3. 2. Створіть рушій, його параметри та міст
  4. 3. Виберіть рушій
  5. Правила, які варто знати
  6. Обмеження
  7. Платформи
  8. Ліцензування

Швидкий старт із JUCE

Додайте рушій sournd до плагіна JUCE 8. Три рядки CMake, три об'єкти C++, жодного інструментарію Rust на вашому комп'ютері.

  1. Завантажитимодуль JUCE і бібліотека вашого рушія
  2. CMakeтри рядки
  3. Три об'єкти C++рушій, параметри, міст
  4. Ваш плагінзбирається JUCE як завжди

Що ви отримуєте

  • sournd_engine: стандартний модуль JUCE, що залежить лише від juce_audio_processors і juce_dsp (Apache-2.0). Завантажте його: sournd-engine-juce-module.zip.
  • Статична бібліотека для вашої платформи (libsournd_cabi.a або sournd_cabi.lib у Windows) і заголовок sournd_engine.h: безкоштовні рушії зі сторінки будь-якого безкоштовного рушія (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), платні зі сторінки «Ваші рушії».
  • SourndEngine, що реалізує juce::dsp::ProcessorBase, і SourndEngineParameters, що будує розкладку APVTS із рушія та тримає їх синхронними.

1. Додайте модуль і бібліотеку

Розпакуйте модуль, щоб мати теку sournd_engine, і розпакуйте завантаження вашого рушія поруч.

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)

Для універсального плагіна macOS збирайте з -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' і підключайте універсальний архів.

У Linux завантаження містить по одному архіву на архітектуру. Виберіть той, що відповідає машині, для якої ви збираєте, і додайте потрібні йому системні бібліотеки:

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. Створіть рушій, його параметри та міст

Створюйте їх у такому порядку, у потоці повідомлень:

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

Що відбувається під час роботи:

Кожен блок

  1. Хостручки й автоматизація
  2. APVTSпараметри вашого плагіна
  3. bridge.applyзмінені значення, раз на блок
  4. engine.processзгладжує семпл за семплом
  5. Вихід звуку

Збереження

  1. Хост запитує стан
  2. getCallbackLock()не пускає processBlock
  3. bridge.syncToEngine()
  4. engine.saveState()непрозорий блок даних

Завантаження

  1. Хост повертає стан
  2. getCallbackLock()
  3. engine.loadState()зіставлення за ідентифікатором параметра
  4. bridge.syncFromEngine()

3. Виберіть рушій

Виберіть будь-який ідентифікатор із каталогу або catalog.json. Невідомий ідентифікатор створює недійсний рушій, який видає тишу, тож перевіряйте isValid() і lastError().

Правила, які варто знати

  • Ідентифікатори параметрів: стабільні десяткові рядки, тобто позиція параметра в маніфесті рушія, яку показано на сторінці кожного рушія. Параметри лише додаються, їх ніколи не перенумеровують.
  • Діапазони хоста відповідають кривій кожного параметра. Логарифмічний параметр (cutoff, час, ratio) відображає 0–1 хоста як min * (max / min)^p, тож доріжки автоматизації й універсальні редактори рухаються рівними відношеннями, як і власні ручки рушія. Якщо ви вже випустили плагін із лінійними діапазонами, передайте createLayout (engine, false), щоб їх зберегти, адже хости зберігають автоматизацію як значення від 0 до 1.
  • bridge.apply передає рушію кожне змінене значення на початку блоку. Рушій сам згладжує неперервні регулятори семпл за семплом, тож звук не залежить від розміру блоку хоста (перевірено біт у біт на 1, 32, 64 і 512 кадрах). Крокові та булеві регулятори перемикаються стрибком.
  • Кількість кадрів на виклик має вміщатися в максимум, переданий до prepare. Обгортка не ділить блоки хоста.
  • Стан непрозорий і прив'язаний до ідентифікатора рушія. Він зберігає налаштування, а не історію delay чи фільтрів. Він переноситься між версіями рушія: значення зіставляються за ідентифікатором параметра, параметри, додані після збереження сесії, отримують типові значення, а значення з новішого рушія, яких немає в цьому, ігноруються (lastStateReport() рахує і те, і те). Стан відхиляється, нічого не змінюючи, лише коли він належить іншому рушію або пошкоджений.
  • Аудіопотік ніколи не виділяє пам'ять, не блокує і не викликає менеджер повідомлень. Використовуйте один екземпляр рушія на кожен потік обробки.
  • Виклики одного рушія не повинні перекриватися. Усе поза processBlock, що торкається рушія (збереження чи завантаження стану, prepare, reset), тримає getCallbackLock(), як вище, тож ніколи не виконується під час обробки звуку.

Обмеження

Ось нинішні межі моста.

  • Звук у 32-бітному float. Міст обробляє лише буфери float. Залиште supportsDoublePrecisionProcessing() за замовчуванням (false), щоб хости передавали вашому плагіну звук у float.
  • Моно або стерео, однаково на вході й виході. Один або два основні канали; моно в стерео, стерео в моно та просторові розкладки не підтримуються. Деякі рушії працюють лише в стерео, тож питайте рушій у isBusesLayoutSupported, а не припускайте (нижче). supportsChannels готує тимчасовий екземпляр, тож кешуйте відповідь замість того, щоб викликати її в аудіопотоці.
  • Рушії з sidechain приймають непідключений, моно або стерео допоміжний вхід.
  • MIDI. Ефекти ігнорують буфер MIDI, а міст ніколи не створює MIDI. Рушії-інструменти читають note on, note off і all notes off (CC 120 і 123) у їхніх позиціях семплів на кожному каналі; pitch bend, aftertouch, інші контролери та MPE не передаються.
  • Частоти дискретизації від 8 kHz до 768 kHz і до 1 048 576 кадрів на блок.
  • Приховані параметри рушія залишаються всередині його стану й не є регуляторами хоста.
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);

Платформи

Завантаження збираються для macOS universal (arm64 і x86_64), Linux (x86_64 і aarch64, glibc 2.36 або новіша) і Windows x64 (MSVC). Платформу вибирають під час завантаження зі сторінки ваших рушіїв; агент запитує її через platform=linux або platform=windows-x64.

У Windows архів містить дві копії sournd_cabi.lib: lib/windows-x64/ для проєктів із динамічним C runtime (/MD, типове для MSVC) і lib/windows-x64-static-crt/ для статичного (/MT). Підключіть ту, що відповідає вашому плагіну, а після неї kernel32 ntdll userenv ws2_32 dbghelp. Рядки CMake є в README в архіві.

Ліцензування

Модуль JUCE і заголовок C мають ліцензію Apache-2.0, тож їх можна підключати до проєктів JUCE під GPL або комерційних. Сам JUCE має власну ліцензію і плани, яких ліцензія sournd не покриває: дотримуйтеся ліцензії JUCE 8 і виберіть план JUCE, що відповідає тому, що ви випускаєте. Платні рушії постачаються як закриті статичні бібліотеки. Див. ліцензування.