____________________________________________ | | | 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:: 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