| 1 |
# audiofiles |
| 2 |
|
| 3 |
> Manage your sample library without the waits. |
| 4 |
|
| 5 |
## What It Is |
| 6 |
|
| 7 |
audiofiles is a standalone desktop sample manager. It stores samples by content hash so nothing is ever duplicated, organizes them in virtual file systems that don't touch your disk, and exports them formatted for 14 hardware samplers. Built entirely in Rust. |
| 8 |
|
| 9 |
## Design |
| 10 |
|
| 11 |
- **Brand:** "audiofiles/" in Recursive Mono Bold. Short form: "af/" |
| 12 |
- **Default theme:** Bold black and white (pure #000000 background, #ffffff text, sharp system accent colors). Bundled themes (dark, light, and high-contrast variants) live in `crates/audiofiles-browser/themes/`. |
| 13 |
- **Typography:** Recursive Mono Bold for the logo; egui system font for all UI text. |
| 14 |
|
| 15 |
## Features |
| 16 |
|
| 17 |
### Sample Import |
| 18 |
- Import folders of audio samples (WAV, AIFF, FLAC, MP3, OGG, M4A, ALAC, CAF, BWF) |
| 19 |
- Three import strategies: flat, new VFS, or merge into existing VFS |
| 20 |
- Content-addressed storage (SHA-256) with automatic deduplication |
| 21 |
- Progress display with cancel support; partial imports remain valid |
| 22 |
- Drag-and-drop import (standalone app) |
| 23 |
- CLI argument import (`audiofiles-app /path/to/folder`) |
| 24 |
- Post-import folder tagging prompt |
| 25 |
|
| 26 |
### Virtual File System (VFS) |
| 27 |
- Organize samples in virtual directories independent of disk location |
| 28 |
- Multiple VFS roots (switch between collections via sidebar or dropdown) |
| 29 |
- Create, rename, delete VFS roots and directories |
| 30 |
- Move and rename sample links (instant, metadata-only operations) |
| 31 |
- Breadcrumb navigation with clickable path segments |
| 32 |
- Keyboard nav: j/k or arrows, Enter to open, Backspace to go up |
| 33 |
- Directories always sort before files |
| 34 |
- Cascade delete (deleting a VFS removes all its nodes) |
| 35 |
- Background right-click context menu: New Folder, Import Folder, Deselect |
| 36 |
|
| 37 |
### Audio Analysis |
| 38 |
- Configurable analysis pipeline (enable/disable each type): |
| 39 |
- Loudness: peak dB, RMS dB, LUFS (bs1770 ITU-R BS.1770-4) |
| 40 |
- BPM detection (stratum-dsp, requires 2+ seconds of audio) |
| 41 |
- Musical key detection |
| 42 |
- Spectral: centroid, flatness, rolloff, zero-crossing rate, onset strength |
| 43 |
- Loop detection: cross-correlation + beat alignment |
| 44 |
- Classification: rule-based into 16 categories |
| 45 |
- Waveform generation: downsampled peak pairs for display |
| 46 |
- Background worker thread (non-blocking UI) |
| 47 |
- Progress bar with cancel support |
| 48 |
- Re-analyze previously analyzed samples |
| 49 |
|
| 50 |
### Classification (16 Categories) |
| 51 |
Kick, Snare, HiHat, Cymbal, Percussion, Bass, Vocal, Synth, Pad, FX, Noise, Music, Ambience, Impact, Foley, Texture |
| 52 |
|
| 53 |
Two-layer ML system: rule-based broad classifier (Layer 1) + 200-tree Random Forest for drum sub-classification (Layer 2). 94.4% accuracy on labeled drum samples. |
| 54 |
|
| 55 |
### Tag System |
| 56 |
- Hierarchical dot-notation tags (e.g., `genre.electronic.house`, `instrument.drum.kick`) |
| 57 |
- Auto-suggested tags from analysis with confidence scores and reasoning: |
| 58 |
- Classification, BPM, genre hint, key, loop/oneshot, loudness character |
| 59 |
- Review suggestions screen: accept/reject per-suggestion with Accept All / Reject All |
| 60 |
- Tag entire folders during import |
| 61 |
- Add/remove tags manually in detail panel |
| 62 |
- Bulk tagging across multi-selection (Cmd+T) |
| 63 |
|
| 64 |
### Collections |
| 65 |
- Cross-VFS sample groupings for quick access |
| 66 |
- Create, rename, delete collections |
| 67 |
- Add/remove samples from any VFS |
| 68 |
|
| 69 |
### Dynamic Collections |
| 70 |
- A collection with a non-NULL `filter_json` is a saved search (the old "smart folder" feature, merged into the collections table in migration M015) |
| 71 |
- Sidebar section with collapsible list |
| 72 |
- Click to apply saved filter instantly |
| 73 |
|
| 74 |
### Search + Filtering |
| 75 |
- Text search by sample name (folder or global scope, 500 result limit) |
| 76 |
- Filter panel: BPM range, duration range, key selector (with compatibility mode), classification checkboxes, tag prefix filter |
| 77 |
- Filters combine with AND logic |
| 78 |
- `/` to focus search bar |
| 79 |
- Similarity search: weighted Euclidean distance on analysis vectors ("Find Similar" in context menu) |
| 80 |
- Near-duplicate detection: VP-tree indexed peak envelope fingerprint comparison ("Find Duplicates" in context menu) |
| 81 |
|
| 82 |
### Preview Playback |
| 83 |
- Double-click or Space to play/pause |
| 84 |
- Plays through system audio via cpal |
| 85 |
- Selecting a different sample switches playback |
| 86 |
- Status footer shows currently playing filename |
| 87 |
|
| 88 |
### MIDI Instrument Mode |
| 89 |
- Chromatic mode: play any sample across the keyboard with pitch shifting |
| 90 |
- Multi-sample mode: assign samples to key zones with velocity layers |
| 91 |
- ADSR envelope (per-sample linear ramps) |
| 92 |
- 8-voice polyphony with oldest-note stealing |
| 93 |
- 3-octave piano keyboard UI with click-to-set root note |
| 94 |
- Drag samples from file list to keyboard to create zones |
| 95 |
- Toggle with I key; panel appears below file list |
| 96 |
|
| 97 |
### Native Drag-Out |
| 98 |
- Drag samples from the file list to Finder, Desktop, or DAW (REAPER, Ableton, Logic, etc.) |
| 99 |
- macOS: NSDraggingSession via AppKit (deferred to run loop, session lifecycle callbacks) |
| 100 |
- Windows: OLE DoDragDrop with CF_HDROP (blocking modal) |
| 101 |
- Temporary symlinks provide friendly filenames (content store uses hash names) |
| 102 |
- Multi-file drag (all selected samples) |
| 103 |
- 4-pixel dead zone prevents accidental drags during clicks |
| 104 |
|
| 105 |
### Export |
| 106 |
- Export VFS subtree to filesystem (preserving directory structure or flattened) |
| 107 |
- Device export with 14 bundled hardware sampler profiles: |
| 108 |
- Dirtywave M8, Elektron Digitakt, Digitakt II, Octatrack, Model:Samples |
| 109 |
- Roland SP-404 MKII, Akai MPC, Polyend Tracker, Synthstrom Deluge |
| 110 |
- 1010music Blackbox, Korg Volca Sample 2, TE OP-1 |
| 111 |
- Novation Circuit Rhythm, NI Maschine+ |
| 112 |
- Profiles handle sample rate conversion, bit depth, channel count, filename sanitization, file size limits |
| 113 |
- Rhai scripting engine for custom/community export profiles |
| 114 |
- Export dialog with device picker, destination, preview, progress |
| 115 |
- Metadata sidecar option (.audiofiles.json per sample) |
| 116 |
|
| 117 |
### Cloud Sync (MNW SyncKit) |
| 118 |
- Optional cloud sync via Makenotwork accounts |
| 119 |
- E2E encrypted (ChaCha20-Poly1305 + Argon2) |
| 120 |
- Push/pull changelog sync with conflict resolution |
| 121 |
- Per-VFS toggle for syncing audio files vs metadata-only |
| 122 |
- Cloud-only samples: visible with cloud icon, metadata searchable, no local blob required |
| 123 |
- Auto-sync scheduler (configurable interval: 5/15/30/60 min) |
| 124 |
- PKCE OAuth authentication flow |
| 125 |
|
| 126 |
### OTA Updates |
| 127 |
- Background update checker (custom reqwest-based, not Tauri) |
| 128 |
- Consent dialog: Download (opens browser) or Not Now |
| 129 |
- Non-intrusive bottom-right overlay notification |
| 130 |
|
| 131 |
### File List + Sorting |
| 132 |
- Multi-column table: Name, BPM, Key, Duration, Classification (configurable) |
| 133 |
- Click column header to sort (ascending, descending, reset) |
| 134 |
- Directories always first regardless of sort |
| 135 |
|
| 136 |
### Selection |
| 137 |
- Single-click, Cmd+Click (toggle), Shift+Click (range) |
| 138 |
- Shift+Arrow to extend selection |
| 139 |
- Cmd+A to select all |
| 140 |
- Keyboard navigation: j/k or arrow keys |
| 141 |
|
| 142 |
### Bulk Operations |
| 143 |
- Bulk delete, move, rename, tag (add/remove) across multi-selection |
| 144 |
- 50-deep undo stack (Cmd+Z) |
| 145 |
- Rename pattern engine: {name}, {ext}, {bpm}, {key}, {class}, {duration}, {n}/{nn}/{nnn} tokens |
| 146 |
- Live preview of rename results before applying |
| 147 |
- Bulk modal UIs: tag editor (Cmd+T), directory picker, pattern builder (F2) |
| 148 |
|
| 149 |
### Detail Panel |
| 150 |
- Waveform display with click-to-seek (rendered from pre-generated peak data) |
| 151 |
- Metadata: duration, sample rate, channels, peak dB, RMS dB, LUFS, BPM, key, classification |
| 152 |
- Tag editor (add/remove chips) |
| 153 |
- Auto-hides when window is narrow (< 700px) |
| 154 |
- Resizable (200-400px) |
| 155 |
|
| 156 |
### Context Menus |
| 157 |
- Sample: Preview, Find Similar, Find Duplicates, Play as Instrument, Copy Path, Export, Delete |
| 158 |
- Folder: Open, Rename, Export, Delete |
| 159 |
- Multi-select: Tag, Move to, Rename, Copy Paths, Delete |
| 160 |
- Background (empty space): New Folder, Import Folder, Deselect |
| 161 |
|
| 162 |
### Keyboard Shortcuts |
| 163 |
- j/k or arrows: navigate |
| 164 |
- Enter or Right: open directory / preview sample |
| 165 |
- Backspace or Left: go up |
| 166 |
- Space: play/pause |
| 167 |
- /: focus search |
| 168 |
- I: toggle instrument panel |
| 169 |
- S: toggle sidebar |
| 170 |
- D: toggle detail panel |
| 171 |
- Cmd+A: select all |
| 172 |
- Cmd+Z: undo |
| 173 |
- Cmd+T: bulk tag |
| 174 |
- F1: help overlay (also reachable via Help toolbar menu → Keyboard shortcuts) |
| 175 |
- F2: bulk rename |
| 176 |
- Cmd+I / Cmd+,: About modal (toggle update-check preference) |
| 177 |
- Delete: delete (with confirmation) |
| 178 |
- Escape: close dialog / clear search |
| 179 |
|
| 180 |
### Themes |
| 181 |
- Bundled themes (audiofiles default + community themes; see `crates/audiofiles-browser/themes/`) |
| 182 |
- Dark: audiofiles, Tokyo Night, Catppuccin Mocha, Dracula, Nord, Gruvbox Dark, Rose Pine, Everforest, Solarized Dark, Kanagawa |
| 183 |
- Light: Catppuccin Latte, Ayu Light, Flatwhite, Neobrute, Gruvbox Light, Rose Pine Dawn |
| 184 |
- High Contrast: High Contrast |
| 185 |
- Custom themes: drop .toml files into `~/.config/audiofiles/themes/` |
| 186 |
- Theme selector in toolbar |
| 187 |
|
| 188 |
### Standalone App |
| 189 |
- Native desktop window (eframe, 900x600 default, 600x400 minimum) |
| 190 |
- System audio output via cpal |
| 191 |
- Drag-and-drop files and folders (import) |
| 192 |
- Native drag-out to Finder/DAW (export) |
| 193 |
- CLI argument import |
| 194 |
- macOS app bundle with squircle icon, file associations (.wav, .flac, .mp3, .ogg, .aiff) |
| 195 |
- System tray icon with Show Window / Toggle Playback / Quit |
| 196 |
- OTA update notifications |
| 197 |
|
| 198 |
### Data Storage |
| 199 |
- SQLite database (versioned migrations) |
| 200 |
- Content-addressed sample store (files named by SHA-256 hash) |
| 201 |
- Waveform data cached in database |
| 202 |
- Database local to the app |
| 203 |
|
| 204 |
### Platforms |
| 205 |
- macOS (primary, signed + notarized) |
| 206 |
- Windows, Linux |
| 207 |
|
| 208 |
## Price |
| 209 |
|
| 210 |
License key required. Sold via Makenot.work store. Source-available (PolyForm Noncommercial 1.0.0). |
| 211 |
|
| 212 |
## Tags |
| 213 |
|
| 214 |
Music Production, Samples, Audio, Sample Manager, Hardware Sampler, Rust |
| 215 |
|
| 216 |
--- |
| 217 |
|
| 218 |
## Technical Reference |
| 219 |
|
| 220 |
### Tech Stack |
| 221 |
|
| 222 |
- **Language:** Rust (2024 edition), zero `unsafe` in production code (17 justified FFI blocks in platform drag-out) |
| 223 |
- **Audio Decoding:** Symphonia 0.5.5 |
| 224 |
- **Analysis:** stratum-dsp 1.0 (BPM/key), bs1770 (LUFS), realfft 3.5 (spectral) |
| 225 |
- **Database:** SQLite via rusqlite 0.31 (bundled) |
| 226 |
- **Hashing:** SHA-256 (content-addressed storage) |
| 227 |
- **GUI:** eframe + egui 0.34 (windowed) + cpal 0.17 (audio output) |
| 228 |
- **Export Scripting:** Rhai 1.21 (sandboxed: 100K ops, 32-level calls) |
| 229 |
- **Sync:** synckit-client (ChaCha20-Poly1305, Argon2, reqwest) |
| 230 |
- **Font:** Recursive Mono Linear Bold (logo) |
| 231 |
|
| 232 |
**Workspace:** 5 crates — `audiofiles-core` (sync-only library), `audiofiles-browser` (egui UI), `audiofiles-app` (standalone desktop), `audiofiles-sync` (cloud sync), `audiofiles-rhai` (export scripting) |
| 233 |
|
| 234 |
### Testing |
| 235 |
|
| 236 |
Tests cover: database, store, VFS, tags, analysis (incl. ML classifier), search, export, instrument, smart folders, rename, fingerprint, similarity, state orchestration, theme parsing, preview decoding, updater, license activation, and full end-to-end pipelines. |
| 237 |
|
| 238 |
### Status |
| 239 |
|
| 240 |
License key activation required. |
| 241 |
|
| 242 |
--- |
| 243 |
|
| 244 |
## Appendix: Building from Source on Linux |
| 245 |
|
| 246 |
audiofiles is built entirely in Rust and compiles on Linux without modification. The source is available on sourcehut. |
| 247 |
|
| 248 |
### Prerequisites |
| 249 |
|
| 250 |
- Rust toolchain (stable, 1.75+): https://rustup.rs |
| 251 |
- System packages for audio and graphics (package names for Debian/Ubuntu): |
| 252 |
|
| 253 |
``` |
| 254 |
sudo apt install build-essential pkg-config libasound2-dev libgtk-3-dev \ |
| 255 |
libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev \ |
| 256 |
libssl-dev libfontconfig1-dev |
| 257 |
``` |
| 258 |
|
| 259 |
For Fedora/RHEL: |
| 260 |
|
| 261 |
``` |
| 262 |
sudo dnf install gcc pkg-config alsa-lib-devel gtk3-devel \ |
| 263 |
libxcb-devel libxkbcommon-devel openssl-devel fontconfig-devel |
| 264 |
``` |
| 265 |
|
| 266 |
For Arch: |
| 267 |
|
| 268 |
``` |
| 269 |
sudo pacman -S base-devel alsa-lib gtk3 libxcb libxkbcommon openssl fontconfig |
| 270 |
``` |
| 271 |
|
| 272 |
### Clone |
| 273 |
|
| 274 |
audiofiles depends on the `synckit-client` crate via a relative path. Clone both repositories side by side: |
| 275 |
|
| 276 |
``` |
| 277 |
git clone https://git.sr.ht/~maxmj/synckit-client |
| 278 |
git clone https://git.sr.ht/~maxmj/audiofiles |
| 279 |
``` |
| 280 |
|
| 281 |
Your directory should look like: |
| 282 |
|
| 283 |
``` |
| 284 |
parent/ |
| 285 |
synckit-client/ |
| 286 |
audiofiles/ |
| 287 |
``` |
| 288 |
|
| 289 |
### Build the Standalone App |
| 290 |
|
| 291 |
``` |
| 292 |
cd audiofiles |
| 293 |
cargo build --release -p audiofiles-app |
| 294 |
``` |
| 295 |
|
| 296 |
The binary is at `target/release/audiofiles-app`. Run it directly or copy it to a location in your `$PATH`. |
| 297 |
|
| 298 |
### Run Tests |
| 299 |
|
| 300 |
``` |
| 301 |
cargo test --workspace |
| 302 |
``` |
| 303 |
|
| 304 |
### Sync (Optional) |
| 305 |
|
| 306 |
Cloud sync requires a Makenotwork account. Set the environment variables before launching: |
| 307 |
|
| 308 |
``` |
| 309 |
AF_SYNC_SERVER_URL=https://makenot.work AF_SYNC_API_KEY=your-key audiofiles-app |
| 310 |
``` |
| 311 |
|
| 312 |
Without these variables, the app runs fully offline with all features except sync. |
| 313 |
|