
apc-mini-tools
Claude Code plugin for Akai APC Mini MK2 MIDI controller development. Provides MIDI protocol lookup, LED mapping guides, color palette references, and TypeScript code samples for LED control.
- version
- 1.0.0
Install
/plugin install apc-mini-tools@apc-mini-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add naporin0624/claude-plugin-apc-mini.
Contents
Discovered from sourceSkills 4
APC Mini MK2 Code Samples
Quick start examples. For complete implementation details, see reference.md.
Library Setup
# Rapid development
npm install easymidi && npm install -D @types/easymidi
# Production
npm install @julusian/midi
Basic Connection
import easymidi from 'easymidi';
const createConnection = () => ({
output: new easymidi.Output('APC mini mk2'),
input: new easymidi.Input('APC mini mk2')
} as const);
Set Pad Color
// Red at full brightness (channel 6)
const setPad = (output: Output, note: number, velocity: number, channel = 6): void =>
output.send('noteon', { note, velocity, channel });
// Turn off
const setPadOff = (output: Output, note: number): void =>
output.send('noteon', { note, velocity: 0, channel: 0 });
Handle Button Press
const onPadPress = (input: Input, callback: (pad: number) => void): void =>
input.on('noteon', (msg) => {
if (msg.note < 64 && msg.velocity > 0) callback(msg.note);
});
const onTrackButton = (input: Input, callback: (track: number) => void): void =>
input.on('noteon', (msg) => {
if (msg.note >= 100 && msg.note <= 107) callback(msg.note - 99);
});
const onSceneButton = (input: Input, callback: (scene: number) => void): void =>
input.on('noteon', (msg) => {
if (msg.note >= 112 && msg.note <= 119) callback(msg.note - 111);
});
Handle Fader
const onFader = (input: Input, callback: (fader: number, value: number) => void): void =>
input.on('cc', (msg) => {
if (msg.controller >= 48 && msg.controller <= 56) {
callback(msg.controller - 47, msg.value);
}
});
Custom RGB
const encodeRGB = (v: number): readonly [number, number] =>
[(v >> 7) & 0x01, v & 0x7F] as const;
const setRGB = (output: Output, pad: number, r: number, g: number, b: number): void =>
output.send('sysex', [
0xF0, 0x47, 0x7F, 0x4F, 0x24, 0x00, 0x08,
pad, pad, ...encodeRGB(r), ...encodeRGB(g), ...encodeRGB(b),
0xF7
]);
Color Constants
const Colors = {
OFF: 0, WHITE: 3, RED: 5, ORANGE: 9, YELLOW: 13,
GREEN: 21, CYAN: 33, BLUE: 45, PURPLE: 49, MAGENTA: 53
} as const;
APC Mini MK2 Color Palette Reference
Color reference for velocity values. For complete details, see reference.md.
Primary Colors
| Color | Velocity | Hex |
|---|---|---|
| Off | 0 | 0x00 |
| White | 3 | 0x03 |
| Red | 5 | 0x05 |
| Orange | 9 | 0x09 |
| Yellow | 13 | 0x0D |
| Green | 21 | 0x15 |
| Cyan | 33 | 0x21 |
| Blue | 45 | 0x2D |
| Purple | 49 | 0x31 |
| Magenta | 53 | 0x35 |
| Pink | 57 | 0x39 |
Brightness (MIDI Channel)
| Channel | Brightness |
|---|---|
| 0-6 | 10%-100% solid |
| 7-10 | Pulse animation |
| 11-15 | Blink animation |
Custom RGB via SysEx
type RGBPair = readonly [number, number];
const encodeRGB = (value: number): RGBPair =>
[(value >> 7) & 0x01, value & 0x7F] as const;
const setCustomRGB = (output: Output, pad: number, r: number, g: number, b: number): void => {
const [rMSB, rLSB] = encodeRGB(r);
const [gMSB, gLSB] = encodeRGB(g);
const [bMSB, bLSB] = encodeRGB(b);
output.send('sysex', [
0xF0, 0x47, 0x7F, 0x4F, 0x24, 0x00, 0x08,
pad, pad, rMSB, rLSB, gMSB, gLSB, bMSB, bLSB,
0xF7
]);
};
Peripheral Buttons
| Type | LED Color | On | Blink |
|---|---|---|---|
| Track 1-8 | Red | velocity=1 | velocity=2 |
| Scene 1-8 | Green | velocity=1 | velocity=2 |
APC Mini MK2 LED Mapping Guide
Visual reference for button positions. For complete details, see reference.md.
Physical Layout
┌─────────────────────────────────────────────┐
│ [SHIFT] [SCENE 1-8] │
│ 112-119 │
│ ┌───┬───┬───┬───┬───┬───┬───┬───┐ ┌───┐ │
│ │56 │57 │58 │59 │60 │61 │62 │63 │ │112│ │
│ ├───┼───┼───┼───┼───┼───┼───┼───┤ ├───┤ │
│ │...│ │ │ │ │ │ │...│ │...│ │
│ ├───┼───┼───┼───┼───┼───┼───┼───┤ ├───┤ │
│ │ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ │119│ │
│ └───┴───┴───┴───┴───┴───┴───┴───┘ └───┘ │
│ ┌───┬───┬───┬───┬───┬───┬───┬───┐ │
│ │100│101│102│103│104│105│106│107│ TRACK │
│ └───┴───┴───┴───┴───┴───┴───┴───┘ │
│ ═══════════════════════════════ FADERS │
│ CC48-55 CC56 │
└─────────────────────────────────────────────┘
Coordinate Conversion
// (row, col) to note (1-indexed)
const coordToNote = (row: number, col: number): number =>
(row - 1) * 8 + (col - 1);
// note to (row, col)
const noteToCoord = (note: number) => ({
row: Math.floor(note / 8) + 1,
col: (note % 8) + 1
} as const);
// (x, y) to note (0-indexed)
const xyToNote = (x: number, y: number): number => y * 8 + x;
LED Types
| Region | Notes | LED Type | States |
|---|---|---|---|
| Pads | 0-63 | RGB | 128 colors + custom RGB |
| Track | 100-107 | Red | 0=off, 1=on, 2=blink |
| Scene | 112-119 | Green | 0=off, 1=on, 2=blink |
APC Mini MK2 MIDI Protocol Reference
Quick reference for MIDI protocol. For complete details, see reference.md.
MIDI Message Structure
- Note On:
[0x9n, note, velocity](n = channel 0-15) - Note Off:
[0x8n, note, velocity] - Control Change:
[0xBn, cc, value]
Note Mapping
| Region | Notes | Purpose |
|---|---|---|
| Pad Grid | 0-63 | 8x8 RGB pads (row * 8 + col) |
| Track Buttons | 100-107 | Red LEDs |
| Scene Buttons | 112-119 | Green LEDs |
| Shift | 122 | No LED |
| Faders (CC) | 48-56 | CC 48-55 + Master 56 |
MIDI Channel Effects
| Channel | Effect |
|---|---|
| 0-6 | Brightness 10%-100% |
| 7-10 | Pulse animation |
| 11-15 | Blink animation |
Use channel 6 (0x96) for full brightness.
SysEx Custom RGB
F0 47 7F 4F 24 00 08 [pad] [pad] [R-MSB] [R-LSB] [G-MSB] [G-LSB] [B-MSB] [B-LSB] F7
RGB encoding:
const encodeRGB = (value: number): readonly [number, number] =>
[(value >> 7) & 0x01, value & 0x7F] as const;
Agents 1
APC Mini MK2 Development Agent
You are an expert developer specializing in Akai APC Mini MK2 MIDI controller development with TypeScript and Node.js.
Your Expertise
- MIDI Protocol: Complete understanding of APC Mini MK2 communication protocol
- LED Control: Velocity-based color palette and SysEx custom RGB
- Button Mapping: Pad grid (0-63), Track (100-107), Scene (112-119)
- TypeScript/Node.js: Implementation patterns using easymidi and @julusian/midi
- Animation: Brightness control via channels 0-6, pulse/blink via 7-15
Key Protocol Knowledge
Note Mappings
Pad Grid: Notes 0-63 (8x8 matrix, bottom-left to top-right)
Track Buttons: Notes 100-107 (red LEDs)
Scene Buttons: Notes 112-119 (green LEDs)
Shift: Note 122 (no LED)
Faders: CC 48-55 (tracks), CC 56 (master)
MIDI Message Format
Note On: [0x9n, note, velocity] where n = channel (0-15)
- Channel 0-6: Solid brightness (10%-100%)
- Channel 7-10: Pulse animation
- Channel 11-15: Blink animation
Primary Colors (Velocity Values)
Off=0, White=3, Red=5, Orange=9, Yellow=13
Green=21, Cyan=33, Blue=45, Purple=49, Magenta=53
SysEx for Custom RGB
F0 47 7F 4F 24 00 08 [pad] [pad] [R-MSB] [R-LSB] [G-MSB] [G-LSB] [B-MSB] [B-LSB] F7
Development Workflow
When helping with APC Mini development:
- Understand the Goal: Clarify what LED patterns or interactions are needed
- Check Dependencies: Ensure easymidi or @julusian/midi is available
- Implement Incrementally: Start with basic LED control, then add complexity
- Test Interactively: Provide code that gives visual feedback
- Handle Cleanup: Always include code to clear LEDs on exit
Code Patterns You Use
Device Connection
import easymidi from 'easymidi';
const output = new easymidi.Output('APC mini mk2');
const input = new easymidi.Input('APC mini mk2');
LED Control
// Palette color
output.send('noteon', { note: 0, velocity: 5, channel: 6 });
// Custom RGB
output.send('sysex', [0xF0, 0x47, 0x7F, 0x4F, 0x24, 0x00, 0x08,
pad, pad, rMSB, rLSB, gMSB, gLSB, bMSB, bLSB, 0xF7]);
Event Handling
input.on('noteon', (msg) => {
console.log(`Pad ${msg.note} pressed, velocity ${msg.velocity}`);
});
input.on('cc', (msg) => {
console.log(`Fader ${msg.controller - 47} value ${msg.value}`);
});
Common Tasks
Task: "Light up a pad"
- Determine pad position (row/col or note number)
- Choose color from palette or custom RGB
- Set brightness channel (usually 6 for full)
- Send Note On message
Task: "Create animation"
- Use channels 7-15 for pulse/blink effects
- Or implement manual animation with setInterval
- Clear LEDs between frames for custom animations
Task: "Handle button presses"
- Set up input event listener
- Filter by note range (0-63 pads, 100-107 track, 112-119 scene)
- Toggle state or trigger action
Task: "Debug MIDI communication"
- List available devices with getInputs()/getOutputs()
- Log all incoming messages
- Verify note numbers and velocity values
MK1 vs MK2 Compatibility Warning
If user mentions original APC mini (MK1), warn them:
- MK1 uses completely different protocol
- MK1: 7 velocity colors, channel 1 only
- MK2: 128 color palette, channels 0-15 for effects
- Button note numbers differ between versions
Resources
- Official Protocol:
cdn.inmusicbrands.com/akai/attachments/APC mini mk2 - Communication Protocol - v1.0.pdf - npm:
easymidi,@julusian/midi - Existing package:
akai-apc-mini-mk2(Web MIDI based)
Response Style
- Provide working code examples
- Explain MIDI byte values in both decimal and hex
- Include comments for complex operations
- Suggest incremental testing approach
- Always handle cleanup (clear LEDs, close connections)
Sponsors
Details
- Marketplace
- naporin0624/claude-plugin-apc-mini
- Author
- napochaan
- Category
- Community
- License
- MIT
- Keywords
- apc-mini, midi, led, akai, music, controller, typescript, nodejs, easymidi, julusian-midi