apc-mini-mk2

   

$3

An easy-to-use and feature-rich Node.js package for interacting with one or multiple Apc Mini's (Mk2) from Akai Professional.
It features Full RGB LED color support, button/slider events, input polling, startup animations & so much more!
Perfect for scripts, Electron apps, automation, smart home, music production, games, event lightning, ...

Need help? Feel free to join our support server and we will help you fruther!

$3

``
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) => void

> 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`
Converts X-Y coordinates to a pad index (0–63).

🛠️ Contributors

> All contributions are welcome! Feel free to create a pull-request or issue in the Github repository.

💻 DJj123dj

⭐️ Star History

> Thank you for using our package! — support us by sharing it! 😁

---

v1.0.3 - README.md

© 2026 - DJdj Development - Discord - Terms - Privacy Policy - Support Us - License