a02d892f831f
scan.rs
//! Finding VST3 plugins on disk (safe, pure `std::fs`), resolving bundles to their binaries and
//! mapping VST3 sub-categories to SoundCraft categories.
use soundcraft_dsp::Category;
use std::path::{Path, PathBuf};
/// Directory recursion limit while scanning (vendors nest folders, never deeply).
const MAX_DEPTH: usize = 8;
/// Upper bound on bundles collected by one scan (hostile or huge folders).
const MAX_BUNDLES: usize = 4096;
/// Upper bound on directory entries visited by one scan.
const MAX_ENTRIES: usize = 100_000;
/// The operating systems whose VST3 bundle layouts we know.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Os {
MacOs,
Windows,
/// Linux and the BSDs (same bundle layout).
Unix,
}
impl Os {
/// The OS this build runs on.
pub fn current() -> Os {
if cfg!(target_os = "macos") {
Os::MacOs
} else if cfg!(windows) {
Os::Windows
} else {
Os::Unix
}
}
}
/// The standard VST3 search locations for this OS (existing or not), followed by every entry of
/// the `VST3_PATH` environment variable.
pub fn default_search_paths() -> Vec<PathBuf> {
default_search_paths_with(Os::current(), |name| std::env::var_os(name), std::env::current_exe().ok())
}
/// [`default_search_paths`] with the environment lookup and executable path injected, so the
/// Windows common-files fallback, `VST3_PATH` and the application-local folders are testable.
fn default_search_paths_with(os: Os, var: impl Fn(&str) -> Option<std::ffi::OsString>, executable: Option<PathBuf>) -> Vec<PathBuf> {
let mut v = search_paths(
os,
var("HOME").map(PathBuf::from),
// A 32-bit process on 64-bit Windows sees the x86 directory in COMMONPROGRAMFILES.
var("COMMONPROGRAMW6432").or_else(|| var("COMMONPROGRAMFILES")).map(PathBuf::from),
var("COMMONPROGRAMFILES(X86)").map(PathBuf::from),
var("LOCALAPPDATA").map(PathBuf::from),
executable,
);
if let Some(cp) = var("VST3_PATH") {
v.extend(std::env::split_paths(&cp).filter(|p| !p.as_os_str().is_empty()));
}
v
}
/// Builds the search list without reading process state, so every OS layout is testable anywhere.
fn search_paths(
os: Os,
home: Option<PathBuf>,
common_program_files: Option<PathBuf>,
common_program_files_x86: Option<PathBuf>,
local_app_data: Option<PathBuf>,
executable: Option<PathBuf>,
) -> Vec<PathBuf> {
let mut v = Vec::new();
match os {
Os::MacOs => {
if let Some(h) = home {
v.push(h.join("Library/Audio/Plug-Ins/VST3"));
}
v.push(PathBuf::from("/Library/Audio/Plug-Ins/VST3"));
v.push(PathBuf::from("/Network/Library/Audio/Plug-Ins/VST3"));
// Standalone binaries have no app bundle; don't scan a directory above their executable.
let contents = executable.as_deref().and_then(Path::parent).filter(|dir| dir.ends_with("Contents/MacOS")).and_then(Path::parent);
if let Some(contents) = contents {
v.push(contents.join("VST3"));
}
}
Os::Windows => {
if let Some(l) = local_app_data {
v.push(l.join("Programs").join("Common").join("VST3"));
}
for c in [common_program_files, common_program_files_x86].into_iter().flatten() {
let path = c.join("VST3");
// Both environment variables can name the same 32-bit common-files directory.
if !v.contains(&path) {
v.push(path);
}
}
if let Some(exe) = executable
&& let Some(app_dir) = exe.parent()
{
v.push(app_dir.join("VST3"));
}
}
Os::Unix => {
// Keep the user/global/application order from Steinberg's Linux plug-in locations.
if let Some(h) = home {
v.push(h.join(".vst3"));
}
v.push(PathBuf::from("/usr/lib64/vst3"));
v.push(PathBuf::from("/usr/lib/vst3"));
v.push(PathBuf::from("/usr/local/lib64/vst3"));
v.push(PathBuf::from("/usr/local/lib/vst3"));
if let Some(exe) = executable
&& let Some(app_dir) = exe.parent()
{
v.push(app_dir.join("vst3"));
}
}
}
v
}
/// True when the path names a VST3 plugin (`*.vst3`, case-insensitive).
pub fn is_vst3_path(p: &Path) -> bool {
p.extension().and_then(std::ffi::OsStr::to_str).is_some_and(|e| e.eq_ignore_ascii_case("vst3"))
}
/// Recursively collects `.vst3` bundles and files under `dirs` (missing directories are skipped).
/// A `.vst3` directory is a bundle and is not descended into. The result is sorted and deduplicated.
pub fn find_bundles(dirs: &[PathBuf]) -> Vec<PathBuf> {
let mut out = Vec::new();
let mut budget = MAX_ENTRIES;
for d in dirs {
if is_vst3_path(d) && d.exists() {
out.push(d.clone());
} else {
walk(d, 0, &mut out, &mut budget);
}
}
out.sort();
out.dedup();
out.truncate(MAX_BUNDLES);
out
}
fn walk(dir: &Path, depth: usize, out: &mut Vec<PathBuf>, budget: &mut usize) {
if depth > MAX_DEPTH || out.len() >= MAX_BUNDLES {
return;
}
let Ok(rd) = std::fs::read_dir(dir) else { return };
for entry in rd.flatten() {
if *budget == 0 || out.len() >= MAX_BUNDLES {
return;
}
*budget -= 1;
let p = entry.path();
// `metadata` follows symlinks (plugins are often symlinked in); errors are skipped.
let Ok(md) = std::fs::metadata(&p) else { continue };
if is_vst3_path(&p) {
out.push(p);
} else if md.is_dir() {
walk(&p, depth + 1, out, budget);
}
}
}
/// The `Contents/<dir>` folder names that hold this machine's binaries, most specific first.
fn arch_dirs(os: Os) -> &'static [&'static str] {
match os {
Os::MacOs => &["MacOS"],
Os::Windows => {
if cfg!(target_arch = "aarch64") {
&["arm64-win", "arm64ec-win", "arm64x-win"]
} else if cfg!(target_arch = "x86") {
&["x86-win"]
} else {
&["x86_64-win"]
}
}
Os::Unix => {
if cfg!(target_arch = "aarch64") {
&["aarch64-linux"]
} else if cfg!(target_arch = "x86") {
&["i386-linux"]
} else {
&["x86_64-linux"]
}
}
}
}
/// The loadable binary of a plugin for this OS: a single-file `.vst3` itself, or inside a bundle
/// directory `Contents/MacOS/<name>` (macOS), `Contents/x86_64-win/<name>.vst3` (Windows) or
/// `Contents/x86_64-linux/<name>.so` (Linux/BSD), falling back to the only/first fitting file there.
pub fn bundle_binary(path: &Path) -> Option<PathBuf> {
bundle_binary_for(Os::current(), path)
}
/// [`bundle_binary`] for a given OS layout (testable everywhere).
pub fn bundle_binary_for(os: Os, path: &Path) -> Option<PathBuf> {
if path.is_file() {
return Some(path.to_path_buf());
}
if !path.is_dir() {
return None;
}
let stem = path.file_stem()?;
let ext = match os {
Os::MacOs => None,
Os::Windows => Some("vst3"),
Os::Unix => Some("so"),
};
for dir in arch_dirs(os) {
let folder = path.join("Contents").join(dir);
let mut named = folder.join(stem);
if let Some(e) = ext {
named.set_extension(e);
}
if named.is_file() {
return Some(named);
}
let Ok(rd) = std::fs::read_dir(&folder) else { continue };
let mut files: Vec<PathBuf> = rd
.flatten()
.map(|e| e.path())
.filter(|p| p.is_file())
.filter(|p| ext.is_none_or(|e| p.extension().and_then(std::ffi::OsStr::to_str).is_some_and(|x| x.eq_ignore_ascii_case(e))))
.take(64)
.collect();
files.sort();
if let Some(f) = files.into_iter().next() {
return Some(f);
}
}
None
}
/// The `|`-separated VST3 sub-category tokens (`"Fx|Reverb"` → `["Fx", "Reverb"]`).
pub fn split_sub_categories(s: &str) -> Vec<String> {
s.split('|').map(str::trim).filter(|t| !t.is_empty()).take(32).map(str::to_string).collect()
}
/// Maps VST3 sub-categories (`Fx|EQ`, `Instrument|Synth`, …) to a SoundCraft insert-menu category.
pub fn category_from_sub_categories<S: AsRef<str>>(subs: &[S]) -> Category {
let has = |names: &[&str]| subs.iter().any(|f| names.iter().any(|n| f.as_ref().eq_ignore_ascii_case(n)));
if is_instrument(subs) {
Category::Instrument
} else if has(&["EQ", "Filter"]) {
Category::Eq
} else if has(&["Dynamics"]) {
Category::Dynamics
} else if has(&["Reverb"]) {
Category::Reverb
} else if has(&["Delay"]) {
Category::Delay
} else if has(&["Modulation"]) {
Category::Modulation
} else if has(&["Distortion"]) {
Category::Harmonic
} else if has(&["Pitch Shift"]) {
Category::PitchShift
} else {
Category::Other
}
}
/// True when the sub-categories mark an instrument (`Instrument`, `Instrument|Synth`, …).
pub fn is_instrument<S: AsRef<str>>(subs: &[S]) -> bool {
subs.first().is_some_and(|f| f.as_ref().eq_ignore_ascii_case("Instrument"))
}
#[cfg(test)]
mod tests {
use super::*;
fn tmp(name: &str) -> PathBuf {
let d = std::env::temp_dir().join(format!("soundcraft-vst3-scan-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
d
}
/// Returns a closure that looks up environment variables from the given pairs, for testing.
fn env_from(pairs: Vec<(&'static str, std::ffi::OsString)>) -> impl Fn(&str) -> Option<std::ffi::OsString> {
move |name| pairs.iter().find(|(key, _)| *key == name).map(|(_, value)| value.clone())
}
#[test]
fn finds_files_and_bundles_recursively_but_not_inside_bundles() {
let d = tmp("find");
std::fs::write(d.join("a.vst3"), b"x").unwrap();
std::fs::write(d.join("readme.txt"), b"x").unwrap();
std::fs::create_dir_all(d.join("vendor/sub")).unwrap();
std::fs::write(d.join("vendor/sub/B.VST3"), b"x").unwrap();
std::fs::create_dir_all(d.join("c.vst3/Contents/MacOS")).unwrap();
std::fs::write(d.join("c.vst3/Contents/MacOS/c"), b"x").unwrap();
std::fs::write(d.join("c.vst3/Contents/inner.vst3"), b"x").unwrap();
let found = find_bundles(&[d.clone(), d.join("missing")]);
let names: Vec<String> = found.iter().map(|p| p.strip_prefix(&d).unwrap().to_string_lossy().replace('\\', "/")).collect();
assert_eq!(names, vec!["a.vst3", "c.vst3", "vendor/sub/B.VST3"]);
assert_eq!(find_bundles(&[d.join("a.vst3")]), vec![d.join("a.vst3")]);
let _ = std::fs::remove_dir_all(&d);
}
#[test]
fn bundles_resolve_per_os_layout() {
let d = tmp("layout");
// macOS
std::fs::create_dir_all(d.join("M.vst3/Contents/MacOS")).unwrap();
std::fs::write(d.join("M.vst3/Contents/MacOS/M"), b"x").unwrap();
std::fs::write(d.join("M.vst3/Contents/MacOS/aaa"), b"x").unwrap();
assert_eq!(bundle_binary_for(Os::MacOs, &d.join("M.vst3")), Some(d.join("M.vst3/Contents/MacOS/M")));
// macOS fallback: first file when the name differs.
std::fs::create_dir_all(d.join("N.vst3/Contents/MacOS")).unwrap();
std::fs::write(d.join("N.vst3/Contents/MacOS/other"), b"x").unwrap();
assert_eq!(bundle_binary_for(Os::MacOs, &d.join("N.vst3")), Some(d.join("N.vst3/Contents/MacOS/other")));
// Windows
let win = arch_dirs(Os::Windows)[0];
std::fs::create_dir_all(d.join(format!("W.vst3/Contents/{win}"))).unwrap();
std::fs::write(d.join(format!("W.vst3/Contents/{win}/W.vst3")), b"x").unwrap();
std::fs::write(d.join(format!("W.vst3/Contents/{win}/helper.dll")), b"x").unwrap();
assert_eq!(bundle_binary_for(Os::Windows, &d.join("W.vst3")), Some(d.join(format!("W.vst3/Contents/{win}/W.vst3"))));
// Linux
let lin = arch_dirs(Os::Unix)[0];
std::fs::create_dir_all(d.join(format!("L.vst3/Contents/{lin}"))).unwrap();
std::fs::write(d.join(format!("L.vst3/Contents/{lin}/notes.txt")), b"x").unwrap();
assert_eq!(bundle_binary_for(Os::Unix, &d.join("L.vst3")), None, "only .so files qualify");
std::fs::write(d.join(format!("L.vst3/Contents/{lin}/Renamed.so")), b"x").unwrap();
assert_eq!(bundle_binary_for(Os::Unix, &d.join("L.vst3")), Some(d.join(format!("L.vst3/Contents/{lin}/Renamed.so"))));
std::fs::write(d.join(format!("L.vst3/Contents/{lin}/L.so")), b"x").unwrap();
assert_eq!(bundle_binary_for(Os::Unix, &d.join("L.vst3")), Some(d.join(format!("L.vst3/Contents/{lin}/L.so"))));
// Single-file plugin, wrong layout, missing.
std::fs::write(d.join("single.vst3"), b"x").unwrap();
assert_eq!(bundle_binary_for(Os::Windows, &d.join("single.vst3")), Some(d.join("single.vst3")));
assert_eq!(bundle_binary_for(Os::Windows, &d.join("M.vst3")), None);
assert_eq!(bundle_binary_for(Os::MacOs, &d.join("nope.vst3")), None);
std::fs::create_dir_all(d.join("Empty.vst3")).unwrap();
assert_eq!(bundle_binary(&d.join("Empty.vst3")), None);
let _ = std::fs::remove_dir_all(&d);
}
#[test]
fn default_paths_are_not_empty() {
assert!(!default_search_paths().is_empty());
}
#[test]
fn macos_paths_cover_documented_locations_in_order() {
let exe = PathBuf::from("/Applications/SoundCraft.app/Contents/MacOS/soundcraft");
let global_and_app = vec![
PathBuf::from("/Library/Audio/Plug-Ins/VST3"),
PathBuf::from("/Network/Library/Audio/Plug-Ins/VST3"),
PathBuf::from("/Applications/SoundCraft.app/Contents/VST3"),
];
let mut with_home = vec![PathBuf::from("/Users/u/Library/Audio/Plug-Ins/VST3")];
with_home.extend(global_and_app.iter().cloned());
assert_eq!(search_paths(Os::MacOs, Some("/Users/u".into()), None, None, None, Some(exe.clone())), with_home);
assert_eq!(search_paths(Os::MacOs, None, None, None, None, Some(exe)), global_and_app);
}
#[test]
fn macos_paths_without_a_bundle_keep_only_standard_directories() {
let globals = vec![PathBuf::from("/Library/Audio/Plug-Ins/VST3"), PathBuf::from("/Network/Library/Audio/Plug-Ins/VST3")];
assert_eq!(search_paths(Os::MacOs, None, None, None, None, None), globals);
for exe in ["/usr/local/bin/soundcraft", "/tmp/MacOS/soundcraft", "/tmp/Contents/bin/soundcraft"] {
assert_eq!(search_paths(Os::MacOs, None, None, None, None, Some(exe.into())), globals);
}
let mut with_home = vec![PathBuf::from("/Users/u/Library/Audio/Plug-Ins/VST3")];
with_home.extend(globals);
assert_eq!(search_paths(Os::MacOs, Some("/Users/u".into()), None, None, None, None), with_home);
}
#[test]
fn windows_paths_cover_documented_locations_in_order() {
let paths = search_paths(
Os::Windows,
None,
Some("D:/Program Files/Common Files".into()),
Some("D:/Program Files (x86)/Common Files".into()),
Some("C:/Users/u/AppData/Local".into()),
Some("D:/SoundCraft/soundcraft.exe".into()),
);
assert_eq!(
paths,
vec![
PathBuf::from("C:/Users/u/AppData/Local/Programs/Common/VST3"),
PathBuf::from("D:/Program Files/Common Files/VST3"),
PathBuf::from("D:/Program Files (x86)/Common Files/VST3"),
PathBuf::from("D:/SoundCraft/VST3"),
]
);
}
#[test]
fn windows_paths_handle_missing_values_and_shared_common_directory() {
assert!(search_paths(Os::Windows, None, None, None, None, None).is_empty());
assert_eq!(
search_paths(Os::Windows, None, None, None, None, Some("C:/SoundCraft/soundcraft.exe".into())),
vec![PathBuf::from("C:/SoundCraft/VST3")]
);
let common = PathBuf::from("C:/Program Files (x86)/Common Files");
assert_eq!(search_paths(Os::Windows, None, Some(common.clone()), Some(common.clone()), None, None), vec![common.join("VST3")]);
assert_eq!(search_paths(Os::Windows, None, None, Some(common.clone()), None, None), vec![common.join("VST3")]);
}
#[test]
fn default_paths_prefer_the_64_bit_windows_common_directory() {
let paths = default_search_paths_with(
Os::Windows,
env_from(vec![
("COMMONPROGRAMW6432", "C:/Program Files/Common Files".into()),
("COMMONPROGRAMFILES", "C:/ignored/Common Files".into()),
("COMMONPROGRAMFILES(X86)", "C:/Program Files (x86)/Common Files".into()),
("LOCALAPPDATA", "C:/Users/u/AppData/Local".into()),
]),
Some("C:/SoundCraft/soundcraft.exe".into()),
);
assert_eq!(
paths,
vec![
PathBuf::from("C:/Users/u/AppData/Local/Programs/Common/VST3"),
PathBuf::from("C:/Program Files/Common Files/VST3"),
PathBuf::from("C:/Program Files (x86)/Common Files/VST3"),
PathBuf::from("C:/SoundCraft/VST3"),
]
);
}
#[test]
fn default_paths_fall_back_to_common_program_files() {
let paths =
default_search_paths_with(Os::Windows, env_from(vec![("COMMONPROGRAMFILES", "C:/Program Files (x86)/Common Files".into())]), None);
assert_eq!(paths, vec![PathBuf::from("C:/Program Files (x86)/Common Files/VST3")]);
}
#[test]
fn default_paths_append_vst3_path_entries() {
let vst3_path = std::env::join_paths(["/opt/one", "/opt/two"]).unwrap();
let paths = default_search_paths_with(
Os::Unix,
env_from(vec![("HOME", "/home/u".into()), ("VST3_PATH", vst3_path)]),
Some("/opt/SoundCraft/soundcraft".into()),
);
assert_eq!(
paths,
vec![
PathBuf::from("/home/u/.vst3"),
PathBuf::from("/usr/lib64/vst3"),
PathBuf::from("/usr/lib/vst3"),
PathBuf::from("/usr/local/lib64/vst3"),
PathBuf::from("/usr/local/lib/vst3"),
PathBuf::from("/opt/SoundCraft/vst3"),
PathBuf::from("/opt/one"),
PathBuf::from("/opt/two"),
]
);
}
#[test]
fn unix_paths_cover_documented_locations_in_order() {
let exe = PathBuf::from("/opt/SoundCraft/soundcraft");
let globals = vec![
PathBuf::from("/usr/lib64/vst3"),
PathBuf::from("/usr/lib/vst3"),
PathBuf::from("/usr/local/lib64/vst3"),
PathBuf::from("/usr/local/lib/vst3"),
];
let mut global_and_app = globals.clone();
global_and_app.push(PathBuf::from("/opt/SoundCraft/vst3"));
let mut with_home = vec![PathBuf::from("/home/u/.vst3")];
with_home.extend(global_and_app.iter().cloned());
assert_eq!(search_paths(Os::Unix, Some("/home/u".into()), None, None, None, Some(exe.clone())), with_home);
assert_eq!(search_paths(Os::Unix, None, None, None, None, Some(exe)), global_and_app);
let mut home_and_globals = vec![PathBuf::from("/home/u/.vst3")];
home_and_globals.extend(globals);
assert_eq!(search_paths(Os::Unix, Some("/home/u".into()), None, None, None, None), home_and_globals);
}
#[test]
fn sub_categories_map_to_categories() {
let c = |s: &str| category_from_sub_categories(&split_sub_categories(s));
assert_eq!(c("Fx|Reverb"), Category::Reverb);
assert_eq!(c("Instrument|Synth"), Category::Instrument);
assert_eq!(c("Fx|Dynamics"), Category::Dynamics);
assert_eq!(c("Fx|EQ"), Category::Eq);
assert_eq!(c("Fx|Filter"), Category::Eq);
assert_eq!(c("Fx|Modulation"), Category::Modulation);
assert_eq!(c("Fx|Distortion"), Category::Harmonic);
assert_eq!(c("Fx|Pitch Shift"), Category::PitchShift);
assert_eq!(c("Fx|Delay"), Category::Delay);
assert_eq!(c("Fx"), Category::Other);
assert_eq!(c(""), Category::Other);
assert_eq!(split_sub_categories(" Fx || Delay |"), vec!["Fx", "Delay"]);
assert!(is_instrument(&split_sub_categories("Instrument|Sampler")));
assert!(!is_instrument(&split_sub_categories("Fx|Instrument")));
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.