═══ 1. Introduction ═══ Piano Please read this document in entirety. I took the time to make it explicit, clear, and very useful. It took me longer to write it than it will ever take you to read it. Therefore, you owe it to both of us to read it. OK? Piano is a Presentation Manager program (for OS/2 2.x) that turns your computer into a MIDI controller. In other words, it allows you to play notes on external MIDI sound modules from your computer's keyboard and mouse via a MIDI Interface. If you have a sound card with a built-in sound module that is triggered via MIDI notes (such as a Turtle Beach MultiSound or Roland RAP-10, SCC-1, or other such cards, with appropriate OS/2 driver), then you can play those like musical instruments as well. Piano also allows you to generate many other types of MIDI data such as Volume, Pan, Effects Level, Chorus Level, Pitch Wheel, Modulation Wheel, AfterTouch (Key Pressure), and Channel Pressure so that if your MIDI sound module supports these MIDI messages, you can control the module appropriately. Some of the words in this manual are highlighted in bold text, such as Program Change. These are words that refer to controls (ie, buttons, sliders, checkboxes) which you manipulate in Piano's window. Other words are in colored text such as Channel Pressure. These refer to MIDI messages (ie, data). Underlined words, such as Pitch Wheel, refer to hardware, such as if I was referring to the Pitch Wheel on your MIDI unit. Words that are in colored text such as Read This are meant to be emphasized. Words in italics refer to aspects of OS/2. This is version 1.6. ═══ 2. Copyright ═══ This OS/2 Online Book and the related files PIANO.EXE and GENMIDI.DLL are all copyright 1995 by Jeff Glatt. These files are freely redistributable, and may be used by and distributed along with any software, be it commercial or otherwise, provided that these files are not internally modified, nor specifically sold as a complete product by themselves. The only price that you have to pay is the one that you're already paying by spending all of your time in front of a computer instead of developing healthier outlets. NOT SO STANDARD DISCLAIMER: These programs are provided "as is" without warranty of any kind either expressed or implied or tatooed in a place that only a few people have ever seen, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, and the dubious assumption that the software has been created by a sane individual who would never do anything that may hurt you. The entire risk as to the results and performance of the programs is assumed by you or someone who looks exactly like you. Jeff Glatt does not guarantee that the functions in these programs will meet your requirements, especially if your requirements involve lots of latex and some docile, domesticated animal. Nor does Jeff Glatt warranty the programs to be uninterruptable or error-free, although mercifully free of "General Protection Faults". If you use said programs, you can not say anything nasty about the author, even if the programs inadvertently cause the erasure of your collection of X-rated GIFs of a conservative, overweight and overrated TV "personality" plooking himself vigorously with his royalty checks from some rancid paperback. Jeff Glatt is not responsible for any damages as a result of anything that he has done, or hasn't done, or was supposed to do but never got around to it, and furthermore, he doesn't even care so leave him alone, ratface. You may have more or less protections in certain states of the union, depending upon how far your local politician is willing to bend over for some bribe from a business lobbyist. Just remember that Jeff Glatt has no money, so don't bother suing him as a result of any damages caused by this OS/2 program. Tell your greasy lawyer to go after IBM, and make sure that you pick 12 really stupid pinheads for the jury. If swallowed, induce vomiting immediately by contemplating the asthetics of Microsoft Windows. OS/2 is a trademark of International Business Machines Corporation. Windows is a trademark of Microsoft Incorporated, and furthermore, Bill Gates is to blame for it. If you have unreasonably presumptuous suggestions (ie, an enduser who expects outrageous amounts of free support), snide comments, criticisms, and anything else other than dollar bills, then send them to someone else because you got it for free, and you know what you get for nothing? On the other hand, any type of positive contribution from other programmers is very much welcome and encouraged as these are the only folks who can made things happen for OS/2. IBM ain't gonna do it. If you do need to contact the author, then either phone some of the more prominent psychiatrict clinics in central New York state, or try this: Jeff Glatt 6 Sycamore Drive East New Hartford, NY 13413 (315) 735-5350 Sure, this copyright notice has attitude. Get used to it, or kill yourself. ═══ 3. Driver Requirements and Setup ═══ Of course, your computer needs some sort of MIDI interface card (ie, with MIDI IN and OUT jacks) to connect the computer to the MIDI unit. Many Sound Cards offer the option of attaching a "box" with MIDI connectors to the card's joystick port. This is the same thing as having a separate card that just does MIDI input and output. Piano requires that your MIDI interface or Sound Card has an OS/2 driver compatible with MPUDEV.SYS (included). Information sent to this driver via DosWrite() must be interpreted as outgoing MIDI data (without any timestamp). Note: Piano does not use MMPM. An MMPM driver will not work with Piano. MMPM is going to die a horrible death anyway due to lack of useful support, as well as IBM introducing a new protocol. You may as well get your shovel and bury MMPM right now. Piano probably also doesn't support IBM's "Realtime MIDI subsystem". I wouldn't know. I didn't look at it, and I don't intend to buy $300 worth of CD-ROMs in order to find out that it may not be for me anyway, plus I'm not too keen upon tying my stuff to an "IBM MIDI subsystem" given IBM's disinterest in pursuing vertical markets like the music market to the extent that Microsoft does. Who's to say that IBM won't traipse off with the development and promotion budget, fawning after their big buck corporate client accounts, and we won't end up with another OS/2 item of "secondary importance" like MMPM on our hands? You must also know your driver's internal name (which might be different than the filename of the driver). Often, this is the driver filename minus the .SYS extension. If you own an MPU-401, or some card that has an MPU-401 compatible interface (UART mode is good enough, but it must be actual hardware compatibility, not just some TSR software driver emulation such as what you get with cheesy sound cards), such as an SCC-1, RAP-10, MusicQuest MQX-16 or MQX-32, etc, then you can use my MPUDEV.SYS OS/2 driver. See the documentation with that driver for its internal name and usage, or see the Port setting. By default, Piano will use my MPUDEV.SYS driver (ie, the first port MPUDEV1$), and so you don't have to supply it with that name. If you want Piano to use a different driver, then you must supply the name of the driver to Piano. If you run Piano from an OS/2 Command Prompt, then simply type the name of your driver as an argument. For example, to use a driver with the internal name BLORT, you would specify BLORT. If you run Piano from a Desktop icon, open up the Settings menu for Piano. In the Parameters field, type the name of your driver. Now whenever you run Piano from the Desktop, it will use that driver. Note: You must omit the .SYS extension from the driver name. If Piano can't open the specified driver, it will display an error dialog box. At this point, the program will run, but it won't really do anything until you open a driver (ie, port). You may want to specify the /I switch when invoking the program if you don't desire the card to be reset when Piano starts up. The RAP-10's entire GM module will be reset to default values otherwise. There are other startup parameters that you can pass to Piano, either by adding them to the command line, or entering them in the Parameters field of the Desktop icon. These will be covered later. Piano also requires that GENMIDI.DLL (included in this archive) be copied to some directory along the path specified by the LIBPATH statement in your config.sys file. Often, placing it in the same directory to which PIANO.EXE is copied will suffice. ═══ 4. Options ═══ When starting Piano, there are a number of optional parameters that can be specified. If running Piano from a Command Prompt Window, then add the parameters to the command line. If running Piano from a Presentation Manager Object (ie, icon), then open up the Settings menu for that object, and in the Parameters field, type the desired options (ie, where you also put the driver name). Now whenever you run Piano from the Desktop, it will use those options. You could even create several program objects (by copying the Program object in OS/2's Template folder), and give each one different options tailored for various MIDI devices (and also give each object a unique name). For example, to specify the unit MPUDEV2$ with channel 7: MPUDEV2$ /C7 You may want to specify the /I switch when invoking the program if you don't desire the card to be reset when Piano starts up. The RAP-10's entire GM module will be reset to default values otherwise. For example, to use a driver called "RAP10", skipping initialization. RAP10 /I Some sound cards, such as the RAP-10, have a built-in General MIDI (GM) sound module. The module will not play MIDI messages sent to it until it receives a "Turn GM Sound On" MIDI System Exclusive Message (although the card may still pass MIDI messages on to its MIDI OUT jack). Initially, Piano will send such a MIDI message unless you specify the /G option. This will prevent Piano from turning on the GM Sound Module (if you desire) of a card that supports this MIDI message. By default, Piano starts with only MIDI channel 1 selected. You can override this, and specify which MIDI channel(s) that Piano should select upon startup. You specify the /C option, and then follow this with the desired MIDI channels to select, each separated by a comma. For example, to select channels 3 and 4 initially: /C3,4 By default, Piano starts with mouse button 2 emulating a Hold Pedal. You can specify a different controller for mouse button 2 to emulate via the /B2 option. Follow the option with a comma, and then the new controller number (in decimal). For example, to specify the Hold2 Pedal Controller (ie, 69) for mouse button 2: /B2,69 By default, Piano starts with mouse button 3 emulating a Portamento On/Off switch. You can specify a different controller for mouse button 3 to emulate via the /B3 option. Follow the option with a comma, and then the new controller number (in decimal). For example, to specify the Data Increment (Button) Controller (ie, 96) for mouse button 3: /B3,96 By default, Piano starts with the "Effect" slider (ie, 2nd slider from the top of the window) set to send Effects Level Controller (#91). You can specify a different controller for this slider via the /B1 option. Follow the option with a comma, and then the new controller number (in decimal). For example, to specify the Breath (ie, Wind) Coarse Controller (ie, 2) for this slider: /B1,2 For the mouse button 2 and 3, and "Effect" slider, you can also specify the controller name (ie, as it appears in Piano's drop down list). For example, instead of controller #69, you can specify "Hold2". If the controller name has an imbedded space, such as "Genr 1", then enclose the option in parentheses, such as: "/B1,Genr 1" Initially, Piano also sends out All Notes Off and Reset Controllers MIDI messages on the selected MIDI channels. On MIDI devices that acknowledge these messages, this turns off any sounding notes, and usually resets the Pitch Wheel to center, the MOD wheel to 0 (ie, off), releases the Hold Pedal, turns off any Pressure or Aftertouch effects, and may reset other controllers. (Check your device's MIDI implementation chart for its response to the Reset Controllers MIDI message). If you don't want Piano to send these messages initially, then specify the /Z option. If you specify this option, note that the state of Piano's sliders and Program may not reflect the true state of the MIDI device. Of course, you can always press Piano's Reset button to force the MIDI device to be set to the state of Piano's sliders and buttons, but this also sets the sliders to default values as well as turning off the controllers associated with Mouse 2 and Mouse 3. Note: You can specify options (and the driver name) in any order. For options that require additional text, such as the /C option, you must not leave blank spaces between the option and additional text, unless you enclose the entire option in quotes. ═══ 5. MultiTimbral Modules ═══ Some MIDI modules are "multi-timbral". This means that the module can listen to all 16 MIDI channels, and play any 16 of its "patches" simultaneously, with each of the 16 patches set to a different MIDI channel. It's as if the module had 16 smaller modules inside of it, with each being able to play a patch on its own MIDI channel. So is there a name for these 16 "sub-modules" inside of your MIDI module? Well, different manufacturers refer to them in different ways, and I'm going to use the Roland preference, a Part. A Roland multi-timbral module has 16 Parts inside of it, and each usually has its own settings for such things as Volume, Panning, Reverb and Chorus levels, Brightness, and its MIDI channel (ie, which MIDI data the Part "plays"). Furthermore, each Part has its own way of reacting to MIDI data such as Channel Pressure (often used to adjust volume or brightness), MOD Wheel controller (often used for a vibrato effect), and Pitch Wheel (used to slide the pitch up and down). For example, one Part can cause its patch to sound brighter when it receives Channel Pressure messages that increase in value. On the other hand, another Part could make its volume increase when it receives increasing Channel Pressure messages. These Parts are completely independent of each other. Just because one Part is receiving a Pitch Wheel message and bending its pitch doesn't mean that another Part has to do the same. ═══ 6. General MIDI Standard ═══ Nowadays, most MIDI modules have specific Patches setup in a specific order according to a standard known as General MIDI (or GM). All this means is that on every GM module, a Piano patch must be the very first patch. Patch #49 must be a Flute. Patch #25 must be a Nylon String Guitar. Etc. There are 128 defined patches that a GM module must have, in the proper order. Note: When you drop down the list box for Piano's Program, you'll see all 128 GM Patch names. Furthermore, all patches must sound a middle C when receiving a MIDI note number of 60. This corresponds to setting the QWERTY Octave to 6 and pressing the z key. If the GM module also has a built-in "drum module" (ie, usually one of 16 Parts), then each of that Drum Part's MIDI notes triggers a different drum sound. Particular drum sounds are assigned to particular MIDI note numbers. For example, a Closed HiHat sound is set to note number 42. The Drum Part is usually set to receive MIDI data on channel 10, and some devices with a built-in drum module have this module permanently set to MIDI channel 10. Note: The QWERTY keyboard counts its octaves from 1. Most MIDI devices count their octaves from -2. What this means is that, to play the Snare 1 sound, which is a D2 (ie, a D note in octave 2), set the QWERTY keyboard to octave 4 (ie, 2 octaves higher than written) and play the z key (ie, a D note). ═══ 7. Piano Window ═══ When run, Piano opens a Presentation Manager window that has a number of controls that you can operate to do 2 things: 1. Setup how the QWERTY (computer) keyboard operates. These controls don't change settings on your MIDI modules, but rather, affect how your computer controls those modules. In other words, if your computer was a real MIDI controller, it would need some means of setting itself to a particular MIDI channel(s), and perhaps offer features such as being able to transpose its "piano keyboard" (if it were a keyboard controller), etc. These controls setup the controller, rather than the external modules that are slaved to the controller. 2. Directly generate MIDI events with sliders, buttons, and the QWERTY keyboard. These MIDI events are what control and change settings on the external modules. You exit Piano by selecting Close from its System Menu, or double-clicking on the window upper left corner icon. ═══ 7.1. QWERTY Keyboard ═══ The QWERTY keyboard is just the bottom 2 rows of your computer keyboard, which are setup as if they were the black and white keys on a piano keyboard. The z key corresponds to a D note. Therefore, the x key next to it would correspond to a E note. You'll note that the s key is above and inbetween the z and x keys. As you might expect, this would be a D# key. The left SHIFT key is the C key. This physical piano keyboard extends all of the way up to the right SHIFT key which represents a high G. In other words, it has an octave and a half range. When you press down one of these keys, it sends a MIDI Note On message to your MIDI interface on each of the MIDI channels that you have selected. The net result is that it will play this one note on each sound module that is assigned to one of those selected MIDI channels. Note: By default, the QWERTY keyboard is set to output MIDI data on only MIDI Channel 1 (unless you specify the /C option when starting Piano). If your external module allows you to set its MIDI channel, make sure that it is set to the same channel as the QWERTY keyboard (or vice versa). You can even press down several keys simultaneously and play a chord. For example, press the left SHIFT, x, and v keys simultaneously to hear a C Major chord. When you release the keys, the QWERTY keyboard sends the appropriate Note Off messages to your MIDI interface on each of the selected MIDI channels. You'll notice that there is a picture of a piano keyboard in the QWERTY window. You can move the mouse pointer over one of the keys on this graphical piano, and click the mouse button 1 to sound that note (ie, in lieu of using the computer keyboard). When you release the mouse button, the note stops playing. (ie, A Note Off is sent). There is a checkbox for each of the 16 MIDI Channels. Make sure that a channel's box is checked if you want the QWERTY keyboard to output upon that channel. You can check as many of those channels as desired, and the QWERTY keyboard will broadcast its notes on all of those channels simultaneously. Because the QWERTY keyboard is "multi-channel", it allows you to play any combination of sound modules (set to various MIDI channels), at any time. So, you could use the QWERTY keyboard to easily play all of your MIDI modules or check the setup of those modules. Note: You must have at least one channel selected in order for any MIDI messages to be sent. By default, the left SHIFT key is middle C, but you can change the octave that the QWERTY keyboard plays within by using the Octave spin button. Click on either the up or down arrows to increment/decrement the octave, or click into the text field, type the desired octave (1 to 10), and press ENTER. If you ever get any "stuck" notes, use the All Notes Off button to turn them off. Holding the Ctrl key while pressing the n key on your computer keyboard is a shortcut for clicking upon the All Notes Off button. If you really get into big trouble with stuck notes, and odd controller settings, click on the Reset button. Holding the Ctrl key while pressing the r key on your computer keyboard is a shortcut for clicking upon the Reset button. By default, MIDI Note On messages are sent with a velocity of 127 (ie, the highest possible velocity). Generally, velocity is used to set the volume on a per note basis, although some modules can use velocity for other effects such as adjust attack time of a voltage controlled generator (VCA). Your computer keyboard does not generate velocity information (which is how fast you press and release the keys). Piano allows you to set the QWERTY keyboard to one of 12 preset velocity ranges. The 12 Function keys represent those 12 levels, with function key 12 being full velocity (ie, 127). So, you can change the velocity while you're playing by pressing the function keys. ═══ 7.2. MIDI (Mouse) Buttons and Effect Slider ═══ Mouse button 1 is always used to play the graphical piano, or manipulate Piano's window and controls. By default, mouse button 2 simulates a Hold Pedal, and sends MIDI Hold Pedal Controller messages. When you push the button down (and hold it down), the hold pedal is on. When you release the button, the hold pedal is also released. In other words, this is a "momentary pedal" because it's only on while you hold the button down. You can specify a different controller for mouse button 2 to emulate by using the Mouse 2 control. See the Mouse 2 section for details. By default, mouse button 3 simulates a Portamento On/Off switch, and sends MIDI Portamento On/Off Controller messages. When you push the button down, Portamento is toggled on or off (ie, if it was previously off, it's now on, and vice versa). This is not a momentary pedal because, when you toggle it on, it stays on until you press mouse button 3 again (at which time it is toggled off). When the switch is "on", an asterisk appears next to the controller name selected for Mouse 3. If the switch is off, there is no asterisk. You can specify a different controller for mouse button 3 to emulate by using the Mouse 3 control. See the Mouse 3 section for details. By default, the "Effect" slider (ie, 2nd slider from the top of the window) sends MIDI Effects Level Controller (#91). Various MIDI devices may interpret this in different ways (if at all). For example, Roland devices that have a built-in reverb unit often use this for the reverb level. You can specify a different controller for this slider by typing the desired Controller number (in decimal) or Controller name into the entry field next to the slider, or dropping down the list of defined Controller names and selecting one. Mouse button 2 is good for emulating controllers that normally are associated with momentary Pedals, such as Hold, Hold2, Soft, and Sustenuto pedals, whereas button 3 is good for controllers normally associated with Foot Switches, such as Data +/-, Portamento On/Off, Local keyboard On/Off, etc. The "Effect" slider is suited for continuous MIDI controllers; controllers that have more than just an "on" and "off" state, such as Breath controller, Mod wheel, Foot pedal, PTme (Portamento time), etc. Any continuous controller has both a coarse and fine controller number. For example, there is a controller number (10) that adjusts the Pan Position in coarse amounts. It offers 128 "coarse" Pan positions. There is another controller number (42) that adjusts Pan in fine increments. It offers 128 "fine" increments in between two, consecutive coarse settings. So, you could use the Pan coarse controller to set a sound to one of the 128 coarse positions, and then use the Pan fine controller to adjust the Pan to one of the 128 fine increments that fall between the current coarse position and the next coarse position. Some MIDI devices only respond to the coarse controllers and do not implement the fine controllers (ie, for example, a device may only implement the 128 coarse pan positions, and allow no fine adjustments to those). In Piano's drop down list of defined controllers, an H at the end of the name refers to coarse (ie, high resolution) controller, and an L refers to fine (ie, low resolution) controller. ═══ 7.3. MIDI Sliders ═══ As mentioned, Piano generates MIDI Note On and Note Off messages on the selected MIDI channels when you play the QWERTY keyboard. Virtually all MIDI modules respond to these messages. But, there are many more types of MIDI messages that Piano can generate and send to your MIDI module. The sliders on the left side of the window generate some of these different types of MIDI messages. Note: Not all MIDI sound modules respond to all of these types of MIDI messages. In particular, old and very cheap equipment may not respond to any of these messages. If you get a response to the QWERTY keyboard (ie, the MIDI module makes some sound), but a particular slider doesn't seem to be having any effect, then you're probably dealing with such limited equipment. On the other hand, sophisticated gear often allows you to turn on/off the module's response to these types of messages, so check your unit's setup. You operate a slider by "grabbing" its knob with mouse button 1 and moving it to a new position. You have to "let go" (ie, release the mouse button) before Piano sends out any MIDI message (and you perhaps hear the result on your MIDI sound module). Alternately, if you want to increment/decrement the knob's position, move the mouse pointer inside of the slider's shaft, but not on top of the knob itself (ie, to either side of the knob), and click the mouse button 1 once. If you're to the left of the knob, it will decrement by 1 position, and a MIDI message will be sent. If you're to the right of the knob, it will increment by 1 position, and a MIDI message will be sent. Note: Each slider has a small arrow above it. (The arrow may be in different positions on different sliders). This arrow marks the default position of the slider. If you want to quickly set the slider to this default position, click on that arrow, and the knob will move to that position, and send out an appropriate MIDI message. This is very handy for such things as Pan and Pitch since the default is to center the Pan and Pitch wheel. Note that when Piano is first started or when you change the MIDI channel checkboxes, the settings shown for the sliders may not reflect the actual state of your external MIDI modules. You could click on a default arrow in order to send a slider's setting to your module, or use the Reset button. You can hold down a key on the QWERTY keyboard to sound a note on your external module. Then, without releasing the key (ie, so that the note on the external module is still sounding), you can operate a slider. If your external unit responds to such a MIDI message while sounding a note, then you will hear the result on the currently sounding note. In fact, that's really how AfterTouch and Channel Pressure are meant to be applied. Some modules won't make changes to any already sounding notes, so you'll have to release the note and play it again in order to hear the results of moving a slider. You don't have to be playing a note when you move a slider. You can simply move the slider, and then play a note to hear the result. It's just that moving a slider while listening to a note sounding can give you a much clearer sonic idea of what that slider is doing to the sound (assuming that your module responds to the slider's MIDI messages). Note: Remember that if you "grab and move" the slider's knob with the mouse, you must eventually "let go" of the knob in order for Piano to send any MIDI message. Some modules use AfterTouch and Channel Pressure to affect the Brightness of the sound (ie, Filter cutoff), or Volume, or some other such parameter. Normally, AfterTouch and Channel Pressure are generated by pressing harder and softer on the piano keyboard while you're holding down a note. Obviously, your computer's keyboard doesn't generate AfterTouch and Channel Pressure. If you press down harder, you'll only break it. So, when you release notes after having adjusted the AfterTouch or Pressure sliders, you may wish to click on the respective default arrow to turn the effect off (which is what would happen as you released the keys on a real controller). If you're adjusting the AfterTouch slider, you should only play one note at a time, and reset AfterTouch to default upon releasing each note, since AfterTouch only works on the last key that you've played (ie, Piano doesn't fully implement Aftertouch). The Reset button also resets AfterTouch and Channel Pressure (as well as the other sliders). ═══ 7.4. Controls ═══ What follows is a description of the controls in the Piano window; what they control, and additional notes about any MIDI information that they send. ═══ 7.4.1. Program ═══ Affects Which one of its Patches, Presets, or Instruments the MIDI module will play. If the module is a MultiTimbral unit, then it usually can play 16 "Parts" at once, each receiving data upon its own MIDI channel. This changes all Parts (which are set to one of the selected MIDI channels) to use that one chosen GM Patch. Note: If a module's Part receives a Program Change message on the channel to which it is assigned, then its Patch will change to the program number embedded in that message. For example, assume that a Part is set to MIDI channel 1, and its Patch is set to Grand Piano. If a Program Change message with a program number of 41 is sent on MIDI channel 1, then the Part will switch to the Violin (ie, which is GM Patch #41). A Program Change can be sent while the Part is playing -- even while the Part is playing some Grand Piano notes. The Part will simply play subsequent MIDI notes using the new Patch. Range One of the 128 GM Patches. You pick out which one from the list box (by clicking on it), or type in the desired Patch name and press the ENTER key. If you prefer to deal with numbers, especially if you're dealing with a non-GM MIDI device, you can instead type in the desired Patch number (where 1 is the first Patch) and press the ENTER key. In this case, Piano will always display the respective GM Patch name. If you type in the Patch name, you may enter only as many characters as are needed for Piano to find a matching name. For example, if you type "Gran" (or "Piano") and press ENTER, then Piano will match this as "Grand Piano". If you type "harp" and press ENTER, Piano will match this with "Harpsichord" (since that comes before "Harp"). Holding the Ctrl key while pressing the p key on your computer keyboard is a shortcut for clicking upon the Program control to change it. Note: It doesn't matter whether you type the name in upper or lower case. ═══ 7.4.2. Pan ═══ Affects Where within the stereo field the module will be placed. If the module is a MultiTimbral unit, then each one of its Parts usually has its own pan position. This changes the pan of all Parts assigned to one of the selected MIDI channels. Note: If the Part receives a Pan Controller message on the channel to which it is assigned, then its pan will change to the value embedded in that message. For example, assume that a Part is set to MIDI channel 1, and is panned hard left. If a Pan Controller message with a value of 64 (ie, center) is sent on MIDI channel 1, then the Part's sound will switch to center position. A Pan Controller can be sent while the Part is playing -- even while the Part is playing some notes. The Part will simply play with a new pan position. Range 128 possible positions, with 0 being hard left, 64 being center, and 127 being hard right. You must center the slider's knob for center pan (ie, where the default arrow is), and moving the knob to the left or right pans in those directions respectively. (This is the coarse controller for Pan). ═══ 7.4.3. Chorus ═══ Affects The chorus effect amount (ie, level) for the module. If the module is a MultiTimbral unit, then each one of its Parts usually has its own chorus level. This changes the chorus level of all Parts assigned to one of the selected MIDI channels. Note: If the Part receives a Chorus Controller message on the channel to which it is assigned, then its Chorus Level will change to the value embedded in that message. For example, assume that a Part is set to MIDI channel 1, and has a Chorus Level of 64. If a Chorus Controller message with a value of 0 is sent on MIDI channel 1, then the Part will switch to having no chorus (ie, chorus level=0). A Chorus Controller can be sent while the Part is playing -- even while the Part is playing some notes. The Part will simply play with a new chorus effect level. Range 0 to 127, with 0 being no chorus effect applied at all. Moving the fader all the way to the left gives a chorus level of 0. ═══ 7.4.4. Volume ═══ Affects The MIDI module's volume. If the module is a MultiTimbral unit, then each one of its Parts usually has its own volume. This changes the volumes of all Parts assigned to one of the selected MIDI channels. Note: If a Part receives a Volume Controller message on the channel to which it is assigned, then its Volume will change to the value embedded in that message. For example, assume that a Part is set to MIDI channel 1, and has a Volume of 127. If a Volume Controller message with a value of 64 is sent on MIDI channel 1, then the Part's volume will drop by half. A Volume Controller can be sent while the Part is playing -- even while the Part is playing some notes. The Part will simply play with a new Volume. Range 0 to 127, with 0 being no volume at all. Moving the fader all the way to the left gives a volume of 0. (This is the coarse controller for volume). ═══ 7.4.5. MOD Wheel ═══ Affects Sends MOD Wheel messages to the MIDI module. If the module is a MultiTimbral unit, then each one of its Parts may respond differently (or not at all) to MOD Wheel. This sends a MOD Wheel message to all Parts assigned to one of the selected MIDI channels. Note: If a Part receives a MOD Wheel Controller message on the channel to which it is assigned, then it may or may not do something depending upon how the Part is set to respond to this message. Usually, MOD Wheel introduces some sort of vibrato effect. For example, assume that a Part is set to MIDI channel 1. If a MOD Wheel Controller message with a value of 64 is sent on MIDI channel 1, then a medium vibrato effect may be applied to the Part's sound. A MOD Wheel Controller can be sent while the Part is playing -- even while the Part is playing some notes. A vibrato effect will simply be applied to any sounding notes. Range 0 to 127, with 0 being no modulation. (This is the coarse controller for MOD wheel). ═══ 7.4.6. Pitch Wheel ═══ Affects Sends Pitch Wheel messages to the MIDI module. If the module is a MultiTimbral unit, then each one of its Parts may or may not respond to Pitch Wheel. This sends a Pitch Wheel message to all Parts assigned to one of the selected MIDI channels. Note: If a Part receives a Pitch Wheel message on the channel to which it is assigned, then it may or may shift its pitch up/down depending upon whether the Part is set to respond to this message. A value of 64 (MSB only) is centered pitch, and values below that shift the pitch downward, whereas values above shift the pitch upward. For example, assume that a Part is set to MIDI channel 1. If a Pitch Wheel message with a value of 95 (MSB only) is sent on MIDI channel 1, then the pitch shifts upward. A Pitch Wheel can be sent while the Part is playing -- even while the Part is playing some notes. The pitch will simply shift accordingly. Range 0 to 127, with 64 being no pitch shift (ie, center position). Note: Piano only sends the MSB of Pitch Wheel. In other words, its a coarse adjustment only. ═══ 7.4.7. Pressure ═══ Affects Sends Channel Pressure messages to the MIDI module. If the module is a MultiTimbral unit, then each one of its Parts may respond differently (or not at all) to Channel Pressure. This sends a Channel Pressure message to all Parts assigned to one of the selected MIDI channels. Note: If a Part receives a Channel Pressure message on the channel to which it is assigned, then it may or may not do something depending upon how the Part is set to respond to this message. Usually, Channel Pressure adjusts the brightness (ie, filter cutoff), the volume, and/or introduces some sort of vibrato effect. For example, assume that a Part is set to MIDI channel 1. If a Channel Pressure message with a value of 64 is sent on MIDI channel 1, then a medium vibrato effect may be applied to the Part's sound. Channel Pressure can be sent while the Part is playing -- even while the Part is playing some notes. Some effect will simply be applied to any sounding notes. Indeed, Channel Pressure is usually generated by pressing harder or softer on the keys while holding them down (ie, so you are playing some notes). So, Channel Pressure is meant to affect sounding notes in some way. Range 0 to 127, with 0 being no channel pressure (ie, off). ═══ 7.4.8. AfterTouch ═══ Affects Sends AfterTouch messages (sometimes referred to as Key Pressure) to the MIDI module. If the module is a MultiTimbral unit, then each one of its Parts may respond differently (or not at all) to these messages. This sends an AfterTouch message to all Parts assigned to one of the selected MIDI channels. Note: If a Part receives an AfterTouch message on the channel to which it is assigned, then it may or may not do something depending upon how the Part is set to respond to this message. Usually, AfterTouch adjusts the brightness (ie, filter cutoff), the volume, and/or introduces some sort of vibrato effect. For example, assume that a Part is set to MIDI channel 1. If an AfterTouch message with a value of 64 is sent on MIDI channel 1, then a medium vibrato effect may be applied one of the Part's sounding notes. AfterTouch can be sent while the Part is playing -- even while the Part is playing some notes. Some effect will simply be applied to the note corresponding to the message. Indeed, AfterTouch is usually generated by pressing harder or softer on a key while holding it down (ie, so you are playing a note). So, AfterTouch is meant to affect a sounding note in some way. What's the difference between AfterTouch and Channel Pressure? Well, AfterTouch messages are for individual keys. Every key that you press down generates its own AfterTouch messages. If you press on one key harder than another, then the one key will generate AfterTouch messages with higher values than the other key. The net result is that some effect will be applied to the one key more than the other key. You have individual control over each key that you play. With Channel Pressure, one message is sent out for the entire keyboard. So, if you press one key harder than another, the module will average out the difference, and then just pretend that you're pressing both keys with the exact same pressure. The net result is that some effect gets applied to all sounding keys evenly. You don't have individual control per each key. A controller would use either Channel Pressure or AfterTouch, but usually not both. Most MIDI controllers don't generate AfterTouch because the circuitry required is a bit too costly. Piano's QWERTY keyboard is no exception. (Hey, you got it free. What do you expect?). It only generates AfterTouch messages for the last key that you play. If you play a chord, only one of the notes gets the AfterTouch effect when you move the slider (ie, the last one that you pressed down). Ideally, there should be AfterTouch messages happening for each key being held down, but that's irrelevant here because your computer keyboard doesn't have some way of detecting pressure for each key, and it would be impractical to be adjusting an AfterTouch slider for every key that you hold down. You should avoid playing chords while adjusting the AfterTouch slider. If you do, you may need to Reset in order to clear aftertouch from all of the keys that you played. Range 0 to 127, with 0 being no aftertouch (ie, off). ═══ 7.4.9. Effect ═══ Affects This slider can be set to emulate any one of the 128 possible MIDI controllers. By default, it emulates the effects level for the module. If the module is a MultiTimbral unit, then each one of its Parts usually has its own effects level. This changes the effects level of all Parts assigned to one of the selected MIDI channels. Various MIDI devices may respond to effects controller differently (if at all). Some Roland devices with a built-in reverb unit, use Effects controller to set the reverb amount. Note: If the Part receives a MIDI Effects Controller message on the channel to which it is assigned, and the device uses that to adjust reverb amount, then its Reverb Level will change to the value embedded in that message. For example, assume that a Part is set to MIDI channel 1, and has a Reverb Level of 64. If an Effects Controller message with a value of 0 is sent on MIDI channel 1, then the Part will switch to having no reverb (ie, reverb level=0). An Effects Controller can be sent while the Part is playing -- even while the Part is playing some notes. The Part will simply play with a new reverb level. When you select a new controller for the Effect slider, this new controller is initially set to whatever value the slider is set to (ie, if the slider is all of the way to the right, then the controller's value is set to 127). Range 0 to 127, with 0 being no effects applied at all. Moving the fader all the way to the left gives an effects level of 0. ═══ 7.4.10. All Notes Off ═══ Affects This button sends Note Off messages to the MIDI module for any notes that Piano thinks are still "on". Due to the way that Presentation Manager works, it's possible for Piano to not "see" a mouse button up message (ie, some other app may get it). Clicking on this button forces Piano to turn off all notes that it played and didn't turn off even though you may no longer be pressing the mouse button over the graphical piano, or holding down a key on the computer. Piano also sends All Notes Off Controller and All Sound Off Controller messages on the MIDI channels that you have selected, as an extra precaution to turn off any "stuck notes". See the remarks about such in the Reset description. ═══ 7.4.11. Reset ═══ Affects This is a more drastic reset than the All Notes Off button. The latter button only turns off notes. This button also resets various controllers to default values, and resets the Program on the MIDI channels that you have selected. This button sends All Notes Off Controller, All Sound Off Controller, and Reset Controllers messages on all 16 MIDI channels. Note that some older or cheap MIDI gear does not implement some of these special controller messages. (ie, On some gear, you have to send an individual MIDI Note Off message for each note that you wish turned off. This is an archaic and slow way of turning off "stuck notes". Piano doesn't bother with that. Likewise, some gear doesn't implement Reset Controllers, and wants individual controller messages for each controller that you wish to reset. Piano does initialize the MIDI parameters associated with the 8 sliders (ie, Volume, MOD, PITCH, etc) as well as the Mouse 2 and Mouse 3 controllers regardless of whether a device understands the Reset Controllers message, but other controllers may not be reset. You'll have to reset those manually. Piano resets the sliders to default values, and turns off the controllers for Mouse 2 and Mouse 3. Finally, this button causes the Program to be changed on all of the selected MIDI channels, to that program displayed in Piano's Program control. ═══ 7.4.12. Octave ═══ Affects The note range that the QWERTY piano (and graphical piano) plays back. In other words, this transposes Piano's note range an octave at a time. Note: The QWERTY keyboard counts its octaves from 1. Most MIDI devices count their octaves from -2. What this means is that, to play a middle C (MIDI note number 60), set Octave to 4 and play the z key (ie, a C note) or click on the leftmost C of the graphical piano. Holding the Ctrl key while pressing the o key on your computer keyboard is a shortcut for clicking upon the Octave control to change it. ═══ 7.4.13. Mouse 2 ═══ Affects The controller that is sent (on the selected MIDI channels) every time that you press and release mouse button 2. You can choose any one of the possible 128 MIDI Controllers. 48 of these 128 Controllers are defined for specific purposes, and have "names". If you drop down the list box for Mouse 2, you'll see those defined controller names. You can choose one of these (by clicking on the name, or typing the name), or you can type in the desired controller number (from 0 to 127 decimal). If you type in the Controller name, you may enter only as many characters as are needed for Piano to find a matching name. For example, if you type "Por" and press ENTER, then Piano will match this as "Porta" (ie, Portamento On/Off). If you type "Mod" and press ENTER, Piano will match this with "Mod H" (since that comes before "Mod L"). It doesn't matter whether you type the name in upper or lower case. When you select a new controller for Mouse 2, this new controller is initially set to 0 (ie, turned off). Holding the Ctrl key while pressing the 2 key on your computer keyboard is a shortcut for clicking upon the Mouse 2 control to change it. Note: Consult my OS/2 online book, "The MIDI Book" for descriptions of all the defined MIDI controllers. ═══ 7.4.14. Mouse 3 ═══ Affects The controller that is sent (on the selected MIDI channels) every time that you press mouse button 3. You can choose any one of the possible 128 MIDI Controllers. 48 of these 128 Controllers are defined for specific purposes, and have "names". If you drop down the list box for Mouse 3, you'll see those defined controller names. You can choose one of these (by clicking on the name, or typing the name), or you can type in the desired controller number (from 0 to 127 decimal). If you type in the Controller name, you may enter only as many characters as are needed for Piano to find a matching name. For example, if you type "Por" and press ENTER, then Piano will match this as "Porta" (ie, Portamento On/Off). If you type "Mod" and press ENTER, Piano will match this with "Mod H" (since that comes before "Mod L"). It doesn't matter whether you type the name in upper or lower case. When you select a new controller for Mouse 3, this new controller is initially set to 0 (ie, turned off). Holding the Ctrl key while pressing the 3 key on your computer keyboard is a shortcut for clicking upon the Mouse 3 control to change it. Note: Consult my OS/2 online book, "The MIDI Book" for descriptions of all the defined MIDI controllers. ═══ 7.4.15. Port ═══ Affects The driver (and therefore MIDI interface card) that Piano outputs MIDI messages through. If you drop down the list box for Port, you'll see that the 4 available ports of MPUDEV.SYS are listed. You can choose one of these (by clicking on the name, or typing the name), or you can type in some other driver name. If you have not disabled Driver Initialization (ie, not specified the /I option) then Piano will attempt to initialize the driver/hardware via the protocol used by my MPUDEV.SYS driver. If you have not disabled turning on GM mode (ie, not specified the /G option) then Piano will attempt to kick the module into General MIDI mode. Holding the Ctrl key while pressing the t key on your computer keyboard is a shortcut for clicking upon the Port control to change it. Note: If the port that you specify can't be opened, Piano will retain the previously opened port for MIDI output. ═══ 7.4.16. Initialize ═══ Affects Initialization of the MIDI driver that Piano outputs MIDI messages through. If you check the Initialize box, then Piano assumes that, everytime a driver is opened, Piano needs to reset the driver and card using a protocol that my MPUDEV.SYS driver establishes. If you aren't using an MPUDEV compatible driver, or don't want the driver and card to be reset whenever a driver is opened, you should turn Initialize off. Holding the Ctrl key while pressing the i key on your computer keyboard is a shortcut for selecting the Initialize checkbox, and then pressing the SPACE BAR toggles it on/off. ═══ 7.4.17. GM Enable ═══ Affects Initialization of a GM MIDI sound module attached to Piano's Port. Whenever you check the GM Enable box, then Piano issues a System Exclusive command to set a sound module into General MIDI mode. (ie, You can force Piano to send this message by turning the check off, and then turning it back on again). If this box is checked when you select a new Port, then Piano sends the GM message out that new Port. Holding the Ctrl key while pressing the g key on your computer keyboard is a shortcut for selecting the GM Enable checkbox, and then pressing the SPACE BAR toggles it on/off. ═══ 8. Driver Sharing ═══ Piano allows shared access to a driver. (ie, Another program may output MIDI data to, or read MIDI data from, that driver while Piano is running, and even while using Piano to play the module). Piano doesn't input any MIDI data, and therefore should not cause a problem for any program that only reads from the same driver (ie, doesn't write to it), nor will that program cause a problem for Piano, Shared MIDI output is usually fine, since when programs are "sitting idle", they usually aren't writing to the driver. So, it's generally OK to simultaneously run two programs that do MIDI output to the same driver, as long as both programs aren't performing such operations simultaneously (ie, one program is "sitting idle" while the other is performing an operation that causes MIDI data to be output). Piano sits idle when you are not actually moving its sliders, pushing its buttons, playing notes, or operating any controls in it. It may even be possible for both programs to simultaneously output MIDI data to the same driver. But both programs need to DosWrite() full MIDI messages to the driver (ie, not break up one MIDI message into several calls to DosWrite()). If a program doesn't conform to this restriction, then its MIDI output may be destroyed by another program attempting to output MIDI data simultaneously. (Of course, even if the two programs conform to this restriction, and therefore, their MIDI data can be successfully "merged", this merge process will slow down the operations of each program, and may cause each program to experience significantly longer delays in MIDI output than if both programs weren't simultaneously outputting MIDI data). Piano fully conforms to this restriction and therefore, performing a MIDI output with some other program that uses the same driver should be OK. You may have to avoid using Piano while the other program is outputting data, if that program also doesn't conform to the restriction. But Piano may be left running while using other programs that access the same driver. Some drivers, such as MPUDEV, support several independent "ports" (ie, each port has its own MIDI hardware interface card), and each port has its own SHARED status. Therefore, it's perfectly acceptable to have two programs running which both use MPUDEV simultaneously, and you won't have to worry about any of the above sharing conditions as long as each program uses a different port. ═══ 9. Error Messages ═══ Here are the possible error messages that you may see. Following each message is a description of likely causes for that error and possible remedies, and what happens as a result of that error (ie, does the program terminate, or stop transmission, or what?). An error message is displayed in a message box that pops up and suspends the operation of the program until you dismiss that message box. Piano returns non-zero error values only if it encounters a problem upon startup. Otherwise, once Piano is up and running, it will return 0 (ie, successful operation) when it terminates. ═══ 9.1. Initialization failed! ═══ Synopsis Piano wasn't able to complete some initialization associated with Presentation Manager. Cause OS/2 couldn't start up another PM program. Cure Close down other running apps as you may have run out of PM resources, or shut down OS/2 itself, and try running Piano again. Error occurs Only during program startup. Result Piano terminates returning RC = -1. ═══ 9.2. Can't load Exit handler! ═══ Synopsis Piano wasn't able to complete some initialization associated with Presentation Manager. Cause OS/2 couldn't install an Exit List handler. Cure Close down other running apps as you may have run out of PM resources, or shut down OS/2 itself, and try running Piano again. Error occurs Only during program startup. Result Piano terminates returning RC = -2. ═══ 9.3. Can't create window! ═══ Synopsis Piano wasn't able to open its Presentation Manager window. Cause OS/2 couldn't create a PM window of the requested class. Cure Close down other running apps as you may have run out of PM resources or there may be a conflict in window classes, or shut down OS/2 itself, and try running Piano again. Error occurs Only during program startup. Result Piano terminates returning RC = -3. ═══ 9.4. Can't open MIDI driver! ═══ Synopsis This error means that the requested driver did not open, and therefore Piano can't do any MIDI output. Cause Some other program already has this driver open and has denied any other program access to it (ie, no Shared access). When a program opens a driver for reading or writing, it may decide to restrict any other program from reading and/or writing to that driver. Subsequent programs will not be allowed to open (and use) that driver while the preceding program is running. Cure There's nothing you can do other than to terminate the program that is refusing to share the driver. If in doubt as to which program that is, terminate all other programs using this driver, and try Piano again. See Driver Sharing for more information about this problem. Cause The driver isn't installed properly with an entry in your config.sys file. Cure Check that entry in your config.sys file. Cause The name you supplied is not the true, internal name of the driver. Every driver has an ascii string embedded inside of it, which is its real name as far as OS/2 is concerned. This might not be the same as the driver's filename. Usually, it is the filename minus the .SYS extension. Cure Contact the author of the driver and verify the driver's name for a DosOpen(). Or use my LISTDRVS.CMD REXX script (included with File REXX) to display a listing of the internal names of all installed drivers, and pick out what you think is the real name of that driver. Error occurs During program startup, or whenever you change the driver Port. Result If the error happens during program startup, Piano terminates returning RC = -4. Otherwise, Piano retains the previously opened driver for its MIDI output. ═══ 9.5. Error with MIDI driver command! ═══ Synopsis The driver returned an error when Piano issued the Reset Command via the driver's IoCtl interface. My MPUDEV.SYS driver uses this scheme to set an MPU-401 into Uart mode. That's what Piano needs to do when using an MPU-401. So, I do it this way. Cause If you're not using an MPU-401 or compatible MIDI interface, then it probably doesn't need to be set like this, its driver will probably not recognize what Piano is telling it to do, and you'll see the error message. Cure Specify the /I option when running Piano, or disable Initialize. This tells Piano that you don't want it to try to reset the MIDI interface using my MPUDEV driver's procedure. For example, if you had a driver named BLORT, and you didn't want it reset, here's what you might type as arguments when running the program (or type into the Parameters field of the Desktop icon) BLORT /I Error occurs During program startup, or whenever you change the driver Port and allow Piano to initialize the driver. Result Piano doesn't regard this as a real error. It's essentially ignored except for displaying the message.