Changes

17,484 bytes added , 17 January

m

Line 2: Line 2:

This section contain documentation for some of this controller drivers.

−

~~{{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.}}~~

Line 41: Line 39:

* 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).

−

* 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.

+

* Use the 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. Each knob will affect a chain, independently of the selected chain. (K1 -> chain 1, K2 -> chain 2, ...)

* 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).

Line 53: Line 51:

* '''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.

−

* Open the '''StepSeq mode''' for a given sequence, pressing <code>SHIFT</code> + a pad button.

+

* Open the '''StepSeq mode''' for a given sequence, pressing <code>SHIFT</code> + a pad button (more info about this mode in the following section).

−

* '''Clear a sequence''', pressing any track button + the sequence pad.

+

* '''Clear a sequence''', pressing any track button + the sequence pad (use SELECT function, and the selected chain's button to avoid changing other settings).

−

* 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.

+

* 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> or <code>SHIFT</code> + <code>RECORD</code> buttons.

* 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.

Line 91: Line 89:

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:

+

* Press and hold <code>SHIFT</code> to '''show the status''':

+

** Buttons <code>UP</code>, <code>DOWN</code>, <code>LEFT</code> and <code>RIGHT</code> will lit indicating the current Notepad page selected (1, 2, 3 or 4, respectively).

+

** Button <code>SEND</code> will lit indicating this mode is selected.

* '''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.

Line 107: Line 109:

* '''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.

+

+

'''NOTE''': Remember to set the ''clock source'' of Zynthian to '''Internal Send'''. Otherwise, the playhead will not be shown!

+

* '''Panic stop''' all sounds, pressing <code>SHIFT</code> + <code>STOP ALL CLIPS</code>. Any sound will stop immediately.

Line 181: Line 187:

==Akai MPK mini MK3==

+

[[File:akai_mpk_mini_mk3_driver_functions.png|800px|right]]

The driver for this device has 4 main operation modes:

Line 187: Line 195:

* 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.

+

* The '''NotePad''' mode, which is used to assign the notes that the PADs will play in ''note'' mode.

There are two more minor modes, which are:

Line 193: Line 201:

* 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.

+

Each mode is shown in the MPK display when active. <code>PADs 1-4 A</code> are used as direct access to some of Zynthian GUI screens:

+

* <code>PAD 1 A</code>: toggles between Zynthian's '''mixer''' and audio levels.

+

* <code>PAD 2 A</code>: cycles between '''Zynpad''', the arranger and pattern editor.

+

* <code>PAD 3 A</code>: opens the '''tempo''' and metronome screen.

+

* <code>PAD 4 A</code>: toggles between '''snapshot''' and ZS3 screens.

+

Each one of these functions or modes is available on every operation mode or screen. Just ensure that '''PC''' (PROG CHANGE) is active on the MPK.

+

====The Mixer mode====

−

This is the default mode, but you can switch back to it with '''PROG CHANGE''':<code>PAD 5</code>. In this mode, you can use the Knobs to adjust chains settings. The general rule is: <code>PAD x</code> + <code>Knob y</code> to adjust the setting '''x''' of chain '''y'''. You can adjust chains 1 to 8 in bank A, and chains 9 to 16 in bank B. The functions that you can change are:

+

[[File:akai_mpk_mini_mk3_mixer_mode.png|800px|right]]

+

This is the default mode, but you can switch back to it with '''PROG CHANGE''':<code>PAD 5 A</code>. You should see <code>Zynthian MIXER</code> in the display of the MPK. In this mode, you can use the Knobs to adjust chains settings. The general rule is: <code>PAD x</code> + <code>Knob y</code> to adjust the setting '''x''' of chain '''y'''. You can adjust chains 1 to 8 in bank A, and chains 9 to 16 in bank B. The functions that you can change are:

−

+

−

+

'''NOTE''': Remember to put PAD CONTROLS in '''CC mode'''. The pads in ''note'' mode will only trigger the assigned notes.

−

'''NOTE''': Remember to put PAD CONTROLS in '''CC mode'''.

−

~~~~

Line 211: Line 229:

The driver will remember the last function pressed, so for adjusting chains 1-8, you can just press the desired PAD (1-4), release it, and then adjust using the knobs. All knobs will affect that PAD's function. For chains 9-16, you need the keep the PAD pressed.

−

If you activate the '''FULL LEVEL''' option in the MPK, then ~~the PADs~~ function changes to '''select''' chain. PADs in bank A will select first 8 chains, and bank B is used to select chains 9-16.

+

In this mode, there is also support for '''transport controls''':

+

* <code>PAD 5 A/B</code> for '''stop all sounds''' (PANIC button).

+

* <code>PAD 6 A</code> for toggle '''audio record'''. <code>PAD 6 B</code> will toggle '''MIDI record'''.

+

* <code>PAD 7 A</code> will trigger '''audio stop''', while <code>PAD 7 B</code> will trigger '''MIDI stop'''.

+

* <code>PAD 8 A</code> is for togging '''audio playback''', and <code>PAD 8 B</code> will toggle '''MIDI playback'''.

+

If you activate the '''FULL LEVEL''' option in the MPK, then PAD's function changes to '''select''' chain. PADs in bank A will select first 8 chains, and bank B is used to select chains 9-16.

+

The joystick in this mode affects the pitch-bend (in the Y axis), and sends <code>CC</code> messages, <code>CC#32</code> for '''-X''' (left) and <code>CC#33</code> for '''+X''' (right) values, available for MIDI learning.

+

+

====The Device mode====

+

[[File:akai_mpk_mini_mk3_device_mode.png|800px|right]]

+

This mode is used to control Zynthian's GUI. You can activate it by pressing '''PROG CHANGE''':<code>PAD 6 A</code> anytime. The MPK display will show the label <code>Zynthian DEVICE</code>. In this mode, you have the following options:

+

+

'''NOTE''': Remember to put PAD CONTROLS in '''CC mode'''. The pads in ''note'' mode will only trigger the assigned notes.

+

+

* In '''bank A''':

+

** Use <code>PADs 1-3</code> and <code>PAD 6</code> to '''move''' around the user interface (up, down, left and right, as shown in the diagram). You can also use the joystick for this.

+

** '''Cancel''' or '''go back''' with <code>PAD 5</code>.

+

** '''Accept''' or '''select''' an item, using <code>PAD 7</code>.

+

** Launch the '''options''' menu, or the '''admin''' menu, by a short press in <code>PAD 8</code>. Each press will toggle between these two screens. With a ''long press'', it will '''shutdown''' the system (a confirm dialog will appear).

+

** Open the '''controls''' or '''preset''' screen of a chain, doing a short press in <code>PAD 4</code>. In Zynpad, a ''long press'' of <code>PAD 4/7</code> will open the '''pattern editor''' for the selected sequence.

+

* In '''bank B''':

+

** Upper row of PADs is used for '''transport buttons''', just like in the mixer mode:

+

*** <code>PAD 5</code>: stop all sounds ('''panic''' button).

+

*** <code>PAD 6</code>: toggle audio '''record'''.

+

*** <code>PAD 7</code>: '''stop''' audio.

+

*** <code>PAD 8</code>: toggle audio '''playback'''.

+

** Lower row is used as V5 Knob '''press buttons'''. The mapping is from <code>PAD 1</code> to <code>PAD 4</code>, which are used as '''Knob#1''' to '''Knob#4''' press buttons. These buttons are available in CC and PC mode. This is mainly needed for MIDI learning features, where a CC message would establish the control's MIDI learn. CC is needed when a bold/long press is required.

+

This mode also maps the V5 Knobs to <code>K1</code>, <code>K5</code>, <code>K2</code>, <code>K6</code>, in that order.

+

Knob <code>K3</code> is used to adjust '''the tempo'''. When rotated, the Zynthian tempo screen will be shown briefly. This tempo setting is synchronized with the MPK.

+

+

'''NOTE''': The MPK resolution is 1BPM, but Zynthian is 0.1BPM; take this into account to avoid drifting.

+

+

+

====The Pattern mode====

+

[[File:akai_mpk_mini_mk3_pattern_mode.png|800px|right]]

+

This mode works only in Zynthian's Zynpad, Arranger or Pattern Editor. To activate it, press '''PROG CHANGE''':<code>PAD 7 A</code>. You should see <code>Zynthian PATTERN</code> in the display of your MPK. Note that all the following PADs are assumed to be in '''bank A'''.

+

+

'''NOTE''': Remember to put PAD CONTROLS in '''CC mode'''. The pads in ''note'' mode will only trigger the assigned notes.

+

+

In any screen (Zynpad, Arranger or Pattern Editor), you can:

+

* '''Move the cursor''' using the joystick, or <code>K2</code> for vertical and <code>K6</code> for horizontal displacement.

+

* Press and hold <code>PAD 3</code> as '''SHIFT''', when required.

+

In '''Pattern Editor''', you will have the following functionality:

+

* '''Transport controls''' using the upper row PADs, following the same arrangement as in Mixer mode (<code>PAD 5</code>: stop all sounds, <code>PAD 6</code>: toggle record, <code>PAD 7</code>: stop, <code>PAD 8</code>: toggle playback).

+

* '''Move along patterns''' of the same track in current sequence. Press <code>PAD 1</code> for previous pattern, and <code>PAD 2</code> for next. If there are no more patterns in current track, you can '''create a new one''' pressing <code>SHIFT</code> + <code>NEXT</code> (i.e: <code>PAD 3</code> + <code>PAD 2</code>) while visiting the last pattern.

+

* '''Toggle step''' in cursor's position, pressing <code>PAD 4</code>.

+

* '''Adjust''' the selected step, using the following Knobs:

+

** Step's '''duration''': <code>K7</code>. It will change in increments of 0.1 steps, or, by pressing <code>SHIFT</code>, in 0.5 steps.

+

** Step's '''velocity''': <code>K8</code>.

+

** Step's '''stutter count''': <code>K3</code>. Ranges from 0 to 32.

+

** Step's '''stutter duration''': <code>K4</code>. Ranges from 1 to 96, and is measured in clock cycles.

+

In '''Zynpad''', you may:

+

** Toggle '''playing''' the selected sequence, by pressing <code>PAD 4</code>.

+

** If the MPK is in '''FULL LEVEL''', each PAD can launch/stop a sequence. PADs in bank A, for sequences between 1 and 8, and bank B for sequences 9-16.

+

+

====The NotePad mode====

+

[[File:akai_mpk_mini_mk3_notepad_mode.png|800px|right]]

+

The purpose of this mode is to modify the notes that the PADs will send in ''note'' mode (i.e. neither CC or PROG CHANGE active). You can switch to this mode by pressing '''PROG CHANGE''':<code>PAD 8 A</code>. You should see <code>Zynthian NOTEPAD</code> in the display of the MPK.

+

+

'''NOTE''': Unlike the other modes, this mode only works if PAD CONTROLS are in '''note mode'''.

+

+

To '''assign a note''' to a PAD, press that PAD and, without releasing it, press any key of the KeyBed. Press the pad again to check the note (it may be sent to a different chain, depending on PAD/KeyBed channels and Zynthian settings). In this mode, both banks A and B are available for note binding.

+

You can '''remove a note''' from a PAD pressing that PAD and, without releasing it, turning <code>K8</code> counter clock-wise. The removal will be done when you release the PAD, so, if you didn't want to remove it (and didn't release the PAD), just turn the Knob clock-wise again.

+

Using the Knob <code>K7</code> on a PAD will adjust its pitch (note) by a semitone, up and down the scale.

+

+

====The User mode====

+

This is a special mode, with no other purpose that letting you all the available controls for '''MIDI learning'''. Only PC 0-7 and 12,13 are NOT available (as they are used for changing modes and Zynthian's shortcuts). You can switch to this mode by pressing '''PROG CHANGE''':<code>PAD 5 B</code>. You should see <code>Zynthian USER</code> in the display of the MPK.

+

This is the available configuration:

+

* PADs channel is the assigned in Config mode (see below).

+

* PAD notes are the assigned in NotePad.

+

* PAD CCs are in range [40-47] for bank A, and [48-55] for bank B.

+

* PC PADs 1, 2, 3, 4, 7 and 8 (all in bank B) are available.

+

* All Knobs are available, and their CCs goes from 56 to 63.

+

* Joystick Y channel is mapped as pitchbend.

+

* Joystick X channel is set as dual mode, with CCs 64 (left side) and 65 (right side).

+

+

====The Config mode====

+

[[File:akai_mpk_mini_mk3_config_mode.png|800px|right]]

+

This is also a special mode, used to '''configure the MPK device''' internal settings, like the channel where the PADs will send their notes, or the '''arpeggiator''' settings.

+

'''Rationale:''' while you can use the MPK arpeggiator or NOTE REPEAT buttons to change some of these settings, they will be overwritten on next mode change (as they are inside the MPK and could not be retrieved). Moreover, there are settings that could only be changed using the MPK Program Editor, so this mode will help you in that case. Zynthian will store the changes you made here per snapshot basis, so that's another reason for using this mode.

+

+

'''NOTE''': Remember to put PAD CONTROLS in '''CC mode'''. The pads in ''note'' mode will only trigger the assigned notes. ALSO, ensure that KeyBed octave is '''in the middle''' (neither <code>OCT+</code> nor <code>OCT-</code> is brightly lit).

+

+

In this mode, all notes of the KeyBed are used as shortcuts for the '''arpeggiator settings'''. See the MPK KeyBed labels to check the purpose of each one. Also note that:

+

* <code>PAD 3 A</code> in CC mode is used as '''SHIFT'''.

+

* <code>PAD 4 A</code> in CC mode toggles '''on/off''' the arpeggiator.

+

For other settings, you can use the Knobs. Move a Knob to see in the MPK display its function (but it won't change anything), and <code>SHIFT</code> + move Knob to actually change that property (changes are applied on <code>SHIFT</code> release). This is the settings mapping:

+

* <code>K1</code>: changes '''tempo taps''', the number of times you need to press the button <code>TAP TEMPO</code> to change it. Ranges from 2 to 4.

+

* <code>K2</code>: to modify the '''arpeggiator swing''', giving you a finer adjustment than using the KeyBed shortcuts.

+

* <code>K3</code>: to change the '''PADs aftertouch''' settings. Values are 0: Off, 1: Channel Aftertouch, 2: Polyphonic Aftetouch.

+

* <code>K4</code>: for changing the KeyBed octave. A value of 4 is the default middle octave, less than 4 is for lowering the octave, and bigger that 4 increases the octave. '''NOTE:''' If you want to change this value, please note that it will affect the KeyBed immediately, so any shortcut that you use later on would be displaced. Just adjust this as the last value, or reset octave before using the shortcuts.

+

* <code>K6</code>: for setting the '''arpeggiator clock''' source as EXT (external). Set it to 1 for using an external clock, or 0 to use the internal clock.

+

* <code>K7</code>: lets you change the '''channel of the PADs'''.

+

* <code>K8</code>: to modify the '''channel of the KeyBed'''.

+

Line 341: Line 500:

+

==Technical Info For Driver Developers==

+

Drivers are python module 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 :wink:

+

You can check the full code here:

+

[https://github.com/zynthian/zynthian-ui/blob/oram/zyngine/zynthian_ctrldev_manager.py zynthian-ui/zyngui/zynthian_ctrldev_manager.py zynthian/zyngine · GitHub]

+

and some example drivers here:

+

[https://github.com/zynthian/zynthian-ui/tree/oram/zyngine/ctrldev zynthian-ui/zyngine/ctrldev/ · GitHub]

+

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

+

<pre>

+

#------------------------------------------------------------------------------------------------------------------

+

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

+

</pre>

+

Quite simple, right? This is for basic “generic” drivers.

+

Zynpad enabled drivers inherit from this base class:

+

<pre>

+

# ------------------------------------------------------------------------------------------------------------------

+

# 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

+

#------------------------------------------------------------------------------

+

</pre>

+

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”]

Lfo

228

edits

Changes

Supported plug & play MIDI controllers (view source)

Revision as of 09:07, 17 January 2025