MPC Sample Kit Converter
by ab1428x · ab1428x/mpcsample-kit-converter
A Python command-line tool that converts Akai MPC expansion packs into ready-to-play .xpj projects for the MPC Sample, with optional demo grooves and multi-layer pads.
About
Bulk-convert Akai MPC expansion packs (.xpm kit definitions) into ready-to-play .xpj projects for the MPC Sample hardware device.
Each kit is exported as a self-contained .xpj project alongside a KitName_[ProjectData]/ folder containing the kit's WAV files. The _[ProjectData] folders are invisible in the MPC device browser, so an entire expansion appears flat — open one folder and see all kit names directly, with no sub-navigation required.
Features
- Reads Akai
.xpmkit definitions and maps every pad to its correct WAV - Preserves mute groups from the source XPM
- Preserves multi-layer pads — velocity switching, stacking, and round-robin are all carried forward from the source XPM
- Auto-detects BPM from kit filenames
- Embeds the kit's demo groove when an
.sxqsequence file is present alongside the.xpm— hit play and the pattern runs immediately at the correct BPM - Sets correct WAV start/end frame values so every sample plays immediately
- Keeps original WAV filenames — no
A01/A02renaming - Processes a single kit, one expansion (by path or short name), or all expansions in one command
- Filter or skip kits by name pattern
- Parallel processing with
--workersfor faster bulk generation - Pure Python stdlib — no dependencies to install
Requirements
- Python 3.10 or later
- A
.xpjproject file exported directly from your MPC device (see Template below)
Understanding the source files
Before running the converter it helps to know what the MPC Content directory looks like and which files do what. All of the source material the converter reads lives in one place on your computer.
Where the Content directory is
macOS
/Library/Application Support/Akai/MPC/Content/
This is the system-level Library folder (/Library), not your user Library (~/Library). If you open Finder, press Cmd+Shift+G, and paste that path, you'll land right in it.
Windows
C:\ProgramData\Akai\MPC\Content\
ProgramData is a hidden folder by default. To reach it, open File Explorer, click the address bar, type that path, and press Enter. You can also press Win+R, type %ProgramData%\Akai\MPC\Content, and hit Enter.
Both locations are set automatically — you only need --content-dir if you've moved your content to a custom drive.
What's inside
Each installed expansion pack gets its own folder inside Content, named with a reverse-domain identifier:
Content/
├── com.akaipro.mpc.expansion.golddust/
├── com.akaipro.mpc.expansion.nuskillz/
├── com.akaipro.mpc.expansion.soulprovider2/
└── ...
Inside each expansion folder you'll find a flat mix of files:
com.akaipro.mpc.expansion.golddust/
│
├── HipHop-Kit-GD Rawcutz Atomic 95.xpm ← kit definition (XML)
├── HipHop-Kit-GD Rawcutz Atomic 95.sxq ← demo groove (optional)
├── HipHop-Kit-GD Rawcutz Block 92.xpm
├── HipHop-Kit-GD Rawcutz Block 92.sxq
│
├── HipHop-Kick-GD Atomic Kik.WAV ← audio samples shared across kits
├── HipHop-Snare-GD Atomic Snr.WAV
├── HipHop-Hat-GD Atomic Hat.WAV
├── ...
│
├── Cache.json ← MPC browser cache (ignored by converter)
└── TagsCache.json ← MPC tag index (ignored by converter)
.xpm files — The kit definitions. Each one is an XML file that maps pad slots (A01 through H16) to sample names, sets mute groups, and lists any additional velocity layers. This is what the converter reads to know which WAVs go on which pads.
.wav files — The actual audio. They sit alongside the .xpm files in the same folder — not in sub-folders. The converter reads the WAV header (just the first 44 bytes) to get the sample length, then either copies the file or leaves it in place depending on your --no-copy-wavs setting.
.sxq files — Demo sequence files. Not every kit has one, but when present, the .sxq carries a pre-programmed groove for that kit — the same pattern that plays in the MPC's built-in demo. The converter reads the pad hits, velocities, and BPM from the .sxq and embeds them directly into the generated .xpj sequence so you can hear the kit in action as soon as you open it.
Cache.json / TagsCache.json — Internal MPC browser index files generated by the device software. The converter ignores them entirely.
Note: Some expansions also contain a demo project file (e.g.
GoldDust Demo.xpj) and a matchingGoldDust Demo_[ProjectData]/folder with its own copies of certain WAVs. These are separate from the kit.xpmfiles and are not used by the converter.
Tutorial
Step 1 — Get the template file from your device
The converter needs a real .xpj file saved from your MPC device. This file provides the correct internal structure (mixer routing, instrument boilerplate) for your specific firmware version. Without it, generated projects won't load correctly.
On your MPC device:
- Create a new empty project
- Go to Menu → Save Project As and save it anywhere on your drive
- Connect your MPC to your computer (USB storage or SD card)
- Copy the
.xpjfile you just saved to thetemplate/folder in this repo and rename itdevice_template.xpj
mpcsample-kit-converter/
└── template/
└── device_template.xpj ← your file goes here
The
template/folder is listed in.gitignoreso your device file is never accidentally committed.
Step 2 — Find your expansions
Run --list-expansions to see what's installed and what short names to use:
python3 mpc_kit_converter.py --list-expansions
Example output:
Expansion Kits
───────────────────────────────────────────────────
golddust 28
nuskillz 20
soulprovider2 35
trapdrums 8
...
Step 3 — Do a dry run first
Before writing anything to disk, use --dry-run to preview what will be generated. This is a good way to check BPM detection and confirm the kit count:
python3 mpc_kit_converter.py --expansion-name golddust --output ~/Desktop/kits --dry-run
Output will look like:
DRY HipHop-Kit-GD Rawcutz Atomic 95 [BPM=95 pads=16 demo=64hits]
DRY HipHop-Kit-GD Rawcutz Block 92 [BPM=92 pads=16 demo=58hits]
...
Done: 28/28 kits.
The demo=Nhits field means a .sxq demo groove was found for that kit and will be embedded in the sequence. Kits without one get a clean empty sequence.
When a kit contains multi-layer pads the status line includes a multi-layer=N count showing how many pads have more than one layer:
DRY MPC TrapKit 1 [BPM=93 pads=16 demo=76hits multi-layer=2]
DRY MPC TrapKit 10 [BPM=76 pads=16 demo=84hits multi-layer=5]
With --no-multi-layer the count is still shown so you can see what is being dropped:
DRY MPC TrapKit 1 [BPM=93 pads=16 demo=76hits multi-layer=2 (layer 1 only)]
DRY MPC TrapKit 10 [BPM=76 pads=16 demo=84hits multi-layer=5 (layer 1 only)]
Step 4 — Convert
Run the same command without --dry-run:
python3 mpc_kit_converter.py --expansion-name golddust --output ~/Desktop/kits
Step 5 — Copy to your MPC
Transfer the output folder to your MPC device via USB or SD card. In the MPC browser, navigate to the folder and you'll see one .xpj entry per kit — no sub-folders, no clutter.
Open any kit and hit Play — if a demo groove was found for that kit, it will play back immediately at the correct BPM.
Converting everything at once
To convert all installed expansions in one go (this can take a while and copies a lot of audio):
python3 mpc_kit_converter.py --all-expansions --output ~/Desktop/kits --workers 4 --quiet
If your expansions are already on the MPC device and accessible at their original paths, you can skip copying WAVs to save disk space:
python3 mpc_kit_converter.py --all-expansions --output ~/Desktop/kits --no-copy-wavs
Re-running after updates
By default the converter skips kits that already exist in the output folder. Use --overwrite to regenerate everything:
python3 mpc_kit_converter.py --expansion-name golddust --output ~/Desktop/kits --overwrite
Multi-layer pads
Many expansion kits use multi-layer pads — pads with more than one sample assigned, triggered by velocity range, round-robin, or simultaneous stacking. The converter carries all of this forward by default, reading each layer's velocity range and play mode directly from the source XPM.
MPC Sample supports multi-layer pads in full: velocity switching, stacking, and round-robin all work on-device. Note that on-device editing is limited to layer 1 only — additional layers play correctly but cannot be adjusted from the hardware UI.
⚠ Warning — stacked layers and CPU load
Some expansion kits (notably Trap Drums and several producer kit packs) use stacked layers — multiple samples all assigned the same full velocity range (0–127) on a single pad, intended to play simultaneously on every hit. While this is faithful to the original kit design, each layer adds a separate voice. A pad with 3 or 4 stacked layers can generate 3–4 simultaneous voices on a single hit, and in a dense sequence with multiple pads firing at once the cumulative voice load can exceed what MPC Sample can handle, causing audio dropout or stuttering.
If you experience performance issues, regenerate with
--no-multi-layerto fall back to layer 1 only on all pads. This is the same behaviour as the previous version of the converter and is guaranteed to be safe on-device.
# Safe fallback — layer 1 only on every pad
python3 mpc_kit_converter.py --expansion-name trapdrums --output ~/Desktop/kits --no-multi-layer
All Options
Mode flags (pick one)
| Flag | Description |
|---|---|
--xpm FILE |
Convert a single .xpm kit file |
--expansion DIR |
Convert all kits in one expansion directory |
--expansion-name NAME |
Convert an expansion by its short name (e.g. golddust) — searches the Content directory automatically |
--all-expansions [DIR] |
Convert every expansion found in the Content directory |
--list-expansions |
Print a table of installed expansions and kit counts, then exit |
Output & paths
| Flag | Default | Description |
|---|---|---|
--output DIR |
(required) | Destination folder for generated kits |
--template FILE |
template/device_template.xpj |
Path to the .xpj template file from your MPC device |
--content-dir DIR |
macOS: /Library/Application Support/Akai/MPC/ContentWindows: C:\ProgramData\Akai\MPC\Content |
Override the MPC Content directory. Only needed if you've moved your content to a custom location. See Understanding the source files for details. |
Sequence & timing
| Flag | Default | Description |
|---|---|---|
--bpm N |
(auto) | Override BPM for every kit. Normally BPM is read from the .sxq demo file if present, or auto-detected from the kit filename (e.g. Kit 95 Am → 95 BPM) |
--bpm-fallback N |
120 |
BPM to use when auto-detection finds nothing in the filename and no .sxq is present |
--bars N |
2 |
Sequence length in bars |
Filtering
| Flag | Description |
|---|---|
--filter PATTERN |
Only convert kits whose name contains PATTERN (case-insensitive). Useful for testing a subset before a full run |
--skip PATTERN |
Skip kits whose name contains PATTERN (case-insensitive). Handy for excluding loop kits or specific categories |
Behaviour
| Flag | Description |
|---|---|
--no-multi-layer |
Use only the first layer per pad. Disables velocity switching, stacking, and round-robin — every pad plays a single sample regardless of how the source XPM was configured. Use this if you experience audio dropout or CPU overload on-device (see Multi-layer pads) |
--overwrite |
Replace existing .xpj files and WAVs in the output folder. Without this, already-converted kits are skipped |
--dry-run |
Preview what would be generated without writing anything to disk |
--no-copy-wavs |
Write .xpj files only — skip copying WAVs. Use this when the WAVs are already accessible on the device at their original Content directory paths |
--quiet |
Suppress per-kit output lines; show only the final summary counts |
--workers N |
Number of parallel workers for kit generation (default: 1). Set to the number of CPU cores for fastest bulk conversion |
--version |
Print version number and exit |
Output structure
kits/
└── golddust/
├── HipHop-Kit-GD Rawcutz Atomic 95.xpj ← visible in MPC browser
├── HipHop-Kit-GD Rawcutz Atomic 95_[ProjectData]/ ← hidden from browser
│ ├── HipHop-Kick-GD Atomic Kik.WAV
│ ├── HipHop-Snare-GD Atomic Snr.WAV
│ └── ...
├── HipHop-Kit-GD Rawcutz Block 92.xpj
├── HipHop-Kit-GD Rawcutz Block 92_[ProjectData]/
│ └── ...
└── ...
How it works
Akai expansion packs ship with .xpm files (XML) that define drum programs — which WAV file goes to which pad, mute group assignments, and layer configuration. This script:
- Parses each
.xpmto extract the 128-slot instrument map, mute groups, and per-pad layer definitions (sample names, velocity ranges, volume, pan, tuning, and play mode) - Reads each WAV file's header to get the exact frame count (so MPC knows where each sample ends)
- Looks for a companion
.sxqdemo sequence file next to the.xpm. If found, the groove is translated into the project's sequence — pad hits, velocities, and BPM are all preserved. Notes that reference pads outside the kit's range are skipped cleanly. - Builds a
.xpjproject JSON using the device template as a structural base, injecting the pad assignments, all layer data, and sequence. Multi-layer pads write a fulllayersvarray with correct velocity ranges and the XPM's original play mode (zonePlayTime). With--no-multi-layer, only the first layer of each pad is written. - Gzip-compresses the result with the standard MPC
ACVSheader - Copies all layers' WAVs (deduplicated) into a
_[ProjectData]hidden folder alongside the.xpj
License
MIT
Something wrong or missing on this page?
Opens GitHub's editor; your change becomes a pull request and you're credited as a contributor.