xphat: a MIDI slider box for Linux/Xxphat: a MIDI slider box for Linux/XPaul Barton-Davis <pbd@op.net> (Late Summer/Fall 1998) ContentsWhat is xphat ?Getting xphatCommand line optionsMIDI portsThe User InterfaceSysex ConfigurationMessage ParametersSlider ModesChanging Slider OperationsProblemsWhat is xphat ?First of all, xphat is a piece of free and open sourcesoftware. I wrote it because I wanted a tool like this. I'm giving itaway because I believe in the idea that most software shouldbe free. I'm giving you the source code because you may want to modifythe program, perhaps to improve it, or perhaps you might like to learnsomething from how I wrote it (or tell me how to to do it better). Iwant xphat to benefit from this kind of software developmentprocess. However, there are some restrictions on what you can do withxphat, since I'm releasing it under the GNU PublicLicense. In particular, you can't distribute it, or any modifiedversion of it that you produce, without giving other people the optionof getting the complete corresponding source code.Secondly, xphat is a program that provides the functionalityassociated with MIDI slider/fader boxes such as the PeaveyPC-1600 and the PhatBoy. Its a device for controlling other MIDI devices that respondto MIDI messages in useful ways. Such devices could include externalMIDI synthesizers, soundcard-based synthesizers that can be controlledvia MIDI, MIDI effects processors, MIDI software tools, softwaresequencers such as Rebirth or Softwerk; basically, any MIDI device.xphat grew out of my frustration with conventionalcomputer-based device simulations, which rely on the mouse for actionand/or use conventional event processing. These approaches typicallyrestrict you to modifying only one thing at a time. It seemed to methat a computer keyboard, although not the ideal control device forevery purpose, had on the order of 100 keys that could be used ascontrols for a device like xphat. I think that xphatis novel in its use of the computer keyboard as a controlling deviceallowing simultaneous manipulation of several objects at once.Getting xphatYou will need:Linux,Sound support that creates at least one functional (raw) MIDI device such as /dev/midi,The X Window System (including libraries),The excellent XForms library,Linux development tools (g++, make, ld, etc.),The X libraries,and last but not least, the source.Once you've collected all the pieces, then: cd /the/right/place/for/source/code/on/your/system tar -zxvf wherever/you/put/the/tar/file/xphat.tar.gz cd xphat edit the Makefile to reflect the location of the XForms library. makeYou can then run xphat by typing ./xphat.What does it do ?xphat displays 1 or more windows each of which contains 16sliders. These sliders can be controlled with the mouse, or, moreusefully, with the keyboard. Each slider can be bound to a keyboardkey. The response of each slider to a keypress is by defaultlogarithmic (the slider moves quicker the longer you press "it"), buteach slider can be given a custom response curve using a simplegraphical curve drawing tool. The space bar gives a convenient methodof reversing the direction of slider movement.Each slider can emit any MIDI message (except Active Sense). Most ofthe modes for each slider feature a well-defined MIDI message type(such as Note On, Controller N, Pitch Bend, etc.) which contain oneparameter which can be varied by moving the slider. Oneexception to this is "Sysex" mode, which allows a slider to beprogrammed with an arbitary sequence of bytes, including parametersthat can be altered.Command Line OptionsThe following command line options are available: -m device-name:tag or --midi device-name:tag defines one or more device files (such as /dev/midi00) to use as a MIDI port. Up to 32 of these options may be used. The ports will be opened in the order given, and numbered accordingly, starting with zero. If no --midi options are given, xphat will attempt to open the first two ports found (using the directory order of /dev to find device files matching "midi*"). Each device file successfully opened will be referred to using the symbol name `tag' given with the option. This allows you to "label" MIDI ports with mnemonic names to help when selecting ports for various reasons. If no --midi options are given, the device file names will be used as the tag. -o N or --oport N defines the default input MIDI port, using the numbering scheme described above. If not given, the first port found (numbered zero) will be used as the default output port. -i N or --iport N defines the default input MIDI port, using the numbering scheme described above. If not given, the second port found (numbered one) will be used as the default input port. If no second port exists, then the first port will be used instead. -t or --thru automatically turns on "thru" mode if the default input and output ports are differen. Turning thru mode on/off can be done by clicking on a button; this just starts up xphat with it turned on, instead of off, which is the default. Note that if the default input and output port are the same, the --thru option will do nothing, and no button for thru mode will be displayed. -d what or --debug what turns on debug options for `what' -s sysex_file_name or --sysex sysex_file_name specifies the name of the System Exclusive file. See Sysex Configuration below for details on the format of this file. If not given, the filename defaults to "xphat.sysex".Message ParametersArbitrary Sysex Messages (either custom or defined in the sysexconfiguration file can contain a number of special references thatprovide for dynamic adjustment of the message sent by thatslider. Each reference is inserted into the message as a singlecharacter, and must be one of the following:P this will result in the current slider value being inserted at that point in the message whenever it is sent.V this will result in the most recent note-on velocity for the slider'sMIDI channel being inserted at that point in the message whenever itis sent. If no note-on velocity has been seen for that channel, avalue of 127 will be used instead.Sysex Configurationxphat uses a simple text file to provide the information necessary topredefine useful System Exclusive messages for a variety of MIDIdevices. The file can be specified on the command line with the -s or--sysex options. If unspecified, xphat looks for a file called"xphat.sysex" in the current directory. This file has a very simple format:Any line beginning with a '#' is considered to be a comment and is ignored.Any line beginning with non-white-space is considered to start asection defining System Exclusive messages for a device whose name isthe entire contents of that line.Any non-blank line starting with whitespace following a device name isconsidered to both name and specify a System Exclusive message forthat device. The name of the message preceeds an '=' sign (and isspace-trimmed before use) and the message itself follows the '=' sign.An example will help:#-----------------------------------------------------------------------## Sysex Info File for xphat#Oberheim Matrix 6 keyboard mode = f0 10 06 06 30 P f7 dco1 freq = f0 10 06 06 00 P f7 dco1 saw shape = f0 10 06 06 05 P f7 dco1 pulse width = f0 10 06 06 03 P f7 dco1 mod/vibrato = f0 10 06 06 07 P f7 dco1 waveform = f0 10 06 06 06 P f7#-----------------------------------------------------------------------The System Exclusive message is specified in a series of two-charactersequences, each of which is a hexadecimal value. They may also containthe parameter references "P" or "V" (see Parameters above for details on how these work.The User InterfaceThe SlidersEach window that xphat displays contains 16 slider interfaces. Eachslider interface looks like this: The Port SelectorThe Port selector pops up a menu of available MIDI ports to assign asthis sliders output MIDI port.The Channel SelectorThe Channel selector has two modes: clicking on it with the rightbutton will advance through the available MIDI channels; clicking withthe left will pop up a list of channel choices.The ButtonThe Button can function in many different ways. Its mode can be set byediting the slider. Possible modes are:Message When the button is in this mode, it has its own pair of MIDImessages, one sent when the button is pushed, and one when it isreleased. One or both these messages may be left unset, which will dothe obvious: pressing or releasing the button will do nothing. Themessage has to be entered as raw MIDI bytes, and may include the usualparameters.Send On Press In this mode, when the button is not pushed, the slider will notemit any messages at all. When the button is pushed, the relevantmessage given the slider's current state will be sent, and while itremains pushed, modifying the slider will continue to cause the slider toactively operate. Releasing the button stops the slider from activelyoperating. This mode can be useful if you want to adjust the slider toa particular value, but not send the messages containing theintermediate values. Just set the button mode, adjust the slider, thenpress the button (and possibly release it).Trigger In this mode, pressing the button causes the slider toautomatically "slide" from its current value to its maximum value,following its own response curve. It can be used, for example, totrigger pre-programmed changes in a MIDI control parameter (say,volume) that vary over some period of time.Recorded MIDI This mode does not currently work, and may be removed.Scene This scene does not currently work, but will do in a future version.The SliderThe slider is just that - a slider. It may be moved by pressing thekey bound to that slider (displayed in the Key Window), or using themouse. If the slider is part of a group, moving any slider in thegroup (with the mouse or with the keyboard) will move all othersliders in the group. The slider will also move if it has been set touse MIDI input for update, and relevant MIDI messages are received onits input port.The Value WindowThe Value window displays the value of the current slider. This is thevalue that will be inserted into the message sent by this slider. Itcan also be directly edited by first clicking on it, typing in a newvalue, and then pressing the TAB or Return keys.The Mode ButtonThe Mode button, when pressed, pops up a list of available modes forthis slider, and displays a description of the mode once selected.See Slider Modes for details on each mode.The Key SelectorThe Key selector allows to specify the key that will control thisslider. Click on the key selector, press the key you want to use, andthen press TAB or Return. NOTE: at present, onlyalpha-numeric keys can be used for binding to a slider. A futureversion may alter this.The Group SelectorThe Group selector allows you to assign the slider to a group, andoptionally, for certain slider modes, a particular MIDI note valuewithin that group. Sliders in a group can be all be simultaneouslycontrolled by adjusting any of the group's member sliders.Click on the group selector, then edit its contents. If you just wantto specify the group, use a simple integer. To specify a group and anote number, separate them with a period (e.g. 3.64 means "group 3,MIDI note number 64). You can also use 0 for the group, which means"no group". Once you've entered the desired value, press TAB orRETURN. This and any other sliders with the same group ID are thenall considered to be part of a group.Notice that the Group selector allows great control when usedwith the On Velocity or Off Velocity modes. If the slider is assignedto a MIDI note number, the slider will only edit the velocity valuesof the specified note. This can be used as a powerful means of fadingparts of a track, especially drumkits, where typically a given MIDInote corresponds to a particular drum sound. By collecting severalMIDI notes together into the same group, you can fade in/out entiresections of a drumkit (or other pattern-based musical form).Per-Window controlsThe Preset buttonThe Preset button pops up an interface for saving, naming, renamingand loading presets. See Preset Handling.The Thru Mode buttonThe Thru Mode button turns on/off MIDI thru mode. When turned on(pressed), each MIDI port used by xphat is connected to the next port(where next is defined by the order they were opened in, and where thelast port is connected to the first, to form a closed circle). Thrumode is shared by all windows created by xphat (i.e. it is a globalproperty of the program).The More Sliders buttonThe More Sliders button creates a new window of 16 sliders and theircontrols. This new window is completely independent of all othersxphat creates, and has its own keybindings, preset storage, and soon. The only setting it shares with other windows is the "Thru mode".The Quit buttonThe Quit button closes the window it is on, and, if this is the lastwindow that xphat has created, exits from xphat.Editing a slider's "hidden" settingsThere's no documentation for this yet. But ... try pressing thecontrol key and one of the keys bound to a slider (mnemonic: "controlslider K"), and see what pops up. It should be fairly obvious. Don'ttry editing the response curve yet, its still broken. Also, the SysExmode selector doesn't do anything useful.Slider ModesEach slider can be set to any one of many different modes. Thesecurrently include:OffThe slider does nothing.Note OnThe slider sends a MIDI note on message every time it is altered,and the note number will be the value of the slider.Note OffThe slider sends a MIDI note off message every time it is altered,and the note number will be the value of the slider.Program ChangeThe slider sends a MIDI Program Change message every time it is altered,and the program number will be the value of the slider.PolyPressureThe slider sends a MIDI Polyphonic Pressure message every time itis altered, and the pressure value will be the value of the slider.ChannelPressureThe slider sends a MIDI Channel Pressure message every time it is altered,and the pressure value will be the value of the slider.Pitch BendThe slider sends a MIDI Pitch Bend message every time it is altered,and the pitch bend value will be the value of the slider.SysexThe slider sends a user-provided MIDI message every time it isaltered. If the message contained anyparameters, they will be set according to thecurrent value of the slider and other relevant conditions.ControllerThe slider will send a MIDI Controller message every time it isaltered. The controller ID is set when this mode is selected. Thevalue of the controller value will be the value of the slider.On VelocityThe slider will edit MIDI Note On messages received on its inputport, setting the velocity value to the value of the slider. If theslider has its note number set, only Note On messages for that notewill be edited. This mode only has an effect if thru mode is in effectto relay the messages from the inport port to its output port.Off VelocityThe slider will edit MIDI Note Off messages received on its inputport, setting the velocity value to the value of the slider. If theslider has its note number set, only Note Off messages for that notewill be edited. This mode only has an effect if thru mode is in effectto relay the messages from the inport port to its output port.ProblemsOne big problem you may notice is that if you try to operate twosliders at the same time using the keyboard, it doesn't alwayswork. I've spent a lot of time investigating this issue, and it turnsout to be very deeply rooted in the hardware of the PC keyboard. Thereis an electrical contact matrix under the keyboard, which is used toidentify which keys are depressed. In certain keyboard designs, thematrix doesn't always allow the correct identification of simultaneous"key held down" conditions for arbitary combinations of keys. Forexample, on my keyboard, once 't' is held down, no keyboard interruptfor 'r', 'y', or 'u' will be generated until 't' is let up and thosekeys pressed again. xphat is not the only program to encounter this:you can see the same behaviour with the X event testing programxev(1), and a Linux console keyboard utility (whose name Iforget). The best approach to this is to rebindthe slider to a key in a different section of the keyboard, althoughthis is a trial-and-error approach, since you can't predict which keyssuffer from this problem. |
|
