>_EXECUTIVE SUMMARY
zpwr-crate is the shared sample-library crate browser of the MenkeTechnologies audio stack — one Rust source of truth for filesystem + SQLite/FTS5 scanning and the faceted query layer. The scanner, schema and query code were lifted verbatim from the Audio-Haxor backend (src-tauri/src/) with the Tauri glue stripped, then extended with additional library scanners (plugins, MIDI, video, PDF/preset metadata) over the same schema.
It builds three crate-types from one source: an rlib linked natively by Audio-Haxor, and a staticlib / cdylib linked over a hand-written C ABI by the JUCE-based zpwr-daw. Both run byte-for-byte identical indexing and browsing against the same database.
~ARCHITECTURE
One library, two link models. The Rust side owns scan / index / browse; consumers attach either natively or over the C ABI. JSON crosses the C boundary; rusqlite is bundled so no system SQLite is required.
| Layer | Implementation |
|---|---|
| Scan | parallel rayon walk; header parse + symphonia decode for duration / channels / sample-rate / bit-depth; symlink + firmlink dedup; build/cache dir skipping; per-directory mtime incremental rescans |
| Index | SQLite WAL with a writer + round-robin read pool (sized from num_cpus); contentless FTS5 trigram table linked to audio_samples.id; a REGEXP user function over a cached regex::Regex map |
| Browse | crate_query faceted filter (category incl. parent node, pack, manufacturer, BPM, key, loop/one-shot, favorites, LIKE/regex search, pagination) plus facets + category counts |
| Native consumer | Audio-Haxor links the rlib and calls Database / scan directly |
| C ABI consumer | zpwr-daw links libzpwr_crate.a (or the cdylib); 19 crate_* exports, JSON params/results, declared in hand-written include/zpwr_crate.h |
| Build | Cargo with crate-type = ["rlib", "staticlib", "cdylib"], publish = false; Linux x86_64 + macOS aarch64 in CI |
&C ABI SURFACE
19 #[no_mangle] extern "C" exports, declared in include/zpwr_crate.h (no cbindgen). Structured data crosses as UTF-8 JSON; every returned char* is freed with crate_string_free, handles with crate_free.
| Export | Role |
|---|---|
crate_open / crate_free | open a database handle; release it |
crate_string_free | free any char* a crate_* function returned |
crate_scan / crate_scan_unified | scan + index sample roots; unified incremental driver across domains |
crate_scan_plugins / crate_scan_midi / crate_scan_video | scan installed plugins / MIDI files / video assets into the library |
crate_query | faceted browse — JSON params in, JSON result out |
crate_browse_query / crate_browse_facets | unified-browser query + facets across domains, as JSON |
crate_facets / crate_category_counts | filter-bar facets; category histogram, as JSON |
crate_genre_rules_report | genre-rules report as JSON |
crate_favorite_list / crate_favorite_toggle | read / toggle favorited pack ids |
crate_waveform_peaks | min/max peak envelope for a sample at a given width, as JSON |
crate_loop_region_get / crate_loop_region_set | read / store a sample's loop region |
/SCHEMA COMPATIBILITY
The schema is built by 15 versioned migrations — v1 / v2 / v6 / v8 / v9 / v10 / v12 / v14 / v15 / v16 / v17 / v20 / v24 / v27 / v28; the subset v1 / v9 / v10 / v12 / v14 / v24 / v27 is aligned with Audio-Haxor, so opening an existing Audio-Haxor database is a no-op — it is already past those versions. audio_samples_fts is a contentless FTS5 trigram table linked to audio_samples.id; a WAL journal plus a writer + round-robin read pool keep reads from blocking on the writer. The per-sample sample_analysis pipeline (BPM/key parse, category + pack/manufacturer assignment) is separate; this crate owns the schema + read/browse side and creates the analysis tables so browser joins resolve.
$CI GATES
| Gate | Command |
|---|---|
| fmt | cargo fmt --all --check |
| clippy | cargo clippy --all-targets -- -D warnings |
| doc | RUSTDOCFLAGS=-D warnings cargo doc --no-deps |
| test | cargo test --verbose (headless; scans temp dirs, exercises the query layer) |
The umbrella MenkeTechnologiesMeta repo additionally pins this crate's metadata across its gate suite — LICENSE present + canonical MIT text, authors/repository/homepage fields, and the four polish gates above.
#PROJECT METADATA
| Item | Value |
|---|---|
| Version | 0.1.0 |
| License | MIT |
| Crate types | rlib + staticlib + cdylib (publish = false) |
| Core deps | rusqlite (bundled, FTS5), symphonia, rayon, regex, serde, serde_json, chrono, dirs, dashmap, num_cpus, libc, plist, lopdf |
| Consumers | Audio-Haxor (rlib), zpwr-daw (C ABI) |
| Author | MenkeTechnologies |
| Repository | github.com/MenkeTechnologies/zpwr-crate |
| Meta umbrella | MenkeTechnologiesMeta |