home *** CD-ROM | disk | FTP | other *** search
/ Share Gallery 1 / share_gal_1.zip / share_gal_1 / MD / MD007.ZIP / PLAYR.DOC < prev    next >
Text File  |  1990-12-27  |  17KB  |  382 lines

  1.  
  2.                    ____________________________________________ 
  3.                   |                                            |
  4.                   |     Play/R -- Resident MIDI File Player    |
  5.                   |                                            |
  6.                   |                Version 1.0                 |
  7.                   |                                            |
  8.                   |        Copyright 1990, Kevin Weiner        |
  9.                   |            All rights reserved             |
  10.                   |____________________________________________|
  11.  
  12.  
  13.  
  14.          -- Introduction --
  15.  
  16.          Play/R is a memory resident version of the Play 3.x program.  It
  17.          is intended to play standard MIDI files in the background while
  18.          performing other operations on the PC.  It runs as a TSR, or
  19.          Terminate and Stay Resident program.  Once loaded, it sits quietly
  20.          until the user invokes it by pressing a special "hot key".  A
  21.          small window pops up allowing the entry of a standard MIDI file
  22.          name or "play list" of multiple files.  Playing begins immediately
  23.          and the user may control various functions such as rewind, play,
  24.          pause, etc., while the pop up window is displayed.  After the
  25.          window is closed, play continues in the background.
  26.  
  27.  
  28.          -- Requirements --
  29.  
  30.          Play/R uses about 58K of memory for the program code, plus an
  31.          amount of memory reserved for the largest MIDI file to be played. 
  32.          The default file allocation is 24K - adequate for many MIDI files.
  33.          The allocation may be changed at load time to accommodate larger
  34.          or smaller files.  MIDI format 0, 1, and 2 files are supported,
  35.          with up to 16 tracks.  Track length is only limited to that which
  36.          will fit in the allocated memory.  In addition, the Creative Music
  37.          variant of the Standard MIDI file is supported.
  38.  
  39.          One of the following interface cards is required:
  40.  
  41.              - Roland MPU-401 and compatibles
  42.              - IBM PC Music Feature
  43.              - Sound Blaster MIDI interface
  44.              - Key Electronics MIDIator
  45.  
  46.  
  47.          -- Command line usage --
  48.  
  49.          Play/R is loaded as follows:
  50.  
  51.              playr [file] [-options]
  52.  
  53.          where [file] is an optional file to be played immediately, and
  54.          [-options] indicates any of the following options codes:
  55.  
  56.              -a         Indicates the amount of memory (in K bytes) to
  57.                         allocate for MIDI file storage.  The default is
  58.                         -a24.
  59.  
  60.              -m         Selects the operating mode: 1, 2, or 3.  The
  61.                         default is -m1.  Modes are described later.
  62.  
  63.              -k         Selects the "hot key" which will pop up the
  64.                         interactive display.  This key can be chosen
  65.                         from any of the letters A to Z.  After the
  66.                         program is loaded, press Alt and this letter
  67.                         simultaneously.  The default is -kp (which
  68.                         selects Alt-P).
  69.  
  70.              -w         Specifies the time in seconds to wait before
  71.                         loading the next song when advancing through
  72.                         a play list.  The default is -w1 (one second).
  73.  
  74.              -d         Selects the MIDI interface to use if more than
  75.                         one is present in the system:
  76.  
  77.                             -dmfc       selects IBM Music Feature
  78.                             -dmpu       selects MPU-401 compatible
  79.                             -dmidiator  selects MIDIator
  80.                             -dsbmidi    selects Sound Blaster MIDI
  81.  
  82.                         (The first 3 letters of the device name are
  83.                          sufficient to identify it.)
  84.  
  85.                         The MIDIator cannot be detected automatically
  86.                         and the -dmid option must always be specified if
  87.                         one is in use.  Any device can be selected in
  88.                         advance by setting a DOS environment variable.
  89.                         For example, to select the MIDIator, use:
  90.  
  91.                              set opt1=-dmid
  92.  
  93.                         Non-standard IRQ and I/O port information can be
  94.                         added following the device id if necessary:
  95.  
  96.                             -d<dev>:<irq>:<ioaddr>
  97.  
  98.                         For example, to define an MPU-compatible interface
  99.                         using IRQ 5 and I/O address 332 (hex), use:
  100.  
  101.                             -dmpu:5:332
  102.  
  103.                         If only the I/O address was required but the
  104.                         default IRQ was alright, use -dmpu::332.
  105.  
  106.                         The irq and ioaddr are not relevant to the
  107.                         MIDIator, though the first option number can be
  108.                         given to indicate use of the com port 2 instead of
  109.                         the default com 1.  (ex: -dmid:2)
  110.  
  111.              -i         Try to determine the IRQ in use automatically
  112.                         (MPU and MFC only).
  113.  
  114.              -v         List the type of interface actually selected
  115.                         before starting.
  116.  
  117.  
  118.          -- Files --
  119.  
  120.          The file name given on the command line, or after pop up, must
  121.          indicate a standard MIDI format (or CMF) file in the current
  122.          directory, or include the device and path name.  If the name is
  123.          preceded by the character "@", it is taken to mean the name of a
  124.          "play list" file.  A play list is a text file containing the name
  125.          of one song file per line.  Up to 30 files may be given in a play
  126.          list.  Songs in the list advance automatically to the next when
  127.          playing.  The list will loop continuously.  Files beginning with
  128.          "@" as part of the actual name are also assumed to be play lists
  129.          (if @ is the first character entered).
  130.  
  131.          At the window prompt, or in a play list, file names may be
  132.          followed by a space, and then a number from 1 to 16, indicating
  133.          the MIDI channel on which to play all notes (regardless of MIDI
  134.          channel designations in the file).  If a channel is specified in
  135.          this way, program changes are disabled, since they are not likely
  136.          to make sense when merging multiple channels.
  137.  
  138.          Auxiliary .PLA files created by Play version 2.2 and higher will
  139.          be loaded and used to control play if available.  A channel number
  140.          specified with the file name will take precedence over the .PLA
  141.          file.
  142.  
  143.  
  144.          -- Pop up window --
  145.  
  146.          To invoke Play/R after it has been loaded, press Alt-P.  It may be
  147.          necessary to hold the key for up to 2 seconds before the pop up
  148.          window appears, depending on system activity.  Pop up can only
  149.          occur on a text mode screen - not a graphics screen.  You will
  150.          receive an audible indication when pop up is not possible.
  151.  
  152.          The pop up window indicates the song file currently being played,
  153.          the length of the file in minutes and seconds, and the current
  154.          song position.  Song length is only displayed if a .PLA file is
  155.          available, unless the song has played through once and the length
  156.          has been determined.  Also, there is a space in which to enter a
  157.          new song file to play.  The following keystroke functions are
  158.          defined:
  159.  
  160.                F3:    Exit and remove from memory (when safe to do so).
  161.  
  162.                F5:    Rewind to beginning of song.  If using a play list
  163.                       and already at the beginning, move to previous song.
  164.  
  165.                F6:    Fast forward - advances 10 seconds at a time.
  166.  
  167.                F7:    Play/Pause
  168.  
  169.                F8:    Skip to next song in play list.  Check song length
  170.                       if no play list.
  171.  
  172.                Esc:   Close window and resume processing.
  173.  
  174.                Up/Down arrows:  Increase/decrease volume.
  175.  
  176.                Left arrow:      Same as F5 (rewind/skip previous).
  177.  
  178.                Right arrow:     Same as F8 (skip next).
  179.  
  180.                Alt-M: Advances through the 3 play modes described below.
  181.  
  182.                Alt-R: Reset the MIDI interface.  Play/R expects the MIDI
  183.                       interface to be in a specific mode.  If another MIDI
  184.                       program changes it, Alt-R will restore it to the
  185.                       necessary state.  Specifically, the MPU interface
  186.                       needs to be in "UART" or "dumb" mode.  If another
  187.                       program changes to intelligent mode or does a
  188.                       hardware reset, Play/R will not appear to be playing.
  189.                       Press Alt-R to restore the interface.  Use care, as
  190.                       a MIDI program in progress may no longer function
  191.                       properly then.
  192.  
  193.                Alt-F7:  Toggles between play and pause.  This functions
  194.                       the same as F7, but also works as a "hot key" when
  195.                       the window is not popped up.
  196.  
  197.  
  198.          -- Modes --
  199.  
  200.          The following operating modes, selected via the -m command line
  201.          option or Alt-M on the are define:
  202.  
  203.            Mode 1:  Use background interrupt stepping (default).
  204.  
  205.            Mode 2:  Use timer interrupt stepping.
  206.  
  207.            Mode 3:  Use both stepping methods.
  208.  
  209.          These modes control the accuracy and continuity of play.  Their
  210.          advantages and disadvantages are summarized below.
  211.  
  212.          Mode      Advantages                    Disadvantages
  213.  
  214.           1      Safest mode.               Playing only proceeds when
  215.                                             strictly safe to do so,
  216.                                             resulting in frequently
  217.                                             interrupted play.
  218.                                             Pop up may be slow to respond.
  219.                                             Ctrl-C may be sluggish.
  220.  
  221.           2      Plays uninterrupted.       Potentially unsafe.
  222.                  Pop up more reliable.      Lower timing accuracy.
  223.  
  224.           3      Most accurate and          Potentially unsafe.
  225.                  consistent play.           Pop up may be slow to respond.
  226.                                             Ctrl-C may be sluggish.
  227.  
  228.          Mode 1 relies on the underlying TSR mechanism, TesSeRact, to
  229.          determine when it is absolutely safe to interrupt DOS in order to
  230.          play or pop up.  These are very stringent requirements, resulting
  231.          in intermittent play while heavy system activity is in progress,
  232.          and possibly no playing in certain applications.
  233.  
  234.          Mode 2 uses the system timer (about 18 ticks per second) to
  235.          advance play.  It will proceed regardless of what else is
  236.          happening in the system, though timing inaccuracies may be noticed
  237.          in some songs.  While it is unlikely that extended timer
  238.          interrupts will cause problems (they account for about 2% of the
  239.          overall processing time), this is technically "unsafe".  High-
  240.          speed operations such as asynchronous port data transfers may not
  241.          work properly if interrupted for even a short time.  While no
  242.          difficulties have been experienced with hard disk activity,
  243.          critical functions such as backups are not recommended while play
  244.          is in progress.
  245.  
  246.          Mode 3 combines idle time processing with timer stepping to assure
  247.          high accuracy and continuous play.  The same warnings about
  248.          critical operations in mode 2 apply here.
  249.  
  250.  
  251.          -- Programming information --
  252.  
  253.          It is possible for an application program to communicate with
  254.          Play/R when it is loaded.  This could be used, for example, to
  255.          allow background playing in a voice editor while changing voices
  256.          or configurations.  Although this may work without special
  257.          handling, there is a possibility that Play/R will interrupt a
  258.          system exclusive or other message being sent, thus invalidating
  259.          the message.  If the application chooses to work in conjunction
  260.          with Play/R, it must suspend Play/R before sending any MIDI data,
  261.          and then restart it.
  262.  
  263.          The following Turbo Pascal unit demonstrates how to set up calls
  264.          to Play/R.
  265.  
  266.          ----------------------------------------------------------------
  267.          unit playrint;
  268.  
  269.          interface
  270.  
  271.          function checkres: integer;
  272.          procedure callplayr;
  273.  
  274.          var
  275.            param: array [0..31] of byte;        {Play/R parameter data}
  276.  
  277.          implementation
  278.  
  279.          uses dos;
  280.  
  281.          const
  282.            playrid: array [0..7] of char = 'Play/R  ';  {PlayR id string}
  283.  
  284.            tessmpx =  $5453; {hex}              {TesSeRact multiplex id}
  285.  
  286.          var
  287.            reg: registers;                      {CPU register set}
  288.            idnum: integer;                      {Play/R id number}
  289.  
  290.          function checkres: integer;
  291.  
  292.           { Check if Play/R loaded - returns id number if found, else -1 }
  293.  
  294.            begin
  295.              reg.ax := tessmpx;                 {ax = Tess int 2fh
  296.                                                   muliplex id}
  297.              reg.ds := seg(playrid);            {ds = id string segment}
  298.              reg.si := ofs(playrid);            {si = id string offset}
  299.              reg.cx := 0;                       {cx = Tess id counter -    
  300.                                                   must be 0}
  301.              reg.bx := 0;                       {bx = Tess check resident
  302.                                                   function}
  303.              intr($2f, reg);                    {Call int 2fh}
  304.              if reg.ax = $ffff then
  305.                idnum := reg.cx                  {Found - return tsr id}
  306.              else
  307.                idnum := -1;                     {Not loaded}
  308.              checkres := idnum;
  309.            end;
  310.  
  311.          procedure callplayr;
  312.  
  313.            { Call Play/R using the contents of the byte array "param".
  314.              Byte 0 is the function code, and the rest is any required
  315.              data. }
  316.  
  317.            begin
  318.              reg.ax := tessmpx;                 {ax = Tess multiplex id}
  319.              reg.es := seg(param);              {es = parameter segment}
  320.              reg.di := ofs(param);              {di = parameter offset}
  321.              reg.cx := idnum;                   {cx = PlayR id number}
  322.              reg.bx := $20;                     {bx = Tess call user
  323.                                                   function}
  324.              intr($2f, reg);                    {Call int 2fh}
  325.            end;
  326.  
  327.          end.
  328.          ------------------------------------------------------------------
  329.  
  330.          In order to call Play/R, it is first necessary to check if it is
  331.          resident, and if so, define its id number.  The function checkres
  332.          sets up the necessary register information and then calls int 2fh
  333.          to see if TesSeRact is active and knows about Play/R.  If so, it
  334.          returns Play/R's id number for future calls; otherwise it returns
  335.          -1.  The routine callplayr is similar, but calls TesSeRact with
  336.          Play/R's id number and a parameter pointer, which is then passed
  337.          on to Play/R.
  338.  
  339.          Note that for MPU use, Play/R expects the device to be operating
  340.          in UART mode.
  341.  
  342.          The following functions are available when calling Play/R:
  343.  
  344.          param[0]   Function
  345.  
  346.             0       Pause
  347.             1       Play
  348.             2       Trigger pop up
  349.             3       Rewind and pause
  350.             4       Load file (param[1..n] contains null-terminated name)
  351.             5       Return play status in param[0] (0=pause/1=play)
  352.             6       Return current file name in param[1..n]
  353.             7       Return song finished status in param[0] (0=not done/
  354.                      1=done)
  355.  
  356.  
  357.          -- Acknowledgement --
  358.  
  359.          This product uses the TesSeRact(TM) Ram-Resident Library and
  360.          supports the TesSeRact Standard for Ram-Resident Program 
  361.          Communication.  For information about  TesSeRact, contact the
  362.          TesSeRact Development Team at:
  363.  
  364.               TesSeRact Development Team
  365.               c/o Chip Rabinowitz
  366.               2084 Woodlawn Avenue
  367.               Glenside, PA 19038
  368.               1-215-884-3373
  369.  
  370.               Compuserve:         70731,20
  371.               MCIMAIL:  315-5415
  372.  
  373.          This MCIMAIL Account has been provided to the TesSeRact
  374.          Development Team by Borland International, Inc.  The TesSeRact
  375.          Development Team is in no way associated with Borland
  376.          International, Inc.  TesSeRact is a trademark of the TesSeRact
  377.          Development Team.
  378.  
  379.          TesSeRact(TM)  Copyright (c) 1988, TesSeRact Development Team,
  380.          All Rights Reserved
  381.  
  382.