# audiofiles

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/).

## Prerequisites

- **[Rust](https://www.rust-lang.org/)** (stable toolchain, 2024 edition)

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.

## Build and Run

```sh
# Standalone app
cargo run -p audiofiles-app

# Standalone app -- import a folder on launch
cargo run -p audiofiles-app -- /path/to/samples

# Run all workspace tests
cargo test --workspace

# Train the ML classifier (developers only)
cargo run -p audiofiles-train -- /path/to/training-data
```

## Workspace Architecture

Six crates:

| Crate | Path | Role |
|-------|------|------|
| `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. |
| `audiofiles-browser` | `crates/audiofiles-browser/` | Shared egui UI. File list, detail panel, waveform display, search/filter, import wizard, analysis progress, export, themes. |
| `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. |
| `audiofiles-sync` | `crates/audiofiles-sync/` | Cloud sync via SyncKit. Pushes/pulls sample metadata, tags, and VFS structure across devices. E2E encrypted. |
| `audiofiles-rhai` | `crates/audiofiles-rhai/` | Rhai scripting engine for device export profiles. Transforms sample metadata and file layout for hardware samplers. |
| `audiofiles-train` | `crates/audiofiles-train/` | ML classifier training binary. Builds the random forest model from labeled sample data. Not shipped in the app. |

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.

Shared libraries from `../../MNW/shared/`: [theme-common](../../MNW/shared/theme-common/) (theme loading), [synckit-client](../../MNW/shared/synckit-client/) (cloud sync SDK).

## Features

### Storage & Organization
- **Content-addressed storage** -- samples stored by SHA-256 hash, automatic deduplication
- **Virtual file system** -- organize samples in virtual directories independent of disk location, multiple VFS roots
- **Tag system** -- hierarchical dot-notation tags with auto-suggestions from analysis results
- **Smart folders** -- saved filter queries that update dynamically
- **Collections** -- cross-VFS sample groupings

### Audio Analysis
- **Analysis pipeline** -- loudness (peak/RMS/LUFS), BPM detection, key detection, spectral analysis
- **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)
- **Loop detection** -- identifies seamless loops via amplitude envelope analysis
- **Similarity search** -- VP-tree indexed fingerprinting for finding similar and duplicate samples (O(log n) lookup)
- **Waveform display** -- pre-computed peak data with click-to-seek playback

### Search & Filtering
- **Text search** -- FTS5 indexed across filenames, tags, and metadata
- **Parameter filters** -- BPM range, duration range, key selector, classification category
- **Tag prefix matching** -- type a tag prefix to filter by hierarchy

### Editing
- **Destructive editing** -- trim, fade in/out, normalize, reverse, gain adjust
- **Edit history** -- full undo/redo stack per sample
- **Bulk operations** -- bulk delete, move, rename, tag across selections
- **Rename engine** -- pattern-based renaming with tokens (name, bpm, key, index, etc.)

### Device Export
- **Rhai export profiles** -- scriptable export for 14 hardware samplers:
  M8, Digitakt, Digitakt II, Octatrack, Model:Samples, SP-404 MKII, MPC, Polyend Tracker, Deluge, Blackbox, Volca Sample 2, OP-1, Circuit Rhythm, Maschine+

### Playback & Integration
- **MIDI instrument** -- chromatic and multi-sample playback modes with 8-voice polyphony and ADSR envelopes
- **Native drag-out** -- drag samples from the file list directly to Finder, Desktop, or any DAW (macOS + Windows)
- **System tray** -- minimize to tray, quick access

### Infrastructure
- **Cloud sync** -- cross-device sync of metadata, tags, and VFS via SyncKit (E2E encrypted, ChaCha20-Poly1305 + Argon2)
- **OTA updates** -- background update checker with consent dialog
- **Bundled themes** -- dark, light, and high-contrast variants in TOML format (see `crates/audiofiles-browser/themes/`)
- **Audio formats** -- WAV, FLAC, MP3, OGG, AIFF (via Symphonia, pure Rust)
- **Platforms** -- macOS, Windows, Linux (standalone, no backend required)

## Key Paths

| What | Where |
|------|-------|
| Domain library | `crates/audiofiles-core/src/` |
| ML classifier model | `crates/audiofiles-core/models/layer2_drum.json` |
| Training binary | `crates/audiofiles-train/` |
| UI components | `crates/audiofiles-browser/src/` |
| Desktop app shell | `crates/audiofiles-app/src/` |
| Device export profiles | `crates/audiofiles-rhai/plugins/bundled/` |
| Architecture | `docs/architecture.md` |

## License

[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)