An easy-to-use and feature-rich package for interacting with one or multiple Apc Mini's (Mk2) from Akai Professional.
npm install apc-mini-mk2
   
Need help? Feel free to join our support server and we will help you fruther!
npm install apc-mini-mk2
`> ### ❤️ Sponsors
> We're still searching for sponsors! Would you like to sponsor us?
📌 Features
- ⚖️ Lightweight — Minimal footprint, maximum performance.
- 🚨 Built with TypeScript — Enjoy full type safety and intelligent autocompletion.
- 🎨 Full RGB Color Support — Display awesome RGB lights with full (0-255) RGB.
- 🔢 Multiple Controllers — Use multiple controllers at the same time.
- ⚙️ Highly Customizable — Choose your own coordinate system, limits & more.
- 🪩 Built-in Effects — Choose between 20+ built-in pulse, flicker & fade effects.
- 📌 Coordinates — Use a location index or
(x,y) coordinates for inputs & outputs.
- 🪦 Preserves State — Preserve the state of the LEDs when disconnected.
- 📢 Event Driven — Listen to events and define your own custom reactions.
- 🎯 Input Polling — Fetch the current state of sliders & buttons without events.
- 🎬 Startup Animations — Display RGB animations while the device is connecting.
- ✅ Multi Platform — Tested on MacOS & Windows. Linux is untested but should work.📸 Examples
> Images will be added to the README soon!
🛠️ Quick Usage
> TIP: Detailed examples are available in the ./examples/ directory in the Github repository.
`ts
const {APCMiniController,rgbToHex,hexToRgb} = require("apc-mini-mk2")
//import {APCMiniController,rgbToHex,hexToRgb} from "apc-mini-mk2"const apcMini = new APCMiniController(2) //max 2 controllers
//list all connected controllers
apcMini.listAvailableControllers()
//listen for errors
apcMini.on("error",(err) => {
console.error(err)
})
//listen for connected & disconnected controllers
apcMini.on("connect",(id,midiName) => {
console.log("Apc with id "+id+" and name "+midiName+" connected succesfully!")
})
apcMini.on("disconnect",(id,midiName) => {
console.log("Apc with id "+id+" and name "+midiName+" disconnected!")
})
//automatically connecting APC Mini Mk2 controllers
apcMini.startAutoConnect()
// RGB LIGHT EXAMPLES:
//(1) first light: static cyan
//(2) light 2 & 3: static red
//(3) last light & (3,3): blinking white
//(4) first 3 lights on second controller: fading-out blue
apcMini.setRgbLights(0,0,"brightness_100","static","#00ffff")
apcMini.setRgbLights(0,[1,2],"brightness_100","static","#ff0000")
apcMini.setRgbLights(0,[63,{x:3,y:3}],"brightness_10","blinking_1/2","#ffffff")
apcMini.setRgbLights(1,[0,1,2],"brightness_100","fade_out_1/2","#0000ff")
//set & configure horizontal/vertical sidebar lights
apcMini.setHorizontalLights(0,[0,2,3,6],"blink")
apcMini.setVerticalLights(1,[0,1,2,3,4,7],"on")
//listen for button events
apcMini.on("padButtonChanged",(id,location,coords,pressed,shift) => {
console.log("pad button event:",pressed,location,coords,"withShift: "+shift,"controller: "+id)
})
apcMini.on("horizontalButtonChanged",(id,location,pressed,shift) => {
console.log("horizontal button event:",pressed,location,"withShift: "+shift,"controller: "+id)
})
apcMini.on("verticalButtonChanged",(id,location,pressed,shift) => {
console.log("vertical button event:",pressed,location,"withShift: "+shift,"controller: "+id)
})
apcMini.on("sliderChanged",(id,location,value) => {
console.log("slider changed:",location,value)
})
//poll current state of buttons & sliders
console.log("horizontal buttons:",apcMini.getHorizontalStates(0))
console.log("rgb pads:",apcMini.getPadStates(0))
console.log("sliders:",apcMini.getSliderValues(0))
`🧩 API Reference
> View full examples in Github Repository---
$3
This is the main class used to connect, manage and control APC Mini Mk2 devices.
Almost all described functions are a method of this class.> Construction Parameters:
>
maxControllerAmount? (number): Maximum simultaneously connected controllers. Default: 1*
> * manualIdAssignmentsEnabled? (boolean): Require manually selecting device IDs by pressing a horizontal button.
> * coordinates? (APCMiniCoordinateSystem): Custom coordinate orientation of the 8×8 RGB grid.
> lightBpm? (number): BPM used for blinking/pulsing modes. Default: 60*$3
- (lightBpm: number) The BPM used for pulsing/blinking light effects.
- (maxControllerAmount: number) Maximum allowed connected APC Mini devices.
- (manualIdAssignmentsEnabled: boolean) Enables manual device ID assignment via pad press during connection.
- (coordinates: APCMiniCoordinateSystem) The coordinate system mapping used for pad grid orientation. ---
$3
#### function startAutoConnect(): void
Begins automatically detecting and connecting APC Mini controllers until the max limit is reached.#### function
stopAutoConnect(): void
Stops auto-connecting new controllers.#### function
manualConnect(midiName, customId?): boolean
Connects to a specific controller by MIDI name.
Returns false on failure.
> Parameters:
> *
midiName (string): Name from listAvailableControllers().
> * customId? (number): Optional forced ID number.
#### function
manualDisconnect(midiNameOrId): boolean
Disconnect a controller by MIDI name or ID.
Returns false on failure.> Parameters:
> *
midiNameOrId (string | number): The controller name or ID.
#### function
manualDisconnectAll(): boolean
Disconnects all currently connected controllers.
Returns false on failure.#### function
listAvailableControllers(): string[]
Returns all unused / available APC Mini Mk2 device names.#### function
listConnectedControllers(): string[]
Returns all currently connected controller names.#### function
listUsedIds(): number[]
Returns all assigned controller IDs.#### function
getConnectedAmount(): number
Returns how many controllers are currently connected.#### function
setBpm(bpm): void
Sets the blinking/pulsing BPM for all RGB LED effects.> Parameters:
> *
bpm (number): New BPM value.---
$3
Each .on(event, callback) registers a listener for one of the following events:#### event
connect
Triggered when a controller successfully connects.> Callback:
(controllerId: number, midiName: string) => void#### event
disconnect
Triggered when a controller disconnects.> Callback:
(controllerId: number, midiName: string) => void#### event
error
Triggered upon connection errors or failures with lights or buttons.
If the error is specific to a controller, it will include the ID.> Callback:
(err: string, controllerId?: number) => void---
$3
#### event
padButtonPressed
Triggered when one of the 64 pad buttons has been pressed.
The location & coordinates correspond to the selected coordinate system.> Callback:
(controllerId: number, location: number, coordinates: APCMiniCoordinates, usingShift: boolean) => void
> Location Values: (0-63)#### event
padButtonReleased
Triggered when one of the 64 pad buttons has been released.
The location & coordinates correspond to the selected coordinate system.> Callback:
(controllerId: number, location: number, coordinates: APCMiniCoordinates, usingShift: boolean) => void
> Location Values: (0-63)#### event
padButtonChanged
Triggered when one of the 64 pad buttons has changed states (pressed/released).
The current state of the button is available in the pressed parameter.> Callback:
(controllerId: number, location: number, coordinates: APCMiniCoordinates, pressed: boolean, usingShift: boolean) => void
> Location Values: (0-63)---
$3
#### event
horizontalButtonPressed / verticalButtonPressed
Triggered when one of the 8 horizontal or vertical buttons has been pressed. > Callback:
(controllerId: number, location: number, usingShift: boolean) => void
> Location Values: (0-7)#### event
horizontalButtonReleased / verticalButtonReleased
Triggered when one of the 8 horizontal or vertical buttons has been released. > Callback:
(controllerId: number, location: number, usingShift: boolean) => void
> Location Values: (0-7)#### event
horizontalButtonChanged / verticalButtonChanged
Triggered when one of the 8 horizontal or vertical buttons has changed states (pressed/released).
The current state of the button is available in the pressed parameter.> Callback:
(controllerId: number, location: number, pressed: boolean, usingShift: boolean) => void
> Location Values: (0-7)
---
$3
#### event
shiftButtonPressed
Triggered when one of the shift buttons on any controller has been pressed. > Callback:
(controllerId: number) => void): void #### event
shiftButtonReleased
Triggered when one of the shift buttons on any controller has been released. > Callback:
(controllerId: number) => void): void #### event
shiftButtonChanged
Triggered when one of the shift buttons on any controller has changed states (pressed/released).
The current state of the button is available in the pressed parameter.> Callback:
(controllerId: number, pressed: boolean) => void ---
$3
#### event
sliderChanged
Triggered when one of slider values changes.
The current state of the slider is available in the value parameter.> Callback:
(controllerId: number, location: number, value: number) => void
> Location: (0-8), Value: (0-127)
---
$3
#### function
setRgbLights(controllerId, positions, brightness, mode, color): boolean
Set RGB pad color, brightness and animation (mode) for one or many pads.> Parameters:
> *
controllerId (number): The Controller ID
> * positions (number|APCMiniCoordinates|Array<...>): Pads to change.
> * brightness (APCMiniBrightnessMode): Brightness of the LEDs.
> * mode (APCMiniLightMode): static or one of the available LED Effects.
> * color (string): Hex color (e.g. #f8ba00)#### function
setHorizontalLights(controllerId, positions, mode): boolean
Changes the horizontal (red) button LEDs.> Parameters:
> *
positions (number|number[]): A position from 0–7.
> * mode ("off"|"on"|"blink"): The LED effect to apply.#### function
setVerticalLights(controllerId, positions, mode): boolean
Changes the vertical (green) button LEDs.> Parameters:
> *
positions (number|number[]): A position from 0–7.
> * mode ("off"|"on"|"blink"): The LED effect to apply.#### function
resetLights(controllerId): boolean
Turns off all lights for a specific controller.#### function
resetAllLights(): boolean
Turns off all lights for all controllers.#### function
fillRgbLights(controllerId, startPos, width, height, brightness, mode, color): boolean
Fills a rectangular region of pads with an RGB color/mode.> Parameters:
> *
controllerId (number): The Controller ID
> * startPos (number|APCMiniCoordinates): Start position.
> * width (number): Width of the rectangle (follows the coordinate system).
> * height (number): Height of the rectangle (follows the coordinate system).
> * brightness (APCMiniBrightnessMode): Brightness of the LEDs.
> * mode (APCMiniLightMode): static or one of the available LED Effects.
> * color (string): Hex color (e.g. #f8ba00)---
$3
#### function
getShiftState(): boolean
Returns whether any controller has its Shift button pressed.#### function
getPadStates(controllerId): boolean[]
Returns pressed state of all 64 RGB pads.> Parameters:
> *
controllerId (number): The Controller ID#### function
getHorizontalStates(controllerId): boolean[]
Returns state of horizontal buttons.> Parameters:
> *
controllerId (number): The Controller ID#### function
getVerticalStates(controllerId): boolean[]
Returns state of vertical buttons.> Parameters:
> *
controllerId (number): The Controller ID#### function
getSliderValues(controllerId): number[]
Returns slider values (0–127) for the specified controller.> Parameters:
> *
controllerId (number): The Controller ID---
$3
All 3 animation methods accept the following callback:
(time: number, currentFrame: Map> Parameters:
> *
time (number): The time since the start of the animation in milliseconds.
> * currentFrame (Map): The current (8x8) animation frame, changes made to this map will update the next frame.#### function
setIntroAnimation(animation, durationMs): void
Sets the animation displayed before the user selects the controller ID.> Parameters:
> *
animation (APCMiniPreconnectAnimation | null)
> * durationMs (number): The duration of the intro animation.#### function
setWaitAnimation(animation): void
Animation played while selecting the controller ID.> Parameters:
> *
animation (APCMiniPreconnectAnimation | null)#### function
setOutroAnimation(animation, durationMs): void
Animation played after controller ID selection is completed.> Parameters:
> *
animation (APCMiniPreconnectAnimation | null)
> * durationMs (number): The duration of the outro animation.---
$3
Utility functions are available directly, outside the APCMiniController class.#### function
isHexColor(hexColor): hexColor is APCMiniHexColor
Checks if a string is a valid hex color.#### function
hexToRgb(hexColor): { red, green, blue }
Converts a hex color to 0–255 RGB values.#### function
rgbToHex(r, g, b): APCMiniHexColor
Converts RGB values into a hex color string.#### function
brightness(multiplier, hexColor): #xxxxxx
Modifies brightness of a hex color using a (0–1) multiplier.#### function
locationToCoordinates(location): APCMiniCoordinates
Converts a pad index (0–63) to X-Y coordinates.#### function
coordinatesToLocation(coordinates): number`![]() |
| 💻 DJj123dj |
|---|
---
v1.0.3 - README.md
© 2026 - DJdj Development - Discord - Terms - Privacy Policy - Support Us - License