Changes

Jump to navigation Jump to search

Supported plug & play MIDI controllers (view source)

Revision as of 09:07, 17 January 2025

6,449 bytes added ,  17 January
m
→‎Technical Info For Driver Developers
Line 2: Line 2:     
This section contain documentation for some of this controller drivers.
 
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.}}
      
<br clear=all>
 
<br clear=all>
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).
 
* 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).
 
* 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.  
 
* '''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.
 
* 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:
 
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.
 
* '''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.
 
* '''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.
 +
 +
<p style="margin: 1em 0 1.5em; padding: 1em; background-color: #fef6e7; display:table-cell">
 +
'''NOTE''': Remember to set the ''clock source'' of Zynthian to '''Internal Send'''. Otherwise, the playhead will not be shown!
 +
</p>
    
* '''Panic stop''' all sounds, pressing <code>SHIFT</code> + <code>STOP ALL CLIPS</code>. Any sound will stop immediately.  
 
* '''Panic stop''' all sounds, pressing <code>SHIFT</code> + <code>STOP ALL CLIPS</code>. Any sound will stop immediately.  
Line 240: Line 246:  
[[File:akai_mpk_mini_mk3_device_mode.png|800px|right]]
 
[[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 5 A</code> anytime. The MPK display will show the label <code>Zynthian DEVICE</code>. In this mode, you have the following options:
+
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:
    
<p style="margin: 1em 0 1.5em; padding: 1em; background-color: #fef6e7; display:table-cell">
 
<p style="margin: 1em 0 1.5em; padding: 1em; background-color: #fef6e7; display:table-cell">
Line 308: Line 314:  
[[File:akai_mpk_mini_mk3_notepad_mode.png|800px|right]]
 
[[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>.
+
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.
    
<p style="margin: 1em 0 1.5em; padding: 1em; background-color: #fef6e7; display:table-cell">
 
<p style="margin: 1em 0 1.5em; padding: 1em; background-color: #fef6e7; display:table-cell">
Line 314: Line 320:  
</p>
 
</p>
   −
To '''assign a note''' to a PAD, press that PAD and, without releasing it, press any key on 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.  
+
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.
 
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.
+
Using the Knob <code>K7</code> on a PAD will adjust its pitch (note) by a semitone, up and down the scale.
    
<br clear=all>
 
<br clear=all>
Line 324: Line 330:  
====The User mode====
 
====The User mode====
   −
This mode 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).  
+
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.
   −
These is the available configuration:
+
This is the available configuration:
    
* PADs channel is the assigned in Config mode (see below).
 
* PADs channel is the assigned in Config mode (see below).
 
* PAD notes are the assigned in NotePad.
 
* PAD notes are the assigned in NotePad.
 
* PAD CCs are in range [40-47] for bank A, and [48-55] for bank B.
 
* PAD CCs are in range [40-47] for bank A, and [48-55] for bank B.
−
* PAD PCs 8,9,10,11 and 14,15 (all in bank B) are available.
+
* 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.
 
* All Knobs are available, and their CCs goes from 56 to 63.
 
* Joystick Y channel is mapped as pitchbend.
 
* Joystick Y channel is mapped as pitchbend.
Line 342: Line 348:  
[[File:akai_mpk_mini_mk3_config_mode.png|800px|right]]
 
[[File:akai_mpk_mini_mk3_config_mode.png|800px|right]]
   −
This mode is a special mode for '''configuring the MPK device''' internal settings, like the channel where the PADs will send their notes, or the '''arpeggiator''' settings.  
+
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 a 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.  
+
'''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.  
    
<p style="margin: 1em 0 1.5em; padding: 1em; background-color: #fef6e7; display:table-cell">
 
<p style="margin: 1em 0 1.5em; padding: 1em; background-color: #fef6e7; display:table-cell">
Line 494: Line 500:     
<br clear=all>
 
<br clear=all>
 +
 +
 +
==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

Retrieved from "http://wiki.zynthian.org/index.php/Special:MobileDiff/13535...14987"

Navigation menu