scanner.hpp

Go to the documentation of this file.

#pragma once
 
// Plugin Scanner for Pulp Host
// Scans standard system directories for VST3, AU, CLAP, and LV2 plugins.
// Returns a list of PluginInfo descriptors that can be used to load plugins.
//
// Usage:
//   auto scanner = PluginScanner();
//   auto plugins = scanner.scan();
//   for (auto& p : plugins) { ... p.name, p.path, p.format ... }
 
#include <pulp/host/plugin_identity.hpp>
#include <cstdint>
#include <functional>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::host {
 
// ── Plugin format identifier ────────────────────────────────────────────
 
enum class PluginFormat {
    VST3 = 0,
    AudioUnit = 1,   // AU v2 (macOS)
    AudioUnitV3 = 2, // AUv3 (macOS/iOS)
    CLAP = 3,
    LV2 = 4,
    BuiltIn = 5,
};
 
// ── Plugin descriptor from scanning ─────────────────────────────────────
 
struct PluginInfo {
    std::string name;
    std::string manufacturer;
    std::string version;
    std::string path;          // Full path to the plugin bundle/binary
    std::string unique_id;     // Format-specific unique ID (FUID, bundle ID, etc.)
    // Deterministic default: Processor nodes never set it, and the graph
    // serializer writes it, so an indeterminate value broke JSON roundtrips.
    PluginFormat format = PluginFormat::VST3;
    bool is_instrument = false;
    bool is_effect = true;
    int num_inputs = 2;
    int num_outputs = 2;
 
    // Each scanner populates the subset it can cheaply extract. Callers
    // filter plugins on these instead of parsing `name` strings. All
    // fields are additive — older cache blobs that don't carry them
    // deserialize with defaults, so scan_cache.hpp's round-trip stays
    // backwards-compatible.
    //
    // category    — broad taxonomy: "Fx", "Instrument", "Analyzer",
    //               "MidiEffect". Sourced from VST3 PClassInfo::category,
    //               AU AUSysExCategory, CLAP descriptor category.
    // features    — free-form tags (CLAP `features` array, VST3
    //               subcategories joined, AU tag list).
    // description — longer human-readable description if the format
    //               surfaces one; empty otherwise.
    // has_editor  — plugin declares an embedded editor view.
    // supports_sidechain — declares a second input bus.
    // supports_midi_in / supports_midi_out — MIDI wiring.
    std::string category;
    std::vector<std::string> features;
    std::string description;
    bool has_editor = false;
    bool supports_sidechain = false;
    bool supports_midi_in = false;
    bool supports_midi_out = false;
 
    // Optional descriptor capture; legacy/cache metadata alone has no authority.
    std::optional<PluginIdentityEvidence> identity_evidence;
};
 
// ── Scanner configuration ───────────────────────────────────────────────
 
struct ScanOptions {
    bool scan_vst3 = true;
    bool scan_au = true;
    bool scan_clap = true;
    bool scan_lv2 = true;
    std::vector<std::string> extra_paths;  // Additional scan directories
 
    // Restrict scanning to `extra_paths`, skipping the platform defaults.
    // Tests and hermetic tools use this so they never walk a user's installed
    // plugin collection or execute third-party CLAP entry points.
    bool only_extra_paths = false;
 
    // Callback for progress reporting during scan
    using ProgressCallback = std::function<void(const std::string& current_path, int scanned, int total)>;
    ProgressCallback on_progress;
 
    // Optional blacklist of bundle paths the scanner should skip, usually
    // populated from a prior out-of-process scanner crash. When non-null,
    // scan() short-circuits any path reported by ScanBlacklist::is_blacklisted
    // and pushes nothing into the result for it, and an isolated CLAP scan
    // records every bundle whose worker crashed or hung into it. Caller-owned;
    // must outlive scan().
    class ScanBlacklist* blacklist = nullptr;
 
    // CLAP enumeration runs the bundle's `clap_entry` (dlopen + init +
    // factory walk). Each bundle runs in a disposable `pulp-scan-worker`
    // child process, so a bundle that crashes or hangs is reported into
    // `blacklist` instead of taking the scanning process down. Entry points
    // run in this process only when this is true; the worker itself scans
    // this way, and `pulp scan --in-process` exposes it. When it is false and
    // no worker can be found, CLAP enumeration is skipped and ScanReport says
    // so: a host process never runs plugin code it did not ask to run.
    bool in_process_clap = false;
 
    // Worker binary for isolated CLAP scanning. Empty resolves the
    // PULP_SCAN_WORKER environment variable, then `pulp-scan-worker` beside
    // the running executable or in a `bin/` or `tools/scan-worker/` directory
    // above it (see find_scan_worker).
    std::string scan_worker_path;
 
    // Per-bundle budget for the isolated worker; a bundle that exceeds it is
    // recorded as a timeout in `blacklist`.
    int scan_worker_timeout_ms = 5000;
 
    // Optional cache of earlier CLAP scan results keyed by bundle path and
    // file stamp. A bundle whose entry still matches is served from here
    // and never handed to a worker; a bundle the worker enumerates to exactly
    // one descriptor is recorded. With a cache and no worker, cached bundles
    // are still listed; only the uncached ones are skipped. Caller-owned;
    // must outlive scan().
    class HostScanCache* scan_cache = nullptr;
};
 
// What a scan found, and what it refused to do.
struct ScanReport {
    std::vector<PluginInfo> plugins;
    // CLAP enumeration was skipped (except for bundles ScanOptions::scan_cache
    // already knew) because no `pulp-scan-worker` was found and
    // ScanOptions::in_process_clap was false. `error` says where the scanner
    // looked and how to opt into in-process enumeration.
    bool clap_skipped_no_worker = false;
    std::string error;
};
 
// ── Plugin Scanner ──────────────────────────────────────────────────────
 
class PluginScanner {
public:
    PluginScanner() = default;
 
    // Scan all standard plugin directories and return found plugins.
    // This performs I/O and may take seconds on large collections. Anything
    // the scan refused to do is logged; scan_report() returns it as data.
    std::vector<PluginInfo> scan(const ScanOptions& options = {});
    ScanReport scan_report(const ScanOptions& options = {});
 
    // Get default scan paths for a specific format on the current platform
    static std::vector<std::string> default_paths(PluginFormat format);
 
    // Quick check if a specific path looks like a valid plugin bundle
    static bool is_plugin_bundle(const std::string& path, PluginFormat format);
 
    // Enumerate exactly one bundle in this process, with no blacklist and no
    // worker: the in-process half of scanning that `pulp-scan-worker` runs on
    // the parent's behalf. A CLAP bundle runs its entry point here. Returns
    // nothing for an Audio Unit (component discovery has no bundle path) or
    // a path that is not a bundle of `format`.
    static std::vector<PluginInfo> scan_bundle(const std::string& path, PluginFormat format);
 
  private:
    std::vector<PluginInfo> scan_directory(const std::string& dir, PluginFormat format,
                                           const ScanOptions& options,
                                           const class IsolatedPluginScanner* isolated);
    PluginInfo scan_vst3_bundle(const std::string& path);
    PluginInfo scan_clap_bundle(const std::string& path);
    PluginInfo scan_lv2_bundle(const std::string& path);
#ifdef __APPLE__
    std::vector<PluginInfo> scan_audio_units();
#endif
};
 
// Clamp an untrusted CLAP plugin count — a malformed bundle's factory can
// return an absurd value that would make reserve()/iteration throw and abort
// the whole scan. Exposed for testing.
uint32_t cap_clap_plugin_count(uint32_t count) noexcept;
 
// Build a loadable PluginInfo from an Audio Unit component identity of the
// form TYPE:SUBT:MANU (three four-byte OSTypes, e.g. "aumu:Vas7:RoCl").
//
// An AU identity is already the complete loader descriptor — unlike VST3/CLAP
// it carries no filesystem path to resolve — so a caller that knows which
// component it wants does not need discovery at all. Scanning to reach a known
// component means walking every installed plugin, which is slow and exposes
// the caller to unrelated third-party bundles that instantiate badly.
//
// Returns false and leaves `info` untouched when the string is not a
// well-formed identity, so callers can fall back to scanning for other formats.
// Only the four component types Pulp can host are accepted: `aumu` (MIDI
// instrument), `augn` (no-input generator), and `aufx`/`aumf` (effects).
bool plugin_info_from_au_identity(std::string_view identity, PluginInfo& info);
 
} // namespace pulp::host