
M F P L A Y
MIDI File Player
Version 1.3
Freeware
Copyright (C) 1997-2020 by Mark A. Fontana


MFPLAY is a Standard MIDI File player for IBM-compatible computers
running MSDOS.  While not as glamourous as other MIDI players (e.g.
MegaMID, Cubic Player), MFPLAY is highly configurable and includes
special features for use in live performance situations.  It is
designed to appeal to the "power user" class of MIDI enthusiast.

Feature summary:

   - User-defined device definition files; configurations for popular
     XG/GS/GM MIDI devices are included
   - Devices may be reset with a user-defined sequence before playing
     each file
   - Playback starts immediately; no preprocessing delay
   - Karaoke lyric display
   - Shuffle play, sort by date/time, and alphabetized modes
   - Fast-forward, skip ahead, and back up during playback
   - Ability to change patches during playback and save those changes
     into the MIDI file
   - Playlist selection screen provides quick access to any file in the
     playlist during playback, showing both filenames and song titles
   - Ability to add title, copyright, and other text information to
     the file during playback
   - Supports nine popular MIDI interfaces
   - Built-in omni mode and event filter for playing MIDI files on
     less-sophisticated MIDI devices (digital piano, etc.)
   - Onscreen display of all notes on all channels
   - Piano keyboard display
   - Scrolling music roll display
   - Smooth tempo adjustment via the pitch bend control makes it easy
     to follow live performers
   - Program can be controlled by MIDI note/controller/patch change
     events from an external keyboard
   - Soft MIDI thru from external keyboard to any MIDI output port
   - MIDI files may be easily moved, renamed, or copied during playback
   - Flexible command line/script file format; wildcards & directory
     recursion supported
   - Elapsed time and bar graph show position in current file
   - Onscreen display of embedded Sound Canvas graphics and text messages
   - Uses textmode display; quick, compact, and fast
   - Panic button kills hung/stuck notes and resets controllers
   - Tempo, velocity, transposition adjustable during playback
   - Muting of individual MIDI channels on individual output ports
   - Plays type 0/1/2 standard MIDI files with up to 256 tracks   
   - Four main configurations may be defined and easily selected
     during playback
   - Runs on any IBM compatible machine... 8086->Pentium
   - Freeware

MIDI interfaces supported:

   Roland MPU401-compatible interfaces (UART mode)
   Midiman PC/S (serial port)
   Midiman PC/P (parallel port)
   MusicQuest parallel port interfaces
   Serial port MIDI (Roland SC-88, Miracle Piano, and others)
   Key Midiator (serial port)
   Soundblaster (and compatibles) MIDI port/daughterboard
   ProAudio Spectrum MIDI port
   Gravis Ultrasound MIDI port

IMPORTANT:

MFPLAY requires a MIDI interface and at least one MIDI device (most
soundcard daughterboards are MIDI devices).  It will NOT play music
on a plain PC soundcard using the FM synthesizer or digital audio
capabilities.  (You might be able to use MFPLAY with such a soundcard
by running a software driver program such as MegaEm on the GUS or
AWEUTIL on the Soundblaster AWE32.)

COMPUTER requirements:

MFPLAY should run on any IBM compatible PC, even old PC and XT machines.
(If you're using a machine this old, see the DISPLAY_TYPE and OLD_PC lines
in MFPLAY.CFG.)  Some MFPLAY features will not run acceptably on less
than a 486-based PC.  For best results, I recommend a 486dx2/66 or better
CPU under MSDOS 6.0 or later.  MFPLAY uses only conventional memory
(256k of free memory is recommended).  The program can be run using only
80x25 textmode, and it should work on any display adapter.  Some optional
features require a VGA card.

MFPLAY is designed to be run under plain MSDOS (or in the MSDOS mode of
Windows 3.1 or Windows 95).  One of my goals in writing MFPLAY was to
create a small, standalone MIDI player that would run on pretty much any
IBM-compatible machine.  A Windows version is not planned at this time.

MFPLAY will not run under Windows NT or later versions of Windows because
these versions will not permit MFPLAY to directly access hardware I/O ports.


SETTING UP MFPLAY ----------------------------------------------------------

  1. Copy MFPLAY.EXE, MFPLAY.CFG, and the included ".dev" files into a
     directory together.

  2. Look through the .dev files with a textfile viewer and find the
     ones that match the MIDI sound modules you want to use.  If you are
     using a Roland GS-compatible device, read through the file "gs.txt"
     to see which of the GS files is appropriate for your device.
     If you have a device for which no .dev file is suitable, you can
     create your own by modifying one of the existing ones.  See the file 
     "template.dev" for details on creating .dev files.  (If you create a
     new .dev file and you're confident it is accurate, please send it
     to me by email and I'll include it in the next release of MFPLAY.
     Be sure to document the device it supports and note any equivalent
     devices that your .dev file may also cover, if you know.)

  3. Edit MFPLAY.CFG with a text editor and configure the "MIDI_PORTS"
     and "MIDI_DEVICES" settings.  (There are four of each; MFPLAY
     allows four independent configurations.  You must define at least
     one configuration.)  In MIDI_PORTS, you'll define the MIDI
     interfaces for a given configuration, and in MIDI_DEVICES, you'll
     list the corresponding .dev files for those MIDI ports.  Thus,
     each physical MIDI output of your PC will have a corresponding
     .dev file associated with it.

  4. Read the notes in MFPLAY.CFG for your MIDI interfaces and make
     sure the required conditions are satisfied and the appropriate
     parameters have been correctly set.  (BLASTER environment variable
     set for Soundblaster, address and IRQ specified for MPU401, etc.)

  5. Adjust the other parameters in MFPLAY.CFG as you prefer.

  6. I recommend that you read the rest of this documentation before
     trying to use MFPLAY.

You can remove the comment lines or any parts of MFPLAY.CFG that don't
apply to your system configuration.  But I recommend that you keep a backup
copy of the original file around in case you need to use the parameters
later on.  You do not need to comment out unused parameters.


COMMAND LINE OPTIONS AND SPECIFYING FILES TO PLAY --------------------------

MFPLAY has a simple but flexible syntax for specifying files to play.
Basically, it expects a sequence of parameters on the command line 
in the form:
               [options] [filespec] [options] [filespec] ...

Filespecs may contain the wildcards * and ?, and files are not assumed to
have an extension of .MID.  If you specify the option "REC" before a 
filespec, MFPLAY will recurse into the filespec's subdirectories, adding
all matching files.  Examples:

	      MFPLAY rec c:\midi\*.mid

     Play all files matching "*.mid" in c:\midi and its subdirectories.

              MFPLAY rec c:\midi\foo.mid

     Play all files called "foo.mid" in c:\midi and its subdirectories.

You can also use the "FIND string" command line option to select files
based on matching text information embedded in the files.  Up to five
FIND options are allowed per filespec.  Files are added only if one or
more of the FIND strings match.  Any underscores ('_') in a search
string are treated as spaces.  Example:

           MFPLAY find Scott_Joplin find Fats_Waller f*.mid

     This would play all MIDI files that have a filename beginning 
     with "f" and which contain the strings "Scott Joplin" or
     "Fats Waller".
     
MFPLAY supports type 0, 1, and 2 standard MIDI files containing up to 256
tracks.  (In the case of type 2 (multi-song) MIDI files, the TRACK option
(described below) specifies which song to play.  If you don't specify a
track, MFPLAY will play each of the songs in the type 2 file in order,
starting with song number 1.)  You can also specify .SYX (SYSEX) files in
filespecs, causing MFPLAY to transmit the contents of these files at the
appropriate points in the playlist.  (SYSEX files must have the extension
".SYX" so that MFPLAY will know not to process them as MIDI files.)
  
The options preceding a filespec are applied ONLY to the files included
by that filespec.  That is, if you specify several different filenames,
MFPLAY only considers the options that you place right before a particular
filename.  Before each group of options is processed, MFPLAY restores
the default configuration.  Example:

      MFPLAY seconds 5 dir1\*.mid pause dir2\myfile.mid
             ^^^^^^^^^ ^^^^^^^^^^ ^^^^^ ^^^^^^^^^^^^^^^
             option    filespec   option   filespec 
            
This command line would instruct MFPLAY to play the first 5 seconds of
all MIDI files in directory dir1, then play "myfile.mid" in directory 
dir2, pausing before starting playback.  The "seconds 5" command only
applies to the files in dir1, and the "pause" command only applies to
the file "dir2\myfile.mid".

Here are the options you can specify to MFPLAY.  These will override the
default options in MFPLAY.CFG when applicable.  Options followed by an 'n'
accept a single argument, and there must be a space between the command
and its argument.  (You can get a quick summary of these options by
running MFPLAY with no arguments.)

   NORESET  Don't reset the MIDI device before playback.
     CFG n  Use MIDI configuration n, where n is 1 2 3 or 4.  MIDI
            configurations are defined in the MIDI_PORTS and MIDI_DEVICES
            lines of MFPLAY.CFG.
 SECONDS n  Play only the first n seconds of each MIDI file.
   TEMPO n  Play the MIDI file at n percent of the original tempo,
            where n is an integer between 1 and 1000 (n < 100 is slower,
            n = 100 is normal speed, n > 100 is faster).  MFPLAY will limit
            the resulting tempos to between 1 and 300 BPM.
   TRANS n  Transpose the music by n half steps, where n = -48 to 48.
            (Notes on drum channels will NOT be transposed.)
     VEL n  Adjust the velocities (volume) of all notes in the MIDI file
            by adding n, where n is an integer from -64 to 64.
   TRACK n  Play only track number n of a multitrack (type 1 or type 2)
            MIDI file.  (Tracks are numbered starting with 1.)
  	    You can also specify "ALL" instead of a number; this will play
            all of the tracks in the file one at a time, in order.
     KEYBD  Use piano keyboard display mode
     NOTES  Use note/channel display mode
      ROLL  Use music roll display mode (DISPLAY must be "VGA32" in 
            MFPLAY.CFG to use this option)
    NODISP  Do not show a note display during playback.
     PAUSE  Start MFPLAY in paused mode.
    PAUSE0  Start MFPLAY in paused mode AFTER playing tick 0 events
            (useful in live performance to set patches, send SYSEXes, etc.
            before starting the actual song).
 MUTE args  Mute ports/channels: args is a comma-separated list with
            no spaces of entries of the form "p:c" or "c" where
            p = port (0,1,2..) and c = chan (1..16).  * is allowed.
  FIND str  Match only MIDI files containing "str".  Up to 5 FIND options
            will be OR'd for each filespec.  (For each file, if *any* string
            matches, the file will be added to the playlist.)  _Underscores_
            in the string will be treated as spaces.
   DELAY n  Pause for n seconds between MIDI files.
    REPEAT  Repeat each MIDI file until told to quit or to move to the
            next/previous file.
       REC  Recurse into a filespec, adding all matching files.
   SHOWCFG  Show a summary of MIDI interfaces, MIDI devices, and logical
            output ports before starting playback.
    THRUON  Enable soft MIDI thru for external keyboard.
   THRURAW  Same as THRUON, but *all* events are routed thru- including
            events with MFPLAY functions assigned to them.
   THRUOFF  Disable soft MIDI thru for external keyboard").
THRUPORT n  Route MIDI thru events to port n when no channel is selected.
 @filename  Read filespecs/options from textfile "filename".
            The filespecs and/or options in this file will be processed
            just as if you had specified them at this point on the command
            line.  (Note: You cannot nest this command.)

*** The following options, if specified, will affect ALL files on the ***
*** command line.  The position of the option does not matter.        ***

     LOOP  Repeat the entire playlist until told to quit.
   NOQUIT  Disable keyboard input during playback; playback cannot
           be aborted.
   TITLES  Display titles on the hotkey file selection screen.
 NOTITLES  Don't display titles on the hotkey file selection screen.
    ALPHA  Alphabetize the list of MIDI files before playback
	   (ascending order).
   BYTIME  Sort the list of MIDI files by time before playback
	   (most recent first).
  SHUFFLE  Shuffle the list of MIDI files before playback.
   NOSORT  Do not sort the playlist.
  RUNSTAT  Use running status compression.
NORUNSTAT  Don't use running status compression.

Naturally, you should only specify one of ALPHA, BYTIME, or SHUFFLE, since
each of these options reorders the playlist!


DURING PLAYBACK ------------------------------------------------------------

During playback, the following keys provide special functions.  Note that
pressing CTRL with certain keys will provide a faster way of making the
adjustment.  (The exact effects are described below.)

              PLAYBACK CONTROL COMMANDS

       SPACE  Pause/resume
           !  Panic button; turn off all notes and reset controllers
              without stopping playback.  (Useful when notes get stuck)
           F  Fast forward (half volume, 2x normal speed)
              Press CTRL-F for faster fast-forwarding (4x normal speed)
	   J  Jump forward by 10 seconds
           B  Jump backward by 10 seconds (takes slightly longer, since
              a seek from the beginning is required)
          Up  Increase velocity of all notes on all channels (volume +)
        Down  Decrease velocity of all notes on all channels (volume -)
        PgUp  Transpose up by 1 half step
              Press CTRL-PgUp to transpose up by one octave (12 half steps)
        PgDn  Transpose down by 1 half step
              Press CTRL-PgDn to transpose down by one octave (12 half steps)
           +  Increase tempo by 1% of original tempo
              Press CTRL- + to increase tempo by 10% of original tempo
           -  Decrease tempo by 1% of original tempo
              Press CTRL- - to decrease tempo by 10% of original tempo
           O  Restore original patches, tempo, key, and velocity
           P  Toggle playback between automatic and manually-pumped mode
              (see explanation of manually-pumped mode below)
           E  Toggle expression between automatic and manual modes. 
              In automatic mode, the velocities of the notes are played
              according to the values in the MIDI file.  In manual mode,
              the velocities will be 64 + MFPLAY's velocity offset setting,
              allowing you to control the expression yourself using an
              external MIDI keyboard.
        Home  Restart the current file from the beginning
              (Ctrl-Home will also work)
      Ctrl-S  If you've specified a maximum number of seconds to play for
              each file (giving an "intro scan" effect) pressing Ctrl-S
              before the time elapses will remove the time restriction
              so that the rest of the file will play.
Ctrl-Up/Down  Select channel (for changing patches, muting, or MIDI thru)
         [ ]  Change patch on selected channel.
      Ctrl-M  Mute selected channel.  If no channel is selected, the mute
              status of ALL channels will be toggled.  (The ENTER key will
              perform the same function.)
           |  Select soft MIDI thru option for an external controller.
       F1-F4  Select MIDI configuration 1, 2, 3, or 4 as defined in
              MFPLAY.CFG.

              PLAYLIST COMMANDS

           A  Alphabetize playlist (ascending order)
	      Press CTRL-A to alphabetize in descending order
           T  Sort files by time (descending order; most recent first)
              Press CTRL-T to sort by time in ascending order (oldest first)
           $  Shuffle the playlist and start at the first file in the
              reordered playlist.
        Left  Move to the previous file in the list
              Press CTRL-Left to jump to the first song in the playlist
       Right  Move to the next file in the list
              Press CTRL-Right to jump to the last song in the playlist
         Tab  Display file selection screen, a page-by-page menu of all the
              files in the playlist.  You can jump immediately to any file,
              and when you exit this page, the files associated with keys
              1..0 will remain in effect for you to use during playback.
              In this screen, the Home and End keys will make the display
              show the beginning and end of the playlist.
        1..0  Jump immediately to song number 1..10 in the file selection
              screen
    Alt-1..0  Jump immediately to song number 11..20 in the file selection
              screen (if more than 10 titles are being displayed)

              DISPLAY COMMANDS 

           D  Toggle note display mode between no note display, 
              note/channel display, piano keyboard display, and
              music roll display.  (The last two display modes require
              a VGA adapter and will not display properly when running
              in a window under Windows.  Also, music roll display mode
              requires that DISPLAY be set to "VGA32" in MFPLAY.CFG).
           N  Toggle patch display between patch names and patch numbers
              Patch numbers are displayed in the format "xxx: yyy zzz"
              where xxx is the patch number (0-127) and [yyy zzz] are the
              MSB (most significant byte) and LSB (least significant byte)
              of the bank select number.
           R  Toggle patch display between showing patches requested by
              the file and patches actually playing on your sound module.
         < >  Page up/down through the active MIDI ports for the current
              configuration (if MFPLAY has been configured to support
              multiple MIDI interfaces)

              MIDI FILE MANAGEMENT COMMANDS
	
           L  Label the current file by adding/editing title, copyright,
              and other information
           U  Update the current file on disk, saving any tempo,
              velocity, transposition, or changes in patch settings.
              Muted channels will be stripped when the file is rewritten.
           C  Copy the current file
           M  Move or rename the current file
         Del  Delete the current file

              MISC. COMMANDS
	 
         ?,H  Display help screens
  	   I  MFPLAY version/author information
           S  Show other settings (which tracks are playing, what reset
              mode is enabled, whether loop or repeat modes are active,
              the port number to which MIDI thru is routed)
      Ctrl-R  Toggle whether or not running status compression is used
              for MIDI output and when updating MIDI files on disk
         ESC  Exit MFPLAY

If the command line option NOQUIT is specified, MFPLAY will ignore all
of the above commands.

Note:  The "M" (move) command is great for sorting out a directory of
assorted MIDI files freshly downloaded from the net.  Using the "DIR"
parameters in MFPLAY.CFG, you can specify up to 12 target directories to
which you can quickly move/copy files while using MFPLAY.  This will
allow you to organize your files during playback with as few as two
keystrokes per file!


PATCH DISPLAY --------------------------------------------------------------

The patches currently playing are displayed on the left side of the
screen.  Note that the numbers 1-16 correspond to MIDI channels, not
tracks in the MIDI file (or Roland "parts").  If a patch entry is shown
in dim text, this indicates that either the patch is the default patch
assigned to that channel or that the patch was set using GS SYSEX messages
(which is nonstandard and not recommended).  Patches shown in bright text
were set using patch change messages in the MIDI file.

Between the MIDI channel numbers and patch entries, you will sometimes
see one of the symbols below.  These provide extra information about the
patch or channel and are similar to the notation used on Roland Sound
Canvas devices:

  * = Drum channel 
  + = Patch is a variation supported by your device (the bank select is
      something other than zero).  If no + is displayed, the displayed
      patchname is in bank 0; Roland calls this a "capital" patch.
  - = Patch shown is the patch to which your device automatically
      defaulted because the requested patch is not supported by
      your device
  ! = Patch shown is not available on your MIDI device (according to
      the .dev file for that device)


NOTE DISPLAY ---------------------------------------------------------------

To the right of the patch entry for each MIDI channel is a display of all
128 notes available on that channel.  Notes that are currently playing are
marked with a bar.  If you have a color display, you will see an
alternating pattern of light and dark columns in the background.  These
mark off the octaves; the leftmost note in a column corresponds to the
note of C.  (Due to hardware limitations, the octave bars will not be
visible on a monochrome display adapter.)

If you have a VGA adapter, MFPLAY will maintain a piano keyboard display
showing all 128 MIDI notes on all ports and channels (combined) as well as
the status of the soft, sostenuto and sustain pedals.

If you are playing a MIDI file with embedded bitmapped graphics, you will
see the 16x16 pixel graphics displayed in the background of the note
display.  Only certain Roland GS files contain these images.


TEXT WINDOW ----------------------------------------------------------------

The narrow window immediately below the note display is the text window.
It displays most of the printable text information in the MIDI file,
including song names, track names, copyright information, generic text
messages, and lyrics.  The text window will store and cycle through the
most important messages during playback.  Occasionally you will see the
text window cycling through unimportant data like instrument or patch
names; this happens because the software that created the MIDI file did
not conform to the standard uses of various text messages.  Blocks of
text larger than the window size will be displayed in chunks.

The text window will also display any Roland GS text messages in the
file (These events appear as a scrolling marquee display on an external
Sound Canvas module.  They will show as bright text in MFPLAY.).

KARAOKE LYRICS

If lyrics are present in a MIDI file, the text window will attempt to
display them in a karaoke-style manner, anticipating each phrase and
highlighting each syllable.  MFPLAY should do a reasonable job with
most MIDI files, as long as the lyrics use the normal printable ASCII
characters.  However, there doesn't seem to be much of a standard for
encoding lyrics in MIDI files, except for in certain commercially-
produced files.  To make matters worse, some files include multiple sets
of lyrics encoded in more than one format!  If you come across a file
that MFPLAY makes a total mess of, email it to me and I'll see what
I can do.

During playback of a MIDI file with lyrics, the text window will display
"(Introduction)" or "(Instrumental)" at the appropriate places in the
music where no lyrics are being sung.  After the last lyric is displayed,
the text window will cycle through any title or copyright information
for the song.


INFORMATION WINDOW ---------------------------------------------------------

Immediately below the text window is a 2-line window showing various bits
of information about MFPLAY's current state, including the filenames
for the next and previous files in the playlist, the number of the current
file, and the total number of files in the list.  Also shown are the 
current transposition, tempo offset, and velocity offset settings, the size
(in bytes) of the current MIDI file, and the maximum polyphony (number of
notes on simultaneously) of the current file.


MESSAGE WINDOW -------------------------------------------------------------

Located at the bottom right of the screen is a message window.  This window
displays various status information and provides feedback for some of the
commands available during playback.  It also notifies you of any SYSEX
messages embedded in MIDI files and identifies the type or manufacturer
of equipment for which they were intended.

During playback, the background of the message window will form a bar graph
growing from left to right.  This graph provides a visual display of how
much of the current file has been played.

When the message window is idle, it will display the full path and
filename of the file currently playing.


LABELING MIDI FILES --------------------------------------------------------

Pressing "L" during playback will permit you to edit title, copyright,
and other text information for the current file.  In order to make
changes, the original file must be on a writeable media (ie. not a CDROM).
When you have finished editing, save your changes by pressing F1 or F2.
Pressing F1 will add the new text information to the current file,
removing any previously existing information (all meta-trackname, meta-
text, and meta-copyright events on the first track).  If you wish to keep
previously existing information, press F2 and this information will
be left intact.

Technical notes:  Following convention, label information is stored at
the 0'th tick of the first track of the file.  The title string is stored
as a meta-trackname event, the copyright string is stored as a meta-
copyright event, and the other information strings are stored as meta-
text events.


UPDATING MIDI FILES --------------------------------------------------------

Pressing "U" during playback will cause MFPLAY to update the MIDI file on
disk with the current tempo, transposition, velocity, and patch change
settings.  (The file must be on a writable media, of course.)
The old version of the file will be overwritten.  You may wish to
create a working copy using the "C" command before modifying the
original file.

MFPLAY will strip away all events on channels that are muted when
you update the file.  (A warning will be displayed to remind you of this
and prevent you from accidentally removing channels when updating.)
If you do not wish to delete the muted channels from the file, simply
unmute all channels before using the update command.  The capability
to remove muted channels is useful for removing vocal melodies from
karaoke files, or for removing garbage tracks from other files, etc.

Note that the "Ctrl-R" command toggles whether MFPLAY uses running status
compression when playing MIDI files.  This setting also affects the Update
command:  If running status compression is enabled when you update a file,
MFPLAY will pack the data as tightly as possible when writing.  Running
status is NOT lossy compression; all it does is eliminate the MIDI status
byte in a sequence of multiple events of the same type on the same channel.
Using running status could reduce the size of an uncompressed file by
10-20%.  Although files created with running status OFF are slightly
larger than their compressed counterparts, these files are considered to
be more robust for live performance situations, since they ensure that
the MIDI status byte is updated more frequently (preventing a bunch
of notes from being lost as the result of a single MIDI transmission
glitch).  MFPLAY gives you the option of playing files with or without
running status, regardless of whether compression was used in the
original file.  (That is, you can store the files with running status
compression to save space, but play them back more robustly with status
bytes sent for all events.)


CHANGING PATCHES -----------------------------------------------------------

You can easily change the instrumentation of a MIDI file within MFPLAY.
After playback has begun, press S to select a channel, then use the
"[" and "]" keys to change the patch playing on that channel.  

If you wish to save your changes, press "U" to update the file on disk.
MFPLAY will automatically replace the file's existing patch changes with
the patches you've selected.

Note that each change you make is only effective until the next patch
change on a particular channel.  For example, suppose that on a given
channel, "Original patches" are the patch changes originally present
in the file, and "Your patches" are the patches you select with "["
and "]" at the times shown:
      
          Time    Original patches    Your patches
          ----------------------------------------
          00:05   Piano 1
          00:15                       Music Box
          01:05   Accordion           
          01:25   Flute
          02:25                       Piccolo

Given the above situation, if you save your changes with the "U" command,
MFPLAY will replace the "Piano 1" patch at 00:05 with "Music Box" and
the "Flute" patch at 01:25 with "Piccolo".  That is, it will move
your patch changes back to overwrite the most recent existing patch
change on a given channel.  It is only possible to add a patch change
where none previously existed at the beginning of a song.  For more
complex patch editing, you will need to use a sequencer.


COMMAND-LINE OPTIONS VS. KEYBOARD COMMANDS ---------------------------------

When using the tempo, velocity, and transposition functions, it is
important to understand the difference between the way MFPLAY handles
keyboard commands and the way it handles the command line options.

If you play a file, and say, change the tempo using +/-, go to the next
file, then go back to the file where you changed the tempo, the tempo
change you made will not be there anymore.
  
But if you specify a tempo adjustment on the COMMAND LINE, that adjustment
WILL be there every time you go to the file to which it applies.  Think of
it as, the command line switch is a stronger way of setting the tempo than
pressing +/-, which provides a temporary adjustment effective only during
a particular use of the file.

Note that in either situation, pressing "O" will ALWAYS set the file back
to its original tempo and velocity settings (exactly as specified in the
MIDI file), with NO transposition.  But like +/-, pressing "O" only has
an effect for the current playback of the file.  If you used command line
options to modify the tempo/velocity/transposition, those settings will
still apply the next time you play the file.


USING MULTIPLE CONFIGURATIONS ----------------------------------------------

MFPLAY supports four separate configurations of MIDI interfaces and
devices.  The configurations are defined in MFPLAY.CFG on the MIDI_PORTS
and MIDI_DEVICES lines.  You can switch between the four configurations
during playback by pressing F1-F4.  When a different configuration is
activated, the file currently playing will be restarted so that the
MIDI devices of the new configuration can be properly reset.


USING MULTIPLE MIDI INTERFACES ---------------------------------------------

Unlike most public-domain MIDI programs, MFPLAY is able to route output
to multiple MIDI interfaces according to port prefix events in MIDI files.
This makes it easy to play compositions requiring more than 16 MIDI
channels without the need to run a sequencer.

In your sequences, you can control which MFPLAY port a track's output
is sent to by using META PORT PREFIX events.  The MFPLAY ports are
numbered starting with 0.  In a MIDI file, the raw data for a META PORT
PREFIX event is as follows:

         FF 21 01 nn   where nn = the port number (00, 01, 02..)

All MIDI and SYSEX events following the META PORT PREFIX event will
be sent to the specified output port.

Note: Some demo files created by Roland for the SC-88 do not include
      these port prefix events and consequently won't play properly
      the first time you try them with MFPLAY.  However, if you load
      the files into MFPLAY and then hit "U" to update them on disk,
      MFPLAY will add the appropriate events and the files will then
      play correctly.


DEFINING YOUR OWN DEVICE FILES ---------------------------------------------

MFPLAY uses .dev files to properly reset and display patchnames for
various MIDI devices.  If no .dev file is included for one of your devices,
you can define your own device file.  Look at the file "template.dev" for
information on the format of .dev files.


TRANSMITTING .SYX FILES ----------------------------------------------------

You can specify .SYX (SYSEX) files on the command line along with MIDI
files, and MFPLAY will transmit them at the appropriate points in the
playlist.  (Note that the file extension *must* be ".SYX".)

Two sample .syx files are included for use with Roland Sound Canvas
devices:

     ARABIAN.SYX  - Performs a GS reset, then tunes the Sound Canvas to
                    the Arabian scale on all channels.
     JUSTTEMP.SYX - Performs a GS reset, then tunes the Sound Canvas to
                    just temperament (keytone = C) on all channels.


USING MFPLAY TO RESET MIDI DEVICES -----------------------------------------

If you specify the option "INIT" on the command line in place of any
MIDI filenames, MFPLAY will simply initialize all MIDI devices and then
exit.  This is useful in batch files when starting a program that expects
your devices to be in a certain state, such as a game or demo.

Note that when using MFPLAY for this purpose, you can still specify
"CFG n" if you have multiple MIDI configurations.  MFPLAY will act
according to the corresponding MIDI_PORTS and MIDI_DEVICES lines
in MFPLAY.CFG.


EXTERNAL CONTROL -----------------------------------------------------------

By defining the CONTROL_PORT variable in MFPLAY.CFG, you can control some
functions of MFPLAY using an external MIDI keyboard.  This makes MFPLAY
useful for live performance applications.

Several functions are predefined for you:

    - MFPLAY will respond to MIDI Song Select messages, starting playback
      of the requested song as soon as the message is received.  Song
      Select #0 maps to the first song in the playlist, and so on.

    - MFPLAY will respond to MIDI Stop, Start, and Continue commands.
      When Start is received, the current song will begin playing from
      the beginning.  Stop acts like a pause function; this command will
      toggle whether MFPLAY is playing or paused.  Continue will resume
      playback if MFPLAY is paused; otherwise it will do nothing.

    - The playback tempo can be adjusted very smoothly using the
      pitch bend control of an external keyboard.  This makes it easy
      to vary the tempo to follow live performers.  Moving the pitch
      bend control downwards will slow the tempo; moving it all the 
      way downwards will stop playback without shutting off playing notes
      (fermata effect).  Moving the control upwards will allow you to
      gradually increase the tempo (up to 2.5x normal playback speed).

      Enabling the music roll display mode in MFPLAY will help you 
      follow performers more exactly, since you will be able to see 
      upcoming musical events before they strike and adjust the tempo
      accordingly.

      Note that this tempo adjustment is independent of MFPLAY's other
      tempo control, which is a coarser adjustment and intended only
      for setting the overall tempo of a file.

In addition to these predefined functions, you can assign other features
of MFPLAY to MIDI events of your choice.  For example, you could have 
middle C start the next song, the sustain pedal pause/resume playback,
and so on.  You can also configure MFPLAY to send a user-defined 
sequence of MIDI bytes on a particular output port in response to any
incoming note, patch change, or controller event.  See MFPLAY.CFG for
examples of how to assign these control functions.  All controllable
MFPLAY features are listed for you in the configuration file; simply
change the triggering events to suit your setup.

When a CONTROL_PORT is defined in MFPLAY.CFG, soft MIDI thru is
available; this allows you to have MIDI events from an external keyboard
routed to any output port in MFPLAY.  Using soft thru, you can play
along with a MIDI file, even on channels already in use by the MIDI file.
Alternatively, you can choose an idle channel on which to play; MFPLAY's
patch select keys [ ] may be used to choose patches.  If a channel 
is currently selected, MFPLAY will route MIDI thru events to that
port and channel.  If not, MIDI thru will be routed to a particular
port, but the channels of the events will be left intact.  Use the
"THRUPORT n" command line option to select the output port in this case
(the default port is 0).

Soft thru can operate in any of three modes:

     - Soft thru off; incoming events from the external keyboard 
       are never routed to MFPLAY's output ports, but any control
       functions assigned to the events are processed by MFPLAY.

     - Soft thru on (control enabled); events assigned to control
       functions are processed by MFPLAY; all other events are 
       routed to the selected output port/channel.

     - Soft thru on (control disabled); MFPLAY does not intercept
       any events and routes all incoming events to the selected
       output port/channel.

The thru mode may be changed within MFPLAY using the "|" key.

When using soft thru in live performance situations, you may want
to use the "[" and "]" keys to select patches on idle channels ahead
of time; you can save these changes into the file using the "U" command,
causing MFPLAY to update the MIDI file.  Then the next time you play the
MIDI file, that channel will be set to the correct patch automatically,
ready for you to play using soft thru.


AUTOMATIC AND MANUALLY-PUMPED MODES ----------------------------------------

By default, MFPLAY plays MIDI files at their correct, original tempos,
requiring no user interaction to keep the performance going.  However,
you can use the P key to put MFPLAY in manually-pumped mode, which allows
you to "pump" the MIDI file, sort of like an old-fashioned player piano.
Two external MIDI controls (pedals or keys) are used to simulate the
pumping.  To use manually-pumped mode, you must define a CONTROL_PORT
setting in MFPLAY.CFG and assign the functions PUMP1 and PUMP2 to the
external MIDI controls of your choice, using the "CONTROL" directives.
The default MFPLAY.CFG comes with these parameters already set up for you,
assuming you have an MPU401-compatible MIDI interface and that you wish
to use two MIDI notes to pump the music.  Edit MFPLAY.CFG to change these
settings.

Once you've got the external control working and the PUMP1 and PUMP2
functions assigned to your MIDI controls, put MFPLAY in manually-pumped
mode by pushing P during playback.  Once in this mode, you must
alternately push the two MIDI controls to keep the music playing.  You
must make at least one pump per second in order to keep the music playing
at full speed.  If you pump at less than one-second intervals, the music
will slow and eventually stop.  Pumping evenly at 1 second intervals will
cause the music to play at its usual volume level.  Pumping faster will
make the music play more loudly, and pumping slowly will make the music
play more softly.  By quickly changing the pump rate, it is possible to
add accents and other expressive effects to the music.  Using MFPLAY's
music roll display mode will make it easier to anticipate upcoming events
in the music.


DAMAGED MIDI FILES ---------------------------------------------------------

MFPLAY will refuse to play MIDI files that are obviously damaged.
However, if you experience long delays or garbage notes during playback,
the MIDI file is probably damaged in a way MFPLAY cannot detect.  One of
the key symptoms of a bad MIDI file is that the delta times (times between
events during playback) seem unreasonably long.  MFPLAY can be set to
detect enormous delta times and abort playback of such files automatically.
The MAX_DELTA option in MFPLAY.CFG specifies the longest delta time
(in seconds) that MFPLAY will allow before giving up on a particular file.
If this value is set too low, MFPLAY may give up on files that aren't
really damaged.  I recommend that you use a value of 20 seconds or more.

MFPLAY automatically removes damaged files from the playlist as they're
detected.  This prevents you from getting the same error message more
than once.

Note: Damaged file detection is disabled when playing a type 1 MIDI file
with the TRACK option specified, since individual tracks in a multitimbral
file may contain large delta times when instruments are silent (tacet).


MISCELLANEOUS NOTES --------------------------------------------------------

Ctrl-Alt-Del, Ctrl-Break, and Ctrl-C are disabled while MFPLAY is
running.  This is because MFPLAY installs interrupt handlers for some
MIDI interfaces.  Exiting the program improperly would leave your
computer in an unstable state and cause it to hang.  

MFPLAY.EXE contains built-in virus protection.  If the program detects
that it has been modified, it will automatically terminate.

Some PC soundcards have MIDI interface hardware that doesn't work reliably
(older ProAudio Spectrum cards are notoriously bad).  This will sometimes
result in hung notes, notes not sounding, and similar kinds of problems.
There is no way for MFPLAY to detect when these problems occur, but you
can fix things temporarily by pressing "!", MFPLAY's "panic button".

If you are using MFPLAY to play a MIDI device that operates mechanically
(for example, a solenoid-driven player piano), be careful about using
really fast tempos (this includes the fast-forward feature).  While most
solenoid piano systems have protection against really short MIDI events,
I don't think it's a good idea to force a real instrument to play this
fast; mechanical damage could result.  Use common sense.

The piano keyboard and music roll display modes will not show properly
if you run MFPLAY in a window under Windows.  The problem is that MFPLAY
uses custom VGA characters for these features, and Windows' textmode
emulation does not support custom characters.  However, these display
modes will work fine if you run MFPLAY fullscreen.


FREQUENTLY ASKED QUESTIONS -------------------------------------------------

Q: Why did you write MFPLAY for MSDOS?

A: MSDOS allows low-level access to your PC's hardware, allowing precise
   timing and efficient support for various MIDI interfaces.  An older
   laptop running MSDOS is good enough for live performance situations,
   where the bloat and instability of Windows is undesirable.  Plus,
   there are dozens of decent MIDI players for Windows already. When MFPLAY
   was developed in the mid-1990s, MSDOS was still widely used.
----
Q: When I run MFPLAY under Windows, dialogue boxes pop up warning that
   my MIDI device is already in use.

A: Windows is intercepting MFPLAY's direct writes to your MIDI hardware.
   Either reboot and run MFPLAY from Windows' DOS mode, or disable the
   Windows device drivers for your MIDI equipment.
----
Q: How come MFPLAY can't play .WAV's, .MOD's, .AVI's etc.?

A: Those files have nothing to do with MIDI, and there are already
   plenty of players for those kinds of files.
----
Q: When running MFPLAY in a window under Windows, there are pauses in 
   the music, particularly when my machine is busy.

A: You can improve the performance a little by turning off the note display
   (press "D").  However, MFPLAY was not designed for Windows and only
   happens to work somewhat.  For best results, run MFPLAY exclusively
   fullscreen.  
----
Q: I have an MPU401-compatible interface, and MFPLAY gives me the message
   "MPU401 transmission timeout".

A: Check that the MPU_ADDR and MPU_IRQ settings in MFPLAY.CFG are correct.
   You may get this message if either setting is wrong.
----
Q: How come MFPLAY doesn't have a file selector like every other PC
   program these days?  I hate using command-line utilities!

A: I recommend using MFPLAY with a shell program that lets you specify a
   particular program to run when you click on a file with a certain
   extension.  I use Norton Commander this way with MFPLAY, and it's great.
   There are also a few shareware file selector shells that will do the
   job just as well.  Using an external shell keeps MFPLAY small and
   provides you with a more consistent user interface for file selection.
----
Q: When I press certain "ctrl" functions during playback, the keyboard
   locks up until the end of the song.

A: This will happen with certain older PC's (IBM XT, for example), 
   because they don't support extended keyboard functions.  Set the 
   parameter "OLD_PC" in MFPLAY.CFG to "Y" and the lockup problem
   won't happen anymore.  You will not be able to use the commands
   CTRL-UP, CTRL-DOWN, CTRL-PLUS, and CTRL-MINUS, but everything
   else should be fine.  (If you have a PC manufactured after, say,
   1986, you shouldn't experience this problem.)
----
Q: MFPLAY crashes when I use both interface X and interface Y at the
   same time.  I thought you said it supports multiple interfaces.
  
A: Since I don't own all the interfaces MFPLAY supports, I'm not able to
   test all the possible combinations.  Most combinations should work okay,
   but if you find a case where using more than one interface locks up the
   machine, make sure there are no IRQ conflicts between the two devices,
   and try various alternative address/IRQ settings for them.  If you still
   have problems, send me email.


DISCLAIMER, DISTRIBUTION, AND HOW TO REACH ME ------------------------------

DISCLAIMER:  Use this program at your own risk.  I accept no responsibility
for hardware damage, data loss, lost revenue, or other mishaps that may
or may not be related to your use of MFPLAY.

DISTRIBUTION:  You may freely distribute MFPLAY as long as you include
MFPLAY.EXE, MFPLAY.CFG, MFPLAY.TXT, and all the included .DEV files in
their original formats.  If you will be including MFPLAY on a disk or
CDROM shareware compilation to be sold for profit, please notify me in
advance.  You may not charge any fees beyond reasonable duplication and
media costs for MFPLAY.  If you wish to bundle MFPLAY along with a
hardware product, please contact me and we'll work something out.

NAG-FREE SOFTWARE!

MFPLAY is free software.  The version you have received is fully
functional and you may use the program indefinitely with no need to
register.  There are no nag messages, delays, disabled features, or
other hassles built into the program.

But if you like MFPLAY and wish to encourage me to expand the program
and do similar projects, I would appreciate an email or postcard with
your comments and suggestions.

I can be reached at mark@kinura.net

The latest version of MFPLAY is available for download at:

     http://www.kinura.net/mfplay/


SPECIAL THANKS TO ----------------------------------------------------------

   Radames Bernath, my primary beta tester, who has provided an amazing
   amount of help in debugging all aspects of MFPLAY, especially the 
   multi-interface support, karaoke lyrics, and SC-88 support.

   Jim Heyworth, who worked with me to get MFPLAY running satisfactorily
   on older machines.

   Steve Cole, who helped me track down a bug with MPU401 interfaces.

   Bob Carwell, who tested MFPLAY on several old machines and loaned me
   his Key Midiator so that I could implement Midiator support.
 
   Mike Kent (Third Party Developer Liaison, Roland Corporation)
   who provided documentation on Roland GS products and the official
   GS Standard specifications.

   Roger Stern, who's provided much support over the course of MFPLAY's
   development.

   And to these other fine beta testers:  Mervyn Kong, Irving Dekterev,
   Thomas Jay Swan, Krunoslav Leljak, Duncan Cambridge, Archana S. Prasad,
   John Grant, David Abramsky, Rob Lynch, Joe Linn, and Dave Lames.


OBLIGATORY ACKNOWLEDGEMENTS ------------------------------------------------

   Roland, GS, and GS Format are registered trademarks of Roland
     Corporation U.S.
   Soundblaster is a registered trademark of Creative Technologies.
   ProAudio Spectrum is a registered trademark of MediaVision.
   Gravis Ultrasound is a registered trademark of Gravis.
   Midiator is a registered trademark of Key Technologies.
   MusicQuest and MidiEngine are registered trademarks of MusicQuest,
     now a division of Opcode Corporation.
   Midiman is a registered trademark of Midiman.
   PianoDisc is a registered trademark of Music Systems Research, Inc. 
   Disklavier is a registered trademark of Yamaha Corp.
   Norton Commander is a registered trademark of Symantec Corp.
   Microsoft Windows and Windows NT are registered trademarks of
     Microsoft Corp.

   MFPLAY was developed with the aid of code derived from the Standard
   MIDI File Programmer's Toolkit, Copyright (c) 1990 by MusicQuest, Inc.
   Support for MusicQuest MidiEngine interfaces was implemented using
   libraries provided by MusicQuest.  Support for the ProAudio Spectrum
   and GUS was implemented using code derived from the PAS and GUS
   software development kits available on the net.  Support for the
   Midiman PC/S and Midiman PC/P was derived from code provided
   by Midiman.

I am not affiliated with any of the companies mentioned above.

-- END OF MFPLAY.TXT -------------------------------------------------------
