Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/irpina/sampson-sample-manager

Universal audio sample manager for hardware samplers (M8, MPC One, SP-404mkII). Browse, preview, listen, and organise your sample library.
https://github.com/irpina/sampson-sample-manager

audio dirtywave-m8 mpc pygame python sample-manager samples sp404 tkinter windows

Last synced: 9 days ago
JSON representation

Universal audio sample manager for hardware samplers (M8, MPC One, SP-404mkII). Browse, preview, listen, and organise your sample library.

Awesome Lists containing this project

README 

          


  

    

    

    SAMPSON Logo

  




**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 on the fly, preview exactly how everything will be renamed and structured, then copy or move it all in one click.



> Pre-built binaries for **Windows** (`.exe`), **macOS** (`.app`), and **Linux** available on the [Releases](https://github.com/irpina/Sampson-Sample-Manager/releases) page — no Python required.



---



## What's new in v1.0



| | |

|---|---|

| **Sample Slicer** | Visual waveform editor — chop loops into slices by transient, BPM, fixed length, or manually. Drag boundaries, undo edits, real seek, playhead tracking. |

| **Audition Stack** | Layer up to 4 samples and preview the mix. Per-track pitch shift, BPM stretch, volume, and offset before you commit. |

| **Sync System** | Keep a destination (SD card, folder) in sync with your processed source — additive or mirror mode, full diff preview before writing. Auto-detects previously synced destinations. |

| **Duplicate detection** | SHA-256 content hashing catches identical files across any filename. Skips re-copies and cleans up existing duplicates in the destination. |

| **BPM & Key — rewritten** | Onset-novelty autocorrelation (BPM) and Goertzel chroma + Krumhansl-Schmuckler matching (Key). Validated against synthetic ground truth — atonal/percussive samples no longer get a random key label. |

| **New UI** | Rebuilt on PyWebView + HTML/CSS/JS. Bundled Inter + JetBrains Mono fonts for consistent cross-platform rendering. Native app icon on all platforms. |



---



## 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 onset-novelty autocorrelation with comb-filter octave resolution; 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) via a Goertzel chroma and Krumhansl-Schmuckler key-profile matching; atonal/percussive samples are left blank rather than mislabelled. 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

- **Audition Stack** — layer up to 4 samples from Deck B and preview them as a mixed playback; Shift+click rows to select (♦ indicator shows slot number), then click ⊕ Audition to open the stack panel

  - Per-track: volume, mute, solo, start offset (ms), pitch shift (semitones ~), BPM sync (~)

  - Master BPM (auto-detected from slot 1), loop toggle, render + preview

- **Sample Slicer** — open any sample for visual waveform editing, auto-slice by silence/BPM/transients/fixed length, and export slices

  - Open Slicer without a file selected — browse button defaults to Deck A's current directory; previously loaded file path is always shown

  - Arrow keys navigate slices in the Slice Editor (no longer pass through to Deck B)

  - Navigating Deck A cancels any in-progress directory scan

- **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](https://github.com/irpina/Sampson-Sample-Manager/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



```bash

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:



```bash

# 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



```bash

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 (onset-novelty autocorrelation + comb filter)

├── 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](https://github.com/irpina)



---



## License



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