dosmid.txt - audio/dosmid - Rivoreo Source Code Repositories


          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 is not a software MIDI emulator, hence it requires a MIDI-capable
 hardware available either via the standard MPU-401 interface, 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 late 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.

 Minimal requirements:
  - a MPU-401 compatible sound card with a synthesizer (wavetable or external),
    or a SoundBlaster AWE32/AWE64, or (if desperate) an OPL FM synth
  - an 8086 CPU or better
  - a video card able to display an 80x25 text mode (ie. CGA or better)

 Highly recommended:
  - an 80386 CPU
  - VGA
  - 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 have XMS. Don't use this option otherwise,
            since without XMS you won't be able to load MIDI files bigger
            than a few dozen KiBs (at least not all tracks).
  /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.
  /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).
  /log=FILE Logs all DOSMid activity to FILE. This is clearly a debugging
            option that you shouldn't be interested in. Beware, the log file
            can be 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!)


 *** 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 "P330" and "E620". The former provides
 the port address of the MPU-401 MIDI interface, while the latter tells the
 port address of the EMU8000 onboard synth (available only on 'AWE' models). 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 use FM synthesis on port 388h.


 *** LICENSE ***

 Copyright (C) 2014, 2015, 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.

	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 is not a software MIDI emulator, hence it requires a MIDI-capable
	hardware available either via the standard MPU-401 interface, 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 late 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.

	Minimal requirements:
	- a MPU-401 compatible sound card with a synthesizer (wavetable or external),
	or a SoundBlaster AWE32/AWE64, or (if desperate) an OPL FM synth
	- an 8086 CPU or better
	- a video card able to display an 80x25 text mode (ie. CGA or better)

	Highly recommended:
	- an 80386 CPU
	- VGA
	- 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 have XMS. Don't use this option otherwise,
	since without XMS you won't be able to load MIDI files bigger
	than a few dozen KiBs (at least not all tracks).
	/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.
	/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).
	/log=FILE Logs all DOSMid activity to FILE. This is clearly a debugging
	option that you shouldn't be interested in. Beware, the log file
	can be 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!)


	* 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 "P330" and "E620". The former provides
	the port address of the MPU-401 MIDI interface, while the latter tells the
	port address of the EMU8000 onboard synth (available only on 'AWE' models). 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 use FM synthesis on port 388h.


	* LICENSE *

	Copyright (C) 2014, 2015, 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.