MPC Sample UI Toolkit
by garrettjwilke · garrettjwilke/mpc-ui-toolkit
A C library for drawing MPC Sample interfaces, with text, shapes, buttons and layout helpers for the device's 320×240 display.
About
A small C library for drawing on the Akai MPC Sample. The panel is always 320×240. Colors are uint32_t values, 0xRRGGBB. Position and size are pixels, origin at the top left. Nothing is drawn unless the call asks for it.
zig cc in the Makefile is only the cross-compiler, the same way the firmware makefile uses it. The source is C.
Draw
ui_clear(ui, 0x1a2744);
ui_box(ui, x, y, w, h, (struct ui_paint){
.fill_set = 1, .fill = 0x2244aa,
.border_set = 1, .border = 0xf0f0f0, .border_px = 3,
});
ui_text(ui, x, y, "clear", 0xe8e8e8, 1); /* scale 1 is 6x12 */
ui_text(ui, x, y, "Two", 0xe8e8e8, 2); /* scale 2 is 8x16 at 2x */
ui_highlight(ui, x, y, w, h, 0xff44aa, 3);
struct ui_button st = {
.fill = 0x303840, .text = 0xe8e8e8,
.border_set = 1, .border = 0x505868, .border_px = 1,
.highlighted = focused, .highlight = 0xffb000, .highlight_px = 3,
};
if (ui_button(ui, x, y, w, h, "Off", st, in)) { /* encoder press on the highlighted button */ }
fill_set or border_set at 0 skips that part. ui_highlight draws an outline on top of what is already there.
Optional starting colors: UI_BG 0x101014, UI_TEXT 0xe8e8e8, UI_HL 0xffb000, UI_BOX 0x303840.
Widgets
Each widget stays inside the rectangle you pass.
ui_soft_keyssplits the rect into three keys for B1, B2, and B3. These buttons have no LEDs.feedbackchooses the light:UI_SOFT_STICKY(the default) keeps the last press lit,UI_SOFT_HOLDstays lit while the key is down, andUI_SOFT_FLASHlights forflash_msafter the press and then goes dark even if the finger stays. A flash setsui.wake_msso the frame loop can draw the key going dark.ui_feedbackis the same rule for a control an app draws itself.ui_knobsdraws three value boxes for K1, K2, and K3. You own the threefloatvalues (0..1) and the text callback. The encoder moves focus. Plus and Minus step bystep. A knob does not jump: it follows only after it crosses the current value.struct ui_knob_state.laststarts at -1.ui_listscrolls rows.row_his the row size. The encoder moves, encoder press returns that row, and the current row gets an outline plus an optional fill. When the rows do not fit, a bar on the right shows where that window sits in the list. The thumb uses the highlight color.ui_padsfits a 4×4 grid to the rect, pad 1 at the bottom left. A hit stores a color (blue when soft, red when hard). Pressure brightens the cell while it is held.ui_griddraws a columns-by-rows board in the rect. You pass the labels and, if you want, a fill for each cell.blockdraws a heavier line every N cells, which is how a Sudoku board marks its 3×3s.cursoroutlines one cell.band_celloutlines the block that contains that cell.ui_pad_modesretargets a cluster of pads while another pad is held. You list the cluster in logical order, the hold for each mode, and any tap pads. The first hold that is down wins. A cluster hit returns that slot only while a hold is down. A tap returns only when none is. A hit does not replace the color. Owned pads are sent to the LEDs on that frame, and a held pad brightens.selectedpaints one cluster slot inselected_colorwhile a mode is armed.ui_menushows rows only while a button combination is held. Let go and the rows disappear. The wheel moves. Encoder press chooses the highlighted row. Each row can also name a pad and a key.ui_text_editorprovides a full-featured single-line text input modal/screen using the 16 MPC pads in a bottom-to-top layout matching the physical hardware pads (Pad 1 at bottom-left:a-cthrough Pad 8:wxyz, Pads 9-11: numbers, Pad 13:DEL, Pad 15:SPC, Pad 16:ACCEPT). The encoder wheel and-/+buttons move the cursor left and right; holding Shift while moving highlights and selects text. Typing on a pad replaces or cycles the character under the cursor. Clicking the encoder button appends a new character space and advances the cursor to the right, letting the user type the next character. Holding Shift switches to uppercase letters and alternate symbols. Hardware soft keys B1, B2, and B3 provide Cancel, Space, and OK (or Cut, Copy, Paste while Shift is held). Soft button B3 confirms (UI_TEXT_OK), and B1 cancels (UI_TEXT_CANCEL).ui_usb_sdis an opt-in full-screen mode that shares the SD card with a computer over USB. Linkusb_sd.cand callui_usb_sd_init, thenui_usb_sdevery frame. The first frame draws "Preparing..." and asks for another frame immediately. The next frame unmounts the card, runsaz0x-usb-gadget switch sd-access, and binds the card. B1, encoder press, or the Exit button starts the eject. The following frame restores the normal gadget and returnsUI_USB_SD_DONE. A failed start shows the error until the user leaves, which returnsUI_USB_SD_FAILED.ui_usb_sd_is_activeis true while the card is bound; callui_usb_sd_stopon reboot, shutdown, or quit.UI_USB_SD_LABELandUI_USB_SD_HINTare the list-row strings. The widget does not insert itself into an app menu. Passui_usb_sd_style_default, or fillstruct ui_usb_sd_stylefrom the app theme. Host tests callui_usb_sd_set_mockso start and stop never touch a real card.ui_helpdraws a help, tutorial, or dialogue window from Markdown pages compiled into the program. The app writes a folder of pages, turns that folder into one C file, and links it. Each page is text, pictures, and links. A link such as[Paste](paste.md)opens another page in that set. A link whose page is not in the set is ordinary text..., absolute paths, andhttp:are ignored, and a picture has to be a PNG or PPM no larger than 640 by 480. The wheel scrolls the page. Shift scrolls faster, lights pads 1 through 6, and draws each pad combo on its link. Those pads are red, green, blue, yellow, teal, and purple. The border uses that color, and the number is white. Up to six links use one pad. More links use a two-pad combo from those six. Press the combo while Shift is held. The page does not jump to the link. B1 goes back, B2 returns to the start page, and B3 closes. A NULL close label leaves that key empty, which is the dialogue case: the links are the replies, and the app decides when to leave. The face is the 6×12 font. Headings and**strong**use the highlight color. Fenced code is a filled block. Zero thestruct ui_helpbefore the first open, and callui_help_closewhen the app is done with it.
mpc-ui-toolkit/tools/embed-help.py help build/help_pages.c help_pages
extern const struct ui_help_file help_pages[];
extern const int help_pages_count;
ui_help_open_files(&help, help_pages, help_pages_count, "index.md");
ui_help(ui, 0, 0, UI_W, UI_H, &help, ui_help_style_default(), in);
ui_help_open still reads a directory. That is for a host check. A device build uses ui_help_open_files, so the pages travel inside the one program.
ui_filebrowserprovides a complete, shared file navigation and management API for all MPC applications. Features can be mixed and matched via bitmask options (UI_FB_OPT_COPY,UI_FB_OPT_PASTE,UI_FB_OPT_MOVE,UI_FB_OPT_RENAME,UI_FB_OPT_DELETE,UI_FB_OPT_MKDIR,UI_FB_OPT_HIDE_DOTFILES,UI_FB_OPT_TOGGLE_DOTFILES,UI_FB_OPT_DIRS_ONLY,UI_FB_OPT_SELECT_DIR,UI_FB_OPT_SHOW_SIZE,UI_FB_OPT_CONFIRM_DELETE). Includes presets (UI_FB_PRESET_READONLY,UI_FB_PRESET_DEFAULT,UI_FB_PRESET_FULL), extension filtering (.wav,.mpcmd, etc.), custom filter callbacks, and an internal clipboard for file copy/move operations with automatic name collision handling. Storage Sandboxing: Users can never see or escape to root (/). Access is strictly constrained to external SD card (/media/<SDCARD>, auto-detected) and internal storage (/data). The top-level Storage Locations view lets the user choose between Internal and External storage; navigating up (..or B1) from a drive root returns to Storage Locations rather than escaping to the OS filesystem. Apps can optionally provideinitial_pathto start in a specific folder, orforced_rootto lock browsing strictly to a single directory tree. Hardware soft keys B1, B2, and B3 provide [Up / Parent / Exit], [Actions Menu], and [Select / Open] (with Shift alternatives for New Folder, Paste, and Dotfiles Toggle). Encoder wheel navigates, encoder press enters directories or selects files, and modal dialogs integrate seamlessly withui_text_editorfor naming/renaming and confirmation alerts for deletion.
Hardware UI Consistency Rules
Physical buttons B1, B2, and B3 sit directly above the 320×240 display. Any widget or screen offering soft key actions for B1, B2, and B3 must place the soft keys bar at the top of the screen (typically y = 0..8, h = 24..32) so on-screen touchpoints visually and spatially align with the physical buttons above them.
Similarly, the MPC's 16 pads sit directly below the display. On-screen pad legends are drawn in the lower portion of the display with Pad 1 at the bottom-left and Pad 16 at the top-right, creating an exact 1:1 spatial map of the physical pads.
hold is every button that has to be down. items, n, and hold can be replaced on any frame. ui_menu_prepare fills those in once, and leaves a later change alone. pad -1 uses the row number (pad 1 is the first row). A row's key is an IN_* button, or -1.
enum { APP_SAVE = 1, APP_QUIT = 2 };
static const struct ui_menu_item items[] = {
{.label = "Save", .id = APP_SAVE, .pad = 4, .key = IN_B2},
{.label = "Quit", .id = APP_QUIT, .pad = -1, .key = -1},
};
struct ui_menu menu = {.title = "Menu", .items = items, .n = 2};
menu.hold = (1u << IN_SHIFT) | (1u << IN_ERASE); /* this app chooses the buttons */
struct ui_menu_style st = ui_menu_style_default();
if (!ui_menu_open(&menu, in)) {
/* wheel and pads belong to the screen under the menu */
}
int id = ui_menu(ui, 48, 44, 224, 152, &menu, st, in);
if (id == APP_SAVE) { /* the app saves */ }
if (id == APP_QUIT) ui_quit(ui);
ui_quit asks app_run to exit after this frame. The app calls it when its own UI decides to leave. Nothing in the toolkit binds that call to a button or a chord. A frame that returns non-zero also exits.
While the menu is open its pads light. Releasing the combination turns those pads off. input.held is the buttons that are still down, so a combination can span more than one frame. Row ids belong to the app. -1 means nothing was chosen.
Examples
Each file is one screen and one idea. make builds fifteen static binaries in bin/ and a zip next to each one: clear, boxes, buttons, highlight, soft-keys, knobs, list, pads, anim, sudoku, text-edit, diagnostics, filebrowser, usb-sd, help. Load bin/<name>.zip with mpc-boot-thingy. Object files and the unpacked autorun/ folders stay in build/.
help compiles a long Passerine sample from examples/help/ into the program. The wheel scrolls, Shift scrolls faster and shows a pad combo on each link, and that combo opens it. Names that have no page are left as ordinary text. B1 B2 B3 are Back, Home, and Close. Shift and Erase open the menu. The zip is that one binary. There is no pages folder beside it.
usb-sd opens USB SD card access from a single list row, then returns to that row when the computer ejects the card or the start fails.
filebrowser provides an interactive, full-featured file manager showcasing directory navigation, file copy/cut/paste, renaming, deletion confirmation, folder creation, and hidden dotfiles toggle.
diagnostics provides a comprehensive hardware and input testing suite. It visualizes and tests all 24 front-panel buttons (illuminating corresponding hardware LEDs on press), all 16 RGB velocity and aftertouch pads (with real-time RGB pressure feedback), K1–K3 knobs, fader, main volume knob, rotary encoder wheel rotation and click, track select LEDs A–H (cycled with Minus/Plus buttons), hardware VU level meters (driven by fader position), and displays a live 4-line event monitor showing raw MIDI note numbers and values.
text-edit demonstrates interactive single-line text input for renaming items using pad multi-tap, cursor wheel navigation, Shift selection, and soft keys B1-B3.
sudoku is a game on ui_grid and ui_pad_modes. The top-left 3×3 of pads is the cluster. Hold pad 16 and tap it to pick a block, pad 12 to pick a cell inside that block, and pad 8 to enter 1–9. Hold pad 1 and tap the cluster to mark a possible number. Those marks sit under the pad legend. Pad 3 clears the marks on the selected cell, and pad 4 clears the digit. The middle top button undoes. Hold the restart pad, or hold the top-right New button, then press the middle button to confirm. A matching pair of entered digits turns red. A clue does not. Leaving uses the same menu as the other examples.
anim slides a block along a track and asks for another frame in 16 ms. The panel is an SPI ST7796S. One update carries every changed row. A full 320×240 frame is about 50 ms on the wire, so a full-screen wipe stays near 20 frames per second. The block is small, and only the rows it leaves and enters are sent.
Each example leaves from a menu it owns. examples/menu.h is that menu. Most of them show it while Shift is held. The filebrowser example shows it while Stop is held, because that screen already uses Shift. Resume is the first row. Choosing Quit calls ui_quit. The process then drops the screen and turns the pad lights off so the boot menu can draw again. Change the hold mask or the rows in that file, or build another struct ui_menu and call ui_quit for the row that should leave.
make test # build/ui-test, host pixel checks
make preview # build/shots/*.ppm
make # bin/<name> and bin/<name>.zip
Autorun package
make writes bin/<name>.zip for every example. The zip holds one autorun/ folder. The stock runner starts that folder when the card is inserted. Another app, after it has the toolkit as a submodule and has built its own binary, calls the same script:
mpc-ui-toolkit/tools/pack-autorun.sh \
--name my-app \
--bin build/bin/my-app \
--out build
That writes build/autorun/ and build/my-app.zip. The zip's entries are autorun/..., even though the folder on disk lives under build/.
autorun.json has askQuestion set to false, so the runner starts the script with no dialog. autorun.check is the stock runner's hash of autorun.json and autorun.sh. A mismatch will not boot. Run the script again after a rebuild. Do not edit the generated files.
On the device the script copies the program to /run and starts that copy, because the card is mounted noexec. It sets MPC_APP_DIR to the package directory on the card. Keep saves there. From the boot menu the program stays in the foreground, so the menu gets the screen back when it exits. On a plain card it is started with systemd-run, so the stock runner can return, and the stock app is stopped until the program exits.
Copy <out>/autorun/ onto the card, or add the zip with mpc-boot-thingy:
setup.sh --SD "/path/to/card" --add bin/clear.zip
For the command above, the zip is build/my-app.zip. --add path copies one more file into autorun/ under its own name. Repeat it for each file.
The script needs python3, and shasum or sha256sum.
The font is Terminus, generated into src/font.h. The license is assets/fonts/OFL.txt.
Recent releases
- v1.0.0 Oct 24, 2026Release on GitHub ↗
Release notes
Static aarch64 Linux binaries. Unzip and load one from
bin/with mpc-boot-thingy.
Something wrong or missing on this page?
Opens GitHub's editor; your change becomes a pull request and you're credited as a contributor.