Panduan cepat JUCE
Tambahkan engine sournd ke plugin JUCE 8. Tiga baris CMake, tiga objek C++, tanpa toolchain Rust di komputer Anda.
- Unduhmodul JUCE dan pustaka engine Anda
- CMaketiga baris
- Tiga objek C++engine, parameter, bridge
- Plugin Andadibangun JUCE seperti biasa
Yang Anda dapatkan
sournd_engine, modul JUCE standar yang hanya bergantung padajuce_audio_processorsdanjuce_dsp(Apache-2.0). Unduh: sournd-engine-juce-module.zip.- Pustaka statis untuk platform Anda (
libsournd_cabi.a, atausournd_cabi.libdi Windows) dan headersournd_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 mengimplementasikanjuce::dsp::ProcessorBase, danSourndEngineParameters, 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.
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:
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:
#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
- Hostknob dan otomasi
- APVTSparameter plugin Anda
bridge.applynilai yang berubah, sekali per blokengine.processdihaluskan sampel demi sampel- Audio keluar
Menyimpan
- Host meminta state
getCallbackLock()menahanprocessBlockagar tidak berjalanbridge.syncToEngine()engine.saveState()blob buram
Memuat
- Host menyerahkan kembali state
getCallbackLock()engine.loadState()dicocokkan berdasarkan id parameterbridge.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, berikancreateLayout (engine, false)untuk mempertahankannya, karena host menyimpan otomasi sebagai nilai 0 sampai 1. bridge.applymenyerahkan 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
processBlockyang menyentuh engine (menyimpan atau memuat state,prepare,reset) memeganggetCallbackLock(), 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. BiarkansupportsDoublePrecisionProcessing()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
isBusesLayoutSupporteddaripada berasumsi (di bawah).supportsChannelsmenyiapkan 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.
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.