# Mackie emulation for the AKAI APCmini

# Copyright (c) 2018 Albert Graef <aggraef@gmail.com>

# Copying and distribution of this file, with or without modification, are
# permitted in any medium without royalty provided the copyright notice and
# this notice are preserved.  This file is offered as-is, without any
# warranty.

JACK_NAME "midizap-APCmini"
JACK_PORTS 2

# This turns the APCmini into a Mackie-compatible controller, so that it can
# be used with Linux DAW programs like Ardour.  The emulation is complicated
# by the APCmini having no encoders, no motorized faders, and not nearly as
# many dedicated buttons as a Mackie device.  But it offers enough controls to
# be usable as a basic DAW controller.  I tested it with Ardour.

# SETUP: In Ardour, enable the Mackie control surface, then connect Ardour's
# Mackie control ports to midizap's midi_out and midi_in2 ports, and the
# APCmini to midizap's midi_in and midi_out2 ports.

# PROTOCOL DOCUMENTATION: The Mackie protocol is fairly ubiquitous, but since
# manufacturers can't be bothered to properly *document* their stuff these
# days, we have to rely on volunteers who do their work using some reverse
# engineering.  Here are the links that I found most useful:

# http://www.budgetfeatures.com/XctlDOC/Xctl Protocol for X-Touch V1.0.pdf

# (This chart really is a piece of art.  It's actually about the Behringer
# X-Touch, but since that device is Mackie-compatible, there's a wealth of
# useful information in there; just ignore the bits which pertain to Xctl.)

# There's another fairly comprehensive one here (lacks the feedback messages,
# though):

# http://www.jjlee.com/qlab/Mackie Control MIDI Map.pdf

# Information about the APCmini can be found in the Akai forums here:
# http://community.akaipro.com/akai_professional/topics/midi-information-for-apc-mini

[MIDI]

# The APCmini's dedicated shift key is used to provide alternative functions
# to some of the buttons and the faders.
D8 SHIFT RELEASE SHIFT

# transport (assigned to the topmost 5 "scene launch" buttons on the right)
A#6 A7  # Stop
B6  A#7 # Play
C7  B7  # Rec
#C7  D7  # Cycle
C#7 G7  # Rew
D7  G#7 # FFwd

# the next three buttons below are used for the MC shift keys
# NOTE: The MC actually has four shift keys, so one has to go. You may want
# to rearrange these as needed.
D#7 A#5 # Shift
E7  B5  # Control
F7  C6  # Option
#F7  C#6 # Alt/Cmd

# shifted "scene launch" buttons
# We assign these to the function keys F1..F8 here, but of course you can
# remap these as needed.
^A#6 F#4
^B6  G4
^C7  G#4
^C#7 A4
^D7  A#4
^D#7 B4
^E7  C5
^F7  C#5

# bottom 3x8 grid: mute/solo/rec
# NOTE: Incidentally, these happen to be identical to corresponding MC input.

# rec (bottom row of the grid)
C0  C0
C#0 C#0
D0  D0
D#0 D#0
E0  E0
F0  F0
F#0 F#0
G0  G0

# solo (next row above)
G#0 G#0
A0  A0
A#0 A#0
B0  B0
C1  C1
C#1 C#1
D1  D1
D#1 D#1

# mute (next row above)
E1  E1
F1  F1
F#1 F#1
G1  G1
G#1 G#1
A1  A1
A#1 A#1
B1  B1

# track select (bottom row right above the faders)
E5  C2
F5  C#2
F#5 D2
G5  D#2
G#5 E2
A5  F2
A#5 F#2
B5  G2

# shifted bottom row
# We have these assigned to the bank/channel and track/pan/send/plugin
# controls, but you may want to remap some or all of these as needed.
^E5  A#3 # Bank Left
^F5  B3  # Bank Right
^F#5 C4  # Channel Left
^G5  C#4 # Channel Right
# NOTE: Plugin appears to be unsupported in Ardour.
^G#5 E3  # Track (Volume)
^A5  F#3 # Pan
^A#5 F3  # Send
^B5  G3  # Plugin (Device)

# faders (MC uses pitch bends here, use 129 as step size to get full range)
CC48[] PB[129]-1
CC49[] PB[129]-2
CC50[] PB[129]-3
CC51[] PB[129]-4
CC52[] PB[129]-5
CC53[] PB[129]-6
CC54[] PB[129]-7
CC55[] PB[129]-8
# master fader
CC56[] PB[129]-9

# faders become encoders when shifted (CC16..CC23, incremental mode)
^CC48= CC16~
^CC49= CC17~
^CC50= CC18~
^CC51= CC19~
^CC52= CC20~
^CC53= CC21~
^CC54= CC22~
^CC55= CC23~

# feedback section ########################################################

[MIDI2]

# transport (will light up in green)
A7  A#6 $M0 # reset all meters, see "meter feedback" below
A#7 B6
B7  C7[2] # Rec, blinks when engaged
#D7 C7 # Cycle
G7  C#7
G#7 D7

# Feedback for the MC shift keys. We've disabled this by default since it
# doesn't add much value and clobbers some of the blinkenlights below.

#A#5 D#7
#B5  E7
#C6  F7

# Blinkenlights galore!  The Mackie protocol provides us with both time and
# meter data for which we provide some translations here which make various
# LEDs light up in different colors.

# Meter feedback: Each meter value is sent as a channel pressure message (on
# the first MIDI channel) with the mixer channel index 0..7 in the hi- and the
# meter value in the lo-nibble of the velocity value.  On a real MCP device
# like the X-Touch, the meters have 7 segments (4 green, 3 orange, and 1 red),
# but the actual range of the meter values seems to be more like 0..13 (at
# least that's what Ardour outputs, YMMV).  Note that we only use the upper
# 5x8 part of the grid here, in order not to clobber the three rows at the
# bottom with the rec/solo/mute buttons, so we have to squash the meter values
# into those 5 LEDs per strip in some way.  The following setup with 3 green,
# 1 yellow and 1 red LED seems to work reasonably well, but you might want to
# adjust the colors and the mapping of the meter values to your liking.

CP[16] C2{0,1} G#2{0:3,1} E3{0:6,1} C4{0:9,5} G#4{0:12,3}

# NOTE: We only report the values as we receive them here, there's no
# automatic decay of the meters like with real Mackie hardware.  Thus we
# explicitly reset all meters when transport stops below.  (Ardour at least
# does *not* do that automatically.)

M0[1] $CP{0} $CP{16} $CP{32} $CP{48} $CP{64} $CP{80} $CP{96} $CP{112}

# This decodes the least significant digit in the time display (CC69) to count
# off time on the 4 bottommost scene launch buttons.  Note that the digits are
# encoded in ASCII here, therefore the copious amount of zeros in the value
# lists below to skip over all the non-digit characters at the beginning of
# the ASCII table.

CC69[] F7{0:49,1,0} E7{0:50,1,0} Eb7{0:51,1,0} D7{0:52,1,0}

# no feedback for faders (faders aren't motorized)

# NOTE: Feedback for rec/solo/mute/select also needs to be recognized in shift
# mode, so that the (shifted) bank/channel left/right keys work as expected.

# rec: color = red (vel. 3)
C0  C0[3]
C#0 C#0[3]
D0  D0[3]
D#0 D#0[3]
E0  E0[3]
F0  F0[3]
F#0 F#0[3]
G0  G0[3]

# solo: color = green (vel. 1)
G#0 G#0[1]
A0  A0[1]
A#0 A#0[1]
B0  B0[1]
C1  C1[1]
C#1 C#1[1]
D1  D1[1]
D#1 D#1[1]

# mute: color = yellow (vel. 5)
E1  E1[5]
F1  F1[5]
F#1 F#1[5]
G1  G1[5]
G#1 G#1[5]
A1  A1[5]
A#1 A#1[5]
B1  B1[5]

# select (will light up in red)
# NOTE: Ardour apparently doesn't update these when changing banks.
C2  E5
C#2 F5
D2  F#5
D#2 G5
E2  G#5
F2  A5
F#2 A#5
G2  B5