| 1 |
# audiofiles |
| 2 |
|
| 3 |
A sample manager with content-addressed storage and a virtual file system. Standalone desktop app built with [Rust](https://www.rust-lang.org/), [egui](https://github.com/emilk/egui), and [SQLite](https://sqlite.org/). |
| 4 |
|
| 5 |
## Prerequisites |
| 6 |
|
| 7 |
- **[Rust](https://www.rust-lang.org/)** (stable toolchain, 2024 edition) |
| 8 |
|
| 9 |
No platform-specific audio libraries are required. Audio decoding uses [Symphonia](https://github.com/pdeljanov/Symphonia) (pure Rust), SQLite is bundled via [rusqlite](https://github.com/rusqlite/rusqlite), and the standalone app uses [cpal](https://github.com/RustAudio/cpal) for system audio output. |
| 10 |
|
| 11 |
## Build and Run |
| 12 |
|
| 13 |
```sh |
| 14 |
# Standalone app |
| 15 |
cargo run -p audiofiles-app |
| 16 |
|
| 17 |
# Standalone app -- import a folder on launch |
| 18 |
cargo run -p audiofiles-app -- /path/to/samples |
| 19 |
|
| 20 |
# Run all workspace tests |
| 21 |
cargo test --workspace |
| 22 |
|
| 23 |
# Train the ML classifier (developers only) |
| 24 |
cargo run -p audiofiles-train -- /path/to/training-data |
| 25 |
``` |
| 26 |
|
| 27 |
## Workspace Architecture |
| 28 |
|
| 29 |
Six crates: |
| 30 |
|
| 31 |
|
| 32 |
|
| 33 |
| `audiofiles-core` | `crates/audiofiles-core/` | Domain library. SQLite database, content-addressed store (SHA-256), audio decoding (Symphonia), analysis pipeline (loudness, BPM, key, spectral, classification), VFS, tag system, VP-tree similarity index. | |
| 34 |
| `audiofiles-browser` | `crates/audiofiles-browser/` | Shared egui UI. File list, detail panel, waveform display, search/filter, import wizard, analysis progress, export, themes. | |
| 35 |
| `audiofiles-app` | `crates/audiofiles-app/` | Standalone desktop app via eframe. System audio (cpal), drag-and-drop import, native drag-out to Finder/DAWs, system tray, CLI import, OTA updates. | |
| 36 |
| `audiofiles-sync` | `crates/audiofiles-sync/` | Cloud sync via SyncKit. Pushes/pulls sample metadata, tags, and VFS structure across devices. E2E encrypted. | |
| 37 |
| `audiofiles-rhai` | `crates/audiofiles-rhai/` | Rhai scripting engine for device export profiles. Transforms sample metadata and file layout for hardware samplers. | |
| 38 |
| `audiofiles-train` | `crates/audiofiles-train/` | ML classifier training binary. Builds the random forest model from labeled sample data. Not shipped in the app. | |
| 39 |
|
| 40 |
Dependency flow: `audiofiles-core` is the leaf -> `audiofiles-rhai` and `audiofiles-sync` depend on core -> `audiofiles-browser` depends on core, sync, and rhai -> `audiofiles-app` depends on browser and core. `audiofiles-train` depends on core only. |
| 41 |
|
| 42 |
Shared libraries from `../../MNW/shared/`: [theme-common](../../MNW/shared/theme-common/) (theme loading), [synckit-client](../../MNW/shared/synckit-client/) (cloud sync SDK). |
| 43 |
|
| 44 |
## Features |
| 45 |
|
| 46 |
### Storage & Organization |
| 47 |
- **Content-addressed storage** -- samples stored by SHA-256 hash, automatic deduplication |
| 48 |
- **Virtual file system** -- organize samples in virtual directories independent of disk location, multiple VFS roots |
| 49 |
- **Tag system** -- hierarchical dot-notation tags with auto-suggestions from analysis results |
| 50 |
- **Smart folders** -- saved filter queries that update dynamically |
| 51 |
- **Collections** -- cross-VFS sample groupings |
| 52 |
|
| 53 |
### Audio Analysis |
| 54 |
- **Analysis pipeline** -- loudness (peak/RMS/LUFS), BPM detection, key detection, spectral analysis |
| 55 |
- **ML classification** -- two-layer system: rule-based broad categories, then 200-tree random forest for drum sub-classification (94.4% accuracy on 4,343 samples) |
| 56 |
- **Loop detection** -- identifies seamless loops via amplitude envelope analysis |
| 57 |
- **Similarity search** -- VP-tree indexed fingerprinting for finding similar and duplicate samples (O(log n) lookup) |
| 58 |
- **Waveform display** -- pre-computed peak data with click-to-seek playback |
| 59 |
|
| 60 |
### Search & Filtering |
| 61 |
- **Text search** -- FTS5 indexed across filenames, tags, and metadata |
| 62 |
- **Parameter filters** -- BPM range, duration range, key selector, classification category |
| 63 |
- **Tag prefix matching** -- type a tag prefix to filter by hierarchy |
| 64 |
|
| 65 |
### Editing |
| 66 |
- **Destructive editing** -- trim, fade in/out, normalize, reverse, gain adjust |
| 67 |
- **Edit history** -- full undo/redo stack per sample |
| 68 |
- **Bulk operations** -- bulk delete, move, rename, tag across selections |
| 69 |
- **Rename engine** -- pattern-based renaming with tokens (name, bpm, key, index, etc.) |
| 70 |
|
| 71 |
### Device Export |
| 72 |
- **Rhai export profiles** -- scriptable export for 14 hardware samplers: |
| 73 |
M8, Digitakt, Digitakt II, Octatrack, Model:Samples, SP-404 MKII, MPC, Polyend Tracker, Deluge, Blackbox, Volca Sample 2, OP-1, Circuit Rhythm, Maschine+ |
| 74 |
|
| 75 |
### Playback & Integration |
| 76 |
- **MIDI instrument** -- chromatic and multi-sample playback modes with 8-voice polyphony and ADSR envelopes |
| 77 |
- **Native drag-out** -- drag samples from the file list directly to Finder, Desktop, or any DAW (macOS + Windows) |
| 78 |
- **System tray** -- minimize to tray, quick access |
| 79 |
|
| 80 |
### Infrastructure |
| 81 |
- **Cloud sync** -- cross-device sync of metadata, tags, and VFS via SyncKit (E2E encrypted, ChaCha20-Poly1305 + Argon2) |
| 82 |
- **OTA updates** -- background update checker with consent dialog |
| 83 |
- **Bundled themes** -- dark, light, and high-contrast variants in TOML format (see `crates/audiofiles-browser/themes/`) |
| 84 |
- **Audio formats** -- WAV, FLAC, MP3, OGG, AIFF (via Symphonia, pure Rust) |
| 85 |
- **Platforms** -- macOS, Windows, Linux (standalone, no backend required) |
| 86 |
|
| 87 |
## Key Paths |
| 88 |
|
| 89 |
|
| 90 |
|
| 91 |
| Domain library | `crates/audiofiles-core/src/` | |
| 92 |
| ML classifier model | `crates/audiofiles-core/models/layer2_drum.json` | |
| 93 |
| Training binary | `crates/audiofiles-train/` | |
| 94 |
| UI components | `crates/audiofiles-browser/src/` | |
| 95 |
| Desktop app shell | `crates/audiofiles-app/src/` | |
| 96 |
| Device export profiles | `crates/audiofiles-rhai/plugins/bundled/` | |
| 97 |
| Architecture | `docs/architecture.md` | |
| 98 |
|
| 99 |
## License |
| 100 |
|
| 101 |
[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) |
| 102 |
|