# Mackie emulation for the NI Maschine Mk3

# 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-Maschine"
JACK_PORTS 2
SYSTEM_PASSTHROUGH # pass through MCP feedback

# automatic connections
JACK_IN1  Ctlra Maschine Mk3
JACK_OUT1 ardour:mackie control in
JACK_IN2  ardour:mackie control out
JACK_OUT2 Ctlra Maschine Mk3

# NOTE: At present, this controller isn't properly supported by ALSA, but it
# can be made to work in Linux with Harry van Haaren's Ctlra software.
# Specifically, you'll need the ctlra_daemonx program from the
# mapping_v1-daemonx branch which for the time being can be found here:
# https://github.com/agraef/openAV-Ctlra/tree/mapping_v1-daemonx

# After cloning the repository and switching to the mapping_v1-daemonx
# branch, you can run the following to install the libctlra library along with
# ctlra_daemonx: meson build && cd build && ninja && sudo ninja install

# Then run ctlra_daemonx -fnm alongside with midizap, and check that the ports
# are connected as follows (the JACK_IN/OUT directives above should take care
# of this automagically): Ctlra Maschine Mk3 -> midizap midi_in / midi_out ->
# Ardour mackie control in / mackie control out -> midizap midi_in2 /
# midi_out2 -> Ctlra Maschine Mk3.

# Usage (executive summary):

# - SHIFT, SELECT, SOLO and MUTE are used as shift buttons which change the
#   functions of the encoders and some keys

# - The transport section (bottom/left) mostly does what you'd expect it to.
#   PLAY, REC, STOP and RESTART/Loop all work as advertized. The two keys
#   above REC and STOP are used as REWIND and FAST FWD.

# - The eight buttons at the top select a channel, or engage Channel
#   Rec/Solo/Mute when combined with SELECT, SOLO and MUTE, respectively.

# - The eight small encoders function as the volume faders, or as encoders
#   (usually pan) when combined with SHIFT. Touching the encoders means
#   touching the faders, or pushing the encoders when combined with SELECT.

# - The big encoder emulates the jog wheel. Pushing this encoder left, right,
#   up and down emulates the cursor keys, pressing it engages the Zoom
#   function (which also lights up all four LEDs around the encoder).

# - The touchstrip is used as the master fader. The four buttons above it
#   emulate the MCP shift keys (SHIFT, CTRL, OPTION, ALT/CMD).

# - The left and right arrow keys in the top/left button group are used to
#   change banks, or move by single channels when combined with SHIFT.

# These are just the most important mappings; there's a bunch of other
# bindings, but I'll leave you to discover them on your own (see below for all
# the gory details). There are so many keys on this device, many of them are
# still unused right now, so you can easily add more bindings if you want. :)

[MIDI]

# We use the Mk3's dedicated SHIFT button as our primary shift key, to provide
# alternative functions to some of the buttons and the faders.
F2  SHIFT ^F2 RELEASE SHIFT ^F2

# transport (assigned to the transport section on the bottom left)
F#5  A7  # Stop
E5   A#7 # Play
F5   B7  # Rec
C5   D7  # Cycle (RESTART/Loop key)
C#5  G7  # Rew   (ERASE/Replace key)
D5   G#7 # FFwd  (TAP/Metro key)
D#5  C#7 # Nudge (FOLLOW/Grid key)

# additional functions on shifted keys
^C#5 D#7 # In    (SHIFT ERASE/Replace key)
^F5  E7  # Out   (SHIFT Rec key)
^D5  F7  # Click (SHIFT TAP/Metro key)
^D#5 C7  # Mark  (SHIFT FOLLOW/Grid key)

# switch between SMPTE and BBT timecode
C#6  F4  #       (MIDI/Channel key)

# Bank/channel left/right (arrow keys in the top left section)
E6   A#3 # Bank Left
A5   B3  # Bank Right
^E6  C4  # Channel Left
^A5  C#4 # Channel Right

# the four buttons below the arrow keys are assigned to the utility functions
F6   G#6 # Save   (SAVE/File key)
G#5  A6  # Undo   (SETTINGS key)
F#6  A#6 # Cancel (AUTO key)
G5   B6  # Enter  (MACRO/Set key)

# Track/Pan/Send/Plugin (4 buttons right above the grid)
# NOTE: Plugin appears to be unsupported in Ardour.
G#3  E3  # Track  (PAD MODE key)
A3   F#3 # Pan    (KEYBOARD key)
A#3  F3  # Send   (CHORDS key)
B3   G3  # Plugin (STEPS key)

# the four buttons right above the touchstrip are used for the MC shift keys
A4   A#5 # Shift   (PITCH key)
A#4  B5  # Control (MOD key)
B4   C6  # Option  (PERFORM key)
D3   C#6 # Alt/Cmd (NOTES key)

# big encoder press/left/right/up/down is assigned to the zoom/cursor keys
D2   C8  # Up
E2   C#8 # Down
D#2  D8  # Left
C#2  D#8 # Right
C2   E8  # Zoom

# These can also be shifted, so that you can bind them in the DAW if you
# want. E.g., I have the previous/next marker functions on the shifted cursor
# left/right keys in Ardour.

^D2  A#5 C8   # Up
^E2  A#5 C#8  # Down
^D#2 A#5 D8   # Left
^C#2 A#5 D#8  # Right
^C2  A#5 E8   # Zoom

# The Mk3 has one row of dedicated "channel buttons" at the top, right above
# the display. Since we'd also like to use these for the channel-based
# rec/solo/mute functions, we combine them with the SELECT, SOLO and MUTE
# buttons as additional shift keys.

F#4 SHIFT2 ^F#4 RELEASE SHIFT2 ^F#4
G4  SHIFT3 ^G4  RELEASE SHIFT3 ^G4
G#4 SHIFT4 ^G#4 RELEASE SHIFT4 ^G#4

# top row, unshifted: track select
G6  C2
G#6 C#2
A6  D2
A#6 D#2
B6  E2
C7  F2
C#7 F#2
D7  G2

# SELECT: rec
2^G6  C0
2^G#6 C#0
2^A6  D0
2^A#6 D#0
2^B6  E0
2^C7  F0
2^C#7 F#0
2^D7  G0

# SOLO: solo
3^G6  G#0
3^G#6 A0
3^A6  A#0
3^A#6 B0
3^B6  C1
3^C7  C#1
3^C#7 D1
3^D7  D#1

# MUTE: mute
4^G6  E1
4^G#6 F1
4^A6  F#1
4^A#6 G1
4^B6  G#1
4^C7  A1
4^C#7 A#1
4^D7  B1

# We also assign these to the function keys F1..F8 when shifted. You may want
# to remap these as needed.
^G6  F#4
^G#6 G4
^A6  G#4
^A#6 A4
^B6  A#4
^C7  B4
^C#7 C5
^D7  C#5

# The grid buttons are passed through unchanged, so that you can still use
# them as drum pads (provided that you filter out all MIDI channels except
# channel 10). Note that we use mod translations here, in order to preserve
# the velocities.

C3[]-10  C3-10
C#3[]-10 C#3-10
D3[]-10  D3-10
D#3[]-10 D#3-10
E3[]-10  E3-10
F3[]-10  F3-10
F#3[]-10 F#3-10
G3[]-10  G3-10
G#3[]-10 G#3-10
A3[]-10  A3-10
A#3[]-10 A#3-10
B3[]-10  B3-10
C4[]-10  C4-10
C#4[]-10 C#4-10
D4[]-10  D4-10
D#4[]-10 D#4-10

# Map the A..H buttons to program changes on channel 10 so that you can
# quickly switch the sounds of your drumkit, drum patterns etc. (This is just
# an example, you might want to disable these or remap them as you see fit.)

F#2 PC0-10
G2  PC1-10
G#2 PC2-10
A2  PC3-10
A#2 PC4-10
B2  PC5-10
C3  PC6-10
C#3 PC7-10

# big encoder assigned to MCP jog wheel
CC0~ CC60~

# encoders are mapped to the MCP channel faders
# (MC uses pitch bends here, use 129 as step size to get full range)
CC1~ PB[129]-1
CC2~ PB[129]-2
CC3~ PB[129]-3
CC4~ PB[129]-4
CC5~ PB[129]-5
CC6~ PB[129]-6
CC7~ PB[129]-7
CC8~ PB[129]-8
# master fader (touchstrip)
CC9[] PB[129]-9

# encoders become the MCP encoders when shifted (CC16..CC23, incremental mode)
^CC1~ CC16~
^CC2~ CC17~
^CC3~ CC18~
^CC4~ CC19~
^CC5~ CC20~
^CC6~ CC21~
^CC7~ CC22~
^CC8~ CC23~

# encoder touches = fader touches
E7  G#8
F7  A8
F#7 A#8
G7  B8
G#7 C9
A7  C#9
A#7 D9
B7  D#9
D#7 E9

# SELECT + encoder touches = push encoders -- we can't use SHIFT here since
# touches might easily get triggered when the encoders are moved
2^E7  G#2
2^F7  A2
2^F#7 A#2
2^G7  B2
2^G#7 C3
2^A7  C#3
2^A#7 D3
2^B7  D#3
2^D#7 E3

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

[MIDI2]

# transport
A7   F#5 $M0 # reset all meters, see "meter" in the MCP feedback section below
A#7  E5
B7   F5 # Rec
D7   C5 # Cycle
G7   C#5
G#7  D5
C#7  D#5

^F7  D5
^C7  D#5

# SMPTE/BBT
F4   C#6

# channel left/right keys
C4  E6
C#4 A5

# row above grid (track/pan/send/plugin)
E3   G#3
F#3  A3
F3   A#3
G3   B3

# feedback for the MC shift keys
A#5  A4  # Shift
B5   A#4 # Control
C6   B4  # Option
C#6  D3  # Alt/Cmd

# zoom (as the big encoder itself has no led, we light up the 4 leds around it
# instead; color: 4 = blue)
E8   C#2[4] D2[4] D#2[4] E2[4]

# select
# NOTE: Ardour apparently doesn't update these when changing banks.
C2  G6
C#2 G#6
D2  A6
D#2 A#6
E2  B6
F2  C7
F#2 C#7
G2  D7

# no feedback for encoders, only touchstrip
PB[128]{0}-9 CC9'

# MCP feedback (simply passed through, ctlra_daemonx handles these
# automagically).

# rec/solo/mute

C0[]  C0
C#0[] C#0
D0[]  D0
D#0[] D#0
E0[]  E0
F0[]  F0
F#0[] F#0
G0[]  G0

G#0[] G#0
A0[]  A0
A#0[] A#0
B0[]  B0
C1[]  C1
C#1[] C#1
D1[]  D1
D#1[] D#1

E1[]  E1
F1[]  F1
F#1[] F#1
G1[]  G1
G#1[] G#1
A1[]  A1
A#1[] A#1
B1[]  B1

# meter values
CP[] CP

# 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}

# timecode
CC64[] CC64
CC65[] CC65
CC66[] CC66
CC67[] CC67
CC68[] CC68
CC69[] CC69
CC70[] CC70
CC71[] CC71
CC72[] CC72
CC73[] CC73