🎛️ Padwright

Turn your sample folders into playable SP-404MKII banks.

Build drum kits and loop banks, audition every pad, and choose the sounds you want to keep.

Desktop app · Local browser interface · Python command line

Get started · Make your first kit · Command line · Troubleshooting

---

✨ What it does

Padwright prepares audio for the Roland SP-404MKII. Give it a folder of samples or ZIP packs; it exports numbered WAV files you can import through the Roland SP-404MKII app.

You want to…	Padwright helps you…
Turn a sample pack into a kit	Pick sounds by filename and arrange them into a consistent pad layout
Choose every sound yourself	Drag samples onto a 4×4 grid in the crate editor
Prepare loops	Export stereo loop banks with up to 16 sounds
Improve an existing kit	Listen to pads and replace individual sounds
Keep track of your choices	Save source paths, audio details, and hashes in a manifest
Find repeated material	Audit exact duplicates in built banks or scan source samples for likely near-duplicates

Your sample folders / ZIP packs
              │
              ▼
     Pick and arrange sounds
              │
              ▼
       Numbered WAV bank ──── manifest + playable pad map
              │
              ▼
   Import with the Roland app
              │
              ▼
          SP-404MKII

Padwright prepares files; it does not connect to the sampler, write SD cards, or create native SP project files. Automatic sound labels come from filenames. You can always choose sounds manually.

🚀 Get started

Current version: 1.0.3. There are no ready-to-download installers yet. The quickest way to use Padwright is its local browser interface. After setup, kit editing happens in your browser.

1. Install the prerequisites

You need:

• Python 3.11 or newer — Python downloads.
• FFmpeg and ffprobe — FFmpeg downloads. Make both commands available on your system's PATH so Padwright can find them.
• The source code — download ZIP, then extract it. Alternatively, clone with Git:

git clone https://github.com/gdamdam/padwright.git
cd padwright

If you downloaded the ZIP, open Terminal or PowerShell in the extracted folder instead. You should see requirements.txt there.

Check the audio tools:

ffmpeg -version
ffprobe -version

Both should print version information. If a command is not found, finish the FFmpeg installation and reopen your terminal.

2. Set up and launch

macOS / Linux — Terminal

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m web.app

Windows — PowerShell

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m web.app

Use Python 3.11 or newer. These commands call the virtual environment directly; no activation script is needed.

A browser window opens to Padwright. Keep the terminal open while using it; press Ctrl+C there to stop the server. If the browser does not open, use the local address printed in the terminal.

3. Set your folders

Open Settings and enter two folder paths:

Setting	What belongs here	Example on macOS
Built kits folder (root)	A separate folder for exported banks	/Users/you/Music/SP_EXPORT
Samples library folder	Your existing source samples	/Users/you/Music/Samples

On Windows, use paths such as C:\Users\you\Music\Samples. Replace you with your actual account name. Save the settings; Padwright remembers them.

Starting again later: open a terminal in the project folder, activate .venv on macOS/Linux, and run python -m web.app. On Windows, run .\.venv\Scripts\python.exe -m web.app.

🥁 Your first kit

A bank is one set of numbered pad sounds. A crate is the editable recipe: which source sample belongs on each pad.

1. Click New crate.
2. Give the kit a new, unique name and leave its kind as drumkit.
3. Browse the Samples section below the grid. Play a file to hear it.
4. Drag a file from that browser onto a pad. Choose its sound type in the dropdown.
5. Repeat for the sounds you want. Unassigned drum-kit pads become short silent WAVs.
6. Click Build kit, then audition the result.
7. Open the kit's folder inside your configured output folder. Sort by filename and import its numbered WAVs with the Roland SP-404MKII app.

For a typical drum kit, start with 13 kick · 14 snare · 15 closed hat · 16 open hat.

When changing a kit: use Swap pad for one sound or Edit as crate for the whole bank. Rebuilding replaces the numbered pad WAVs and preserves unrelated files. Conversion failures leave the previous bank intact; choose a new name if you want to keep both versions.

The automatic drum layout

┌─────────────┬─────────────┬─────────────┬─────────────┐
│ 01  empty   │ 02  empty   │ 03  empty   │ 04  empty   │
├─────────────┼─────────────┼─────────────┼─────────────┤
│ 05  rim     │ 06  clap    │ 07  cowbell │ 08  perc    │
├─────────────┼─────────────┼─────────────┼─────────────┤
│ 09  low tom │ 10  mid tom │ 11  hi tom  │ 12  crash   │
├─────────────┼─────────────┼─────────────┼─────────────┤
│ 13  kick    │ 14  snare   │ 15  cl. hat │ 16  op. hat │
└─────────────┴─────────────┴─────────────┴─────────────┘

The automatic builder leaves the top row silent. The crate editor lets you assign all 16 pads. Unrecognized sounds may fill available slots as other; missing sounds are named empty.

What gets exported?

SP_EXPORT/
└── My First Kit/
    ├── 01_empty.wav … 16_open_hh.wav
    ├── manifest.json     # source paths, pad assignments, audio details
    ├── pad-map.html      # open in a browser to audition the bank
    └── crate.json        # editable recipe saved by the web crate builder

Output	Audio format
Drum-kit sounds	WAV · 48 kHz · 16-bit · mono
Loop-bank sounds	WAV · 48 kHz · 16-bit · stereo
Silent placeholders	WAV · 48 kHz · 16-bit · mono

Keep the manifest with the WAVs: it is used for audits, pad swaps, and rebuilds. Keep the original source samples if you plan to rebuild later.

💻 Command line

Run commands from the project folder using your Python environment. Examples below use macOS/Linux paths; on Windows, substitute your folder paths and the virtual environment's Python executable. Quote paths containing spaces.

Build sample packs in bulk

For a folder containing unzipped pack folders:

python make_kits.py --unzipped --src "$HOME/Music/Samples" --dst "$HOME/Music/SP_EXPORT" --dry-run
python make_kits.py --unzipped --src "$HOME/Music/Samples" --dst "$HOME/Music/SP_EXPORT"

For a folder of ZIP packs, omit --unzipped. A dry run previews choices without exporting audio.

Output is grouped into drumkit/, extra category blocks/ for large packs, and cross-pack super/ banks. Existing folders containing WAVs are skipped; use a fresh destination when you need a complete new build.

Common tasks

# Build stereo loop banks.
python make_breakbeats.py --src "$HOME/Music/Samples" --dst "$HOME/Music/SP_LOOPS"

# Find exact duplicate exported pads, ignoring intentional super-bank copies.
python audit_kits.py "$HOME/Music/SP_EXPORT" --exclude-super

# Find likely near-duplicates in source samples; review matches by ear.
python scan_dupes.py "$HOME/Music/Samples" --threshold 0.95

# Replace pad 13 in an existing bank.
python swap_pad.py "/path/to/kit" 13 "/path/to/kick.wav"

# Rebuild into a fresh folder, preserving the existing bank.
python rebuild_kit.py "/path/to/kit" --out "/path/to/new-kit"

Each script accepts --help. Loop detection uses names containing loop in the filename or folder path, a size cap, and a maximum duration of 16 seconds by default; use --loop-seconds to change the duration limit.

Make a crate file

Save this as my-kit.crate.json, replacing the source paths with real absolute paths. Use a plain folder name for name and pad numbers from 1 to 16. JSON paths on Windows can use forward slashes, for example C:/Users/you/Music/Samples/kick.wav.

{
  "name": "My Custom Kit",
  "kind": "drumkit",
  "pads": [
    { "pad": 13, "source": "/path/to/kick.wav", "type": "kick" },
    { "pad": 14, "source": "/path/to/snare.wav", "type": "snare" }
  ]
}

python make_kit_from_crate.py my-kit.crate.json "/path/to/output"

# Or export an existing bank's recipe to edit in a text editor.
python make_kit_from_crate.py --from-kit "/path/to/kit" --out my-kit.crate.json

drumkit and loop_bank fill unassigned pads with silence. block and super are also supported. Missing crate sources become silent pads with warnings, so check the build output and listen before importing. ZIP-backed sources such as pack.zip#folder/kick.wav are resolved automatically by the crate builders and can be previewed in the web editor.

🔧 Troubleshooting

Problem	What to do
python, python3, or py is not found	Install Python and reopen your terminal. On Windows, try the py launcher.
No module named fastapi	Use the project's virtual environment and run python -m pip install -r requirements.txt.
FFmpeg is missing or a conversion fails	Check ffmpeg -version and ffprobe -version, then inspect the binary paths in Settings. You can set FFMPEG_PATH and FFPROBE_PATH to explicit executable paths.
The library is empty	It lists built banks, not source samples. Create a crate or build sample packs first.
The Samples browser is empty	Set the samples folder in Settings and open a subfolder containing audio.
A source is rejected	In the web interface, sources must be inside the configured samples folder.
An older kit has extra numbered WAVs	Rebuild it with this version to replace obsolete pad exports. Unrelated files are preserved; import only the numbered pad WAVs.
A pack has unexpected sound labels	Automatic classification uses filenames. Use a crate to choose and label sounds yourself.
A desktop build stays on its loading screen	Check the terminal's [padwright-server] messages. Rebundle the Python sidecar after changing Python, templates, or static files.

Where settings are stored

Platform	Configuration file
macOS	~/Library/Application Support/com.padwright.app/config.json
Windows	%APPDATA%\Padwright\config.json
Linux	~/.config/padwright/config.json (or under XDG_CONFIG_HOME)

Startup options --root and --samples override saved settings. Old com.sp404mk2.toolkit settings are read as a fallback when no new config exists.

🧰 Desktop builds and development

The browser interface does not need Rust or Node.js. The optional Tauri desktop wrapper packages the same interface with a Python server and FFmpeg tools.

Build the desktop app from source

Start with the Python environment above, then install a Rust toolchain, Node.js 18+, and the Tauri platform prerequisites. Build on the target operating system. Cross-platform bundles are not verified by the Python tests.

python -m pip install -r requirements.txt -r requirements-dev.txt
npm install
npm run tauri -- icon icon.png

# Bundle Python and install the resulting server as a Tauri sidecar.
python -m PyInstaller --clean pyinstaller_app.spec
node scripts/install_sidecar.mjs

# Print the target-specific FFmpeg filenames and installation hints.
node scripts/install_ffmpeg.mjs

The FFmpeg helper prints instructions; it does not download or install binaries. Obtain ffmpeg and ffprobe for your exact operating system and CPU architecture from the FFmpeg download resources. Verify the architecture and license of the build you choose; do not assume the helper's suggested download is suitable for every target.

Place the binaries in src-tauri/binaries/ using the target-suffixed names printed by the helper. On macOS/Linux, make them executable. See binary naming.

npm run tauri:dev
# Or create a production bundle:
npm run tauri:build

Bundles are written under src-tauri/target/release/bundle/ (target-specific builds add a target-triple directory). Signing, notarization, and automatic updates are not configured as a ready-to-use release pipeline.

After changing Python code, templates, or static assets, rerun PyInstaller and install_sidecar.mjs so the desktop app contains the new files.

Run the tests and find your way around the code

python -m pip install -r requirements.txt -r requirements-dev.txt
python tests.py

Install FFmpeg and ffprobe before testing audio exports. Web tests need httpx from requirements-dev.txt. Missing dependencies cause some tests to skip, so inspect the output as well as the exit code.

Location	Responsibility
sp404_core.py	Classification, pad layout, exports, manifests, crate helpers
sp404_analysis.py	Audio fingerprints, measurements, cached analysis
make_kits.py, make_breakbeats.py	Automatic drum and loop bank builders
swap_pad.py, rebuild_kit.py, make_kit_from_crate.py	Individual pad replacement and curated builds
audit_kits.py, scan_dupes.py	Exact exported-pad audits and source near-duplicate scans
reorder_kits.py	Legacy pad-layout migration
web/	FastAPI routes, templates, styles, browser interactions
src-tauri/, scripts/	Desktop shell and packaging helpers
tests.py	Regression and end-to-end checks

Found a bug? Open an issue with your OS, Python version, steps to reproduce, and error output. Include a small example when possible; avoid uploading sample packs you cannot redistribute.

🚧 Current limitations

• Near-duplicate matching is approximate. It works best on short one-shots; loops and bright cymbals can produce false matches. Listen before deciding. Scans write a cache under <samples>/.padwright/analysis.json; they do not delete samples. Byte-identical paths collapse to one content entry in the current near-duplicate report.
• Automatic classification uses filenames, and loop banks have no BPM detection. Numeric names may produce evenly spread other sounds.
• Desktop installation still requires a build. No prebuilt installers, automatic updates, or verified platform-wide release matrix are provided.

See CHANGELOG.md for the project's change history.

📄 License

Padwright's code is licensed under GNU GPL version 3 only (GPL-3.0-only). You may use, modify, and share it, including commercially. When distributing covered modified versions or binaries, comply with GPL v3, including its corresponding-source requirements. See NOTICE for copyright, branding, and third-party information.

Your audio remains subject to its own licenses. Installing Padwright does not grant redistribution rights to sample packs or exported sounds.

Bundled dependencies retain their own licenses. In particular, FFmpeg's license depends on its build configuration; some builds are GPL rather than LGPL. Before distributing a desktop bundle, verify its actual binaries and update third-party notices accordingly. See FFmpeg's licensing guidance.