dosmid.txt

         DOSMid - a low-requirements MIDI and MUS player for DOS
                    http://dosmid.sourceforge.net


*** INTRO ***

DOSMid is a MIDI and MUS player for DOS. It's a real mode application designed
to run on very modest hardware configurations. It plays standard MIDI files,
as well as MIDI in RIFF (ie. RMID), and MUS tunes (as used by Id Software in
numerous games like Doom, Heretic, Hexen, etc).
DOSMid requires a MIDI-capable hardware available either via the standard
MPU-401 interface, or an RS-232 port, or an EMU8000 engine (as found on
SoundBlaster 32/64 AWE series). Note, that some sound cards provide an MPU-401
interface natively, although many need an additional 'wavetable' daughterboard
to produce actual MIDI sound.
Since DOSMid v0.7 it is also possible to somewhat emulate MIDI via FM
synthesis using an OPL chip (that is one of the Yamaha YM3812 or YMF262 chips,
found on most sound cards from the nineties) - be warned however that, most of
the time, such MIDI-over-OPL emulation will yeld less than desirable results,
unless the MIDI file was specifically crafted for OPL.

Minimum requirements:
 - a compatible synthesizer (wavetable, OPL or external - see the compat list)
 - an 8086-compatible CPU
 - ca. 200K of available conventional memory (less if you have XMS)
 - a video card able to display an 80x25 monochrome text mode

Highly recommended:
 - 80286 CPU for a guaranteed lag-free experience even on complex MIDI files
 - VGA graphic with a color monitor
 - 512K of available XMS memory


*** USAGE ***

During runtime, DOSMid can be controlled with the keyboard:
 ESC       Quits to DOS
 +/-       Volume up/down
 PAUSE     Pause the song (press any key to resume)
 ENTER     Skip to next song

At the command-line, DOSMid accepts several options, as listed below:

DOSMID [options] file.mid (or m3u playlist)

 /noxms    Use conventional memory instead of XMS. This is obviously useful
           only if you don't have XMS. Don't use this option otherwise, since
           without XMS you won't be able to load MIDI files bigger than a few
           few dozen KiBs.
 /delay    Wait 2ms before each XMS access. Such waiting is required sometimes
           when the MPU controller is emulated by a TSR driver (specifically,
           the AWEUTIL driver used with SoundBlaster AWE 32/64 cards happens
           to crash if XMS accesses are not slightly delayed).
 /mpu=XXX  Force dosmid to use MPU-401 on port XXX. If not forced, DOSMID
           scans the BLASTER environment variable for the MPU port, and if not
           found, it fallbacks to port 330h. The port part is optional, that
           means you can use "/mpu" to just force MPU usage.
 /awe=XXX  Use the EMU8000 synth chip found on SoundBlaster AWE32/AWE64 cards
           on port XXX (the port is optional, you can specify just "/awe").
           KNOWN BUG: On some AWE cards, the FM music module becomes muted or
           noisy after using the EMU8000 chip. This is not a bug in DOSMid,
           and happens with other applications using AWE as well. If you have
           this problem, execute AWEUTIL /S after using DOSMid to reinit FM.
           I observed this problem on an AWE64 CT4390 ("Gold"), but not on an
           AWE32 CT2760.
 /opl=XXX  Use an OPL2-compatible chip on port XXX. This should be a last
           resort option if you don't have a wavetable device. Do NOT expect
           pleasing results. The port part is optional ("/opl" will use port
           388h by default).
 /sbmidi=XXX Drives an external synth connected to the gameport of your Sound
           Blaster card.  The port part is optional ("/sbmidi" will use the
           port read from BLASTER, or fallback to 220h).
 /com=XXX  Send MIDI messages out via the RS232 port at I/O port XXX. This can
  or /com1 be used to hook a hardware synth to a computer with no MIDI
  or /com2 interface, only a standard serial port. DOSMid does NOT reconfigure
  or /com3 the COM port, so you should take care of setting it correctly, for
  or /com4 example using the 'MODE COM1: ...' command. The port part is not
           optional, you are expected to pass the hexadecimal I/O address of
           the RS232 port you wish to use (for example "/com=3f8" is pointing
           to COM1 on most BIOS implementations).
           It is also possible to use simpler "/com1", "/com2", "/com3" and
           "/com4" switches. These will autodetect the correct I/O port.
 /syx=FILE Uses SYSEX instructions stored in FILE for initializing the MIDI
           device. FILE must be in "SYX" format, and can contain one or more
           SYSEX messages.
 /sbnk=FILE Makes DOSMid load a custom sound bank. This is supported only on
           OPL and AWE hardware. The sound bank file must be in the IBK format
           when used with OPL, and SBK format for AWE. OPL accepts one or two
           IBK files (eg. /sbnk=file1.ibk,file2.ibk). If two are provided,
           then the first one will be used for the standard 128-instruments GM
           set, and the second one for defining percussion instruments.
 /log=FILE Logs all DOSMid activity to FILE. This is a debugging feature that
           you shouldn't be interested in. Beware, the log file can get pretty
           big (MUCH bigger than the MIDI file you are playing).
 /fullcpu  Do not let DOSMid being CPU-friendly. By default DOSMid issues an
           INT 28h when idle, to let the system be gentler on the CPU, but on
           some hardware this might lead to degraded sound performance.
 /dontstop Never ask the user to press a key after an error occurs. This is
           useful if you want to play a long playlist and don't care about
           bad MIDI files, simply skipping them (or if you play a single file
           and wish that DOSMid exit immediately if the file is unplayable).
 /nosound  Disable sound (not very useful for a music player!)

Note: All the above options can also be written to the DOSMID.CFG file. This
file is loaded by DOSMID and used as default parameters that can still be
overloaded by command-line options.


*** THE BLASTER VARIABLE ***

When not forced into a specific configuration via command-line switches,
DOSMid scans the BLASTER environment variable to find out the most desirable
settings. A BLASTER environment variable usually looks similar to this:

  SET BLASTER=A220 I5 D1 T3 P330 H6 E620

The bits DOSMid is interested in are "A220", "P330" and "E620". P330 provides
the port address of the MPU-401 MIDI interface, while E620 tells the port
address of the EMU8000 onboard synth (available only on 'AWE' models). A220,
on the other hand, provides the base I/O address of the SoundBlaster card, so
DOSMid can output directly to the card's MIDI port. If not instructed
otherwise, DOSMid will always try to use the EMU8000 synth if found in the
BLASTER string, and if not, it will use the MPU-401. If neither of them are
found in the BLASTER string, or if there is no BLASTER variable at all, then
DOSMid will try to fall back to FM synthesis on port 388h.


*** COMPATIBLE SOUND HARDWARE ***

DOSMid supports a variety of MIDI hardware. Here below I list the types of
hardware that DOSMid can talk to, as well as a few examples.

External MIDI synthesizers:
 - Connected through a MIDI/game port: either using an industry standard
   MPU-401 interface, or SoundBlaster MIDI port (pretty much all non-USB
   external synthesizers have a 'MIDI IN' port),
 - Connected through a RS232 ("COM") port: many synthesizers come with an
   RS-232 port that can be used instead of the standard MIDI port, like
   Roland SoundCanvas models, Yamaha PSR series, the Miracle Piano, many Korg
   devices, or even software solutions based on ttymidi...

Internal MIDI synthesizers:
 - Available through a virtual MPU-401 interface: some AzTech Waverider 32
   models, some versions of the HighScreen SoundBoostar 16, SoundBlaster 64
   cards using the 'AWEUTIL' MPU emulator,
 - Based on the EMU8000 chip (SoundBlaster 32, SoundBlaster 64),
 - Based on an OPL2 or OPL3-compatible chip (most ISA sound cards from the
   nineties: Adlib, all SoundBlaster ISA models, Opti, AzTech...).


*** BUILDING ***

DOSMid is compiled with OpenWatcom. The entire build process is automated via
a Makefile file, so if you wish to rebuild DOSMid, all you have to do is type
"wmake". A few compile-time options are available to disable features you
don't need. Edit the Makefile and adapt FEATURES to your likeness. The
FEATURES list is documented in the Makefile. The default build comes with all
features compiled in, so you really should fiddle with FEATURES only in case
you desperately need to lower DOSMid's memory footprint.


*** LICENSE ***

Copyright (C) 2014-2016 Mateusz Viste
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.