                         ******************
                        * DBE PLAYER v2.03 *
                         ******************
                      by STGHOST of SECTOR ONE



1/ Introduction
---------------
  Here is a the second release of my soundtrack player. It is the first
official release as the previous one was quite buggy...It can be run as well
as a program or as a desk accessory. It is a modular player as the soundtrack
formats recognized depend on the installed drivers and as each kind of sound
output has its driver...For now, there are little drivers available as I've
not a lot of free time. Drivers can be added by putting them in the DBEPLR
directory.

  The following items should appear in the same directory:
    - DBPLAY2.ACC (or PRG, or APP)
    - DBEPLAY2.RSC
    - DBEPLR\ (directory of drivers)

  It has been tested on STE and Falcon succesfully and it is supposed to work
on every machine through the driver system. It runs as well under TOS, Magic,
MultiTOS, NAES and Geneva. As the aim of this player is to run in background
(as an accessory), you should have at least a MegaSTE so that the player
doesn't take all the processor time...(even if the driver says STE driver)
  There's not a lot of drivers in this release: that's normal ! I don't have
enough time for coding everything...If you want to write drivers, just contact
me (look at the end of this file).


2/ How to use
-------------
  When you run the program/open the accessory, you get the main dialog window.
This window shows informations about the current soudtrack and some buttons
below. Here is the detail of these buttons:
 * SETUP: enter the setup dialog window
 * LIST:  enter the soundtrack list-editor dialog window
 * PLAY:  start the replay of the soundtrack
 * STOP:  stop the replay, and erase the soundtrack in memory
          it also turn off the list replay
 * PAUSE: stop the replay but keep the soundtrack in memory
          clic again on it to resume the replay
 *  <<  : go back in the soundtrack (of 1 position)
 *  >>  : go forward in the soundtrack (of 1 position)
 * LOAD:  open the fileselector, and load the selected soundtrack
 * NEXT:  jump to the next file of the active list
 * QUIT:  exit the program / close the accessory window

  The SETUP window controls some parameters of the player. The changes are
immediately made when you click on the buttons but you can restore the
previous setup by exiting with the CANCEL button. With OK, your settings are
kept. You come back to the main window.
 The output setup just shows the current output driver in memory. Click either
on the button or the text to enter the output selector.
  The available options are:
 * AMIGA MODE: toggles limits on some effects for better compatibility
 * USE TEMPO:  allow the tempo commands in addition of speed commands
 * AUTOPLAY:   automatically play the soundtrack selected with the LOAD button
 * REPEAT SOUNDTRACK:
               allows the looping of the soundtrack, else the soundtrack is
               paused at the end (click on PAUSE to play again)
 * REPEAT LIST:
               allows the looping of the list in memory

  The LIST EDITOR has been made to build lists of soundtracks that will be
played automatically in the specified order. The editor is very basical...
  The ADD DIRECTORY button doesn't work (sorry). The ADD FILE button calls
the fileselector to select a soundtrack to add at the end of the list. If
the file is recognized, it is added to the list using its soundtrack-name.
 * Warning: you can't move soundtracks once they are in the list (except by
clearing a previous entry).
  The KILL SELECT button removes all the entries selected with the mouse in
the list. KILL LIST clears all entries, be careful !
  Use LOAD LIST / SAVE LIST buttons to read or write a list. The PLAY LIST
button starts the replay of the current list.
  The EXIT button brings you back to the main window.

  The output selector shows the list of the available drivers. Select one and
clic on SELECT to load it. CANCEL keeps the current driver. You go back to the
setup window.


3/ How to call ?
----------------
  There are 3 ways of calling the program. The easiest way is to run it (or
open it if it's an accessory)...Then select the file and play it ! If you use
it as an accessory, there are 2 other ways. The first one is by programmation:
the player install a cookie to signal its presence and it can be called with
some functions detailed below. The last way of calling is a little program
called DBCALL.APP which will call for you the accessory: just intall it as an
application with your favourite desktop and double click on the wanted files.
Of course you can also drag and drop the soundtracks onto the DBCALL icon...


4/ Control
----------
  The DBE player 2 can be called by other GEM applications that want to play
some soundtrack files...First, the calling application must look for the DBE
player. If the player is run as an accessory or in a multitasking operating
system, there is a 'DBPL' cookie in the cookie jar followed by the BCD version
number on 1 word and the application id on 1 word too. Use this id with the
appl_write function to talk with the player.
  Here are the recognized messages and the answers (the sent-message array is
called msg[] and the reply-message is called answer[]):

* GET_STATUS
Input:
	msg[0]=0x4250
Output:
	answer[3] major version
	answer[4] minor version
	answer[5] status flags:
	            bit 0 : if 1, there's a soundtrack in memory
	            bit 1 : if 1, the replay is active
	            bit 2 : if 1, a list is being played
	            bit 3 : if 1, the player has been reserved by another app
	answer[6] the id of the app that reserved the player
	answer[7] supported messages flags:
	           if bit n is set, function 0x425n is available

* LOAD_FILE
Input:
	msg[0]=0x4251
	msg[3] bit 0 : if 1, play the file once loaded
	       bit 1 : if 1, reserve the player
	msg[4]=filename string address high word
	msg[5]=filename string address low word
Output:
	answer[3] = 0 if loaded
	            1 if loaded and playing
	            -1 if function not recognized
	            -2 if not loaded
	            -3 if player reserved by another app
	answer[4] = soundtrack address high word
	answer[4] = soundtrack address low word

* PLAY_TRACK
Input:
	msg[0]=0x4252
	msg[3] bit 1 : if 1, reserve the player
Output:
	answer[3] = 0 if done
	            -1 if function not recognized
	            -3 if player reserved by another app

* STOP_TRACK
Input:
	msg[0]=0x4253
	msg[3] bit 0 : if 1, stop and clear soundtrack
	               if 0, pause (use play to unpause)
	       bit 1 : if 1, unlock the player
Output:
	answer[3] = if not <0,
	                bit 0 : if 1, soundtrack paused, else cleared
	                bit 1 : if 1, player still reserved
	            -1 if function not recognized
	            -3 if player reserved by another app

* LOCK_ACCESS
Input:
	msg[0]=0x4254
Output:
	answer[3] = 0 if locked (reserved)
	            -3 if player reserved by another app

* UNLOCK_ACCESS
Input:
	msg[0]=0x4255
Output:
	answer[3] = 0 if unlocked
	            -3 if player reserved by another app

* SET_PREFS
Input:
	msg[0]=0x4256
	msg[3] if bit 15 set, just read current setup
	       else set setup:
	         bit 0 : if 1, allow soundtrack looping
	         bit 1 : if 1, allow list looping
	         bit 2 : if 1, activate autoplay (it's no use here)
	         bit 3 : if 1, allow tempo commands
	         bit 4 : if 1, enter amiga (nearly-)compatible mode
Output:
	answer[3] = 0 if done
	            -3 if player reserved by another app
	answer[4] previous setup word


5/ Last words
-------------
  At the moment, only the MOD and DBT formats are supported and there's only
the STE output driver (takes 90% CPU time on STE). Other drivers will come
soon. The inter process communication has not been tested yet...and I've no
time for this...so test it and tell me how it behaves. If you want to write
drivers for this player or for any other reason, contact me at this address:

   HUGUET Denis
   104 bis Avenue du General de Gaulle
   18500 Mehun sur Yevre
   FRANCE
   deunstg@club-internet.fr


                                                       STGHOST/SECTOR ONE
                                                           24/02/1999



