******** Mark Feaver's Standard Midi and Karaoke File Player *********

Temporary program information and instruction until a standard Windows
Help file is created.  This file last updated 6-30-96.

System requirements to run the program:  Windows 3.1/3.11 or Win95.
A 386 or better processor, the faster the better.  An old 386x20 mhz
is really too slow!  Runs great on a 486DX2-66 or better!  An external
midi port or internal card capable of General Midi.  256 colors needed.
Screen resolution should be 640x480, but it will run in 800x600.  The
keyboards will have an extra octave+ of notes, but will be smaller and
more difficult to see unless you have a large screen monitor!

Required files in the program's directory:

  _SMFKAR4.EXE     The program itself.
  _SMFKAR4.INI     INI file remembers user settings and midi device.
  _SMFKAR4.TXT     This pseudo help file (not required to run program).
  DEFAULT.CFG      Binary file which has Voice Names & Variations.
  MIDISYS.DLL      DLL copyright by Paul Messick which handles Midi.
                   See the About... dialog under the Help Menu item.
                   This file should be in Windows\System directory,
                   but may work from the programs directory.
  CTL3D.DLL        A current version of DLL for 3D Dialogs.  Earlier
                   versions will not work.  Usually put in Windows
                   System directory.  Sorry, no installation program.
  CTL3DXXX.JNK     If this 'dummy' file is present, the program will
                   not use the 3D dialogs.  If the version of CTL3D.DLL
                   supplied is not used, dialogs may not appear.  This
                   file prevents that.  Delete or rename it if it is
                   not needed and 3D dialogs work OK for you.

This is a very early release beta demo version offered for your fun
and amusement.  It is not entirely 'bug' free, and is not the finished
product.  I am not a developer, only a hobbiest midi nut and programmer.

************************************************************************

The program plays Standard Midi and Karaoke song files of either format
0 or format 1.  Other than commercial programs, it is the only one that
I know that handles format 0 Karaoke files.  It will display four piano
keyboards, each handling 4 midi channels.  The notes being played will
show as colored boxes on the keyboard associated with the midi channel
(not track!) that the notes are sounding from.  When notes overlap (play
the same note), the last ones played will overwrite the first ones.  This
is not a bug.  The Drum channel (10) is NOT displayed intentionally.
When notes play beyond the octave range of the keyboards, they will loop
back on the keyboard.  This might be confusing, when it occurs, to 'hear'
the pitch go up, and 'see' the note displayed lower than a previous one.

The channel numbering is from top to bottom keyboard so that each keyboard
shows one of 4 adjacent channels.  The top keyboard shows channels: 1, 5,
9, and 13.  The second keyboard shows channels: 2, 6, 10 (drums), and 14.
The third keyboard displays channels: 3, 7, 11, and 13.  Bottom keyboard
shows channels: 4, 8, 12, and 16.  With this logic, a four part piece on
channels 1 to 4 will show each part on its own keyboard.

Each midi channel has a unique color for its Voice Name box and the keys
that are being played on that channel.  The position and color of a Voice
Name box indicates what midi channel is being played.

When a program change (voice select) is sent on any midi channel, its
number and name will be displayed using the original Roland Sound Canvas
names.  If a voice variation using the 'control 0' bank switching occurs,
the correct voice name will be displayed and the black border around the
box will change to white (no black border at all), to indicate that a
variation is being used (such as the MT32 voices bank #127).  The program
cannot recognize a 'second' drum channel which might be set up by some
midi files.  Example: channel 11 shows a Trumpet #57 but is sounding
drums (actually SFX) instead.  The note duration may be very short and
too fast to be seen, except for an occasional flicker.

Note: there are several midi files around that use invalid 'control 0'
data values (as far as a Roland Sound Canvas is concerned).  These may
display white borders but show the default (base) voicename.  Also, the
program doesn't know about the new variations available with the SC-88
or its equivalents.  The voicenames are updated in real time as a song
plays to always show what voices are currently playing.

If no Voice Name boxes show up, then no program changes were sent!  If
the Voice Names themselves are missing (only the number shows), then
the file DEFAULT.CFG is not in the programs directory.  Voice names are
displayed in realtime as they are sent, so they may not all show up at
the same time.  Depends on the construction of the midifile.  Some files
have no program changes in them, but this is rare.

************************************************************************

The Karaoke word logic will handle both format 0 and format 1 midi
files of up to 64 tracks.  Any extra tracks will be ignored.  Some
experimentation may be needed to find the best combination of options
when using larger fonts for the Karaoke words.  Upgrades to the program
will include added intelligence, but until then try the various options
such as: 'Line=NewPage', 'Skip NewLines', 'Hyphenation', etc.

Full screen Karaoke mode is available which hides the Player Pianos.
It is available only with the 'W' key (for Window).  If multi-playing
files and one is not karaoke, the keyboards will return for that song,
until the next Karaoke file is encountered.  Some Karaoke midi files
are constructed with long paragraphs of many lines.  Using the 'W' key
to open a full karaoke window usually allows these to display correctly
without using the 'L' option to limit each page to one line.

You may change Fonts and Window Size while playing.  Program will try
to display the words within the window size you select.  Later releases
will clean up some of the minor bugs with word display.  Words are allowed
to draw off bottom of screen if Font is too large for the area, or there
are too many lines (as mentioned above).  Try the 'W' key to see all the
text and/or the 'L' key to limit display to one line (instead of a
paragraph of 2 or more lines).  Try the 'H' and 'N' keys to hyphenate or
concatenate words also.  See description of Hot Keys below.

If you adjust window sizing during Karaoke Play, and happen to catch the
moment when it is updating to the next page, you may get garbled words
and lines.  Either resize or click the Maximize Window Button a time or
two to force a redraw.  Pressing any Karaoke format key will also cause
a redraw (N, L, K for instance).

************************************************************************

Midi files are loaded and played as-is.  They are not converted to a
special internal format.  If they are defective, ie., chopped off at
the end (from Internet travel?), or not constructed correctly, the
file will not play, and a message box will indicate the error.  Some
errors that are detected:  Not a Midi File (uue or zip?),  Can't find
a track (chopped off?),  Track Lengths not correct,  Missing End of
Track bytes, etc.  These will have to be repaired in another program.

If a defective file is encountered, the message box displays some info
about the defect and if multi-play is going (jukebox mode), there will
be two buttons 'OK and CANCEL'.  Selecting OK will continue on to the
next song.  Selecting CANCEL will exit multiplay mode if you desire.
If a single file is being loaded (non multiplay), only a single button
is displayed to acknowledge the error.

Later versions of the program may include the ability to manage midi
files as they are found 'defective'.  Ideas include deleting or moving
selected file to a special user defined directory (for bad files etc.).
I have been simply ALT+TABing to File Manager and moving them manually.

  Note:  Most other sequencer programs throw away Karaoke words and
  convert files to an internal format, which often destroys the good
  'sound' of the original file.  I've seen the most expensive ones
  reverse the order of note-on's and note-off's, strip out Sysex and
  Text, and generally 'trash' an otherwise good midi file.

A known bug in the midisys.dll prevents a song playing if there are too
many SYSEX messages in it!  If multiplay skips to next song, or single
play just stops and the Button shows 'Play', this is what has happened.
If I can find a 'fix' for this, it may be corrected in future upgrades.
The item 'Limit Sysex' in the options menu should be 'checked' so that
files with more than 30 sysex messages will still play.  All the sysex
messages will not be sent (event though Midi Info reports 77 for example).

If you run the program as a 'jukebox' in the background, and a program
you are using in the foreground ties up the CPU and Windows, when the
midisys.dll needs more 'music' data to play and can't get it, it will
assume the song is done.  This will cause it to abort and move on to
the next song.  This could happen during a lengthy initialization or
computation mode, and is relatively harmless.  It is not a bug in my
program (which is simply starved for CPU time).

************************************************************************

Tempo may be changed during play by Left or Right Clicking in the
tempo display box above the Bar:Beat display and Play Push Button.
Each click changes one BPM faster or slower.  Left Button=Slower etc.
Later revisions will refine this operation.  Nothing is changed in
the midifile, so tempo will return to normal the next time it is
started, or if there are additional tempo changes in the file.

Left-Click the Bar:Beat display to Restart any song or use the 'R' key.
Right-Click it to back up to the previous song if in MultiPlay mode.

  Note: the Bar:Beat display only 'understands' 4/4 time and doesn't
        change when a 3/4 time or other time signature is played.
        All are treated as though they were 4/4 time with 4 beats
        to a measure.

SpaceBar stops playing in MultiPlay mode.  The Enter key will skip to
the next song in MultiPlay mode, which is what a Left-Click on the Next
Button will do.  Either key will Stop/Start a 'single play' song, or
you can click the 'Stop'/'Play' button.

If you click the 'Next' button several times, the next few songs will
only 'initialize' and check for errors.  Before they start playing the
next file will be skipped to.  If there are files with errors, they
will stop the operation.  The filename will show in the windows caption
bar.  You may want to write down the filename to move it to a directory
where you store defective files waiting for repair.  Select OK to go
on to next song, or CANCEL to stop multiplay mode.

If you Right-Click anywhere to the left of the Button and BBC/Tempo
displays, it will Hide these (useful with karaoke).  A Left-Click
outside the normal area for these will restore them.  While they are
hidden, the mouse will perform the same actions as if they were not!
If the Tempo space is L/R clicked, the tempo will change.  The BBC
area will Restart or Jump to previous Multiplay song.  The Button
area will skip to next song (Multiplay) or start/stop playing, etc.

Note: Right or Left Clicking above the Tempo/BBC will NOT work.
      Only the area on the left is 'sensitive' to hide/show Button.

A feature which I find indespensible is the ability to automatically
send a GS and/or GM reset before each song is started, to restore
soundcards and midi synths to 'normal' operation which is often
changed by a previous song.  These both default to 'ON' and can be
changed as desired.  Sometimes midi files include one or both of these
messages, but more often do not.  This solves the problems of volume
and expression controllers being turned down and not back up, as well
as restoring normal voices where 'customized' ones have been setup in a
previous file.

************************************************************************

Suggested setup when starting the program:

   Note: You may use File Manager to associate .mid and .kar file
         extensions with the program.  Then if you double-click a
         .mid or .kar file, the program will automatically start
         playing that file.  You could also drop a filename on the
         .exe name in the File Manager.  You cannot drop a filename
         on the Program's Icon (doesn't accept Drag and Drop).

         You can 'install' an Icon in the Program Group of your
         choice and give it a working directory which would
         typically be your favorite midi or karaoke file path.
         You could also include the path and filename you would
         like to start playing automatically, on the Command line
         with a single space after the .exe extension.

         Example: C:\MARKMIDI\_SMFKAR4.EXE C:\MIDI_GM\FAVORITE.MID

1. You must select a Midi Device (Midi Mapper or other) when the
   program is run for the first time.  Select the 'Device' you
   normally use to play .mid files with.  If it can't be opened
   you will get the Dialog back again to select another.  The program
   will 'remember' the Device you select in its .ini file.  To select
   a different Device later, edit the .ini file in Notepad and erase
   the Device name, leaving only 'device=' on the line.

2. The program will automatically select the initial Karaoke Word
   Font.  You may change it with the menu item or the 'F' key.
   It is fun to sometimes use full screen mode with a large font!
   The starting font is: New Times Roman BOLD at 28 points.
   If you change Fonts, the new Font will be saved in the .ini file.

3. You are presented with a File Selector Dialog so you may choose a
   midi file or karaoke file.  If you choose the CANCEL button, you
   will see a 'splash' screen about the program and possibly a line
   or two of help info if you have the Menu Bar hidden or Buttons.

   Otherwise, select a file in the usual manner.  Anytime a file is
   selected, it is assumed that you want to Play it!  So, the song will
   start playing immediately unless it is defective.  New songs can be
   selected while one is yet playing, and in either Single or Multiplay
   modes.

   Note: The single file selector will show both .mid and .kar filenames.
         Once either type is selected, it remembers that file name and
         extension.  To show files with both extensions (.kar and .mid)
         you must erase the filename in the box above the file listing.
         The multi-play selector shows both .kar and .mid anytime it is
         called.  I prefer to rename my .kar files to .mid so they can
         be recognized by any program.  Then I keep Karaoke files in a
         separate directory.  Did you know that you can select multiple
         files to Rename... and enter '*.mid' as the new name (less the
         quotes)? (From the Windows File Manager).

4. When you are comfortable with and understand the 'Hot Keys', you
   can use the 'B' key to hide the Menu Bar and get more Karaoke space
   below the keyboards.  I also suggest using the Maximize Window Button
   to hide the sizing borders.  This also gives more space.  The program
   will 'remember' via its .ini file the status of the Menu Bar and the
   Maximize button, also all the 'options' such as Auto GS Reset, etc.

   To redisplay the Menu Bar, simply press the 'B' key again.

5. With long karaoke lines, you may want to hide the Tempo, BBC,
   and Play/Stop/Next Button by Right-Clicking to the left away
   from them anywhere.  Get them back with a Left-Click away from
   their normal display area which is always in lower right corner.
   The status of these (shown or hidden) is also saved in the .ini.

************************************************************************

   Hot Keys used to control program operation and various modes:
       (Most items are duplicated in the DropDown Menu Bar)

A  Auto GS Reset toggle, sends GS Reset before each song is played.
B  Hide/Show the Menu Bar (Opens more space for Karaoke lines).
   Hiding the Menu Bar also gives a more pleasing display.  All
   important Menu Bar functions are available with 'Hot Keys'.
C  Count In one measure bar, for songs that start on tick zero
   and start too abruptly.
D  If NOT Playing and Karaoke is loaded.  Finds/Displays 1st Page.
   Always use this when stopped and before using the 'U' key.
F  Select a new Karaoke Font and size anytime.  Displays the standard
   Font Select Dialog.  Dialog remembers last Font chosen.  The chosen
   Font is remembered in the .ini and is used the next time program
   is started.
G  Auto GM Reset toggle, sends GM Reset before each song if on.
   GM Reset is different than GS.  Both are included to cover most
   synths and soundcards.
H  Hyphenate words if checked, else moves complete word to next line.
   Words tend to look better when not hyphenated as sometimes only
   a single letter is on a line.
I  Show Midi File Info when a non-Karaoke file is loaded.  Shows the
   actual filename, number of bytes, format, number of tracks, etc.
J  Force 'Show Midi File Info' to overwrite Karaoke Display.  Next
   page of Karaoke will clean up display.  Or press 'N' 2 times.
K  Turns Karaoke ON or OFF.  If turned OFF, Karaoke words will not
   be 'searched for' and only Player Pianos will show.  If ON and
   song has no words, none will be displayed.  If full screen mode
   is selected for Karaoke ('W') which normally hides Pianos, they
   will automatically show when no words are found.
L  If ON (checked) treats newline characters as newpage characters.
   Used to break up long paragraphs with many lines that display
   off screen (until more intelligence is added!).
M  Calls up MultiPlay Dialog-Listbox.  Select-unSelect multiple songs
   to play.  May be called and changed anytime.  Shows .mid/.kar files.
N  If 'L' is off ('L' overrides), newline codes are ignored.
   Appends lines (words) together until display lines are full.
   Karaoke files have NewPage and NewLine codes to try and display
   words, lines, and pages correctly.  Poorly created Karaokes may
   use lines and paragraphs that exceed available display space.
O  Opens Single File Selector. Useful when Menu Bar is hidden with 'B'.
   Use to select a single new song to play anytime.  Use 'M' to
   select multiple songs to play (also anytime).
P  Show info about selected Font (temporary if Karaoke is going).
R  Restart the current song in either Single or MultiPlay modes.
   Sometimes GS/GM Resets do not 'take' or program changes are
   missed due to system timing.  Restarting a song does it all
   again!  Most useful in Multiplay mode.  Also a Left-Click on the
   Bar:Beat display (hidden or not) will restart a song.
S  Limit Sysex toggle.  The midi.dll has a bug or two in dealing with
   SYSEX messages.  Best left checked to limit output of sysex data.
U  If NOT playing and 'D' has been used to display 1st Page, this
   key will page Up through the rest of the Karaoke Pages. Use 'D'
   again to restart from page one.
W  If Karaoke is playing, hides Player Pianos and gives full screen
   for Karaoke display.  A larger font can be used, but needs to return
   to a smaller font for Player Piano mode or words will display
   off bottom of page.  Could try 'L' to limit each page to one
   line of text.  Experiment!
ESC     Instantly quit the program without asking if you want to!
ENTER   Skip to next song in multiplay.  Stop/start song in single play.
SPACE   Stop playing in multiplay.  Start/Stop in single play.

************************************************************************

Future enhancements will include the ability to Edit or Repair midi
files, Add Karaoke words to any type of existing file, show Event
and Track Lists, change or add Song Titles, enter midi songs on a
grand staff, and change Presets and Controllers on the fly.  Later
versions will be likely be issued under the Shareware principal.

As a 'free' midi and karaoke player, I think the program is far more
entertaining than the Media Player in Windows, and even some of the
midi 'auto' players I have seen posted.  With Multi-play, Auto GS/GM
Resets, and Karaoke display for format 0 and 1 files the program may
prove to be highly useful to the average Midi Song Collector.  It is
even handy to 'screen' bad midi files downloaded from the internet.

Your comments are welcomed and appreciated.  Disclaimer: If you decide
to use this program, you do so at your own risk.  I will not be liable
for any damage to your computer system, hardrives, or audio equipment.
Windows is a trademark of Microsoft, Inc.  Sound Canvas is a trademark
of Roland Corporation.

This program was written using GFA Basic for Windows.  If you are
interested in receiving 'update' notices, or have ideas, comments or
suggestions, please send me an email.  If the program doesn't run on
your system, I will try to help, but I am not a developer, so I don't
have the resources to 'debug' all possible situations.

Email to: mfeaver@s3.sonnet.com (Mark Feaver).

P.S.  I would really like to hear from you!  Ideas for a program name?

P.S.S.  A big thank you goes out to Paul A. Messick for his fine midi
        processing DLL, the Midi Programmers ToolKit Lite!

************************************************************************
