sample-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
  JMMidiBassPedalController v3.0
  File: src/conf/sample-config.xml
  By:   Josef Meile <jmeile@hotmail.com> @ 28.10.2020
  This project is licensed under the MIT License. Please see the LICENSE.md file
  on the main folder of this code. An online version can be found here:
  https://github.com/jmeile/JMMidiBassPedalController/blob/master/LICENSE.md

  With this file you will be able to setup every parameter for this Controller.
  Please note that this application will only catch NOTE ON and NOTE OFF
  messages, then it will look in the current selected Bank if there is a Pedal
  definition for that note, then it will proceed to excecute the specified
  commands.

  In order to setup your system, you need to follow this steps:
  * First you always have to include this four lines:
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://www.technosoft.solutions/xsd 
    MidiBassPedalController.xsd"
    xmlns="https://www.technosoft.solutions/xsd"
   
  * Then you can start by defining the MIDI in and out ports you are going to
    use. You can either use: 
    - the port number (starting from 1):
      InPort="1" OutPort="3"
    - or the port name: 
      InPort="loopMIDI Port" OutPort="*loopMIDI*"
    - you can also make the software to create the virtual ports:
      InPort="Virtual:Midi In" OutPort="Virtual:Midi Out"
      where:
      - The Keyword: "Virtual:" indicates it is a virtual port
      - The part after the ":" is the name you want to use. On this case, I set
        it to "Midi In" and "Midi Out".
      Please note that virtual ports aren't supported by Windows. In order to
      guarantee that the configuration files are compatible in several operating
      systems, you will have to create the port with loopMIDI before running the
      software; for this, use the name after: "Virtual:".
      
      On the first definition: "InPort", the full port name: "loopMIDI Port"
      will be used. On the second definition: "OutPort" only part of the name:
      "*loopMIDI*" is given; here you can use wildcards '*' to match part of
      the name or the question mark '?' to match only one character.
    Remarks:
    - This two ports are optional. If you don't give them, then the last 
      available MIDI port will be used.
    - You can see the port numbers and names by running the python script with
      the "list" command line switch (See the README.md file for more details).
  * Next you need to set the MIDI channels, which can be values starting from 1
    to  16:
    - First the MIDI in channel to which this controller will listen to:
      InChannel="1"
    - And finally the MIDI out ports for the bass pedal and chord notes:
      OutBassPedalChannel="3,5" OutChordChannel="4,1,3"
      
      Here you should use a comma separated with values between 1 and 16, the
      order doesn't really matters, but you can't repeat any number. On this
      specific example, I'm giving the following:
      > OutBassPedalChannel="3,5" -> This means that two set of pedal notes will
        be sent: one on channel 3 and other on channel 5. Please note that they
        will be transposed and changed according to the values of:
        BassPedalVelocity and BassPedalTranspose. This is really useful if you
        want to play those pedal notes with different voices, so, you should
        also setup your keyboard accordingly. If you don't need more than one
        note, then you can just set one channel.
        
      > OutChordChannel="4,1,3" -> This means that three set of chord notes will
        be sent: one on channel 4, on on channel 1, and other on channel 3.
        Please note that they will be transposed and changed according to the
        values of: ChordVelocity and ChordTranspose. This is really useful if
        you want to play those chord notes with different voices, so, you should
        also setup your keyboard accordingly. If you don't need more than one
        chord, then you can just send one chanel.
        
    Please note that these channels are optional; if not given, then channel '1'
    will be assumed.
  * Then setup the controller to either echo or not other MIDI messages comming
    to it:
    MidiEcho="true"
    If not given, then it defaults to "true".
  * Next setup the bass pedal and chord notes velocities (volumes):
    BassPedalVelocity="70,36" ChordVelocity="fff,p,mf"
    
    Here you can either set a comma separated list containing either:
    * a number between 0 and 127
    * a relative velocity beginning with + or - and a number between 0 and 127.
      Here the original velocity comming from the pedal controller will be added
      or substracted according to this value. If the resultant velocity is
      greather than 127 or less or equal than 0, then 127 or 1 will be
      respectively assumed.
    * or one of the following symbols:
      s:    silence,                        numeric value: 0
      pppp: minimum value,                  numeric value: 10
      ppp:  pianississimo, very very soft,  numeric value: 23
      pp:   pianissimo,    very soft,       numeric value: 36
      p:    piano,         soft,            numeric value: 49
      mp:   mezzo-piano,   moderately soft, numeric value: 62
      mf:   mezzo-forte,   moderately loud, numeric value: 75
      f:    forte,         loud,            numeric value: 88
      ff:   fortissimo,    very loud,       numeric value: 101
      fff:  fortississimo, very very loud,  numeric value: 114
      ffff: maximum value,                  numeric value: 127
    
      Avoid using the minimum value (zero or 's'). This is normally
      interpreted as a NOTE OFF message. If you really need to send it, then
      you could either set it to 1 or use another MIDI channel.

    Remarks:
    - If "BassPedalVelocity" is not given, then the note velocity comming from
      your foot controller will be assumed.
    - If "ChordVelocity" is not given, then "BassPedalVelocity" will be assumed.
    - The length of this lists must be less or equal than the length of
      OutBassPedalChannel and OutChordChannel; otherwise an error will be
      raised. On this example, we previously set OutBassPedalChannel to: "3,5",
      so the length of BassPedalVelocity must be at most 2. The same applies for
      ChordVelocity. 
    * If the length of this lists are less than the length of
      OutBassPedalChannel or OutChordChannel, then the velocities of the
      remaining elements will be set according to the last value of the list.
  * Then setup the note transposition for the bass pedal and chord notes:
    BassPedalTranspose="-2,23" ChordTranspose="2,-25,127"
    The "Transpose" values are between -127 and 127. So, if you set 2, then the
    note will be transposed by two higher semitones, similarly, if you set -2,
    then the note will be trasposed by two lower semitones.
           
    If the resulting note is lower than 0 (C-2), then it will be transposed to a
    note on the octave -2. If on the contrary, it is higher than 127 (G8), then
    the following cases will be considered:
    * If the note is between C and G, then it will be transposed to a note on
      the octave 8.
    * Otherwise, the note is between G# and B, then it will be transposed to a
      note on the octave 7.
    
    Default values:
    - If "BassPedalTranspose" is not given, then it defaults to 0 (zero), which
      means that no transposition will be done.
    - On the contrary, if "ChordTranspose" is not given, then the same
      transposition of the pedal notes will be used. So, if you want to disable
      transposition, you have to set this to 0 (zero).
      
    Notes:
    * The length of this lists must be less or equal than the length of
      OutBassPedalChannel and OutChordChannel; otherwise an error will be
      raised.
    * If the length of this list is less than the length of OutBassPedalChannel
      and OutChordChannel, then the transposition of the remaining elements will
      be set according to the last value of the list.

  * Next set the MIDI controller that you are going to use for sending
    BankSelect messages:
    BankSelectController="32"
    If not given, it default to controller 32.
  * Set the bank that will be select when running starting the software:
    InitialBank="2"
    This is a number between 1 and the number of banks that you setup here. The
    maximum posible value would be 124. If not given, then '1' will be assumed.
  * We the OnBankChange attribute as follows:
    OnBankChange="QuickChange"
    This means that if a BankSelect message is detected and pedals are being
    pushed, then the NOTE OFF messages for the previous bank will be sent and
    then the NOTE ON messages from the current bank will be set. This is useful
    if for example a C Major chord is being played and after the bank changes
    you want to inmediatelly change it by a C Minor chord. Please note that if
    there are no definitions for the active pushed pedals on the current bank,
    then only the NOTE OFF messages will be sent. Here you also have this
    options:
    - "StopPlayback": triggers NOTE OFF messages for the current pushed pedals.
    - "ContinuePlayback": the current pushed pedals continue playing without any
      change.
    If this attribute is omitted, then "StopPlayback" will be assumed.
  * Decide how you are going to treat NOTE ON messages with a  velocity of zero,
    for this purpose set MinVelocityNoteOff to true if they are going to be
    treated as NOTE OFF or set it to false otherwise. If omitted it defaults to
    true.
  * Octave: This parameter only applies if you use a note symbol and it is the
    octave of that note, wich can be a value between -2 and 8, so, the middle C
    would be: Note="C" Octave="3" or C3 for short. The only thing you need to
    know is that the maximum note is G8, so, giving a note like: A#8 will raise
    an error. Please also be aware that this number will be ignored if you use
    note numbers. The value of this parameter can be overriden by the child
    nodes: Bank and Pedal.
    * PedalMonophony: Whether or not to enable monophony for pedals. If true,
      only one set of notes will be played at one time; pushing one pedal
      without having released the previous one, will cause to send MIDI NOTE OFF
      messages for the first pedal. It defaults to "false".
  * Optionaly, you may set an encoding for your bank names. If other than UTF-8,
    you may add it, ie:
    Encoding="GB2312"
    
    In order to test this in a Windows that is setup on a diffent unicode, you
    will have to use the python ide and not the command prompt, which seems to
    not support other encoding than the setup on the user's profile.
-->

<Controller xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://www.technosoft.solutions/xsd 
            MidiBassPedalController.xsd"
            xmlns="https://www.technosoft.solutions/xsd"
            InPort="MIDI In*" OutPort="MIDI Out*"
            InChannel="1"
            OutBassPedalChannel="3,5" OutChordChannel="4,1,3"
            MidiEcho="true"
            BassPedalVelocity="70,36" ChordVelocity="fff,p,mf"
            BassPedalTranspose="-2,23" ChordTranspose="2,-25,127"
            BankSelectController="32" InitialBank="2" OnBankChange="QuickChange"
            MinVelocityNoteOff="true"
            Octave="2"
            PedalMonophony="false"
            Encoding="UTF-8">

  <!--
    The following next three nodes: Start, Stop, and Panic are optional and they
    are used for sending MIDI or SysEx messages while the controller is
    starting or stopping respectively. The Panic node is used to define a
    sequence of messages that a controller sends to fix posible playback issues;
    during the transmition of this message bank select messages will be disabled
    in order to avoid unexpected behaviour.

    For each the start and stop nodes, you can send one or more messages at once
    and they will be excecuted sequentially in the order you define.
  -->

  <Start>
    <!-- Turns on the INTRO./ENDING switch -->
    <Message Type="SysEx" String="F0 43 70 70 40 4B 7F F7"/>
    
    <!-- Start the rythm -->
    <Message Type="Midi" String="FA"/>
  </Start>

  <Stop>
    <!--
      Sends a rhythm stop
    -->
    <Message Type="Midi" String="FC"/>
  </Stop>

  <!--
    Panic messages can be either included as text, ie:
    <Panic>
      Line 1
      Line 2
      ...
    </Panic>
    
    or if they are really long, then you may save it on a text file, ie:
    <Panic file="/path/to/file.txt"/>
  
    On the last case, you have to give either an absolute or a relative path,
    ie:
    
    Absolute:
    Windows:
      C:\my_path\my_command.txt
      C:/my_path/my_command.txt
    Linux:
      /my_path/my_command.txt
    
    Relative:
    Windows:
      conf\unitor8_panic.txt
      conf/unitor8_panic.txt
    Linux:
      conf/unitor8_panic.txt
    
    Please note that Windows can also use "/" for paths. This is because the
    python function for doing this validation doesn't care if it is an slash or
    a backslash.
    
    Finally, if you give a file and also a text, then an error will be shown;
    you can only use one of them.
    
    The command text can contain the following elements:
    * a comment: //some comment
    * a MIDI message
    * A SysEx message
    You may have spaces or tabs at the beginning and end of each line;
    each line will be separated by an enter.
  -->
  <Panic File="conf/unitor8_panic.txt"/>

  <!--
    Next you can define the different Banks for each bass pedal. You need to
    have at least one and maximum 119. Inside each bank, you can overwrite the 
    BassPedalVelocity, ChordVelocity, BassPedalTranspose, and ChordTranspose if
    you want. You may optionally give it a name.
  -->
    
  <!--
    The following bank overwrites the BassPedalVelocity, ChordVelocity,
    BassPedalTranspose, ChordTranspose, and Octave settings comming from the
    Controller node.
    
    Since OutBassPedalChannel and OutChordChannel were set to ="3,5" and "4,1,3"
    respectively, and BassPedalVelocity and ChordVelocity were set to: "p" and
    "40,12" respectively, two sets of pedal notes will be sent on channels "3,5"
    each with a velocity of "p"; one chord will be sent on channel "4" with a
    velocity of "40", then two chords will be sent on channels: "1,3" with a
    velocity of "12". Similarly, the two sets of pedal notes will be transposed
    by -47 semitones, one chord by 27 semitones, and two chords will be
    transposed by -16 semitones.
  -->
  <Bank Name="Bank names can be really long; they have literaly no limit and include unicode characters like: öèãí; In theory even chinese should be possible. just set the correct encoding, ie: UTF-8 or GB2312"
        BassPedalVelocity="p" ChordVelocity="40,12"
        BassPedalTranspose="-47" ChordTranspose="27,-16"
        Octave="1">
    <!--
      Next you can define the different Pedal actions for each NOTE ON and OFF
      messages that you send. You can define up to 128 Pedals, which is the
      maximum number of MIDI notes; however take in mind that the number of
      pedals is in deed the number of switches of your pedal board.
      
      Inside each pedal, you can overwrite the BassPedalVelocity, ChordVelocity,
      BassPedalTranspose, and ChordTranspose if you want.
      
      Next you have to set the following attributes:
      * Note: MIDI note number or note name to catch. Note must be a number
        between 0 and 127 or one of the following symbols: A, A#, B, C, C#, D,
        D#, E, F, F#, G, or G#; please note that I don't intend to include the
        usage of flat intervals (ie: Gb) because excentially they can be also
        expressed in terms of the sharp intervals. It is not really necessary
        and including them would mean to make my code longer and perhaps
        complicated. Please also be aware that the values of "Note" must be
        unique inside a Bank, so, you can't define two pedals for the MIDI note
        34; only one must be setup.
    -->
        
    <!--
      The following pedal will overwrite the values of OutBassPedalChannel,
      OutChordChannel, BassPedalVelocity, ChordVelocity, BassPedalTranspose, and
      ChordTranspose, and it will listen to the note C1. Then it will send the
      bass note "A#0", which is what we get after transposing C1 by -3
      semitones, and the chord: D#1, F#1, A#1, which is what we get after
      transposing C# Major (C#1, F1, G#1) by two semitones.
      
      Please also be aware that the order of the chord notes matters when
      calculating the chord note octaves, ie: if you enter: G#, F, and C#, then
      the octaves will be calculated based on the first note: G#, so, the
      resulting chord would be: G#1, F2, and C#3, which is called "spread
      voicing". Finally, the minimum length of a chord would be one note; you
      can also set your keyboard to fingered note, so that's really what you
      need on this case.
      
      Also noticed that the Channel attributes are no longer comma list; this
      means that for this case, you will only send a pedal and a chord note set
      at the time.
    -->
    <Pedal OutBassPedalChannel="1" OutChordChannel="1"
           BassPedalVelocity="pp" ChordVelocity="f"
           BassPedalTranspose="-3" ChordTranspose="2"
           Note="C" BassNote="C#" ChordNotes="C#,F,G#"/>

    <!--
      The following pedal won't overwrite the values of BassPedalVelocity,
      ChordVelocity, BassPedalTranspose, and ChordTranspose, and it will listen
      to the note C#-2 (-2 = default of Octave), then it will switch to the
      Bank number 2.
      
      Note: you don't need to send BankSelect messages on your pedal
      definitions; alternativelly, you can send a MIDI CONTROL CHANGE message,
      so, assuming that your InChannel is 2 and that the bank you want to select
      is the number 11, then this is the message that you need to send:
      * B1 20 0A
      Explanation:
      - 'B' indicates that your message is a CONTROL CHANGE
      - '1' is the MIDI channel to use; since it begins from 0, then channel 2
        is in reality a '1' in the hexadecimal string
      - 20 is the hexadecimal equivalence of controller 32 (Bank Select)
      - 0A would be the bank number 11. Again since banks on the hexadecimal
        strings begin with 0, you need to rest 1 to the 0B hexadecimal number
        representing 11.
      This last alternative ways gives you the flexibility to use two or more
      foot controllers connected serially, ie: a StudioLogic MP-117 for the bass
      notes and a FCB1010 for changing banks and sending another messages for
      your keyboard.
    -->
    <Pedal Note="C#" BankSelect="2"/>
    
    <!--
      The following pedal will only override ChordTranspose by disabling it (0
      semitones), then it will listen to the note 60 (C3 or middle C). Next, the
      chord: G3, C4, and E4 will be send three times according to the value of
      OutChordChannel comming from the Controller node, channels: 4, 1, and 3.
      Please note that the chord octave was calculated according to the octave
      of the note 60, which is 3.
      
      Finally, the next bank will be selected. Please note that if here you
      instead use 'Previous', and because this is the first bank, then the last
      bank will be selected. Please note that if you are in a bank in the middle
      and you want to select the last bank, then you can also use 'Last' for
      this; this is useful if you are continuing changing your configuration,
      but the last bank always remains the same. Other posible values:
      - 'List': Sends a SysEx back with the bank names. This SysEx has the form:
        F0 7D 00 (lengh1.1) (lengh1.2) ... (bank_name1)
                 (lengh2.1) (lengh2.2) ... (bank_name2) ...
                 (checksum)
        F7
        where:
        * 7D is the manufacturer ID, which on this case, we used this ID, which
          is used for reasearch and not for commercial purposes.
        * 00 is the operation ID: right now I only have this operation, but if
          there is a need of defining more SysEx, then this field will be
          increased.
        * length are the lengths of the bank's name (see the file
          MidiBassPedalController.xsd for more details about the format of this
          bytes).
        * bank_name is the name of the bank, which will be coded in 7 bit bytes.
          To decode it, you will have to use the function:
          convert_unicode_from_7_bit_bytes from the ByteUtilities.py module.
        * checksum is a byte to ensure that the data was properly transmited
          (see the file MidiBassPedalController.xsd for more details about the
          format of this byte).
      - 'Quit': Quits the controller software.
      - 'Reload': Stops and starts the controller software. Useful if you
        changed the configuration file, and want to reload it.
      - 'Reboot': Reboots the system running the software.
      - 'Shutdown': Shutdowns the system running the software.

      Note: For the two last commands, under Linux or MACOS, you will need to
      run the software with "sudo" or become the super user. Under Windows,
      a user without admin rights can usually restart or shutdown the system;
      howerver, there are cases where your administrator disable this; on this
      case, you will have to run the controller software as administrator.
    -->
    <Pedal Note="60" ChordNotes="G,C,E" BankSelect="Next"/>
    
    <!--
      If you wish, you can also setup pedals that only send general MIDI or
      system exclusive messages. You only need to setup the note to which listen
      to, then define the messages inside the pedal. You can set as many
      messages as you want, either: MIDI, SysEx, or both; they will be
      sequentially excecuted. Please note that you can define when to trigger
      the messages by using the attribute: "Trigger", which can be: "NoteOn" or
      "NoteOff"; it defaults to "NoteOn".
    -->
    <Pedal Note="61">
      <!--
        On a Yamaha Electone HS-8 organ, this command will turn on the upper
        combination voice, when pressing this note. Please note that since
        "Trigger" defaults to "NoteOn", you can omit it, if you want.
      -->
      <Message Type="SysEx" Trigger="NoteOn" String="F0 43 70 72 41 30 01 F7"/>

      <!-- Sends a program change on channel 1, program = 1A -->
      <Message Type="Midi" String="C0 1A"/>
      
      <!-- Sets the modulation wheel on chanel 2 to its maximum -->
      <Message Type="Midi" String="B1 01 7F"/>
      
      <!--
        Again a Yamaha Electone message, which will set the lower orchestral
        voice to 1 when triggering a NOTE OFF message.
      -->
      <Message Type="SysEx" Trigger="NoteOff" String="F0 43 70 72 41 03 03 F7"/>
    </Pedal>
    
    <!--
      Here a panic command will be sent when releasing the note 62. Please note
      that "SendPanic" can be used together with other options, ie: sending
      bass or chord notes, sending BankSelect messages, etc.. Please note that
      if this is used together with other MIDI or SysEx messages, the panic
      command is the last thing that will be excecuted.
    -->
    <Pedal Note="62" SendPanic="true"/>
  </Bank>
  
  <!--
    The following bank won't overwrite the BassPedalVelocity, ChordVelocity,
    BassPedalTranspose, and ChordTranspose settings comming from the Controller
    node (note that it is written without any attribute).
  -->
  <Bank>
    <!--
      The following pedal will only list the bank names after the note 123 gets
      released (NOTE OFF message).
    -->
    <Pedal Note="123" BankSelect="List"/>
    <!--
      The following pedal will override some values comming from the controller,
      then some transposed bass pedals and chords will be sent.
      
      Please note the "+0" on the BassPedalVelocity and ChordVelocity values;
      this indicates that the velocity comming from the pedal controller will be
      used. Setting just "0" will set the velocity to zero, which is quite
      diffent.
    -->
    <Pedal Note="124" OutBassPedalChannel="5,3,16" OutChordChannel="1,3"
           BassPedalVelocity="-22,15,+0" ChordVelocity="+0,-33"
           BassPedalTranspose="+0,+5,-3" ChordTranspose="+0,23"
           Octave = "0" ChordNotes="G,C,E" BassNote="C"/>
  </Bank>
</Controller>