Universal Audio Sample Manager — a cross-platform desktop app (Windows, Linux, macOS) for organising audio sample libraries for hardware samplers. Browse a source library, hear files before you move them, convert formats for specific devices, preview exactly how they'll be renamed and structured, then copy or move them in one click.

Pre-built binaries for Windows (.exe), macOS (.app), and Linux available on the Releases page — no Python required.

---

Features

• Audio playback — click any file in the preview to hear it instantly; navigate with ◀ ▶ ▶▶ transport controls or arrow keys
• Hardware profiles — path-limit enforcement and format presets for specific devices:
  • Generic — no limit
  • M8 — 127-character SD path limit (Dirtywave M8), auto-convert to 44.1kHz/16-bit WAV
  • MPC One — 255-character limit
  • SP-404mkII — 255-character limit
  • Elektron Digitakt — Auto-convert to 48kHz/16-bit mono WAV
  • Elektron Analog Rytm — Auto-convert to 48kHz/16-bit WAV
  • Elektron Syntakt — Auto-convert to 48kHz/16-bit WAV
• Folder structure modes — choose how files land in the destination:
  • Flat — all files together in one folder
  • Mirror — preserve the full source directory tree
  • One folder per parent — group by immediate parent folder name
• Rename pattern — files are prefixed with their parent folder name (Kicks_kick_01.wav), keeping context in a flat folder. Disable with Keep original names.
• Custom filename prefix — optionally override the parent-folder prefix with your own (max 10 chars, e.g. KIT_kick_01.wav). Live preview updates instantly.
• Live preview — Deck B shows every file alongside its renamed form, duration, BPM, and root note before you commit; hover for a full-path tooltip
• Smart search — filter Deck B in real time with plain text or structured tokens:
  • BPM:120 · BPM:100-130 · BPM:12* — exact, range, or wildcard BPM
  • Note:C · Note:F# — root note (case-insensitive)
  • MinLength:10 · MaxLength:90 — duration bounds in seconds
  • Tokens combine freely: kick BPM:120 MaxLength:5
• Column sorting — click the BPM, Note, or Length header in Deck B to sort ascending/descending (▲/▼); click again to flip
• BPM detection — automatic tempo analysis using energy-envelope autocorrelation; cached per file, with a Fresh scan option to re-detect. Manual override by double-clicking the BPM cell. Optionally append _120bpm to output filenames.
• Key / Note detection — automatic root-note detection (C, C#, D … B) using pitch-period autocorrelation; same caching and manual-override system as BPM. Optionally append _C to output filenames.
• Sync mode — keep a destination folder (e.g. SD card) in sync with your source library without redundant work:
  • Additive — add new files and update changed ones; existing destination files not in the source are left untouched
  • Mirror — destination becomes an exact copy of the processed source; files no longer in the source are deleted
  • Preview the full sync plan (add / update / delete / skip) in Deck B before executing a single byte is written
  • Auto-detects previously processed destinations on selection and pre-computes the sync plan automatically
• Duplicate detection — on by default; skips files whose audio content already exists at the destination (any filename), catches source-to-source duplicates within the same run, and cleans up existing content-duplicate files in the destination top level. Uses SHA-256 with size pre-filtering for performance
• Copy or Move — copy (default, non-destructive) or move
• Dry run mode — default-on; logs every action without touching the filesystem
• Operation log — colour-coded (red = move, green = copy, yellow = dry run, cyan = done)
• Dark / Light theme — MD3 near-black palette or warm 60s/70s pastels; toggle preserves your session
• Session memory — source and destination paths are saved and restored on next launch
• Audio conversion — Convert samples to device-compatible formats:
  • Output formats: WAV, AIFF
  • Sample rates: 44.1kHz, 48kHz, 96kHz (or keep original)
  • Bit depths: 16-bit, 24-bit, 32-bit float (or keep original)
  • Channel conversion: stereo ↔ mono
  • Auto-apply presets when selecting hardware profiles
• HiDPI / 4K support — DPI-aware on Windows; scales via system settings on Linux/macOS

Supported formats

Input: .wav · .aiff · .aif · .flac · .mp3 · .ogg

Output: .wav · .aif

---

Download

Grab the latest release for your platform from the Releases page — no installation or Python needed.

Platform	Download	Notes
Windows	SAMPSON_win_vX.X.X.zip	Portable executable
macOS	SAMPSON_mac_vX.X.X.zip	Apple Silicon, signed & notarized
Linux	SAMPSON_linux_vX.X.X.tar.gz	x86_64 binary

---

Running from source

pip install -r requirements.txt
python main.py

Requires Python 3.10+. Core dependencies:

• pygame-ce — audio playback (Windows/Linux)
• AppKit (NSSound) — audio playback (macOS native)
• pywebview — modern web-based UI
• pydub — audio conversion
• static-ffmpeg — bundled ffmpeg binary (no separate install needed)

Linux prerequisites

The pre-built Linux binary uses Qt/WebEngine (bundled — no extra install needed).

Running from source requires the Qt WebEngine stack:

# Debian/Ubuntu
sudo apt install python3-pyqt6 python3-pyqt6.qtwebengine

# Fedora
sudo dnf install python3-qt6-webengine

# Arch
sudo pacman -S python-pyqt6-webengine

Building a binary

pip install pyinstaller
pyinstaller SAMPSON.spec

The binary will be in dist/SAMPSON (macOS/Linux) or dist/SAMPSON.exe (Windows).

---

Usage

1. Set the source (Deck A)

   • Click Browse or type a path into the source field.
   • The file browser populates with subfolders and audio files.
   • Click a folder to navigate into it; click ↑ or .. to go up.

2. Set the destination (Deck B)

   • Click Browse or type a path.

3. Preview and listen (Deck B)

   • The table shows every audio file found alongside its renamed form, length, BPM, and root note.
   • Click any row to hear the file. Use ◀ ▶ ▶▶ buttons or ↑ / ↓ arrow keys to navigate and auto-play.
   • Hover over a name in the Will become column for a full-path tooltip.
   • Use the search bar to filter by filename, BPM:120, Note:C, MinLength:10, MaxLength:90, or any combination.
   • Click the BPM, Note, or Length column header to sort ascending/descending.

4. Configure options (centre panel)

   • Options are grouped into collapsible sections. Click any header to expand or collapse it.

   Option	Default	Description
   Move files	Off	Move instead of copy. Off = copy (safe).
   Dry run	On	Log actions without writing files. Turn off to commit.
   Keep original names	Off	Skip the folder-prefix; keep original filenames.
   Custom prefix	(empty)	Override the parent-folder prefix with your own text (max 10 chars).
   Folder structure	Flat	How files are arranged in the destination.
   Hardware profile	Generic	Enforces device-specific path length limits.

5. Click Run (or press Enter)

   • The status bar and log panel update in real time.
   • Use Clear log to reset between runs.

---

How renaming works

By default, each file is prefixed with the name of its immediate parent folder:

Source:       Drums/Kicks/kick_01.wav
Destination:  Kicks_kick_01.wav

This keeps a flat destination usable on hardware samplers while preserving context. Enable Keep original names to skip the prefix entirely, or enter a Custom prefix to replace the parent-folder name with your own.

When a hardware profile with a path limit is selected, the filename stem is silently truncated so the full destination path fits within the device's limit — the extension is always preserved.

---

Theming

Click ☀ Light / ☾ Dark in the top-right corner to switch themes. Source, destination, and browser position are all restored after the toggle.

Theme	Deck A accent	Deck B accent
Dark	Cyan #4dd0e1	Amber #ffb74d
Light	Avocado sage	Terracotta

---

Project structure

SAMPSON/
├── main.py              # entry point — initialises app, launches pywebview window
├── api.py               # JS↔Python bridge — all calls from the UI land here
├── state.py             # all shared mutable globals (widgets, vars, flags)
├── constants.py         # AUDIO_EXTS, MAX_PREVIEW_ROWS, hardware PROFILES
├── conversion.py        # audio conversion engine (pydub + ffmpeg)
├── operations.py        # file copy/move/conversion worker
├── browser.py           # Deck A file browser — navigation and browse dialogs
├── preview.py           # Deck B rename preview, hover tooltip, background scan
├── bpm.py               # BPM detection engine (energy-envelope autocorrelation)
├── key.py               # Musical key / root-note detection
├── playback.py          # audio playback via pygame-ce (Linux) or NSSound (macOS)
├── settings.py          # Persistent app settings (last source + destination)
├── ui/                  # HTML/CSS/JS front-end (index.html, app.js, style.css, logos)
├── build_macos.sh       # macOS build script (sign, notarize, zip)
├── requirements.txt     # Python dependencies
├── SAMPSON.spec         # PyInstaller configuration (macOS + Linux)
└── docs/                # per-module documentation

---

Limitations

• Preview is capped at 500 rows for performance; the search bar bypasses this cap and shows all matches.
• The file browser only shows non-hidden subfolders and audio files.
• Name-collision overwrites are not handled — if two source files produce the same output filename, the second silently overwrites the first. Content duplicates (identical audio) are caught by the duplicate detection feature.
• Audio conversion uses bundled ffmpeg (via static-ffmpeg).
• Duration is read from file headers (WAV/AIFF instantly; MP3/FLAC/OGG via ffprobe). Files with unreadable headers show no length and are excluded from MinLength/MaxLength filters.
• Auto-sync detection does not fire if source is loaded after the destination is already set; click Preview Sync manually in that case.

---

Author

Created by @irpina

---

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.