Audio 4.94 - Over 11,000 Files/audio-11000.iso/msdos/midi/playpak/playr.doc

Text File | 1990-12-27 | 17.0 KB | 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