Skip to main content
skill CX Codex

mpc-plugin-ui — Claude Code skill for MPC interfaces

The mpc-plugin-ui Claude Code skill builds touch-screen layouts and Q-Link mappings for MPC plugins. It comes into play when an agent needs to arrange controls, set themes, or create a custom skin.

MIT ★ 200 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add inmusic-software/mpc-plugin-builder-sdk --skill mpc-plugin-ui -a claude-code
Open on GitHub

What mpc-plugin-ui does

The skill helps build an MPC plugin interface with ui.json or hand-authored TUI.json and Q-Links.json files. The simpler route uses the SDK’s UI kit and tools/build.py; parameter names come from build/params.json after a native build. Layouts can include pages, knobs, faders, switches, labels, themes, and controls that appear only for selected parameter values.

The full format allows custom images and precise placement. MPC checks object versions and required JSON keys; a mismatch can remove every plugin tab. Run python tools/validate.py plugins/<Name> after editing. Building and validation require Python and the SDK files; the manual format also relies on correct parameter and tab indices.

What it helps with

  • arrange plugin parameters across MPC pages
  • map Q-Link controls to knobs and faders
  • show a control only for selected parameter values
  • build a skin with custom images

Example prompts for the agent

  • Arrange this MPC plugin’s parameters into pages with ui.json.
  • Set up Q-Link mappings for this plugin’s knobs and faders.
  • Create a hand-authored skin with TUI.json and Q-Links.json.

How to install mpc-plugin-ui

1Skills CLI (Vercel)

npx skills add inmusic-software/mpc-plugin-builder-sdk --skill mpc-plugin-ui -a claude-code

2Manually: put the files in place

~/.claude/skills/mpc-plugin-ui/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mpc-plugin-ui/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mpc-plugin-ui

How do I install mpc-plugin-ui in Claude Code?

Run npx skills add inmusic-software/mpc-plugin-builder-sdk --skill mpc-plugin-ui -a claude-code. The skill file is at ~/.claude/skills/mpc-plugin-ui/SKILL.md.

What does mpc-plugin-ui do?

It helps design an MPC plugin’s screen UI and map hardware Q-Link controls to parameters. It supports a simple ui.json layout and full TUI.json and Q-Links.json skins.

What does mpc-plugin-ui need to work?

Building and validation require Python and the SDK files. To get the parameter list for ui.json, run a native build first.

Source text

SKILL.md · MIT
---
name: mpc-plugin-ui
description: Design or change an MPC plugin's touch-screen UI and hardware knob (Q-Link) mapping, via the simple ui.json layout (film-strip knobs, faders and switches from the SDK's UI kit) or the full Plugin Skins JSON format (TUI.json, Q-Links.json). Use when the user wants pages, knobs, faders, switches, layout, labels, themes, conditional controls, images or custom skins for their plugin.
---

# Plugin UI on the MPC

The MPC draws plugin UIs from JSON skins in `Plugin Skins/`. Two ways to produce them. Use A unless the user asks for something it cannot do.

## A. The simple way: `ui.json` with the UI kit (default)

Edit `plugins/<Name>/ui.json`; `tools/build.py` turns it into the skin files. Full format: `docs/ui-guide.md`; schema: `schemas/ui.schema.json`. **Always give every parameter a real widget (`knob`, `fader` or `switch`) rather than the generic `slider`**; the generic bar is a fallback for long choice lists only. The kit graphics live in `ui-kit/` (look at `ui-kit/preview.png`; `ui-kit/README.md` explains them).

```json
{ "kit": "mpc-red",
  "pages": [ { "name": "FILTER", "controls": [
      { "param": "Cutoff",  "widget": "knob" },
      { "param": "Reso",    "widget": "knob" },
      { "param": "Mode",    "widget": "switch" },
      { "param": "Env Amt", "widget": "knob", "polarity": "bipolar" },
      { "param": "Attack",  "widget": "fader" }, { "param": "Decay", "widget": "fader" },
      { "param": "Sustain", "widget": "fader" }, { "param": "Release", "widget": "fader" },
      { "param": "Shape",   "widget": "slider", "overlay": "menu" },
      { "param": "Rate",    "widget": "knob", "visibleWhen": { "param": "Sync", "choice": "Off" } },
      "empty", { "widget": "text", "text": "Modulation" } ] } ] }
```

- Controls are parameter **names** exactly as declared in code (not ids). `build/params.json` lists them after a native build.
- ≤ 16 controls per page, reading order into a 4 × 4 grid that matches the 16 hardware knobs. The MPC itself does not require a grid (hand-written skins place controls freely), but the knobs work in **groups of four** and the focus rectangle wraps a group, so arrange controls as blocks of four (a row of four or a column of four; Q-Link groups can be horizontal or vertical). Each block should be one coherent set, so the interface looks intentionally aligned; page names ≤ 8 characters; ≤ 32 pages.
- Widgets: `knob`, `fader`, `switch` (kit), `slider` (generic bar), `text`, `empty`. `polarity` (`auto` / `unipolar` / `bipolar`) on knobs and faders. `overlay: "menu"` for long choice lists. `visibleWhen` shows a control only for a given choice/bool value.
- `kit`: `mpc-red` (default), `amber`, `cyan`, `lime`, `violet`, `mono`, or `{ "theme": "...", "accent": "AARRGGBB" }`. One theme per plugin. The build renders it (cached in `build/`) and copies only the PNGs the layout uses.
- `switch` needs a bool or a choice parameter with ≤ 4 choices; the generator fails with a hint otherwise.
- Bool and choice parameters automatically get discrete steps and labels.

### Which widget (apply these, in order)

1. **Bool → `switch`.** Choice with 2–4 options → `switch` (captioned segments). Choice with 5+ → `slider` + `"overlay": "menu"`.
2. **Levels, mix, dry/wet, sends, envelope stages → `fader`.** Put A, D, S, R as four faders in one row or one column.
3. **Anything centred on zero (pan, tune, pitch offset, signed mod amounts) → `knob`, bipolar.** Auto-detection catches centre-zero defaults; set `"polarity": "bipolar"` when the range is signed but the default is not zero.
4. **Every other continuous parameter (cutoff, resonance, drive, time, feedback, rate, depth, width) → `knob`.**
5. `slider` only when the value text is the point (note names, divisions, ratios) or the list is long.
6. **Design in blocks of four.** One related set per row or column of four (envelope ADSR, filter cutoff/resonance/drive/tracking, delay time/feedback/tone/mix); never split a set across two blocks; use `empty` or a `text` heading rather than a stray control to complete a block. Choose rows or columns per page for whichever reads best, and stay consistent within a page.
7. Same role, same widget on every page. Top row of page 1 = the four controls touched first, knobs or faders, never switches. Group by signal flow; keep a section's mode switch beside the knobs it affects. Rarely used settings go on a `MORE` page; leave them out of the UI if they are rarely touched (still saved and automatable).
8. Theme: `mpc-red` unless the plugin has a character (`amber` drums/analogue, `cyan` delay/reverb/digital, `lime`/`violet` playful, `mono` utilities) or the user names a colour (`accent`).

Regenerate by rebuilding (`python tools/build.py plugins/<Name>`), or run the generator alone for a quick check:
`python tools/gen_ui.py --params plugins/<Name>/build/params.json --ui plugins/<Name>/ui.json --out "plugins/<Name>/build/<Manufacturer> - VST - <Name>/Plugin Skins" --kit-cache plugins/<Name>/build`. Read its NOTE lines (bipolar auto-detection) and fix any ERROR (it names the control and the allowed values).

## B. Full control: hand-written skins

Create `plugins/<Name>/skins/` containing `TUI.json`, `Q-Links.json` and any images; the build copies it verbatim and does not run the generator. Start from the generated files in `build/<folder>/Plugin Skins/` (they already contain the kit PNGs and the component definitions for knobs, faders, toggles and segments) and edit. `python tools/make_ui_kit.py --out plugins/<Name>/skins --theme cyan` renders a full kit there, including vertical faders, small knobs and LED buttons that `ui.json` does not use; `ui-kit/README.md` gives the TUI.json snippet for each. The complete format, every widget and every key, is in `docs/ui-reference.md`; read the relevant sections before editing. Critical facts:
- Every object has an integer `version` the MPC checks; wrong versions or a missing key make the **whole file fail**, and the plugin then shows no tabs at all.
- `"Parameter N"` handles are 0-based parameter indices; `Q-Links.json` `Tab`/`SubTab` are 1-based; knob values are 0-based indices or -1.
- Overlay widgets need the documented duplicate `version` keys; do not "fix" them.
- Film-strip frames and button images are drawn at their native pixel size, never scaled: size the entry bounds to the asset. Labels do not intercept touches, so captions can sit over buttons.
- Tab area is 1280 × 628; overlays 1280 × 800; fonts Titillium Web / Roboto / Nexa only; images PNG/JPEG relative to the file; colours `AARRGGBB`.
- Run `python tools/validate.py plugins/<Name>` after editing; it checks versions, indices, image presence and JSON validity.

Own knob artwork instead of the kit: `python tools/make_knob.py plugins/<Name>/assets/knob.png --frames 127 --size 90` then `"knobImage": "knob.png"` in `ui.json` (files in `assets/` are copied into `Plugin Skins/`).

© inmusic-software · MIT · inmusic-software/mpc-plugin-builder-sdk

Similar skills

All skills for Frontend and UI →

From the same set9

mpc-plugin-presets The mpc-plugin-presets Claude Code skill adds built-in presets to MPC plugins and explains .xpl preset files. It activates for requests about patches, programs, sound banks, or an initial patch. CX Codex +1 ★ 200repo stars mpc-plugin-package The mpc-plugin-package Claude Code skill creates a distributable ZIP for a built MPC plugin, including install instructions. It runs when a plugin needs to be shared, sent out, or prepared for release. CX Codex +1 ★ 200repo stars mpc-plugin-test mpc-plugin-test — a Claude Code skill that tests MPC plugins in the SDK host simulator before they reach hardware. It runs after builds and helps investigate silence, noise, crashes, glitches, or lost settings. CX Codex +1 ★ 200repo stars mpc-plugin-troubleshoot The mpc-plugin-troubleshoot Claude Code skill diagnoses MPC plugin faults and build or test tool issues. It handles reports of missing plugins, load failures, lost settings, audio glitches, and crashes. CX Codex +1 ★ 200repo stars mpc-plugin-build The mpc-plugin-build Claude Code skill builds MPC plugin projects into deployable folders and helps resolve build failures. It activates when a plugin needs compiling or a build reports errors. CX Codex +1 ★ 200repo stars mpc-plugin-dsp The mpc-plugin-dsp Claude Code skill guides DSP work on MPC plugins. It applies to changes involving synthesis, effects, MIDI, or plugin parameters. CX Codex +1 ★ 200repo stars mpc-plugin-new The mpc-plugin-new Claude Code skill scaffolds plugins for Akai MPC standalone hardware from plain-language descriptions. It activates for requests to start an instrument or audio effect project. CX Codex +1 ★ 200repo stars mpc-plugin-deploy The mpc-plugin-deploy Claude Code skill manages VST2 plugins on a real Akai MPC over the network. It activates for plugin installs, device updates, or plugin backups. CX Codex +1 ★ 200repo stars

Project sponsors

Companies that keep this analytics open