Starr Labs Clipper User Manual

1

Starr Labs Clipper

Clip-Based Live Interactive Performance controller

USER Manual R1.1 12/27/12

User Manual R0.2, Beta release 12/7/2012.

(Firmware Revision 3.0 12/1/2012)

Copyright © 2012 Starr Labs

The Clipper fingerboard is a programmable music control surface with multicolor LED visual feedback in
each key. The key-action is a standard Ztar fully polyphonic, touch-sensitive fingerboard. The Clipper’s
embedded software is designed to act as a remote Ableton Live * clip control matrix, as well as offering
a variety of dynamic lighting effects. In addition, the Clipper integrates the standard Starr Labs MIDI
guitar functionality with many MIDI control setup options. Using our standardized LED controller MIDI
command set you can create many types of interactive applications such as games and teaching
software.

This document primarily describes the detailed User setups to the Clipper for use with Ableton Live.
These setups are pre-loaded in your instrument, and this is your reference to the menu screens
pertinent to the interactive lighting features.

 “Ableton Live” property of Ableton Inc.

Contents:

Overview 1
Ableton Live to Clipper: Detailed Interface Specification 2
MIDI message Format 6
Setting up Ableton Live to work with the Clipper 7
Setting up the Clipper to work with Ableton Live 7
Zone Setup 8
Keymap setup 9
MIDI Merge settings 10
Color settings 11
Images 12
Tuning Maps 12
LED Controller Command Specification 14
Appendices and Charts __________________________________________________________ 21
QUICK Ableton Mac/PC setup _____________________________________________________ 23
Index _________________________________________________________________________ 24

2

Hardware setup

 The Clipper can be connected to your computer with a MIDI cable to the Clipper’s MIDI Out

Port, or a standard USB A/B cable.

 At full brightness the LEDs require more power than a standard USB2.0 port can provide. The

Clipper must be powered by “Phantom power” through the MIDI cable in order to run the
lighting. Power is supplied to MIDI cable by our PB-1 interface adapter and the AC/9VDC wall­adapter. You can still connect to your computer via the USB cable which will carry only data.
USB power will only support the MIDI control functions of the instrument.

 A 3-position power switch is provided: USB<OFF>MIDI

Overview of the Ableton Live interface

When configured as an Ableton Live controller the Clipper functions much like other commercially
available Clip grid controllers, but with added functionality. Other grid controllers have a limited amount
of visual feedback, usually representing only the state of a clip with LED blinking/brightness and three
colors. For instance Yellow for standby, blinking Yellow for cued, Green for playing, Red for recording.

However, on the Clipper the color of each LED represents the color of each respective clip in Ableton’s
Session View GUI with brightness and blinking representing the clip states. When a clip is loaded it is at
half brightness. When a clip is cued to play it blinks between half brightness and off. When the clip
launches it lights up at full brightness. This allows the user to color code a Live set and not have to look
at the computer screen throughout a performance. Thus the Clipper liberates the computer musician
from the laptop stand, allowing for greatly improved virtuosity. ---Imagine how much cooler you will be

when you aren’t hidden behind a computer screen twisting knobs and pushing buttons on a tabletop
control surface… SO COOL!

If you’re interested to try programming the Clipper for your own lighting effects it’s easy with our

dedicated MIDI control command-set. Using standard MIDI Note and Continuous Control messages you
can light the LEDs to any color, program and stream text and images, scroll the display, blink individual
LEDs and other functions. Using the setups in the Ztar OS you can create Zones of color, Tuning maps
for different guitar tunings, load and select images, and create animations.

Now that you’re excited about your new Clipper fingerboard, let’s get into the specifics.

3

Ableton Live to Clipper: Detailed Interface Specification

Ableton Live (currently at Rev.8.3) is a popular music software application that allows a user to record

and playback clips of music in a wide variety of ways, all synced to a master beat. It is also popular to use
a Remote Control surface, a small console with buttons and knobs, and often LEDs for stratus feedback,
using semi-proprietary command sets developed specifically for each peripheral.
The Ztar is a MIDI guitar controller with a keyboard-like fingerboard having a touch-sensitive key for

each note position. The keys can easily be mapped to control a Live ‘Session’, or instance of Ableton Live

running in a host PC or Mac. With some modifications the Ztar can be made to reflect the status of the

session’s display screen as well. The Ztar or any MIDI controller directs Ableton Live by sending MIDI

commands which are interpreted and re-mapped by Live to perform various internal functions of the
software.

These MDI commands are standard and need no special coding from the device side other than a simple
user-setup to make the specific assignments. When there are a lot of controls to be mapped, it is more
convenient to create a profile, or Control Surface script using Python that is loaded into the program
when the device is plugged in. Also, when it becomes necessary for the remote device to show the
Host’s programs status, host-to-device output software must be created, also using Python scripts which
are loaded into the same master profile for that device.

Requirement for Host-to-Device MIDI communication:

An Ableton Live “Session” displays on the computer screen an array of colored boxes that form the Clip
Grid and change dynamically as the music performance proceeds. In order to have a remote control
surface display this same dynamic status information from the current Session in the host computer,
Ableton communicates the various color changes to the remote peripheral control surface via a
USB/MIDI connection. As the activity of the Live session changes, with different audio and MIDI clips
turning on and off, playing, recording, and cueing for the next operation, the computer display is
continually changing to reflect the current status, and the remote surface will update to correspond
with the computer screen including color-matching the status LEDs for the Live clip performance matrix,
or Clip Grid”.

Ableton Live provides an API for creating modifications to the operation of Live. When a new hardware
Control Surface is defined for Live, a set of assignments maps the MIDI messages from the Control
Surface to the internal functions of the Live software. This mapping is created by use of a Python script
that loads manually or when Live recognizes the connected (enumerated) USB- MIDI device. MIDI Notes
and MIDI CC messages are commonly used to control the Live software.

4

In addition to mapping the MIDI-notes input to control Live, the Python script can extract the dynamic

status of the individual virtual “buttons” and “pot/encoders” on the Live GUI, including color

information for the buttons. When the current color-state of a button is determined, the corresponding
location on the remote Control Surface can be made to light up to match the appearance of the
software.

That said, we can most easily define the necessary control stream to the LEDs in the StarrLabs
peripherals by using standard MIDI messages from the host computer. The format is simple, and it
carries enough data payload in a simple message to light any arbitrary LED. Also, it affords some unique
opportunities for direct musical control of the LEDs, aside from their use in the Ableton Live context.

The Clipper fingerboard is a guitar-format keyboard with 6 “Strings” (columns) x 24 “frets” (rows) of
touch-sensitive keys for a total of 144 keys. We may add more Strings to cover expanded arrays. Each of
the 144 keys is fitted with a 3-color LED for a total of 432 LEDs. This array of LEDs may be controlled in
full color by sending an encoded color-value to each pixel, or triad, located under each key.

The colors themselves are encoded in 15 bits allowing a total of over 32000 colors. These color values
are arbitrary and when we’re connected to Live we use Live’s color table so that you can match the LEDs
to the clip-colors in your session. The colors are then re-mapped inside the Clipper so they can be
selected by a 7-bit MIDI note-velocity value. From the point of view of the host computer, the array of
LEDs is a list containing a 7-bit color value for each of 144 locations.

Ableton Live Clip-array:

This is a Ztar zone of arbitrary size that reflects the RedBox within the Clip-grid on the Ableton Live
screen. In performance mode, clips are loaded, recorded or launched.

When we set up the Ableton "Live Zone" on the controller we will define X-Y boundaries on the
fingerboard. That becomes a static box for your performance and also defines the boundaries for the
RedBox. Thus the RedBox size is arbitrary. Maximum size is 5x23 for Clips with a sixth row for StopClips,
and a twenty-fourth column for Scene Launch. Live only controls the “Live” Zone on the Clipper. All other
Zones are unaffected.

Automatically the Stop Clips Row is lit at the Bottom in Red and the Scene Launch Column is lit in Green.

Launch Scene Keys:
This is the column of Green-lit keys placed to the right of the clip keys array for the LiveZone on the Ztar
for a Zone of any size. This is also called the master channel. The function of each of these keys is to
trigger all keys in the corresponding row in the clip key array.
The bottom key in the far right column is Stop All Clips.

5

Stop Keys:
This is a row of keys placed below the clip keys and the launch scene keys. The function of each of a Stop
key is to stop all clips in the corresponding column in the clip key array. The rightmost key stops all clips
in all columns.

Blinking stop clip button:

The stop clip buttons should blink during pre-roll to indicate that a button push on that stop clip has
been initiated. The stop clip button should blink until the downbeat where it stops the playing clip
(bringing it to half brightness) and returns the stop clip button to full brightness (non-blinking ).

Visual Feedback

The lighting for the keys enclosed by the RedBox is controlled by the Ableton script according to the
LiveZone setup in the controller. Ableton only controls what's in the Live Zone. The colors of the various
Clips will scroll through the LiveZone as the RedBox scrolls on the Ableton screen. Likewise, visual

feedback from scrolling the RedBox from the controller is shown on the computer screen.

Other Zones on the fingerboard that are not controlled by Ableton can have their color data controlled
separately either from the Ztar or an external computer.

To be clear, where the boundaries of the RedBox on the fingerboard are fixed but the LiveZone is
scrolled, the lighting values of the clips outside of the Live Zone do not show on the fingerboard. The
Non-LiveZone areas are for other performance purposes to be colored separately. The Ztar OS has
utilities for creating zones with a base color.

1. When a Clip location is empty, the color is a low-intensity White to highlight the LiveZone.

2. When a Clip is loaded in Ableton the fingerboard key-color assumes the clip’s color.

3. When the Clip is idle the color is half-intensity.

4. When the Clip is playing the color is full intensity.

Clip Launch modes:

(These are ordinarily set in the Ableton Clip Launch Mode setup dialog)

Trigger - once the button is pressed it latches and plays the clip until it reaches it’s end or a Stop

6

button is pressed. This will usually be the stop clip button at the bottom of the track, but can be
any blank clip with an active stop button in that track. Note-offs are ignored.

Gate - Full intensity when active. Momentary operation. You must hold down the button to play
the clip. This is handled by Note-On on button-press and Note-Off issued button-release. Normal
keyboard mode.

Toggle - Full intensity when active. Press once for the clip to play and repeat, press again for it to
stop. Ignore Note-Off. Successive Note-On's toggle the function.

Repeat - mouse down/note on repeatedly plays the clip, retriggering at the time interval of the
clip’s launch quantization. when released the clip plays out like Trigger mode

Button Flashing: Ableton buttons flash when they are Armed, that is, the clip is ready to Play or Record

but is waiting for the actual Start-time, to come around before firing. The start time is usually the
"downbeat" but other Launch Quantizations are available.

Recording Mode:

When recording to a Clip, color is Red. We aim to represent the status of the little Clip arrow at the left
of the Scene (row), which is sometimes solid and sometimes blinking.
The fingerboard Clip button becomes Red and is steady-state or flashing depending on the Recording­status.

1. Recording may be started by pressing a Record button in which case the recording starts

immediately and the arrow glows solid Red.

2. Recording may be "Armed" with a 2-bar count-in where the LED flashes and when the recording

actually begins the LED glows solid Red.

Playback Mode:

The fingerboard Clip button is steady-state or flashing depending on the Playback-status. The Ableton
Record/Playback Arrow shows the status.

1. Playback may be started by pressing the play button in which case the playback starts

immediately and the button glows at full intensity with the assigned color.

2. Playback may be "Armed" with a 2-bar count-in where the LED flashes and when the recording

actually begins the LED glows its solid color.

MIDI message format:

7

Each MIDI channel can address 128 note-numbers.

A full MIDI Note-On message is composed of (3) 7-bit bytes.

A full frame of color data assigns a 7-bit value to each fingerboard location. (144) 7-bit bytes.

Byte #:1 Status byte (in binary) 0101nnnn where 09h = MIDI Note-On, and nnnn is a 4-bit channel
number.

Byte #2: MIDI Note-number, 0nnnnnnn, where nnnnnnn is a 7-bit note-number. This is used to address
each LED location. Each key on the fingerboard has a unique channel/note address.

Send MIDI Note-Off to turn off an individual LED. Both a literal Note-Off and a Note-On velocity=0.

Byte #3: Velocity value, 0nnnnnnn, where nnnnnnn is a 7-bit value. This normally encodes the force of
a key-strike. In our case this is used to encode the color-value for each LED pixel.

These color values are index-numbers into an array on the device that holds a list of values to create 128
unique colors (including OFF = 0 = no light)*.

*Note there are two ways to turn OFF an LED.

Additionally, once a MIDI status byte has been issued from a MIDI controller, the channel number is
then established, and most controllers will enter what is called “Running Status” which dispenses with
the status byte and sends only 2-byte messages containing just the note-number and velocity
information. When the channel-number must be changed or a different type of message must be sent,
then the controller drops out of Running Status, sends a new Status byte as necessary, and re-enters
Running Status. In the case where there are more than 127 LEDs in the array, a channel switch will be
necessary to address the full array.

We can use, arbitrarily, MIDI channels 15 and 16 which are rarely used in most MIDI setups. Two
channels yield 256 programmable locations which will easily cover our requirements.

The array is ordered starting with “String#1, Fret#1” which is the lowest fretted note on a guitar for a

right-handed player. The highest note-location on String#1 is LED-location #24.

Setting up Ableton Live to work with the Clipper

The Clipper communicates with Ableton’s Live API using MIDI Remote Scripts. These Python scripts are

available on our website, and interpret incoming standard MIDI messages and translate them to API
calls within Live. You can edit these if you want, but if you just want to get things going right at the start
we recommend that you simply copy the folder containing the remote scripts into the following
operating system specific locations.

8

Windows: /Program Files/Ableton /Live 8.x.x/Resources/MIDI Remote Scripts

Mac OSX: /Applications/Live 8.x.x/Live.app/Contents/App-Resources/MIDI Remote Scripts

The name of this folder will be the name of the control surface in Ableton Live. Currently the standard
name is “Ztar” but feel free to rename it something you like and will remember for the next step.

Once this folder has been copied, (re)start Ableton Live, open up the Preferences menu and navigate to
the MIDI tab. There you will be presented with a grid of dropdown menus. In the control column open
one of the dropdown menus and scroll down to Ztar (or whatever you renamed it). Then in the next two
columns to the right, select your input and ouput ports for the instrument.

In the lower half of the MIDI preferences window you will see a grid with options for all of the active

MIDI ports. Make sure that both “Track” and “Remote” are set to “On” for your previously assigned
input and output ports. The “Sync” option is for sending/receiving MIDI clock messages and can be left

off for most use cases. We recommend leaving it off to reduce the amount of messages the Ztar has to
handle.

Now Ableton is ready to interact with your Clipper enabled Ztar, but is your Ztar ready? We have
Ableton ready setups available on our website which can be programmed into your Ztar via System
Exclusive MIDI messages (SysEx). You can also set up the necessary fingerboard zones with using the
following instructions

Setting up the Ztar/Clipper to work with Ableton Live

- These setups have already been included in the Ztar-ABL-OS version. The following instructions

explain how the setups are created and the way the Ztar interacts with Ableton Live.

- The Ztar and the Clipper LED Controller communicate with any external MIDI device, including

Ableton Live running in a host computer, by means of standard MIDI note and Continuous
Control messages, as defined in the Clipper LED interface specification. For this purpose we
reserve MIDI channels 15 and 16 for our various MIDI control functions.

On the output side, the Ztar fingerboard uses a special “keymap” that assigns a unique channel

and note-number combination to each note-location on the fingerboard. Keymaps are selected,
edited, and stored in the Fretboard/Tunings Menu and where a unique set of eight full maps
may be saved for each “Song”, or master preset in the Ztar.