home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Sound Sensations!
/
sound_sensations.iso
/
midifile
/
playpak
/
playr.doc
< prev
next >
Wrap
Text File
|
1990-12-26
|
17KB
|
382 lines
____________________________________________
| |
| Play/R -- Resident MIDI File Player |
| |
| Version 1.0 |
| |
| Copyright 1990, Kevin Weiner |
| All rights reserved |
|____________________________________________|
-- Introduction --
Play/R is a memory resident version of the Play 3.x program. It
is intended to play standard MIDI files in the background while
performing other operations on the PC. It runs as a TSR, or
Terminate and Stay Resident program. Once loaded, it sits quietly
until the user invokes it by pressing a special "hot key". A
small window pops up allowing the entry of a standard MIDI file
name or "play list" of multiple files. Playing begins immediately
and the user may control various functions such as rewind, play,
pause, etc., while the pop up window is displayed. After the
window is closed, play continues in the background.
-- Requirements --
Play/R uses about 58K of memory for the program code, plus an
amount of memory reserved for the largest MIDI file to be played.
The default file allocation is 24K - adequate for many MIDI files.
The allocation may be changed at load time to accommodate larger
or smaller files. MIDI format 0, 1, and 2 files are supported,
with up to 16 tracks. Track length is only limited to that which
will fit in the allocated memory. In addition, the Creative Music
variant of the Standard MIDI file is supported.
One of the following interface cards is required:
- Roland MPU-401 and compatibles
- IBM PC Music Feature
- Sound Blaster MIDI interface
- Key Electronics MIDIator
-- Command line usage --
Play/R is loaded as follows:
playr [file] [-options]
where [file] is an optional file to be played immediately, and
[-options] indicates any of the following options codes:
-a Indicates the amount of memory (in K bytes) to
allocate for MIDI file storage. The default is
-a24.
-m Selects the operating mode: 1, 2, or 3. The
default is -m1. Modes are described later.
-k Selects the "hot key" which will pop up the
interactive display. This key can be chosen
from any of the letters A to Z. After the
program is loaded, press Alt and this letter
simultaneously. The default is -kp (which
selects Alt-P).
-w Specifies the time in seconds to wait before
loading the next song when advancing through
a play list. The default is -w1 (one second).
-d Selects the MIDI interface to use if more than
one is present in the system:
-dmfc selects IBM Music Feature
-dmpu selects MPU-401 compatible
-dmidiator selects MIDIator
-dsbmidi selects Sound Blaster MIDI
(The first 3 letters of the device name are
sufficient to identify it.)
The MIDIator cannot be detected automatically
and the -dmid option must always be specified if
one is in use. Any device can be selected in
advance by setting a DOS environment variable.
For example, to select the MIDIator, use:
set opt1=-dmid
Non-standard IRQ and I/O port information can be
added following the device id if necessary:
-d<dev>:<irq>:<ioaddr>
For example, to define an MPU-compatible interface
using IRQ 5 and I/O address 332 (hex), use:
-dmpu:5:332
If only the I/O address was required but the
default IRQ was alright, use -dmpu::332.
The irq and ioaddr are not relevant to the
MIDIator, though the first option number can be
given to indicate use of the com port 2 instead of
the default com 1. (ex: -dmid:2)
-i Try to determine the IRQ in use automatically
(MPU and MFC only).
-v List the type of interface actually selected
before starting.
-- Files --
The file name given on the command line, or after pop up, must
indicate a standard MIDI format (or CMF) file in the current
directory, or include the device and path name. If the name is
preceded by the character "@", it is taken to mean the name of a
"play list" file. A play list is a text file containing the name
of one song file per line. Up to 30 files may be given in a play
list. Songs in the list advance automatically to the next when
playing. The list will loop continuously. Files beginning with
"@" as part of the actual name are also assumed to be play lists
(if @ is the first character entered).
At the window prompt, or in a play list, file names may be
followed by a space, and then a number from 1 to 16, indicating
the MIDI channel on which to play all notes (regardless of MIDI
channel designations in the file). If a channel is specified in
this way, program changes are disabled, since they are not likely
to make sense when merging multiple channels.
Auxiliary .PLA files created by Play version 2.2 and higher will
be loaded and used to control play if available. A channel number
specified with the file name will take precedence over the .PLA
file.
-- Pop up window --
To invoke Play/R after it has been loaded, press Alt-P. It may be
necessary to hold the key for up to 2 seconds before the pop up
window appears, depending on system activity. Pop up can only
occur on a text mode screen - not a graphics screen. You will
receive an audible indication when pop up is not possible.
The pop up window indicates the song file currently being played,
the length of the file in minutes and seconds, and the current
song position. Song length is only displayed if a .PLA file is
available, unless the song has played through once and the length
has been determined. Also, there is a space in which to enter a
new song file to play. The following keystroke functions are
defined:
F3: Exit and remove from memory (when safe to do so).
F5: Rewind to beginning of song. If using a play list
and already at the beginning, move to previous song.
F6: Fast forward - advances 10 seconds at a time.
F7: Play/Pause
F8: Skip to next song in play list. Check song length
if no play list.
Esc: Close window and resume processing.
Up/Down arrows: Increase/decrease volume.
Left arrow: Same as F5 (rewind/skip previous).
Right arrow: Same as F8 (skip next).
Alt-M: Advances through the 3 play modes described below.
Alt-R: Reset the MIDI interface. Play/R expects the MIDI
interface to be in a specific mode. If another MIDI
program changes it, Alt-R will restore it to the
necessary state. Specifically, the MPU interface
needs to be in "UART" or "dumb" mode. If another
program changes to intelligent mode or does a
hardware reset, Play/R will not appear to be playing.
Press Alt-R to restore the interface. Use care, as
a MIDI program in progress may no longer function
properly then.
Alt-F7: Toggles between play and pause. This functions
the same as F7, but also works as a "hot key" when
the window is not popped up.
-- Modes --
The following operating modes, selected via the -m command line
option or Alt-M on the are define:
Mode 1: Use background interrupt stepping (default).
Mode 2: Use timer interrupt stepping.
Mode 3: Use both stepping methods.
These modes control the accuracy and continuity of play. Their
advantages and disadvantages are summarized below.
Mode Advantages Disadvantages
1 Safest mode. Playing only proceeds when
strictly safe to do so,
resulting in frequently
interrupted play.
Pop up may be slow to respond.
Ctrl-C may be sluggish.
2 Plays uninterrupted. Potentially unsafe.
Pop up more reliable. Lower timing accuracy.
3 Most accurate and Potentially unsafe.
consistent play. Pop up may be slow to respond.
Ctrl-C may be sluggish.
Mode 1 relies on the underlying TSR mechanism, TesSeRact, to
determine when it is absolutely safe to interrupt DOS in order to
play or pop up. These are very stringent requirements, resulting
in intermittent play while heavy system activity is in progress,
and possibly no playing in certain applications.
Mode 2 uses the system timer (about 18 ticks per second) to
advance play. It will proceed regardless of what else is
happening in the system, though timing inaccuracies may be noticed
in some songs. While it is unlikely that extended timer
interrupts will cause problems (they account for about 2% of the
overall processing time), this is technically "unsafe". High-
speed operations such as asynchronous port data transfers may not
work properly if interrupted for even a short time. While no
difficulties have been experienced with hard disk activity,
critical functions such as backups are not recommended while play
is in progress.
Mode 3 combines idle time processing with timer stepping to assure
high accuracy and continuous play. The same warnings about
critical operations in mode 2 apply here.
-- Programming information --
It is possible for an application program to communicate with
Play/R when it is loaded. This could be used, for example, to
allow background playing in a voice editor while changing voices
or configurations. Although this may work without special
handling, there is a possibility that Play/R will interrupt a
system exclusive or other message being sent, thus invalidating
the message. If the application chooses to work in conjunction
with Play/R, it must suspend Play/R before sending any MIDI data,
and then restart it.
The following Turbo Pascal unit demonstrates how to set up calls
to Play/R.
----------------------------------------------------------------
unit playrint;
interface
function checkres: integer;
procedure callplayr;
var
param: array [0..31] of byte; {Play/R parameter data}
implementation
uses dos;
const
playrid: array [0..7] of char = 'Play/R '; {PlayR id string}
tessmpx = $5453; {hex} {TesSeRact multiplex id}
var
reg: registers; {CPU register set}
idnum: integer; {Play/R id number}
function checkres: integer;
{ Check if Play/R loaded - returns id number if found, else -1 }
begin
reg.ax := tessmpx; {ax = Tess int 2fh
muliplex id}
reg.ds := seg(playrid); {ds = id string segment}
reg.si := ofs(playrid); {si = id string offset}
reg.cx := 0; {cx = Tess id counter -
must be 0}
reg.bx := 0; {bx = Tess check resident
function}
intr($2f, reg); {Call int 2fh}
if reg.ax = $ffff then
idnum := reg.cx {Found - return tsr id}
else
idnum := -1; {Not loaded}
checkres := idnum;
end;
procedure callplayr;
{ Call Play/R using the contents of the byte array "param".
Byte 0 is the function code, and the rest is any required
data. }
begin
reg.ax := tessmpx; {ax = Tess multiplex id}
reg.es := seg(param); {es = parameter segment}
reg.di := ofs(param); {di = parameter offset}
reg.cx := idnum; {cx = PlayR id number}
reg.bx := $20; {bx = Tess call user
function}
intr($2f, reg); {Call int 2fh}
end;
end.
------------------------------------------------------------------
In order to call Play/R, it is first necessary to check if it is
resident, and if so, define its id number. The function checkres
sets up the necessary register information and then calls int 2fh
to see if TesSeRact is active and knows about Play/R. If so, it
returns Play/R's id number for future calls; otherwise it returns
-1. The routine callplayr is similar, but calls TesSeRact with
Play/R's id number and a parameter pointer, which is then passed
on to Play/R.
Note that for MPU use, Play/R expects the device to be operating
in UART mode.
The following functions are available when calling Play/R:
param[0] Function
0 Pause
1 Play
2 Trigger pop up
3 Rewind and pause
4 Load file (param[1..n] contains null-terminated name)
5 Return play status in param[0] (0=pause/1=play)
6 Return current file name in param[1..n]
7 Return song finished status in param[0] (0=not done/
1=done)
-- Acknowledgement --
This product uses the TesSeRact(TM) Ram-Resident Library and
supports the TesSeRact Standard for Ram-Resident Program
Communication. For information about TesSeRact, contact the
TesSeRact Development Team at:
TesSeRact Development Team
c/o Chip Rabinowitz
2084 Woodlawn Avenue
Glenside, PA 19038
1-215-884-3373
Compuserve: 70731,20
MCIMAIL: 315-5415
This MCIMAIL Account has been provided to the TesSeRact
Development Team by Borland International, Inc. The TesSeRact
Development Team is in no way associated with Borland
International, Inc. TesSeRact is a trademark of the TesSeRact
Development Team.
TesSeRact(TM) Copyright (c) 1988, TesSeRact Development Team,
All Rights Reserved
