Difference between revisions of "Supported plug & play MIDI controllers"

From ZynthianWiki
Jump to navigation Jump to search
m (Move the remaining devices out to separate pages)
 
(116 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
Zynthian can be connected to almost any existing MIDI device and you can use the MIDI learning mechanism, as described in the [[Zynthian_UI_User_Guide_-_V1/V4|UI user's guide]], to assign parameters to faders and knobs in your MIDI controller, for instance. You could also assign pad trigger to notes, etc. But MIDI learning process takes time, it's limiting and you can't get feedback easily. Sometimes it's a lot better to plug a well-known (supported) MIDI controller and get everything mapped automatically. For having this, zynthian implements a controller driver API that allows developers to create specific drivers for specific devices.  
+
==Introduction==
 +
Zynthian can be connected to almost any existing MIDI device and you can use the MIDI learning mechanism, as described in the [[Zynthian_UI_User_Guide_-_V1/V4|UI user's guide]], to assign parameters to faders and knobs in your MIDI controller, for instance. You could also assign pad trigger to notes, etc. But MIDI learning process takes time, it's limiting and you can't get feedback easily. Sometimes it's a lot better to plug a well-known (supported) MIDI controller and get everything mapped automatically. For having this, Zynthian implements a controller driver API that allows developers to create specific drivers for specific devices.
  
−
This section contain documentation for some of this controller drivers.
+
===Supported Drivers and Guides===
 +
* After expanding greatly, the driver page has been split into multiple pages according to similar devices. See [[#Driver Pages|'''Driver Pages''']] for a categorised list of device driver pages.
 +
* There is also a [[#Table of Device Features|'''sortable table of devices''']] to get a glance of what devices have drivers and what functions are available for them. Click the title link to go to the device driver page.
 +
* As with the rest of the wiki, some information here may be slightly out of date, there may be devices available that aren't shown here. For more up to date info on driver development, see the forum. For a list of drivers currently integrated into Zynthian you can check [https://github.com/zynthian/zynthian-ui/tree/vangelis/zyngine/ctrldev the (Vangelis version) list on github].
  
−
{{NoteBox|This documentation is valid for the "chain_manager" development branch. It's only partially valid for the current testing branch so you could find some differences.}}
+
===Accessing Drivers in Zynthian===
 +
As the title hints, if you connect your device (via USB), Zynthian will automatically load the driver if a compatible one exists. Where there are multiple drivers for a given device (or to use a generic driver such as Mackie Control, the active driver mode can be selected from within the '''Midi Input Devices''' menu from the Chain Manager screen or the individual chain options screen (also the admin menu). '''Bold press''' the driver entry for further options.
  
 +
===Driver Functions===
 +
This section contains documentation for some of these controller drivers. There are two core driver functions which control the primary screens in the Zynthian UI:
 +
* '''Launcher mode (Zynpad)''': Launch patterns in the launcher grid interface (as with DAWs like Ableton or Logic)
 +
* '''Mixer mode (ZynMixer)''': Control chain levels, mutes and solo. Different devices may have some additional controls and functions.
 +
There are also additional driver modes/functions depending on the device and driver:
 +
* '''UI Navigation''': Adds some degree of UI navigation control via arrow buttons or by emulating encoders & buttons on the device
 +
* '''SuperLooper Mode''': Provides an interface to the native SuperLooper UI within Zynthian for looping live performance.
 +
* '''Sequencer Mode (ZynSeq)''': (Sequencer functionality for the device depends on the Zynthian version installed) Provides some degree of control over the sequencer or pattern editor.
 +
* '''Moder Mode''': Adjusts device note inputs to stay in scale or provides some chord functionality
 
<br clear=all>
 
<br clear=all>
 +
==Driver Pages==
 +
* [[Akai APC Series]]
 +
* [[Akai MIDI MIX]]
 +
* [[Akai MPK Series]]
 +
* [[Arturia Keylab Series]]
 +
* [[Novation Launchpad Series]]
 +
* [[Novation Launchkey Series]]
 +
* [[Behringer MOTÖR 61 / 49]]
 +
* [[Korg nanoKONTROL Series]]
 +
* [[Fostex Mixtab]]
 +
* [[Mackie Control]]
 +
* [[Teenage Engineering OP-1]]
 +
* [[SooperLooper CCx10, for Behringer FCB1010 & others]]
 +
* [[Worlde Mini Moder Driver]]
 +
* [[Sinco smk25]]
  
−
==Akai APC Key25 MK2==
+
==Table of Device Features==
−
 
+
{| class="wikitable sortable" style="text-align:center;"
−
This device supports three operation modes:
+
|- style="font-weight:bold;"
−
 
+
! style="vertical-align:middle;" | Device
−
* The '''"Mixpad"''' mode (default), which controls the Zynthian's Mixer and ZynPad.
+
! style="vertical-align:middle;" | Launcher mode (ZynPad)
−
* The '''"Device"''' mode, which handles the Zynthian UI.
+
! style="vertical-align:middle;" | Mixer mode (ZynMixer)
−
* The '''"Sequencer"''' mode, which handles the Zynthian Step Sequencer.
+
! UI Navigation
−
 
+
! style="vertical-align:middle;" | SuperLooper mode
−
====The Mixpad mode====
+
! style="vertical-align:middle;" | Sequencer mode (ZynSeq)
−
 
+
! style="text-align:left;" | Moder (chords/scales)
−
[[File:akai_apc_key25_mk2.png|800px|right]]
+
! style="vertical-align:middle;" | Extra features / notes
−
 
+
|-
−
This is the default mode, selected automatically on start. You can also change to it pressing <code>SHIFT</code> + <code>VOLUME</code> or <code>SHIFT</code> + <code>PAN</code>. In this mode you can perform the following actions:
+
| style="vertical-align:middle; text-align:left;" | [[Akai APC Series|Akai APC Key25 MK2]][[File:Akai_apc_key25_mk2.png|150px|left]]
−
 
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
* Tap a pad to '''start/stop a sequence'''. The pad LED will show its status as follows (pad color will always match the sequence color):
+
| style="background-color:#C8E6C9;" | yes
−
** Dim solid: Stopped sequence without content (no notes in patterns).
+
| style="background-color:#F8D7DA;" | no
−
** Bright solid: Stopped sequence with content.
+
| style="background-color:#F8D7DA;" | no
−
** Blinking slow: Playing sequence.
+
| style="background-color:#C8E6C9;" | yes
−
** Blinking fast: Recording sequence.
+
| style="background-color:#F8D7DA;" | no
−
** Pulsing: Syncing to play/stop.
+
| style="vertical-align:middle; text-align:left;" | Mixpad (default) controls Mixer + ZynPad; also Step Sequencer / pattern editor; Device mode controls the Zynthian UI.
−
 
+
|-
−
* Change controller's bank. There are '''two banks''' (1 and 2), which are used to handle up to 16 chains (with the eight track buttons/knobs). Bank 1 is for chains 1 to 8 and bank 2 manage chains 9 to 16. To show current selected bank, press and hold <code>SHIFT</code>. One of the track buttons <code>LEFT arrow</code> or <code>RIGHT arrow</code> will light up in red, <code>LEFT arrow</code> is bank 1 and <code>RIGHT arrow</code> is bank 2. You can press one of these buttons while holding <code>SHIFT</code> to change the bank.
+
| style="vertical-align:middle; text-align:left;" | [[Akai APC Series|Akai APC Key25 MK2 + SL]]
−
 
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
* Use track buttons to '''perform a function''' on chains. The function is chosen by pressing <code>SHIFT</code> + one of <code>SELECT</code>, <code>MUTE</code> or <code>SOLO</code> soft key buttons. Press and hold <code>SHIFT</code> to see current selected function on soft key buttons (in green). Functions are:
+
| style="background-color:#C8E6C9;" | yes
−
** <code>SELECT</code>, used to change the selected chain. The key bed (black and white keys) will play on that chain.
+
| style="background-color:#C8E6C9;" | yes
−
** <code>MUTE</code>, used to mute the corresponding chain.
+
| style="background-color:#C8E6C9;" | yes
−
** <code>SOLO</code>, used to enable solo in the corresponding chain.
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
 
+
| style="background-color:#F8D7DA;" | no
−
* '''Mute main chain''', pressing <code>SHIFT</code> + <code>PLAY</code>.
+
| style="vertical-align:middle; text-align:left;" | Adds SooperLooper looper controls + Levels/Pan/Sync&Quantize/Session save+load; base modes otherwise match the non-SL driver.
−
 
+
|-
−
* '''Change current scene''' using the track buttons. You need first to select that function by pressing <code>SHIFT</code> + <code>REC ARM</code> button. This function is affected by bank selection, so you can change up to 16 scenes. When selecting a new scene, the ZynPad will be shown.
+
| style="vertical-align:middle; text-align:left;" | [[Akai MIDI MIX]][[File:Akai-midi-mix.jpg|150px|left]]
−
 
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
* Start/stop '''sequences of a row''', pressing the corresponding SOFT KEY (without modifiers). If there are any sequence playing, they will stop. If there are no sequences playing, it will start those not empty. The action to be run is shown by the LED status (lit will stop, off will start).
+
| style="background-color:#C8E6C9;" | yes
−
 
+
| style="background-color:#F8D7DA;" | no
−
* Use knobs to modify '''chains' volume or balance'''. The function is given by current KNOB CTRL selected: <code>VOLUME</code> or <code>PAN</code> (for balance). To change the function, press <code>SHIFT</code> + <code>VOLUME</code> or <code>SHIFT</code> + <code>PAN</code>. The knobs are also affected by current controller's bank.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
* Use <code>SHIFT</code> + <code>KNOB k1</code> to change volume or balance for main chain (what changes is selected by the current KNOB CTRL function).
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; text-align:left;" | Maps mixer functionality (chains 1–16 via banks, master slider, balance, mute/solo, rec-arm).
−
* Press <code>SHIFT</code> + <code>STOP ALL CLIPS</code> for a ''''panic' stop''', which stops all sequences, audio and midi playback.
+
|-
−
 
+
| style="vertical-align:middle; text-align:left;" | [[Akai MPK Series|Akai MPK mini MK3]][[File:Akai-mpk-mini-top.jpg|150px|left]]
−
* '''Toggle audio playback''' with <code>PLAY/PAUSE</code> button. If Zynthian's ALT mode is active, it will '''toggle MIDI playback'''.
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
 
+
| style="background-color:#C8E6C9;" | yes
−
* '''Toggle audio record''' with <code>SHIFT</code> + <code>RECORD</code> button. If Zynthian's ALT mode is active, it will '''toggle MIDI recording'''.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="background-color:#F8D7DA;" | no
−
* '''Stop all sequences''' of current scene (but not audio/midi playback or recording), doing a ''short'' press on <code>STOP ALL CLIPS</code> button; ''bold'' press to stop all sequences on all scenes.  
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
 
+
| style="background-color:#F8D7DA;" | no
−
* Open the '''StepSeq mode''' for a given sequence, pressing <code>SHIFT</code> + a pad button.
+
| style="vertical-align:middle; text-align:left;" | Modes: Mixer (default), Device UI, Pattern (ZynPad + Pattern Editor), NotePad; plus User and Config modes.
−
 
+
|-
−
* '''Clear a sequence''', pressing any track button + the sequence pad.
+
| style="vertical-align:middle; text-align:left;" | [[Akai MPK Series|Akai MPK mini MK3 Moder]]
−
 
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
* Start '''recording a pattern'''. For this, press <code>RECORD</code> + a pad button, which will 1) select the chain associated with the group of the sequence, 2) open the pattern editor for that sequence, 3) start playing the sequence and 4) start recording that sequence. If you press the pad again (without holding any other button), the recording will stop. Press again to stop playback too. You can also control the playback/recording with <code>PLAY/PAUSE</code> and <code>SHIFT</code> + <code>RECORD</code> buttons.  
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="background-color:#F8D7DA;" | no
−
* If the pattern editor is open, press <code>SHIFT</code> + <code>UP arrow</code> to '''go back to ZynPad'''. Press it again to go to mixer screen.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
* '''Open the ZynPad''' pressing <code>SHIFT</code> + <code>DOWN arrow</code>.
+
| style="background-color:#C8E6C9;" | yes
−
 
+
| style="vertical-align:middle; text-align:left;" | This is a very simple "Mode Enforcer" driver for the Akai MPK mini MK3.
−
* Open the '''sequence manager''' (also known as the ''Seqman'' sub-mode), pressing <code>SHIFT</code> + <code>CLIP STOP</code>. If this mode is active, the LED of the <code>CLIP STOP</code> button will blink in green, and one of <code>VOLUME</code>, <code>PAN</code> or <code>SEND</code> buttons will also be solid in red, each one related to a specific function:
+
|-
−
** <code>SEND</code>: this is CLEAR mode. It will remove all patterns of the sequence when its pad is pressed (leaving only a single empty pattern).
+
| style="vertical-align:middle; text-align:left;" | [[Novation Launchpad Series|Novation LAUNCHPAD MINI MK1]][[File:Novation_launchpad_mini_mk1_zynpad.png|150px|left]]
−
** <code>VOLUME</code>: this is COPY mode. Press the pad of a non-empty sequence to mark it as source (it will blink fast). Press another pad to copy the selected source to it. It will CLEAR the destination sequence, and then copy all the patterns of the source sequence. Press the selected source pad to clear selection.
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
** <code>PAN</code>: this is MOVE mode. It works like COPY mode, but also CLEARS the source sequence.
+
| style="background-color:#F8D7DA;" | no
−
** Use <code>LEFT</code> and <code>RIGHT</code> arrows to move from one scene to another. You can also copy/move patterns between scenes.
+
| style="background-color:#F8D7DA;" | no
−
** Press <code>SHIFT</code> + <code>SELECT</code> to exit this sub-mode.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
====The Device mode====
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; text-align:left;" | ZynPad driver.
−
[[File:Akai-apc-key-25-mk2-ui-legend.png|800px|right]]
+
|-
−
 
+
| style="vertical-align:middle; text-align:left;" | [[Novation Launchpad Series| Novation LAUNCHPAD MINI MK3]][[File:Novation_launchpad_mini_mk3_zynpad.png|150px|left]]
−
This mode allows you to '''control the Zynthian UI'''. You can enable it by pressing <code>SHIFT</code> + <code>DEVICE</code>. If this mode is active, the button <code>DEVICE</code> will blink in red.
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
 
+
| style="background-color:#F8D7DA;" | no
−
As you can see in the image, this mode mimics the Zynthian V5 hardware interface. The upper four buttons are <code>OPT/ADMIN</code>, <code>MIX/LEVEL</code>, <code>CTRL/PRESET</code> and <code>ZS3/SHOT</code>. Next row is <code>ALT</code>, <code>METRONOME</code> and <code>PAD/STEP</code>. The four buttons at the right side (in white) are <code>F1</code> to <code>F4</code>. In this mode, transport is handled by <code>PLAY/PAUSE</code> and <code>RECORD</code> buttons, and the transport pads are only to show playback/recording status. Navigation buttons are <code>UP</code>, <code>DOWN</code>, <code>LEFT</code>, <code>RIGHT</code>, (in yellow) <code>BACK/NO</code> (in red) and <code>SEL/YES</code> (in green). For the directional keys, you can also use the track keys labelled as such.  
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="background-color:#F8D7DA;" | no
−
The behaviour and status are '''similar of those in the hardware interface''': there is support for short, bold and long press; screen access buttons are blue when no function is selected, green on it's primary and orange on its secondary function; <code>ALT</code> key changes to violet when active (and <code>F1</code>-<code>F4</code> also change).
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
 
+
| style="background-color:#F8D7DA;" | no
−
The nearest four knobs has the functions of '''Knob#1''' to '''Knob#4'''. They can be used to control volume of selected/main chain, move vertically/horizontally in pattern editor or Zynpad, move selected item in menus, etc. Press <code>SHIFT</code> with a knob for a finer (slower) adjustment. The knob press is activated using the first four soft keys to the left (in green), and also has short/bold press support. The mapping is: '''Knob#1''' = (<code>K1</code>, <code>CLIP STOP</code>); '''Knob#2''' = (<code>K5</code>, <code>SOLO</code>); '''Knob#3''' = (<code>K2</code>, <code>MUTE</code>); '''Knob#1''' = (<code>K6</code>, <code>REC ARM</code>). This scheme is very comfortable in the V4 four-corners layout.
+
| style="vertical-align:middle; text-align:left;" | ZynPad driver.
−
 
+
|-
−
<br clear=all>
+
| style="vertical-align:middle; text-align:left;" | [[Novation Launchpad Series| Novation LAUNCHPAD PRO MK2]][[File:Novation_launchpad_pro_mk2_zynpad.jpg|150px|left]]
−
 
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
====The Step Sequencer mode====
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
 
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
<embedvideo alignment="right" dimensions="600" service="youtube" description="Zynthian - Akai APC Key25 mk2 - StepSeq (alpha) demo I">https://www.youtube.com/watch?v=Y4JTWJTz2Q0</embedvideo>
+
| style="background-color:#F8D7DA;" | no
−
<embedvideo alignment="right" dimensions="600" service="youtube" description="Zynthian - Akai APC Key25 mk2 - StepSeq (alpha) demo II">https://www.youtube.com/watch?v=zprRUIbjHqs</embedvideo>
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
<embedvideo alignment="right" dimensions="600" service="youtube" description="Zynthian - Akai APC Key25 mk2 - StepSeq (beta) demo III">https://www.youtube.com/watch?v=3EPUusfwmEg</embedvideo>
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; text-align:left;" | Three modes using the top row buttons:
−
This mode allows you to control Zynthian's step sequencer (and also the pattern editor). You can activate it by pressing <code>SHIFT</code> + <code>SEND</code>, or in '''Mixpad''' mode pressing <code>SHIFT</code> + a sequence pad. In this mode, the pad matrix is divided in two parts: first four rows (from top to bottom) are '''the steps''' of current pattern. The last row is used to assign notes or '''instruments''' for easy access (called ''NotePads'' in this document). With this mode, you can:
+
* Launcher - similar function to Ableton Live
−
 
+
* Mixer - volume, pan and (needs testing) sends
−
* '''Open the pattern editor''' in Zynthian's UI with the current pattern, pressing <code>SHIFT</code> + <code>DOWN</code>. Press <code>SHIFT</code> + <code>UP</code> to go back.
+
* Device Control - emulates the 20 button array of the V5 and encoder buttons
−
 
+
|-
−
* '''Assign an instrument''' to a NotePad, by pressing the pad + any key of the key bed (black and white keys). The note will be ''stored'' in that pad, with the velocity you used. It will be lit with a brightness proportional to the velocity. If you press again the NotePad, it will play the note.
+
| style="vertical-align:middle; text-align:left;" | [[Novation Launchpad Series| Novation LAUNCHPAD PRO MK3]][[File:Novation_launchpad_pro_mk3_zynpad.jpg|150px|left]]
−
 
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
* '''Remove a NotePad assignment''', pressing <code>STOP ALL CLIPS</code> + the NotePad. Only the assignment is removed, the steps for that note are kept.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="background-color:#F8D7DA;" | no
−
* '''Select the active instrument''', pressing <code>SHIFT</code> + a NotePad. It will start pulsating in the color of the instrument's page.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
* '''Change current instruments page''', pressing <code>LEFT</code> and <code>RIGHT</code> arrows. There are 4 pages, each with its own color (1: blue, 2: green, 3: yellow, 4: purple). Upon selecting a new page, one of the first four track buttons will be lit for a second, indicating the active page.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; text-align:left;" | ZynPad driver.
−
* '''Toggle a step''' in the current pattern, pressing a pad in the upper four rows. If the step is on, it will be lit in red (again, the brightness is proportional to the note velocity). Note that for this to work, you will need to first select an active NotePad.
+
|-
−
 
+
| style="vertical-align:middle; text-align:left;" | [[Novation Launchpad Series| Novation LAUNCHPAD X]][[File:Akai-mpk-mini-top.jpg|150px|left]]
−
* '''Extend a step duration''', by pressing an active step, holding it for 0.5 seconds, and then pressing another step (it must be greater in sequence). The source step will increase its duration to fill the space between the two pressed steps (included). The extended duration will be lit in orange. If you press the last pad in orange (while still holding the starting step), it will toggle between full and half step.
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
 
+
| style="background-color:#F8D7DA;" | no
−
* '''Play current sequence''' pressing the <code>PLAY</code> button. You will see the playhead (in white) moving along the steps. Pressing <code>SHIFT</code> + <code>PLAY</code> will start stage-play, which will update the pattern as it moves along the current track (press any pad to stop stage-play). Press <code>PLAY</code> again to stop playing.
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="background-color:#F8D7DA;" | no
−
* '''Panic stop''' all sounds, pressing <code>SHIFT</code> + <code>STOP ALL CLIPS</code>. Any sound will stop immediately.  
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
 
+
| style="background-color:#F8D7DA;" | no
−
* '''Adjust the tempo''' rotating the knob <code>K1</code>. The TEMPO screen will be shown briefly in the UI. Press <code>SHIFT</code> while rotating for a finer adjustment (0.1 BPM).  
+
| style="vertical-align:middle; text-align:left;" | ZynPad driver.
−
 
+
|-
−
* '''Adjust sequence's chain level''' rotating the knob <code>K2</code>. Also, the Mixer screen will be shown briefly in the UI while adjusting. Press <code>SHIFT</code> while rotating for a finer control.
+
| style="vertical-align:middle; text-align:left;" | [[Novation Launchkey Series| Novation LAUNCHKEY MINI MK3]][[File:Launchkey_mini_mk3.jpg|150px|left]]
−
 
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
* Change the '''velocity, duration, stutter count or stutter duration''' of a step or NotePad, pressing the corresponding pad and rotating one of the following knobs:
+
| style="background-color:#C8E6C9;" | yes
−
** <code>K1</code>: note duration
+
| style="background-color:#F8D7DA;" | no
−
** <code>K2</code>: note velocity
+
| style="background-color:#F8D7DA;" | no
−
** <code>K3</code>: stutter count
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
** <code>K4</code>: stutter duration
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; text-align:left;" | Mixer + ZynPad.
−
* You can also change these properties using '''control levels'''. With a control level, you will use the columns of the pad matrix to see and change the level of certain property of a step or NotePad. These are the key bindings:
+
|-
−
** Press <code>VOLUME</code> + a step/NotePad to activate the control level for '''velocity''' adjustment. <code>VOLUME</code>'s track button will be solid lit in red. Press <code>VOLUME</code> again to exit control level mode.
+
| style="vertical-align:middle; text-align:left;" | [[Novation Launchkey Series| Novation LAUNCHKEY 88 MK3]][[File:Launchkey_88_mk3.jpg|150px|left]]
−
** Press <code>SEND</code> + a step/NotePad for '''stutter count''' adjustment. <code>SEND</code>'s track button will be solid lit in red.
+
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
−
** In stutter count control level, press again <code>SEND</code> to switch to '''stutter duration''' adjustment. <code>SEND</code>'s track button will blink in red. Press <code>SEND</code> again to exit control level mode.
+
| style="background-color:#C8E6C9;" | yes
−
** If, instead of pressing a pad, you press <code>VOLUME</code> or <code>SEND</code> + one of the 5 soft keys to the right, it will '''open the control level for each step or NotePad''' in that row. Now, just pressing another soft key will switch to the related row.
+
| style="background-color:#F8D7DA;" | no
−
** You can switch between different control levels by pressing the function that is not currently active (otherwise, it will exit that control level).
+
| style="background-color:#F8D7DA;" | no
−
** Pressing <code>SHIFT</code> + any pad in the active column will set the property value to zero (or 1, in case of stutter duration).
+
| style="vertical-align:middle; background-color:#F8D7DA;" | no
−
** Press a pad in any active column to '''change''' the related step/NotePad value. Press top lit pad to switch between full and half value (the brightness will also change). The following table shows the relation between rows and values of each function (rows are from bottom to top, values are for Full/Half):
+
| style="background-color:#F8D7DA;" | no
−
 
+
| style="vertical-align:middle; text-align:left;" | Mixer + ZynPad.
−
{| class="wikitable center"
+
|-
 +
| style="vertical-align:middle; text-align:left;" | [[Behringer MOTÖR 61 / 49]][[File:Behringer_motor.jpg|150px|left]]
 +
| style="vertical-align:middle; background-color:#C8E6C9;" | yes
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; text-align:left;" | This driver is focused in stage control of setBfree and Pianoteq engines. It also includes the mode enforcer that can be controlled from the pads (notes).
 +
|-
 +
| style="vertical-align:middle; text-align:left;" | [[Korg nanoKONTROL Series|Korg nanoKONTROL]][[File:NanoKONTROL1.png|150px|left]]
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; text-align:left;" | Not currently available.
 +
|-
 +
| style="vertical-align:middle; text-align:left;" | [[Korg nanoKONTROL Series|Korg nanoKONTROL-2]][[File:NanoKONTROL2.png|150px|left]]
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; text-align:left;" | ZynMixer driver with UI navigation.
 +
|-
 +
| style="vertical-align:middle; text-align:left;" | [[Mackie Control]][[File:Mackie_control.jpg|150px|left]]
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; text-align:left;" | This driver can be loaded for devices that support MCU protocol and variants.
 +
|-
 +
| style="vertical-align:middle; text-align:left;" | [[Fostex Mixtab]][[File:Mixtab.png|150px|left]]
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; text-align:left;" | This driver maps the hardware controls to relevant parameters in zynthian (mostly zynmixer).
 +
|-
 +
| style="vertical-align:middle; text-align:left;" | [[Teenage Engineering OP-1]][[File:Te-op1.jpg|150px|left]]
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; text-align:left;" | Encoder control of parameters and UI navigation via encoders and buttons.
 +
|-
 +
| style="vertical-align:middle; text-align:left;" | [[SooperLooper CCx10, for Behringer FCB1010 & others]][[File:Fcb1010.jpeg|150px|left]]
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="vertical-align:middle; background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="vertical-align:middle; text-align:left;" | SooperLooper CCx10 controller support.
 +
|-
 +
| style="text-align:left;" | [[Worlde Mini Moder Driver]]
 +
[[File:Worlde mini.png|150px|left|Worlde mini midi keyboard]]
 +
| style="background-color:#ffce93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="text-align:left;" |
 +
|-
 +
| style="text-align:left;" | [[Akai MPK Series|Akai MPK249]][[File:Akai mpk249.webp|Akai mpk249|150px|left]]
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="text-align:left;" |
 
|-
 
|-
−
! Row !! Velocity !! Stutter Count !! Stutter Duration
+
| style="text-align:left;" | [[Novation Launchkey Series|Launchkey Mini Mk4 37]][[File:LaunchKeyM37-MKIV.jpg|150px|left|Launchkey Mini Mk4]]
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="text-align:left;" |
 
|-
 
|-
−
| 1 || 25 / 12 || 2 / 1 || 2 / 1
+
| style="text-align:left;" | [[Launchkey Mini Mk3]][[File:LaunchkeyMiniMk3.jpg|150px|left|Launchkey Mini Mk3]]
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="text-align:left;" |  
 
|-
 
|-
−
| 2 || 50 / 38 || 4 / 3 || 4 / 3
+
| style="text-align:left;" | [[Novation Launchkey Series|Launchkey Mk3 88]][[File:Launchkey88.jpg|150px|left|Launchkey88]]
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="text-align:left;" |  
 
|-
 
|-
−
| 3 || 76 / 63 || 8 / 6 || 8 / 6
+
| style="text-align:left;" | [[Novation Launchkey Series|Launchkey Mk4 37]][[File:Launchkey37-MKIV.jpg|150px|left|Launchkey37-MKIV]]
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="text-align:left;" |  
 
|-
 
|-
−
| 4 || 101 / 88 || 12 / 10 || 20 / 10
+
| style="text-align:left;" | [[Sinco smk25]]
 +
[[File:Simco smk25.webp|150px|left|Simco smk25]]
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="text-align:left;" |  
 
|-
 
|-
−
| 5 || 127 / 114 || 20 / 15 || 40 / 30
+
| style="text-align:left;" | [[Arturia Keylab Series|Arturia Keylab Mk2 61]]
 +
[[File:Arturia keylab mk2 61.jpg|150px|left|Arturia keylab mk2 61]]
 +
| style="background-color:#C8E6C9;" | yes
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#FFCE93;" | tbc
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="background-color:#F8D7DA;" | no
 +
| style="text-align:left;" |  
 
|}
 
|}
−
 
−
* Quick '''change pattern''' in current track, by pressing <code>SHIFT</code> + <code>LEFT</code>/<code>RIGHT</code>. If next pattern (to the right) does not exist, it will be created (up to 8 patterns). The bottom row of the pad matrix will show current pattern (in red), and also where there exists a pattern (bright white) or not (dim white).
 
−
 
−
* '''Roll current pattern to a side''', pressing <code>SHIFT</code> + <code>SELECT</code> + <code>LEFT</code> or <code>RIGHT</code>. This will copy current pattern to the pattern on the left or right.
 
−
 
−
* You can also '''enter the arranger sub-mode''' (also called ''PatMan'', for pattern manager), to handle the patterns of current track, pressing <code>SHIFT</code> + <code>SELECT</code>. This mode will also open the arranger in Zynthian's UI. In this sub-mode, you can:
 
−
** '''Change''' current pattern, just pressing a pad where there is a pattern (bright white). The selected pattern will be shown in red. You can also move to the left or right using the track buttons.
 
−
** '''Clear''' a pattern, pressing <code>MUTE</code> + pattern pad. It will remove all notes on that pattern. The pad will blink briefly in red.
 
−
** '''Remove''' a pattern, pressing <code>STOP ALL CLIPS</code> + pattern pad. The pattern will be removed, and all patterns to the right will slide to fill the gap.
 
−
** '''Create''' a new empty pattern, if there are no pattern to the right, by pressing <code>SHIFT</code> + <code>RIGHT</code>.
 
−
** '''Roll''' current pattern to one side, pressing <code>SHIFT</code> + <code>SELECT</code> + <code>LEFT</code> or <code>RIGHT</code>.
 
−
** '''Copy''' a pattern to another pattern, pressing source pattern pad + destination pattern pad. The destination will blink briefly in green.
 
−
** To exit this sub-mode, press <code>SELECT</code>. Zynthian's UI will also go to the previous screen.
 
−
 
−
<br clear=all>
 
−
 
−
==Akai MIDI MIX==
 
−
====ZynMixer driver====
 
−
 
−
[[File:Akai-midi-mix.jpg|800px|right]]
 
−
 
−
This Akai MIDIMix driver maps the basic mixer's functionality.
 
−
Chains are numbered from left to right as shown in the zynmixer screen. Note that these numbers are not MIDI channels! 
 
−
 
−
* '''Bank Left:''' Strips assigned to chains 1-8
 
−
* '''Bank Right:''' Strips assigned to chains 9-16
 
−
* '''Master Slider:''' Main volume
 
−
* '''Strip 1-8:''' Chain's mixer control, depending of bank selection
 
−
** '''Upper Knobs:''' The 2 upper knobs are available for MIDI learning. 
 
−
** '''Lower Knob:''' Chain's balance
 
−
** '''Mute:''' Chain's mute switch
 
−
** '''Solo''': Push <code>SOLO</code> to see solo status. Push <code>SOLO</code> + <code>MUTE</code> for toggling solo.   
 
−
** '''Rec Arm''': Red light indicates active chain. Push to set active chain.
 
−
** '''Slider:''' Chain's volume
 
  
 
<br clear=all>
 
<br clear=all>
  
−
==Akai MPK mini MK3==
 
  
−
The driver for this device has 4 main operation modes:
 
  
−
* The '''Mixer''' mode (default) which handles Zynthian's Mixer.
 
−
* The '''Device''' mode, to control the Zynthian GUI (Graphical User Interface).
 
−
* The '''Pattern''' mode, for controlling the Zynpad and Pattern Editor.
 
−
* The '''NotePad''' mode, which is used to assign the notes that the Pads will play.
 
  
−
There are two more minor modes, which are:
 
  
−
* A '''User''' mode, where every PAD and KNOB is available for MIDI learn.
 
−
* A '''Config''' mode, used to configure the MPK internal settings, like the channels, the arpeggiator, and more.
 
  
−
====The Mixer mode====
 
  
−
In this mode, you can use the Knobs directly to adjust the chains settings.
+
==Technical Info For Driver Developers==
  
−
<br clear=all>
+
Drivers are python modules implementing a class. This class can call internal zynthian-ui API, so it has full access to Zynthian functionality. It’s not limited by CUIA. No limits, so you can break the UI too 😉
  
−
==Novation LAUNCHPAD MINI MK1==
+
<blockquote>'''NOTE:''' the name of the class should be identical to that of the file name. This is a common pitfall when developing new drivers.</blockquote>
−
====ZynPad driver====
 
  
−
[[File:novation_launchpad_mini_mk1_zynpad.png|800px|right]]
+
<code>dev_ids</code> is a list of identifiers that the driver will match. You can find this by looking at the name of the device in the MIDI Input view in Zynthian. If you bold press the corresponding input to see its options menu, the "Rename port" option shows its USB port / MIDI input name. Use the MIDI input name for your <code>dev_ids</code> list, e.g. Rename port 'USB:2.2/Launchkey Mini MK3 In 2' would provide the device id: "Launchkey Mini MK3 In 2".
  
−
<br clear=all>
+
You can check the full code here:
  
−
==Novation LAUNCHPAD MINI MK3==
+
[https://github.com/zynthian/zynthian-ui/blob/oram/zyngine/zynthian_ctrldev_manager.py zynthian-ui/zyngui/zynthian_ctrldev_manager.py zynthian/zyngine · GitHub]
−
====ZynPad driver====
 
  
−
[[File:novation_launchpad_mini_mk3_zynpad.png|800px|right]]
+
and some example drivers here:
  
−
<br clear=all>
+
[https://github.com/zynthian/zynthian-ui/tree/oram/zyngine/ctrldev zynthian-ui/zyngine/ctrldev/ · GitHub]
  
−
==Novation LAUNCHPAD PRO MK2==
+
All drivers must inherit from ''zynthian_ctrldev_base'', implementing the needed functionality as commented in the base code:
−
====ZynPad driver====
 
  
−
[[File:novation_launchpad_pro_mk2_zynpad.png|800px|right]]
+
<pre>
  
−
It works much like the Launchpad Mini MK3.
+
#------------------------------------------------------------------------------------------------------------------
 +
# Control device base class
 +
#------------------------------------------------------------------------------------------------------------------
  
−
<br clear=all>
+
class zynthian_ctrldev_base():
  
−
==Novation LAUNCHPAD PRO MK3==
+
dev_id = None  # String that identifies the device (class variable!)
−
====ZynPad driver====
+
dev_zynpad = False # Can act as a zynpad trigger device
 +
dev_zynmixer = False # Can act as an audio mixer controller device
 +
dev_pated = False # Can act as a pattern editor device
  
−
[[File:novation_launchpad_pro_mk3_zynpad.png|800px|right]]
 
  
−
It works much like the Launchpad Mini MK3.
+
# Function to initialise class
 +
def __init__(self):
 +
self.idev = 0 # Slot index where the device is connected, starting from 1 (0 = None)
 +
self.zyngui = zynthian_gui_config.zyngui
  
−
<br clear=all>
 
  
−
==Novation LAUNCHPAD X==
+
# Setup the device connected in slot #idev
−
====ZynPad driver====
+
# Before calling this, the caller (ctrldev-manager) should check that driver's ID string matches device's ID string
 +
def setup(self, idev=None):
 +
if idev != self.idev:
 +
# Release currently selected device, if any ...
 +
self.release()
 +
# Init new selected device
 +
if idev > 0:
 +
self.idev = idev
 +
logging.info("Setting-up {} in slot {}".format(self.dev_id, self.idev))
 +
# Setup routing
 +
lib_zyncore.zmip_set_route_extdev(self.idev - 1, 0)
 +
zynautoconnect.midi_autoconnect(True)
 +
# Initialize new selected device
 +
self.init()
 +
self.refresh(force=True)
  
−
[[File:novation_launchpad_x_zynpad.png|800px|right]]
 
  
−
It works much like the Launchpad Mini MK3.
+
def release(self):
 +
if self.idev > 0:
 +
logging.info("Releasing {} in slot {}".format(self.dev_id, self.idev))
 +
# If device is still connected, call end
 +
dev_id = zynautoconnect.get_midi_device_name(self.idev)
 +
if dev_id and dev_id == self.dev_id:
 +
self.end()
 +
# Restore routing
 +
lib_zyncore.zmip_set_route_extdev(self.idev - 1, 1)
 +
zynautoconnect.midi_autoconnect(True)
 +
self.idev = 0
  
−
<br clear=all>
 
  
−
==Novation LAUNCHKEY MINI MK3==
+
# Refresh device status (LED feedback, etc)
−
====ZynPad driver====
+
# It *SHOULD* be implemented by child class
 +
def refresh(self, force=False):
 +
logging.debug("Refresh LEDs for {}: NOT IMPLEMENTED!".format(self.dev_id))
  
−
[[File:novation_launchkey_mini_mk3_zynpad.png|800px|right]]
 
  
−
<br clear=all>
+
# Device MIDI event handler
 +
# It *SHOULD* be implemented by child class
 +
def midi_event(self, ev):
 +
logging.debug("MIDI EVENT FROM '{}'".format(self.dev_id))
  
−
==Behringer MOTÖR 61 / 49 ==
 
  
−
====ZynPad driver====
+
# Light-Off LEDs
 +
# It *SHOULD* be implemented by child class
 +
def light_off(self):
 +
logging.debug("Lighting Off LEDs for {}: NOT IMPLEMENTED!".format(self.dev_id))
  
−
[[File:behringer_motor.jpg|800px|right]]
 
  
−
====ZynMixer driver====
+
# Sleep On
 +
# It *COULD* be improved by child class
 +
def sleep_on(self):
 +
self.light_off()
  
−
<br clear=all>
 
  
−
==Korg nanoKONTROL ==
+
# Sleep On
 +
# It *COULD* be improved by child class
 +
def sleep_off(self):
 +
self.refresh(True)
 +
</pre>
  
−
====ZynMixer driver====
+
Quite simple, right? This is for basic “generic” drivers.
 +
Zynpad enabled drivers inherit from this base class:
  
−
[[File:NanoKONTROL1.png|800px|right]]
 
  
−
<br clear=all>
+
<pre>
 +
# ------------------------------------------------------------------------------------------------------------------
 +
# Zynpad control device base class
 +
# ------------------------------------------------------------------------------------------------------------------
  
−
==Korg nanoKONTROL-2  ==
+
class zynthian_ctrldev_zynpad(zynthian_ctrldev_base):
  
−
====ZynMixer driver====
+
dev_zynpad = True # Can act as a zynpad trigger device
  
−
[[File:NanoKONTROL2.png|800px|right]]
 
  
−
This Korg nanoKONTROL2 driver maps the mixer screen and transport buttons basic functionality.
+
def __init__(self):
−
Chains are numbered from left to right as shown in the zynmixer screen. Note that these numbers are not MIDI channels! 
+
super().__init__()
 +
self.zynpad = self.zyngui.screens["zynpad"]
  
−
=====Common buttons=====
 
  
−
* '''Cycle:''' SHIFT mode button. Toggle alternate functions as described below.
+
def refresh(self, force=False):
−
* '''Track Left:''' UI Left arrow
+
# When zynpad is shown, this is done by refresh_status, so no need to refresh twice
−
* '''Track Right:''' UI RIGHT arrow
+
if force or not self.zynpad.shown:
−
* '''Marker Set:''' UI SELECT button
+
self.refresh_pads(force)
−
* '''Marker Left:''' UI UP arrow
+
self.refresh_zynpad_bank()
−
* '''Marker Right:''' UI DOWN arrow
+
if force:
 +
self.refresh_zynpad_bank()
  
−
* '''Transport FRWD (Left):''' Bank 1. Strips assigned to chains 1-8. When light, it acts as the UI BACK button.
 
−
* '''Transport FFWD (Right):''' Bank 2. Strips assigned to chains 9-16
 
  
−
=====NORMAL mode=====
+
# It *SHOULD* be implemented by child class
 +
def refresh_zynpad_bank(self):
 +
pass
  
−
* '''Transport STOP:''' Stop audio play and reset play position.
 
−
* '''Transport PLAY:''' Start/Resume/Pause audio play. Light indicates playing state.
 
−
* '''Transport REC:''' Start/Stop audio recording. Light indicates recording state.
 
  
−
* '''Strip 1-8:''' Chain's mixer control, depending of bank selection
+
def refresh_pads(self, force=False):
−
** '''Knob:''' Chain's balance
+
if force:
−
** '''Slider:''' Chain's volume
+
self.light_off()
−
** '''M:''' Chain's mute switch
+
for pad in range(self.zyngui.zynseq.col_in_bank ** 2):
−
** '''S''': Chain's solo switch
+
# It MUST be called for cleaning the dirty bit
−
** '''R''': Red light indicates active chain. Push to set active chain.
+
changed_state = self.zyngui.zynseq.libseq.hasSequenceChanged(self.zynpad.bank, pad)
 +
if changed_state or force:
 +
mode = self.zyngui.zynseq.libseq.getPlayMode(self.zynpad.bank, pad)
 +
state = self.zynpad.get_pad_state(pad)
 +
self.update_pad(pad, state, mode)
  
−
=====SHIFT mode=====
 
  
−
* '''Transport STOP:''' Stop MIDI play and reset play position.
+
def refresh_pad(self, pad, force=False):
−
* '''Transport PLAY:''' Start/Resume/Pause MIDI play. Light indicates playing state.
+
# It MUST be called for cleaning the dirty bit!!
−
* '''Transport REC:''' Start/Stop MIDI recording. Light indicates recording state.
+
changed_state = self.zyngui.zynseq.libseq.hasSequenceChanged(self.zynpad.bank, pad)
 +
if changed_state or force:
 +
mode = self.zyngui.zynseq.libseq.getPlayMode(self.zynpad.bank, pad)
 +
state = self.zynpad.get_pad_state(pad)
 +
self.update_pad(pad, state, mode)
  
−
* '''Knobs 1-8:''' Available for engine control (MIDI learning).
 
  
−
* '''Strip 1-7:''' Chain's mixer control, depending of bank selection
+
# It *SHOULD* be implemented by child class
−
** '''Slider:''' Chain's volume
+
def update_pad(self, pad, state, mode):
−
** '''M:''' Chain's mute switch
+
pass
−
** '''S''': Chain's solo switch
+
#------------------------------------------------------------------------------
−
** '''R''': Chain's recorder arm switch
+
</pre>
  
−
* '''Strip 8:''' Main mixer control
 
−
** '''Slider:''' Main volume
 
−
** '''M:''' Main mute switch
 
−
** '''S''': Global solo indication. Switch does nothing.
 
−
** '''R''': Main recorder arm switch
 
  
−
<br clear=all>
+
If you kind-of-understand this, you shouldn’t have problem to understand the driver examples and program your own drivers. Simply copy your driver file in the the zyngui/ctrldev folder and restart zynthian-ui. Refer to this thread for more information [https://discourse.zynthian.org/t/new-control-device-manager-controller-device-drivers/8593/1 NEW: Control-device manager + controller device “drivers”]
  
−
==Mackie Control==
 
  
−
[[File:mackie_control.jpg|800px|right]]
+
==Driver Discussion on the Forum==
 +
Refer to some threads discussing driver development on different devices:
  
−
<br clear=all>
+
* https://discourse.zynthian.org/t/akai-apc-key25-mk2-driver/9082/168
 +
* https://discourse.zynthian.org/t/seeking-help-refactoring-midi-controller-device-drivers-for-vangelis/13218/29
 +
* https://discourse.zynthian.org/t/akai-mpk249-support/11825/45
 +
* https://discourse.zynthian.org/t/novation-launchkey-88-mk3-driver/13359
 +
* https://discourse.zynthian.org/t/akai-mpk-mini-plus-driver/9441
 +
* https://discourse.zynthian.org/t/driver-for-ableton-push-1-first-steps/12166/63
 +
* https://discourse.zynthian.org/t/ctrldev-driver-how-to-bypass-audio-processor-in-chain-solved/13095/9

Latest revision as of 11:33, 2 August 2026

1 Introduction

Zynthian can be connected to almost any existing MIDI device and you can use the MIDI learning mechanism, as described in the UI user's guide, to assign parameters to faders and knobs in your MIDI controller, for instance. You could also assign pad trigger to notes, etc. But MIDI learning process takes time, it's limiting and you can't get feedback easily. Sometimes it's a lot better to plug a well-known (supported) MIDI controller and get everything mapped automatically. For having this, Zynthian implements a controller driver API that allows developers to create specific drivers for specific devices.

1.1 Supported Drivers and Guides

  • After expanding greatly, the driver page has been split into multiple pages according to similar devices. See Driver Pages for a categorised list of device driver pages.
  • There is also a sortable table of devices to get a glance of what devices have drivers and what functions are available for them. Click the title link to go to the device driver page.
  • As with the rest of the wiki, some information here may be slightly out of date, there may be devices available that aren't shown here. For more up to date info on driver development, see the forum. For a list of drivers currently integrated into Zynthian you can check the (Vangelis version) list on github.

1.2 Accessing Drivers in Zynthian

As the title hints, if you connect your device (via USB), Zynthian will automatically load the driver if a compatible one exists. Where there are multiple drivers for a given device (or to use a generic driver such as Mackie Control, the active driver mode can be selected from within the Midi Input Devices menu from the Chain Manager screen or the individual chain options screen (also the admin menu). Bold press the driver entry for further options.

1.3 Driver Functions

This section contains documentation for some of these controller drivers. There are two core driver functions which control the primary screens in the Zynthian UI:

  • Launcher mode (Zynpad): Launch patterns in the launcher grid interface (as with DAWs like Ableton or Logic)
  • Mixer mode (ZynMixer): Control chain levels, mutes and solo. Different devices may have some additional controls and functions.

There are also additional driver modes/functions depending on the device and driver:

  • UI Navigation: Adds some degree of UI navigation control via arrow buttons or by emulating encoders & buttons on the device
  • SuperLooper Mode: Provides an interface to the native SuperLooper UI within Zynthian for looping live performance.
  • Sequencer Mode (ZynSeq): (Sequencer functionality for the device depends on the Zynthian version installed) Provides some degree of control over the sequencer or pattern editor.
  • Moder Mode: Adjusts device note inputs to stay in scale or provides some chord functionality


2 Driver Pages

3 Table of Device Features

Device Launcher mode (ZynPad) Mixer mode (ZynMixer) UI Navigation SuperLooper mode Sequencer mode (ZynSeq) Moder (chords/scales) Extra features / notes
Akai APC Key25 MK2
Akai apc key25 mk2.png
 yes yes no no yes no Mixpad (default) controls Mixer + ZynPad; also Step Sequencer / pattern editor; Device mode controls the Zynthian UI.
Akai APC Key25 MK2 + SL yes yes yes yes yes no Adds SooperLooper looper controls + Levels/Pan/Sync&Quantize/Session save+load; base modes otherwise match the non-SL driver.
Akai MIDI MIX
Akai-midi-mix.jpg
 no yes no no no no Maps mixer functionality (chains 1–16 via banks, master slider, balance, mute/solo, rec-arm).
Akai MPK mini MK3
Akai-mpk-mini-top.jpg
 yes yes no no yes no Modes: Mixer (default), Device UI, Pattern (ZynPad + Pattern Editor), NotePad; plus User and Config modes.
Akai MPK mini MK3 Moder no no no no no yes This is a very simple "Mode Enforcer" driver for the Akai MPK mini MK3.
Novation LAUNCHPAD MINI MK1
Novation launchpad mini mk1 zynpad.png
 yes no no no no no ZynPad driver.
Novation LAUNCHPAD MINI MK3
Novation launchpad mini mk3 zynpad.png
 yes no no no no no ZynPad driver.
Novation LAUNCHPAD PRO MK2
Novation launchpad pro mk2 zynpad.jpg
 yes yes yes no no no Three modes using the top row buttons:
  • Launcher - similar function to Ableton Live
  • Mixer - volume, pan and (needs testing) sends
  • Device Control - emulates the 20 button array of the V5 and encoder buttons
Novation LAUNCHPAD PRO MK3
Novation launchpad pro mk3 zynpad.jpg
 yes no no no no no ZynPad driver.
Novation LAUNCHPAD X
Akai-mpk-mini-top.jpg
 yes no no no no no ZynPad driver.
Novation LAUNCHKEY MINI MK3
Launchkey mini mk3.jpg
 yes yes no no no no Mixer + ZynPad.
Novation LAUNCHKEY 88 MK3
Launchkey 88 mk3.jpg
 yes yes no no no no Mixer + ZynPad.
Behringer MOTÖR 61 / 49
Behringer motor.jpg
 yes no no no no no This driver is focused in stage control of setBfree and Pianoteq engines. It also includes the mode enforcer that can be controlled from the pads (notes).
Korg nanoKONTROL
NanoKONTROL1.png
 no no no no no no Not currently available.
Korg nanoKONTROL-2
NanoKONTROL2.png
 no yes no no no no ZynMixer driver with UI navigation.
Mackie Control
Mackie control.jpg
 no yes no no no no This driver can be loaded for devices that support MCU protocol and variants.
Fostex Mixtab
Mixtab.png
 no yes no no no no This driver maps the hardware controls to relevant parameters in zynthian (mostly zynmixer).
Teenage Engineering OP-1
Te-op1.jpg
 no no no no no no Encoder control of parameters and UI navigation via encoders and buttons.
SooperLooper CCx10, for Behringer FCB1010 & others
Fcb1010.jpeg
 no no yes yes no no SooperLooper CCx10 controller support.
Worlde Mini Moder Driver
Worlde mini midi keyboard
 tbc tbc tbc no no yes
Akai MPK249
Akai mpk249
 tbc tbc tbc no no no
Launchkey Mini Mk4 37
Launchkey Mini Mk4
 tbc tbc tbc no no no
Launchkey Mini Mk3
Launchkey Mini Mk3
 yes yes tbc no no no
Launchkey Mk3 88
Launchkey88
 yes yes tbc no no no
Launchkey Mk4 37
Launchkey37-MKIV
 tbc tbc tbc no no no
Sinco smk25
Simco smk25
 tbc tbc tbc no no no
Arturia Keylab Mk2 61
Arturia keylab mk2 61
 yes tbc tbc no no no





4 Technical Info For Driver Developers

Drivers are python modules implementing a class. This class can call internal zynthian-ui API, so it has full access to Zynthian functionality. It’s not limited by CUIA. No limits, so you can break the UI too 😉

NOTE: the name of the class should be identical to that of the file name. This is a common pitfall when developing new drivers.

dev_ids is a list of identifiers that the driver will match. You can find this by looking at the name of the device in the MIDI Input view in Zynthian. If you bold press the corresponding input to see its options menu, the "Rename port" option shows its USB port / MIDI input name. Use the MIDI input name for your dev_ids list, e.g. Rename port 'USB:2.2/Launchkey Mini MK3 In 2' would provide the device id: "Launchkey Mini MK3 In 2".

You can check the full code here:

zynthian-ui/zyngui/zynthian_ctrldev_manager.py zynthian/zyngine · GitHub

and some example drivers here:

zynthian-ui/zyngine/ctrldev/ · GitHub

All drivers must inherit from zynthian_ctrldev_base, implementing the needed functionality as commented in the base code: 


#------------------------------------------------------------------------------------------------------------------
# Control device base class
#------------------------------------------------------------------------------------------------------------------

class zynthian_ctrldev_base():

	dev_id = None  		# String that identifies the device (class variable!)
	dev_zynpad = False		# Can act as a zynpad trigger device
	dev_zynmixer = False	# Can act as an audio mixer controller device
	dev_pated = False	# Can act as a pattern editor device


	# Function to initialise class
	def __init__(self):
		self.idev = 0		# Slot index where the device is connected, starting from 1 (0 = None)
		self.zyngui = zynthian_gui_config.zyngui


	# Setup the device connected in slot #idev
	# Before calling this, the caller (ctrldev-manager) should check that driver's ID string matches device's ID string
	def setup(self, idev=None):
		if idev != self.idev:
			# Release currently selected device, if any ...
			self.release()
			# Init new selected device
			if idev > 0:
				self.idev = idev
				logging.info("Setting-up {} in slot {}".format(self.dev_id, self.idev))
				# Setup routing
				lib_zyncore.zmip_set_route_extdev(self.idev - 1, 0)
				zynautoconnect.midi_autoconnect(True)
				# Initialize new selected device
				self.init()
				self.refresh(force=True)


	def release(self):
		if self.idev > 0:
			logging.info("Releasing {} in slot {}".format(self.dev_id, self.idev))
			# If device is still connected, call end
			dev_id = zynautoconnect.get_midi_device_name(self.idev)
			if dev_id and dev_id == self.dev_id:
				self.end()
			# Restore routing
			lib_zyncore.zmip_set_route_extdev(self.idev - 1, 1)
			zynautoconnect.midi_autoconnect(True)
		self.idev = 0


	# Refresh device status (LED feedback, etc)
	# It *SHOULD* be implemented by child class
	def refresh(self, force=False):
		logging.debug("Refresh LEDs for {}: NOT IMPLEMENTED!".format(self.dev_id))


	# Device MIDI event handler
	# It *SHOULD* be implemented by child class
	def midi_event(self, ev):
		logging.debug("MIDI EVENT FROM '{}'".format(self.dev_id))


	# Light-Off LEDs
	# It *SHOULD* be implemented by child class
	def light_off(self):
		logging.debug("Lighting Off LEDs for {}: NOT IMPLEMENTED!".format(self.dev_id))


	# Sleep On
	# It *COULD* be improved by child class
	def sleep_on(self):
		self.light_off()


	# Sleep On
	# It *COULD* be improved by child class
	def sleep_off(self):
		self.refresh(True)

Quite simple, right? This is for basic “generic” drivers. Zynpad enabled drivers inherit from this base class: 


# ------------------------------------------------------------------------------------------------------------------
# Zynpad control device base class
# ------------------------------------------------------------------------------------------------------------------

class zynthian_ctrldev_zynpad(zynthian_ctrldev_base):

	dev_zynpad = True		# Can act as a zynpad trigger device


	def __init__(self):
		super().__init__()
		self.zynpad = self.zyngui.screens["zynpad"]


	def refresh(self, force=False):
		# When zynpad is shown, this is done by refresh_status, so no need to refresh twice
		if force or not self.zynpad.shown:
			self.refresh_pads(force)
			self.refresh_zynpad_bank()
		if force:
			self.refresh_zynpad_bank()


	# It *SHOULD* be implemented by child class
	def refresh_zynpad_bank(self):
		pass


	def refresh_pads(self, force=False):
		if force:
			self.light_off()
		for pad in range(self.zyngui.zynseq.col_in_bank ** 2):
			# It MUST be called for cleaning the dirty bit
			changed_state = self.zyngui.zynseq.libseq.hasSequenceChanged(self.zynpad.bank, pad)
			if changed_state or force:
				mode = self.zyngui.zynseq.libseq.getPlayMode(self.zynpad.bank, pad)
				state = self.zynpad.get_pad_state(pad)
				self.update_pad(pad, state, mode)


	def refresh_pad(self, pad, force=False):
		# It MUST be called for cleaning the dirty bit!!
		changed_state = self.zyngui.zynseq.libseq.hasSequenceChanged(self.zynpad.bank, pad)
		if changed_state or force:
			mode = self.zyngui.zynseq.libseq.getPlayMode(self.zynpad.bank, pad)
			state = self.zynpad.get_pad_state(pad)
			self.update_pad(pad, state, mode)


	# It *SHOULD* be implemented by child class
	def update_pad(self, pad, state, mode):
		pass
#------------------------------------------------------------------------------


If you kind-of-understand this, you shouldn’t have problem to understand the driver examples and program your own drivers. Simply copy your driver file in the the zyngui/ctrldev folder and restart zynthian-ui. Refer to this thread for more information NEW: Control-device manager + controller device “drivers”


5 Driver Discussion on the Forum

Refer to some threads discussing driver development on different devices:

Retrieved from "http://wiki.zynthian.org/index.php?title=Supported_plug_%26_play_MIDI_controllers&oldid=16152"