Документация
Важное ограничение
Формат .xpj закрытый. Без эталонного проекта нельзя гарантировать, что
синтезированный JSON откроется на конкретной прошивке. Поэтому инструмент:
- читает эталонный
.xpj через --inspect;
- клонирует эталонный
.xpj при экспорте (--template) и меняет только
документированные поля: имя, BPM, samples, pad-назначения, sequence и notes;
- не придумывает неизвестные поля;
- блокирует реальный экспорт без
--template с сообщением
«Требуется эталонный .xpj от MPC Sample для заполнения схемы»;
- позволяет посмотреть план и ограничения через
--dry-run даже без эталона.
Итоговая папка ресурсов: <ProjectName>_[ProjectData] — именно такой вариант
используют известные реализации для MPC Sample / MPC 3.x.
Зависимости
Основные функции работают на стандартной библиотеке Python 3.11+.
Для USB Audio нужен sounddevice (PortAudio):
python -m pip install -e ".[audio]"
Для drag-and-drop из Splice/OLE нужен tkinterdnd2:
python -m pip install -e ".[dnd]"
В Windows installer и portable ZIP оба пакета уже включены.
Установка как CLI
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
mpc-xpj-builder --version
mpc-xpj-builder --help
После установки доступна команда mpc-xpj-builder с теми же аргументами,
что и python main.py.
GUI
После установки:
mpc-xpj-builder-gui
Или из исходников:
python gui.py
GUI позволяет выбрать папку семплов, MIDI (необязательно), эталонный .xpj,
карту --map, имя/BPM/папку экспорта, посмотреть план (--dry-run) или создать
проект. Сборка идёт в фоне, лог показывается в окне.
Кнопка «Карта семплов…» открывает редактор:

- список WAV с длительностью/форматом;
- сетка всех 128 pads по банкам A–H (A1 внизу слева, как на MPC Sample);
- назначение выбранного WAV на pad;
gain, pan, tune, loop;
- автоназначение по числовому префиксу (
36_kick.wav) и именам
(kick, snare, hat, ride, crash, …);
- загрузка/сохранение
map.json;
- прослушивание WAV: выбранного в списке или назначенного на пад
(
▶ Прослушать / ■ Стоп);
- автовоспроизведение WAV при клике по файлу в списке;
- именованные пресеты карт: сохранить, загрузить, удалить;
- «Сохранить и применить» подставляет путь в поле
--map.
GUI сохраняет последние папки, MIDI, template, map, имя, BPM и флаги в:
%APPDATA%\mpc-xpj-builder\settings.json
При следующем запуске поля заполняются автоматически. GUI также хранит до 10
последних созданных проектов; выбранный проект можно открыть в проводнике.
Кнопка «Проекты…» открывает browser всех .xpj в папке экспорта:

В таблице показаны имя, BPM, число семплов, такты, число треков, дата изменения.
Оттуда можно открыть папку проекта или назначить проект эталоном. В окно
браузера можно перетащить папку с проектами или .xpj: папка откроется, а
перетащенный проект будет выбран в таблице.
Кнопка «Редактировать…» открывает существующий .xpj в отдельном окне:
- показывает прошивку, BPM, sequence, треки, семплы, число падов с семплами и
WAV в
_[ProjectData];
- позволяет изменить название проекта и BPM;
- «Сохранить копию…» создаёт новый
.xpj и копирует папку ресурсов;
- «Перезаписать с backup» атомарно сохраняет изменения и создаёт
<имя>.xpj.bak;
- все остальные поля
.xpj сохраняются без изменений.
Кнопка «Пады…» открывает редактор падов этого проекта.
Подробнее: руководство пользователя.
Кнопка «Sync…» открывает окно MIDI-синхронизации:

PC отправляет MIDI Clock, Start и Stop; MPC Sample следует за темпом и
транспортом. Подробная настройка — в разделе
«Синхронизация с MPC Sample».
Кнопка «Batch…» открывает окно batch-сборки:

В окне: общие template, output и BPM, таблица проектов,
добавление/изменение/удаление job, map и extended_notes, проверка
(--dry-run) и запуск всего batch. Манифест можно загрузить из .json и
сохранить обратно.
В главное окно можно перетащить:
- папку с WAV — подставится в
--samples;
.wav — подставится его папка;
.mid / .midi — MIDI;
.xpj — эталон;
.json — карта --map.
Поддерживаются как обычные файловые drops, так и OLE drag-and-drop
(Splice Desktop, Electron-приложения). Для OLE используется tkinterdnd2; в
Windows installer/portable он уже включён.
Если перетаскиваешь sample из Splice, приложение получает путь к WAV и
обрабатывает его как обычный .wav. В редакторе падов WAV можно перетащить
прямо на конкретный пад — sample импортируется в проект и назначается.
Если Splice отдаёт временный файл, проверь, что в поле «Папка с WAV»
подставилась нужная папка.
Редактирование существующего .xpj
Откройте «Проекты…», выберите проект и нажмите «Редактировать…».

Окно показывает:
- файл, прошивку и platform;
- название, BPM и sequence;
- число треков, семплов, падов с семплами;
- папку
_[ProjectData] и число WAV в ней.
Можно изменить название проекта и BPM. Остальные поля .xpj
сохраняются как есть, включая неизвестные для инструмента.
Сохранение:
- «Сохранить копию…» — новый
.xpj и копия папки ресурсов; исходник не
меняется;
- «Перезаписать с backup» — атомарная запись, перед ней создаётся
<имя>.xpj.bak.
Это файловый round-trip, а не совместное редактирование: не открывайте один
проект одновременно на MPC и в редакторе, чтобы не потерять изменения.
Редактирование падов существующего проекта
В «Проекты…» выберите проект и нажмите «Пады…».

Редактор использует папку _[ProjectData] проекта:
- показывает все пады банков A–H;
- подставляет текущие назначения из
.xpj;
- позволяет назначить WAV из папки ресурсов, снять назначение, изменить
gain, pan, tune, loop;
- поддерживает автоназначение и пресеты;
- «Сохранить в .xpj» пишет изменения с backup
<имя>.xpj.bak;
- «Копия .xpj…» создаёт новый проект и копирует папку ресурсов.
- WAV из Splice можно перетащить прямо на пад: файл копируется в
_[ProjectData], добавляется в samples проекта и назначается на пад.
Ограничения:
- меняются только pad-назначения и параметры падов;
- WAV должен уже входить в
samples проекта; добавление новых файлов в
существующий .xpj пока не поддерживается;
- изменения не отправляются на MPC в реальном времени — проект нужно
перезагрузить на устройстве.
Живой Pad MIDI
В редакторе падов есть Pad MIDI:
- На MPC:
Pad MIDI Out = Always, MIDI Port = USB.
- Выберите MIDI-вход
MPC Sample.
- Нажмите ▶ Слушать пады.
- Нажимайте пады на MPC — соответствующий пад подсвечивается в приложении,
показываются note и velocity.
Это монитор нажатий, а не live-синхронизация назначений. Изменения назначений
сохраняются в .xpj файлово.
Audition и MIDI Learn
- Audition — клик по паду в приложении отправляет MIDI-ноту на MPC, чтобы
услышать пад на устройстве. Нужен MIDI-выход
MPC Sample и на MPC
Pad MIDI In = On.
- MIDI Learn — выберите WAV в списке, включите
MIDI Learn, нажмите пад
на MPC. WAV назначится на этот пад с текущими gain/pan/tune/loop.
Затем сохраните проект в .xpj.
Audition включён по умолчанию; его можно отключить галочкой.
Синхронизация с MPC Sample
Кнопка «Sync…» умеет работать в двух режимах:
- PC → MPC — PC отправляет MIDI Clock, Start и Stop;
- MPC → PC — приложение слушает MIDI Clock от MPC и показывает BPM и
состояние транспорта.
PC — мастер
- Подключите MPC Sample к PC по USB-C.
- На MPC: SHIFT + PAD 8 → MIDI Config:
MIDI Port = USB;
MIDI Sync In = Midi Clock;
MIDI Sync Out = Off.
- В окне Sync… выберите режим PC → MPC.
- Выберите MIDI-выход
MPC Sample, укажите BPM и нажмите ▶ Start.
- ■ Stop останавливает транспорт.
MPC — мастер
- На MPC: MIDI Sync Out = Midi Clock,
MIDI Sync In = Off.
- В окне Sync… выберите режим MPC → PC.
- Выберите MIDI-вход
MPC Sample и нажмите ▶ Слушать.
- Запустите транспорт на MPC — приложение покажет входящий BPM и состояние.
Особенности:
- 24 импульса MIDI Clock на четверть;
- в режиме PC-мастера BPM можно менять на лету;
- синхронизация не sample-accurate: возможен небольшой джиттер;
- MIDI Clock синхронизирует транспорт и темп, но не заменяет
аудио-синхронизацию и компенсацию задержки.
Если MPC Sample не виден в списке MIDI-устройств, проверьте USB-кабель (не
только зарядный), режим MIDI Port = USB и закройте другие приложения,
которые могли занять MIDI-порт.
USB Audio

Кнопка «Audio…» открывает запись и мониторинг USB-аудио MPC Sample.
- Подключите MPC Sample по USB-C.
- Откройте «Audio…».
- Вход: «Микрофон (MPC Sample Audio)».
- Для мониторинга выберите выход наушников/колонок. Не выбирайте выход MPC
Sample — получится петля.
- ● Запись WAV… — запись в стерео WAV.
- ▶ Монитор — прослушивание без записи.
- ■ Стоп — остановка.
Поддерживается:
- выбор входа и выхода;
- 44100 / 48000 Hz;
- запись int16 PCM WAV;
- индикатор уровня и времени;
- остановка без зависания.
Ограничения:
- один стереопоток, без многодорожечной записи;
- без ASIO и без компенсации задержки;
- запись идёт через WASAPI/MME PortAudio; WDM-KS исключён, потому что не
поддерживает blocking API; если выбрана неподдерживаемая частота, появляется
Invalid sample rate — выберите другую.
Сборка .exe
PyInstaller нужен только для сборки, не для работы:
python -m pip install -e ".[dev]"
powershell -ExecutionPolicy Bypass -File .\scripts\build_exe.ps1 -Clean
powershell -ExecutionPolicy Bypass -File .\scripts\build_gui_exe.ps1 -Clean
powershell -ExecutionPolicy Bypass -File .\scripts\build_portable.ps1
Результаты:
dist\mpc-xpj-builder.exe
dist\mpc-xpj-builder-gui.exe
dist\mpc-xpj-builder-v1.11.0-win64.zip
Windows installer (нужен Inno Setup 6):
powershell -ExecutionPolicy Bypass -File .\scripts\build_installer.ps1
Результат:
dist\mpc-xpj-builder-v1.11.0-setup.exe
Как получить эталон
На MPC Sample создайте минимальный drum-проект (один drum-трек, одна sequence),
сохраните его и скопируйте полученный .xpj на компьютер. Этот файл должен быть
создан той же прошивкой, на которой потом будет открываться результат.
Команды
Проверка эталона (исходный файл не изменяется):
python main.py --inspect reference.xpj
После этого рядом появится reference_pretty.json.
План без создания файлов (можно запускать до получения эталона):
python main.py `
--samples "C:\Samples\Kit" `
--midi "C:\MIDI\drums.mid" `
--name "My Kit" `
--bpm 120 `
--output "C:\MPC Projects" `
--dry-run --verbose
Реальный экспорт:
python main.py `
--samples "C:\Samples\Kit" `
--midi "C:\MIDI\drums.mid" `
--name "My Kit" `
--bpm 120 `
--output "C:\MPC Projects" `
--template "C:\MPC Projects\reference.xpj" `
--verbose
Несколько --midi создают несколько sequence в одном проекте:
python main.py `
--samples "C:\Samples\Kit" `
--midi "C:\MIDI\verse.mid" `
--midi "C:\MIDI\chorus.mid" `
--name "My Kit" `
--bpm 174 `
--output "C:\MPC Projects" `
--template "C:\MPC Projects\reference.xpj" `
--verbose
Файлы также можно перечислить одной строкой через ;.
MIDI можно не указывать совсем — тогда создаётся kit с одной пустой sequence
на 1 такт. Это удобно, когда нужно только загрузить набор семплов на пады.
Экспорт с явной картой семплов:
python main.py `
--samples "C:\Samples\Kit" `
--midi "C:\MIDI\drums.mid" `
--name "My Kit" `
--bpm 174 `
--output "C:\MPC Projects" `
--template "C:\MPC Projects\reference.xpj" `
--map "C:\MPC Projects\my-kit-map.json" `
--verbose
Если карта использует банки B–H и MIDI-ноты за пределами 35–51:
python main.py `
--samples "C:\Samples\Kit" `
--midi "C:\MIDI\drums.mid" `
--name "My Kit" `
--bpm 174 `
--output "C:\MPC Projects" `
--template "C:\MPC Projects\reference.xpj" `
--map "C:\MPC Projects\my-kit-map.json" `
--extended-notes `
--verbose
Результат:
My Kit.xpj
My Kit_[ProjectData]\
Kick_01.wav
Snare_01.wav
...
Карта семплов --map
Пример лежит в examples/map.example.json. Рекомендуемый формат:
{
"samples": [
{
"file": "kicks/kick.wav",
"note": 36,
"gain": 0.9,
"pan": 0.5,
"tune": 0.0,
"loop": false
},
{
"file": "snares/snare.wav",
"note": 38,
"gain": 1.0,
"pan": 0.5
},
{
"file": "cymbals/ride.wav",
"pad": "B1",
"gain": 0.8
}
]
}
Допустим и компактный формат:
{
"kick": { "file": "kick.wav", "note": 36 },
"snare": { "file": "snare.wav", "note": 38 }
}
Правила:
file — путь относительно папки --samples; .. и абсолютные пути запрещены;
note — MIDI-нота; по умолчанию 35..51, с --extended-notes — 0..127;
pad — A1..H16, можно использовать вместо note для любого из 128 падов;
gain — 0..1;
pan — 0..1;
tune — полутона, -24..24 (дробные значения раскладываются в coarse/fine);
loop — bool;
- один и тот же WAV можно назначить на несколько падов;
- WAV, не упомянутые в карте, игнорируются;
- дубли
note/pad запрещены.
Правила назначения
- По умолчанию поддерживаются MIDI-ноты 35..51.
--extended-notes разрешает MIDI-ноты 0..127 (все банки A–H).
- Максимум 128 WAV-файлов.
- WAV: RIFF/WAVE, PCM или IEEE float, mono/stereo, 8/16/24/32-bit PCM или
32-bit float, 8–192 kHz.
- WAV-имена приводятся к ASCII
[A-Za-z0-9_], без пробелов; при конфликте
добавляется _01, _02, ...
- Без
--map семплы сортируются по относительному пути; уникальные ноты — по
возрастанию. Первые N семплов назначаются N уникальным нотам, остальные —
свободным падам.
- С
--map используются только файлы из карты; лишние WAV игнорируются.
- Карта
pad <-> MIDI note берётся из padNoteMap эталонного проекта.
Для dry-run без эталона используется наблюдаемая карта MPC Sample:
A1–A16 = 36–51, B1 = 52, …, H16 = 35.
- Каждый MIDI-файл превращается в отдельную MPC sequence;
trackClipMaps
каждой sequence содержит одну строку с клипами всех сохранённых треков.
Инфраструктурные треки (submix/output) из эталона сохраняются.
- Без MIDI создаётся одна пустая sequence на 1 такт; семплы назначаются на
пады без MIDI-нот.
Batch-режим --batch
Один JSON-манифест — несколько проектов. Пример: examples/batch.example.json.
{
"template": "D:\\MPC-Sample\\Projects\\reference.xpj",
"output": "D:\\MPC-Sample\\Projects",
"bpm": 174,
"jobs": [
{
"name": "Kit A",
"samples": "C:\\Samples\\Kit A",
"midi": "C:\\MIDI\\kit-a.mid",
"map": "C:\\Samples\\Kit A\\map.json"
},
{
"name": "Kit B",
"samples": "C:\\Samples\\Kit B",
"midi": "C:\\MIDI\\kit-b.mid",
"bpm": 160
}
]
}
Запуск:
python main.py --batch "C:\MPC Projects\batch.json" --dry-run
python main.py --batch "C:\MPC Projects\batch.json" --verbose
Правила:
- относительные пути в манифесте считаются от папки манифеста;
template, output, bpm можно задать глобально и переопределить в job;
map и extended_notes задаются на уровне job;
- все job сначала проходят preflight;
- при ошибке preflight ни один проект не записывается;
- при ошибке записи уже созданные проекты не откатываются;
- дубли имён/целей запрещены.
Коды возврата
| Код |
Значение |
| 0 |
успех / dry-run |
| 2 |
ошибка аргументов CLI |
| 3 |
ошибка валидации входных данных |
| 4 |
схема требует эталонный .xpj |
| 5 |
ошибка файловой системы / записи |
| 1 |
непредвиденная ошибка |
Известные неизвестные
Список ведётся в xpj_schema.py (unresolved_fields()):
- версия и platform в заголовке;
- top-level UI/controller/mixer-поля (
data.*);
programPads, base.*, custom Q-Link и macro-scene поля;
- полная структура
drum.instruments[] (synthSection, articulations,
chopProperties, padEffects, modLinks, noteCounters, random seeds);
padNoteMap и семантика pad index на конкретной прошивке;
loadImpl и metadata семплов;
- служебные поля sequence/clip/event;
data.mixer;
- версии схемы и точное имя ProjectData-папки.
Всё перечисленное сохраняется из --template, а не синтезируется.
Калибровка по эталону 1.3.0.12
Проверено на реальном пустом проекте MPC Sample:
trackClipMaps — ровно одна строка, внутри неё по одному клипу на каждый
трек (Drum, Out 1/2, Out 3/4, Submix 1);
- у слоя
sampleEnd = 0, а длина задаётся sliceInfo.End = frames - 1;
sliceIndex = 129;
sampleName и sampleFile — без расширения в имени семпла;
loadImpl встречается как 0, так и 1;
- порядок клипов в строке сохраняется из эталона.
Loop-калибровка по пересохранённому MPC Sample проекту:
- loop включается через
instrument.triggerMode = 3;
layer.loop остаётся false;
layer.loopMode = 1;
layer.layerLoopModeOverridesSliceLoopMode = true;
sliceInfo.LoopMode = 1;
sliceInfo.LoopCrossfadeLength = -1.
Hardware test kit
Сгенерировать набор проектов для ручной проверки на MPC Sample:
python scripts/make_hardware_test_kit.py `
--template "D:\MPC-Sample\Projects\ 0.xpj" `
--output "D:\MPC-Sample\Projects\XPJ Hardware Test"
Создаются:
XPJ Test Notes — 17 нот 35..51;
XPJ Test Loop — loop-семпл;
XPJ Test Long — длинный one-shot;
XPJ Test 128 — 128 WAV;
README-HARDWARE-TEST.md — чек-лист.
Подробности: docs/HARDWARE_TEST.md.
Тесты
python -m unittest discover -s tests -v
Покрыты: карта --map, конфликты/ошибки карты, batch-манифест и preflight,
running status и note-on velocity 0 в MIDI, tempo/time signature, dry-run,
экспорт с mapped-семплами, sampleEnd, sliceInfo.End, gain/pan/tune/loop,
GUI-аргументы, project browser, drag-and-drop routing, pad-based карта,
extended-ноты, автоназначение, настройки GUI, recent projects, native drag-and-drop,
пресеты карт, batch GUI, несколько sequence, прослушивание WAV, round-trip
существующего .xpj, MIDI Clock, USB Audio, пады проекта и игнорирование
лишних WAV. Всего 124 теста.
Статус проверки
Код компилируется и проверен на синтетических WAV/MIDI, реальном эталонном
.xpj и реальных семплах (чтение, dry-run, экспорт, повторный --inspect).
Hardware: PSX DnB Kit успешно открыт на MPC Sample, все 32 one-shot
семпла загрузились. Это подтвердило pad-based mapping и загрузку банка B.
XPJ Test Long и XPJ Test 128 также прошли проверку. Loop-фикс подтверждён
проектом XPJ Loop Final: loop играет сразу после загрузки, без ручного
переключения. Музыкальный PSX DnB Break на 8 падов также подтверждён.
Несколько sequence в одном проекте пока проверены структурно и через
--inspect; на самом MPC Sample эта комбинация ещё не тестировалась.
Источники наблюдений
kurtjcu/MPC-project-file-definitions — публичная база полей MPC 3.x .xpj.
tarikcampos/MPC-Sample-Toolkit и WorldLinkStudio/mpcsample — открытые
реализации, подтверждавшие загрузку проектов на MPC Sample.
- Локальный эталонный
.xpj целевой прошивки — единственный источник истины
для полей, помеченных как неизвестные.