Skip to content
RESONON

The Plugin Database

A DAW keeps a database of the plugins installed on the machine, so that choosing one is a lookup rather than a search of your disk. Resonon does the same. This page explains how that database is kept up to date, and why it treats a misbehaving plugin the way it does.

The database maintains itself

Section titled “The database maintains itself”

Every run that starts the audio engine — running a file, the REPL, a server — sweeps the CLAP and VST3 folders in the background and opens only bundles that are new or have changed since last time. The sweep after installing one plugin costs one plugin, not your whole folder, so you rarely think about it.

The folders swept are the standard ones for your OS, CLAP_PATH and VST3_PATH, and every [folders] plugins entry in ~/.resonon/preferences.toml (Plugin folders). Those entries are read before the sweep starts, so a folder of your own is swept from the first run. That is the reason the folder list is data rather than a function call: a call runs only once a session is executing code, which is after the sweep it needed to reach.

Scanning runs third-party code, and you may prefer to say when that happens. Automatic sweeping can be switched off — see Use a Plugin. A plugin named by path or filename still resolves without any sweep; only lookup by display name depends on the database.

A name is resolved where you write it

Section titled “A name is resolved where you write it”

Effect(...) and Instrument(...) resolve the plugin name on the constructor line: a full path, then a filename in your plugin folders, then a display name from the database. CLAP is tried before VST3.

There is no format preference. With both a CLAP and a VST3 build of the same plugin installed, the piece says which one it means:

Instrument("Diva");             // CLAP if there is one, VST3 otherwise
Instrument("Diva", plugin_id);  // exactly this build, recorded in the piece

Which binary loads changes the sound, so it belongs in the piece rather than in a machine-wide setting that would make the same code play differently in two places. With only one format installed there is nothing to say.

A bundle the database has never seen — or one that changed on disk since it was recorded — is scanned right then, and your code waits for it: normally a moment, at most the scan timeout. The result is remembered, so it is a once-per-bundle cost.

Scanning is isolated

Section titled “Scanning is isolated”

A plugin can crash while merely being loaded. So each bundle is opened in a separate process, and a crash takes down that process instead of your session. A bundle that crashes or fails to load is recorded and skipped from then on, so it can’t break later scans — which also means it doesn’t appear in plugin_scan() or resolve in Effect().

Setting RESONON_SUBPROCESS_SCAN=0 scans inside resonon itself, which is useful for debugging a plugin — you see it fail in place, with a stack trace. It is exactly the isolation described here turned off, so a bad bundle then takes the session down with it.

A timeout is provisional

Section titled “A timeout is provisional”

A bundle that goes 30 seconds without finishing is a weaker case than a crash. It might be hanging; it might equally be a plugin on a cold network volume, a machine that was thrashing, or an antivirus scanning the file for the first time. So the scan process is killed and the sweep carries on, but the verdict is provisional: the next ordinary sweep opens the bundle again, and only after three timeouts in a row on the same build is it skipped. A plugin that was merely unlucky comes back with nothing asked of you.

Time that resonon spent suspended doesn’t count. Stopping a scan with Ctrl-Z, or putting the machine to sleep mid-sweep, does not spend a plugin’s budget, so it can’t cost a working plugin its place.

A skipped plugin comes back when it changes

Section titled “A skipped plugin comes back when it changes”

A skipped bundle is skipped as it is on disk. Updating or reinstalling the plugin is enough to bring it back: the next ordinary sweep sees a new build and opens it. Retrying the same build — after a crash that was really the machine running out of memory, say — is an explicit act, one bundle at a time or all of them with a forced sweep.

Section titled “Related”