spektroaudio / ap2js

Max JS script for controlling and programming the Ableton Push 2 hardware controller

AP2JS

AP2JS is a JavaScript script for Cycling 74' Max 7 / 8 designed to simplify the process of controling and programming the Ableton Push 2 by abstracting the MIDI and SySex messages available on the Ableton Push 2 MIDI and Display Interface Manual.
The different methods available in AP2JS lets the user control the leds of the 8x8 pad grid, buttons, and touchstrip. AP2JS also includes extra methods for using 8x1 rows / columns as "faders" and for setting exclusive buttons per row / column (similar to a radio buttons).
AP2JS also re-routes MIDI commands coming from the Push 2 (pad /button presses + encoder direction) to it's second output to simplify the programming process.

Current version: 0.05 (BETA)

AP2JS was created by Ícaro Ferre (@icaroferre).

Developed by Spektro Audio
spektroaudio.com

---

HOW TO INSTALL

• Download the latest verison of ap2js.
• Move folder to a secure location.
• Open Max's File Preferences, add the ap2js folder and enable the option for sub-folders.

HOW TO USE

Basic Setup Snippet

• Create a new Max patch.
• Open the Snippet section of the side-bar and drag the [ap2js] Basic Setup snippet into your patch.
• If you wish to run AP2JS alongside Ableton Live, click on the Push 2 User button to enable AP2JS.
• If you'd like to use AP2JS without Ableton Live, click on the initialize message.

Manual Instructions

• Add a js ap2js.js object to your Max patch
• Add a midiin and a midiout to your Max Patch. Set both to the Push 2 User port.
• Route the output of the midiin to the input of the js ap2js.js and route the output of the js ap2js.js to the input of the midiout object.
• If you wish to run AP2JS alongside Ableton Live, click on the Push 2 User button to enable AP2JS.
• If you'd like to use AP2JS without Ableton Live, send a initialize message to the js ap2js.js object.

ATTENTION: AP2JS is designed to only send messages when in User Mode therefore the Push must be set to User Mode via the initialize message / method.

---

INCOMING MIDI MESSAGES

MIDI messages generated by the Push 2 are parsed by AP2JS and routed to the second output of the js object.

Because all messages are sent to a single output, AP2JS automatically prepends the message type so different types can be filtered via a route object.

These are the MIDI messages that are parsed by AP2JS:

• xy (8x8 Pad Grid): MIDI notes generated by the pads are re-formatted as X Y VALUE.
• button (RGB / Mono buttons): CC messages generated by button presses are re-formatted as BUTTON_NAME VALUE.
• encoders: because encoders don't generate specific MIDI values, AP2JS outputs their messages as ENCODER_NAME inc bang or ENCODER_NAME dec bang (depending on the direction of the movement).

---

FEATURES

SCENES

AP2JS automatically stores the values for all pads and buttons as a scene. This is a useful feature for creating multi-page apps / patches. Different scenes can be recalled using the scene scenename message. When a scene is recalled, it's automatically set as the active scene. Because new values are stored to the active scene automatically, there's no need to save scenes. When initialized, AP2JS selects the user scene.

COLORS

To make it easier for programmers to set different colors for each pad and button of the Push 2, AP2JS uses "on" and "off" colors.
By default, "off" is set to 0 and "on" is set to 1 (ember). These colors can be overwitten using the different methods available below.
The pads and buttons can also be set to other colors without overwritting the colors of the two states.

---

AVAILABLE MESSAGES

Here's a list of all available messages that can be sent to the js ap2js.js object. Remember to replace the arguments displayed after the messages with the desired values.

GLOBAL

parallel 0 or 1: activates parallel mode which lets AP2JS to work alongside Ableton Live via the Push 2 User Mode.

initialize: sets the Push 2 to User mode and sets the touchstrip to Default mode.

set_mode mode: sets the Push 2 mode (modes available: live, user, both).

scene scene_name: sets the AP2JS scene (check the SCENES section above for more info).

set_blinkrate rate: sets the blink rate for the pads and buttons (1-16).

PADS

Pads can be addressed via their X/Y position on the 8x8 grid (x and y valued range from 0 to 7).

set_pad_color x y off on: sets the off and on colors for the pad in the x/y position

set_row_color y off on: sets the off and on colors for an entire row of pads

set_column_color x off on: sets the off and on colors for an entire column of pads

set_allpads_color off on: sets the off and on colors for all pads

set_pad x y value: sets the pad in the x/y position to a color (if value is integer) or to a state (if value is on or off)

set_pad_blink x y value: sets the blink mode (value = 1 or 0) of the pad in the x/y position

set_row y value: sets a row of pads to a color (if value is integer) or to a state (if value is on or off)

set_row_b y value: converts value (0-255) to binary and sets the y row of pads to on or off based on the 8 bits

set_column x value: sets a column of pads to a color (if value is integer) or to a state (if value is on or off)

set_column_b x value: converts value (0-255) to binary and sets the x column of pads to on or off based on the 8 bits

clear_row y: sets a row of pads to off

clear_column x: sets a row of pads to off

clear_all: sets all pads to off

set_row_fill y fill value: sets a row (y) as a horizontal fader by setting a number of pads (fill) to value (remaining pads are set to off).

set_column_fill x fill value: sets a column (x) as a vertical fader by setting a number of pads (fill) to value (remaining pads are set to off).

set_row_exclusive x y: clears row y and sets x/y pad to on

set_column_exclusive x y: clears column x and sets x/y pad to on

set_xy_exclusive x y: clears all pads and sets x/y pad to on

set_pads_outputmode mode: sets the output mode for the pads (0 outputs on notes only, 1 outputs on and off notes).

BUTTONS

Buttons can be addressed via their name in lowercase (e.g. play, fixed_legth, tap_tempo, etc).
The rectangular buttons above the display are named track_1 through track_8 and the ones below the display are name device_1 through device_8.

get_button_type button_name: outputs button type (rgb / mono) to the second output of the js object.

set_button_color name off on: sets the "off" and "on" colors of the button

set_button name value: set button to a specific color (if value is integer) or to a state (if value is "on" or "off")

set_button_blink name value: sets the blink mode (value = 1 or 0) of the button

get_button_list: prints a list of all available buttons to the Max Window / Console.

TOUCHSTRIP

set_touchstrip_mode mode: sets the touchstrip mode (available modes: default, centered, and bottom).

set_touchstrip value: sets the touchstrip value (0 - 127).

KNOWN ISSUES / LIMITATIONS

• The touchstrip is not recalled correctly when switching from Live mode back to User mode. A possible workaround is to manually send a restore_touchstrip message to js ap2js.js.

DISCLAIMER

While AP2JS should be safe to use, Ícaro Ferre or Spektro Audio are not responsible for any damages or errors. Use at your risk.