Practical Tutorial - Build a Channel Switcher

nic
Soapbox Supremo

Troublemaker

Press any key to continue

Posts: 2,011

Practical Tutorial - Build a Channel Switcher May 8, 2019 6:31:14 GMT topaz likes this

Post by nic on May 8, 2019 6:31:14 GMT

In this tutorial, I will take you through creating a simple MIDI FX unit step by step. We will create a channel switcher where the user can choose a MIDI channel and all MIDI events will be remapped to the channel as they pass through. In addition we will add a toggle button to disable the remapping (ie. a bypass)

Here is what the UI will look like:

First, we will configure the look and feel of the controls box to match the above. We will use the first control (array variable Q0) to select the channel using a slider ranging from 1 to 16, and the second (Q1) is a toggle button to engage/disengage the channel remapping. However, let's also alias those two array variables in our code to make that more obvious while we are at it. I recommend you place aliases and UI setup inside an 'if load' block at the top of your script. - this is more efficient when processing MIDI events.

# simple channel switcher
if load
# give controls q0 and q1 meaningful names
alias q0 ChannelSlider
alias q1 EngageButton

# configure our two controls
set ChannelSlider Channel $1 $16 +slider
set EngageButton Engage +toggle

# set the default values for the two
# controls and preserve them
assign ChannelSlider = 1 +preserve
assign EngageButton = 1 +preserve
end

The last two lines above configure the controls with default MIDI channel of 1 and the switcher engaged when the script is loaded. However, I have added the '+preserve' flag which means that if the user changes the slider or button and then saves that into a preset, then the next time that loads, the channel/button will not be restored to the defaults we put in our script, but to the values that were in place when it was saved.

Now, the above script will run but doesn't actually do any remapping. We now need to add the MIDI processing logic - we want to remap all channelised MIDI events to the selected channel but only if the Engage button is on. Outside of the 'if load' is where we add this:

# event processing logic
if MT != F0
if EngageButton == 1
math M0 = MT + ChannelSlider
math M0 = M0 - 1
end
end

The first if statement makes sure that the message type (MT) is a channelised event (ie. not a sysex/realtime event). The second if statement makes sure the Engage button is on.

There are two steps to rewriting the channel. The first math statement takes the current message type and adds the current value of the slider and puts that into the first byte of the current MIDI message (M0). In MIDI messages, the channels are numbered from 0 to F (0 to 15) but our channel slider range is 1 to 16; we therefore need to subtract 1 from the first byte to align correctly.

And there you have it, a working channel switcher. Here is the complete code:

# simple channel switcher
if load
  # give controls q0 and q1 meaningful names
  alias q0 ChannelSlider
  alias q1 EngageButton

  # configure our two controls
  set ChannelSlider Channel $1 $16 +slider
  set EngageButton Engage +toggle

  # set the default values for the two
  # controls and preserve them
  assign ChannelSlider = 1 +preserve
  assign EngageButton = 1 +preserve
end

# event processing logic
if MT != F0
  if EngageButton == 1
    math M0 = MT + ChannelSlider
    math M0 = M0 - 1
  end
end

Last Edit: May 20, 2019 19:09:46 GMT by nic

nic
Soapbox Supremo

Troublemaker

Press any key to continue

Posts: 2,011

Practical Tutorial - Build a Channel Switcher May 8, 2019 7:47:41 GMT

Post by nic on May 8, 2019 7:47:41 GMT

The code works, but we can refine it with some niceties for the user and also use includes to make our code look even neater.

First, we can give our script a short name that will be shown over the controls box and in the host (if it supports it) and we can automatically have the controls box open up when the script is loaded:

set name Switch
set slider_display 1

These two statements should be added into the if load block of our script.

Next, to make it more obvious when the switcher is engaged, we can change the text on the button to reflect the current state when the user toggles the Engage button. When the user changes a control, an internal sysex message is sent into the script which we can watch out for and then do something when it happens. This sysex message looks like F0 7D 01 00, but we can use the standard includes which have defines for this message instead to make it more readable. To use the standard includes, add this line to the top of the if load:

set include factory standard_includes

This is the logic for changing the button text when the user touches the engage button:

# handle engage button press
if control_q1_moved
if EngageButton == 1
set EngageButton Engaged +t
else
set EngageButton Engage +t
end
end

So, when the user touches the button, the text on the button changes to 'Engage' (when off) and 'Engaged' when on.

There is one tiny complication though! When the script loads we want the button text to reflect the current state of the button, so we want to manually trigger the above logic at that time. We do this by injecting a control changed sysex message as follows:

send control_sysex 01 sysex_end +inject

The '01' above maps to our EngageButton (Q1)

The standard includes also define meaningful names for message types and the like and also 'increment/decrement' subroutines which we can also re-use and modify our script with. Making use of these and incorporating the above, our script now looks like:

# quite-simple channel switcher
if load
  # load in factory includes
  set include factory standard_includes
  
  # give controls q0 and q1 meaningful names
  alias q0 ChannelSlider
  alias q1 EngageButton

  # configure our two controls
  set ChannelSlider Channel $1 $16 +slider
  set EngageButton Engage +toggle

  # set the default values for the two
  # controls and preserve them
  assign ChannelSlider = 1 +preserve
  assign EngageButton = 1 +preserve

  # give script a name and expose controls box
  set name Switch
  set slider_display 1

  # inject control_q1_moved manually
  send control_sysex 01 sysex_end +inject
end

# event processing logic
if midi_msg_type != sysex_msg
  if EngageButton == 1
    math midi_msg_data = midi_msg_type + ChannelSlider
    decrement midi_msg_data
  end
end

# handle engage button press
if control_q1_moved
  if EngageButton == 1
    set EngageButton Engaged +t
  else
    set EngageButton Engage +t
  end
end

Last Edit: May 10, 2019 11:23:04 GMT by nic

nic
Soapbox Supremo

Troublemaker

Press any key to continue

Posts: 2,011

Practical Tutorial - Build a Channel Switcher May 8, 2019 8:41:43 GMT

Post by nic on May 8, 2019 8:41:43 GMT

The final part of this tutorial demonstrates using subroutines. It doesn't add any new functionality and actually lengthens our script, but we do this in the name of education...

We will create two subroutines; one for handling the MIDI processing logic and another for handling the button text logic:

# subroutines
if load

# remap a midi event
subroutine remap msg_byte_0 channel
if EngageButton == 1
# calc msg_type into temp I0
math I0 = msg_byte_0 & F0

if I0 != sysex_msg
# remap channel
math I0 = I0 + ChannelSlider
decrement I0
assign msg_byte_0 = I0
end
end
end

# handle engage button press
subroutine set_button_text
if EngageButton == 1
set EngageButton Engaged +t
else
set EngageButton Engage +t
end
end

end

These subroutines go into a (separate, just to show you can have multiple) if load blocks. The remap subroutine takes two arguments, the first byte of a midi message and the channel number (1 to 16). The second subroutine takes no arguments.

Then we replace the old logic code with the subroutine calls instead:

# remap (optionally) MIDI events
remap midi_msg_data ChannelSlider

# handle Engage button press
if control_q1_moved
set_button_text
end

So, our final script looks like:

# not-so-simple channel switcher
if load
  # load in factory includes
  set include factory standard_includes
  
  # give controls q0 and q1 meaningful names
  alias q0 ChannelSlider
  alias q1 EngageButton

  # configure our two controls
  set ChannelSlider Channel $1 $16 +slider
  set EngageButton Engage +toggle

  # set the default values for the two
  # controls and preserve them
  assign ChannelSlider = 1 +preserve
  assign EngageButton = 1 +preserve

  # give script a name and expose controls box
  set name Switch
  set slider_display 1

  # inject control_q1_moved manually
  send control_sysex 01 sysex_end +inject
end

# subroutines
if load

  # remap a midi event
  subroutine remap msg_byte_0 channel
    if EngageButton == 1
      # calc msg_type into temp I0
      math I0 = msg_byte_0 & F0
 
      if I0 != sysex_msg
        # remap channel
        math I0 = I0 + ChannelSlider
        decrement I0
        assign msg_byte_0 = I0
      end
    end
  end

  # handle engage button press
  subroutine set_button_text
    if EngageButton == 1
      set EngageButton Engaged +t
    else
      set EngageButton Engage +t
    end
  end

end

# remap (optionally) MIDI events
remap midi_msg_data ChannelSlider

# handle Engage button press
if control_q1_moved
  set_button_text
end

Last Edit: May 10, 2019 11:24:58 GMT by nic