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-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add naporin0624/claude-plugin-apc-mini.

Contents

Discovered from source

Skills 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

ColorVelocityHex
Off00x00
White30x03
Red50x05
Orange90x09
Yellow130x0D
Green210x15
Cyan330x21
Blue450x2D
Purple490x31
Magenta530x35
Pink570x39

Brightness (MIDI Channel)

ChannelBrightness
0-610%-100% solid
7-10Pulse animation
11-15Blink 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

TypeLED ColorOnBlink
Track 1-8Redvelocity=1velocity=2
Scene 1-8Greenvelocity=1velocity=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

RegionNotesLED TypeStates
Pads0-63RGB128 colors + custom RGB
Track100-107Red0=off, 1=on, 2=blink
Scene112-119Green0=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

RegionNotesPurpose
Pad Grid0-638x8 RGB pads (row * 8 + col)
Track Buttons100-107Red LEDs
Scene Buttons112-119Green LEDs
Shift122No LED
Faders (CC)48-56CC 48-55 + Master 56

MIDI Channel Effects

ChannelEffect
0-6Brightness 10%-100%
7-10Pulse animation
11-15Blink 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:

  1. Understand the Goal: Clarify what LED patterns or interactions are needed
  2. Check Dependencies: Ensure easymidi or @julusian/midi is available
  3. Implement Incrementally: Start with basic LED control, then add complexity
  4. Test Interactively: Provide code that gives visual feedback
  5. 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"

  1. Determine pad position (row/col or note number)
  2. Choose color from palette or custom RGB
  3. Set brightness channel (usually 6 for full)
  4. Send Note On message

Task: "Create animation"

  1. Use channels 7-15 for pulse/blink effects
  2. Or implement manual animation with setInterval
  3. Clear LEDs between frames for custom animations

Task: "Handle button presses"

  1. Set up input event listener
  2. Filter by note range (0-63 pads, 100-107 track, 112-119 scene)
  3. Toggle state or trigger action

Task: "Debug MIDI communication"

  1. List available devices with getInputs()/getOutputs()
  2. Log all incoming messages
  3. 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