sOURnd Dokumentasi Engine Anda
Di halaman ini
  1. Yang Anda dapatkan
  2. 1. Tambahkan modul dan pustaka
  3. 2. Buat engine, parameternya, dan bridge
  4. 3. Pilih engine
  5. Aturan yang perlu diketahui
  6. Batasan
  7. Platform
  8. Lisensi

Panduan cepat JUCE

Tambahkan engine sournd ke plugin JUCE 8. Tiga baris CMake, tiga objek C++, tanpa toolchain Rust di komputer Anda.

  1. Unduhmodul JUCE dan pustaka engine Anda
  2. CMaketiga baris
  3. Tiga objek C++engine, parameter, bridge
  4. Plugin Andadibangun JUCE seperti biasa

Yang Anda dapatkan

  • sournd_engine, modul JUCE standar yang hanya bergantung pada juce_audio_processors dan juce_dsp (Apache-2.0). Unduh: sournd-engine-juce-module.zip.
  • Pustaka statis untuk platform Anda (libsournd_cabi.a, atau sournd_cabi.lib di Windows) dan header sournd_engine.h: engine gratis dari halaman engine gratis mana pun (https://sournd.com/download/free/macos, https://sournd.com/download/free/linux, https://sournd.com/download/free/windows), engine berbayar dari Engine Anda.
  • SourndEngine, yang mengimplementasikan juce::dsp::ProcessorBase, dan SourndEngineParameters, yang membangun layout APVTS dari engine dan menjaga keduanya tetap selaras.

1. Tambahkan modul dan pustaka

Ekstrak modul sehingga Anda memiliki folder sournd_engine, dan ekstrak unduhan engine Anda di sebelahnya.

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)

Untuk plugin macOS universal, bangun dengan -DCMAKE_OSX_ARCHITECTURES='arm64;x86_64' dan tautkan arsip universalnya.

Di Linux, unduhan berisi satu arsip per arsitektur. Pilih yang sesuai dengan mesin tujuan build Anda dan tambahkan pustaka sistem yang diperlukannya:

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. Buat engine, parameternya, dan bridge

Buat objek-objek ini dengan urutan berikut, di thread pesan:

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

Yang terjadi saat berjalan:

Setiap blok

  1. Hostknob dan otomasi
  2. APVTSparameter plugin Anda
  3. bridge.applynilai yang berubah, sekali per blok
  4. engine.processdihaluskan sampel demi sampel
  5. Audio keluar

Menyimpan

  1. Host meminta state
  2. getCallbackLock()menahan processBlock agar tidak berjalan
  3. bridge.syncToEngine()
  4. engine.saveState()blob buram

Memuat

  1. Host menyerahkan kembali state
  2. getCallbackLock()
  3. engine.loadState()dicocokkan berdasarkan id parameter
  4. bridge.syncFromEngine()

3. Pilih engine

Pilih id apa pun dari katalog atau catalog.json. Id yang tidak dikenal menghasilkan engine tidak valid yang mengeluarkan keheningan, jadi periksa isValid() dan lastError().

Aturan yang perlu diketahui

  • Id parameter adalah string desimal yang stabil: posisi parameter di manifes engine, ditampilkan di setiap halaman engine. Parameter hanya ditambahkan, tidak pernah dinomori ulang.
  • Rentang host mengikuti taper setiap parameter. Parameter logaritmik (cutoff, waktu, rasio) memetakan 0 sampai 1 dari host sebagai min * (max / min)^p, sehingga jalur otomasi dan editor generik bergerak dalam rasio yang sama, seperti knob milik engine itu sendiri. Jika Anda sudah merilis plugin dengan rentang linear, berikan createLayout (engine, false) untuk mempertahankannya, karena host menyimpan otomasi sebagai nilai 0 sampai 1.
  • bridge.apply menyerahkan setiap nilai yang berubah ke engine di awal blok. Engine menghaluskan kontrol kontinu sendiri, sampel demi sampel, sehingga suara tidak bergantung pada ukuran blok host (diuji bit demi bit pada 1, 32, 64, dan 512 frame). Kontrol bertahap dan boolean langsung berpindah.
  • Jumlah frame per panggilan harus muat dalam batas maksimum yang diberikan ke prepare. Pembungkus tidak memecah blok host.
  • State bersifat buram dan terikat pada id engine. State menyimpan pengaturan, bukan riwayat delay atau filter. State bermigrasi antarversi engine: nilai dicocokkan berdasarkan id parameter, parameter yang ditambahkan sejak sesi disimpan memakai nilai bawaannya, dan nilai dari engine yang lebih baru yang tidak dimiliki engine ini diabaikan (lastStateReport() menghitung keduanya). State hanya ditolak, tanpa mengubah apa pun, jika milik engine lain atau rusak.
  • Thread audio tidak pernah mengalokasikan memori, mengunci, atau memanggil message manager. Gunakan satu instans engine per thread pemrosesan.
  • Panggilan ke satu engine tidak boleh saling tumpang tindih. Apa pun di luar processBlock yang menyentuh engine (menyimpan atau memuat state, prepare, reset) memegang getCallbackLock(), seperti di atas, sehingga tidak pernah berjalan saat audio sedang diproses.

Batasan

Inilah batas-batas bridge saat ini.

  • Audio berupa float 32-bit. Bridge hanya memproses buffer float. Biarkan supportsDoublePrecisionProcessing() pada nilai bawaannya (false), sehingga host menyerahkan audio float ke plugin Anda.
  • Mono atau stereo, sama pada masukan dan keluaran. Satu atau dua kanal utama; mono ke stereo, stereo ke mono, dan layout surround tidak didukung. Beberapa engine hanya berjalan dalam stereo, jadi tanyakan kepada engine di isBusesLayoutSupported daripada berasumsi (di bawah). supportsChannels menyiapkan instans sementara, jadi simpan jawabannya di cache daripada memanggilnya di thread audio.
  • Engine sidechain menerima masukan tambahan yang tidak tersambung, mono, atau stereo.
  • MIDI. Efek mengabaikan buffer MIDI, dan bridge tidak pernah menghasilkan MIDI. Engine instrumen membaca note on, note off, dan all notes off (CC 120 dan 123) pada posisi sampelnya, di setiap kanal; pitch bend, aftertouch, kontroler lain, dan MPE tidak diteruskan.
  • Sample rate dari 8 kHz sampai 768 kHz, dan hingga 1,048,576 frame per blok.
  • Parameter engine yang tersembunyi tetap berada di dalam state engine dan bukan kontrol 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);

Platform

Unduhan dibangun untuk macOS universal (arm64 dan x86_64), Linux (x86_64 dan aarch64, glibc 2.36 atau lebih baru), dan Windows x64 (MSVC). Pilih platform saat mengunduh dari halaman engine Anda; agen memintanya dengan platform=linux atau platform=windows-x64.

Di Windows, zip berisi dua salinan sournd_cabi.lib: lib/windows-x64/ untuk proyek dengan runtime C dinamis (/MD, bawaan MSVC) dan lib/windows-x64-static-crt/ untuk yang statis (/MT). Tautkan yang sesuai dengan plugin Anda, diikuti kernel32 ntdll userenv ws2_32 dbghelp. README di dalam zip memuat baris CMake-nya.

Lisensi

Modul JUCE dan header C berlisensi Apache-2.0, sehingga bisa ditautkan ke proyek JUCE GPL maupun komersial. JUCE sendiri memiliki lisensi dan paketnya sendiri, yang tidak dicakup lisensi sournd: ikuti lisensi JUCE 8 dan pilih paket JUCE yang sesuai dengan apa yang Anda rilis. Engine berbayar dikirim sebagai pustaka statis tertutup. Lihat lisensi.