                                +~~~~~~~~~~~~~+
                                |   FalcAMP   |
                                | GEM version |
                                +~~~~~~~~~~~~~+
                              by SPLASH & STGHOST
                                 of SECTOR ONE
                               v1.01  21/04/2000

  Welcome to FalcAMP v1.01 ! This is the first GEM based version of our MP3
player for Atari Falcon030 computers. After a long while, it's finally here,
we hope you'll enjoy the work we put in this project.

Table Of Contents:
------------------
 I   / The Player
 II  / GEM interface
 III / External control
 IV  / Troubles ?


I/ The Player
--------------

  Here's a completely new version of our player, now spread as a PRG with
built-in GEM interface unlike previous releases. This version features a
plugin system that will allow other fileformats to be played. Currently,
only the Mpeg audio layer 3 plugin is available... Please refer to the
documentation of the plugin itself for details about the supported features
and abilities.
  The GEM interface is plugin independant (it's only designed for streamed
replay). Some parts of the interface<->plugin protocol are not finished
yet, so we apologize for missing functions... Don't contact us just for that,
there will be other releases.


II/ GEM Interface
------------------

  We've tried to make it as easy to use as possible. However, please read
what follows before complaining about strange behaviour because it has
not a pure GEM behaviour in some cases...

  The interface is splitted into many windows and features keyboard shortcuts
to move between these windows and access most function even without a mouse.
Check KEYS.TXT for the detail of available shortcuts.

  The player will open many windows, if the system gets out of available
windows, current one will be used for the new display, that's not a bug.

  This has been betatested under TOS, Mint and  Magic, so in case of trouble
remember it's (nearly) not OS-dependant.

 1) Main window
 --------------

  This window is icon based, most icons are quite specific but aren't... You
can also find a sliding bar in the bottom that will allow you to move inside
a file. Here comes the detail of all this...

  In the top of the window, you'll find the filename. It will be replaced by
the title of the song if the file contain such information (ID3 tag in case
of MP3 file).

  The 1st group of icons on the left controls the replay. It features basic
cd player functions: load/stop/play/pause/next/previous...
 * LOAD: use it to change file... The new file will be loaded but won't
        be played directly.
 * STOP: use it to stop current replay. The audio system will remain locked
        and the file will remain locked, it's kind of super-pause in fact.
        The file will be restarted at the begining if you play it again...
        Click on STOP a 2nd time to physically close the file and to release
        audio subsystem & DSP. NB: When you quit FalcAMP, the audio subsystem
        will always be released.
 * PLAY: start the replay of current file (or unpause it if it was in pause).
        If no file is loaded or if the replay is already active, it will call
        the fileselector to load another file. If you load a file using this
        button, it will be played directly.
 * PAUSE: stops replay but keep current position. Re-select this button to
        unpause the file.
 * PREVIOUS: if elapsed time is higher than 3 seconds, it will seek to the
        file to its start. Else, will jump to previous file in playlist (if
        it's not empty...)
 * NEXT: jumps to next file in playlist (if it's not empty...)
 * FASTFORWARD: not available yet...
 * LOOP: when selected current file won't stop at the end, and will restart
        from its beginning, thus it won't allow the player to jump to next file
        if you're in playlist mode !

 The second group of icons is a bit less obvious but not tricky at all...Here
comes the details (from left to right and top to bottom order)
 * PLAYLIST: will open the playlist editor window
 * FILEINFO: will open a window with information about loaded file
 * ABOUT: will display informations about the program
 * ADDTOLIST: current file will be added at the end of the playlist
 * PLUGINFO: will open the plugin-info window
 * CONFIG: preliminary setup window... will be redesigned later.

  Then comes the time display. It displays theorically elapsed playtime, not
real playtime. It's not possible to show the remaining time because of
variable bitrate files...

  And finally, there's the slidebar that shows current position in current
file. You can use it to move inside the file. BUT DON'T TRY TO SLIDE IT,
just click to the position you want to go to !

 2) Program Information / File Informations
 ------------------------------------------

  Well, these windows are rather obvious I think... nothing to do except
reading what is written ! :-)

 3) Playlist editor
 ------------------

  This player comes with a very basic playlist editor. The playlist format
is M3U, it's an ascii format so you can even make/edit list by hand too.
The editor features a small display window and a slider on its right side
(you can either click to where you want to go or slide the cursor here).
  Then comes a few buttons in the bottom:
 * ADD: open fileselector to select a new file... File will be appended at
       the end of the list or right before the 1st selected item on display.
       If you select a playlist, it will be appended to current one too.
 * DELETE: use it to remove all selected entries from the playlist.
 * PLAY: start the replay of playlist (the player is now in playlist mode
        until you manually load a file).
 * LOAD: let you load a new playlist
 * SAVE: save current playlist
 * CLEAR: flush all entries of current playlist

 4) Plugin informations
 ----------------------

  Nothing special here. It will display informations about available plugins
in the player. Refer to the each plugin information file for details of
supported/missing features. You can either slide or click to where you want with
the slider.

 5) Player setup
 ---------------

  Here you'll find an opton to force mono output, it's useful for slow
Falcons (esp if you want to play MPEG1 streams). This was formerly known
as the "Special Standard mode" in TTP version.


III/ External control
--------------------

  This interface accept commandlines parameters and also VA_START & DRAG'n'DROP
protocols.

  The commandline control is quite basic, you can specify either 1 or more
files even with longnames. If multiples filenames are present, a playlist
will be automatically built and started. If commandline contains 1 playlist,
it will be loaded and played too (but the playlist has to be alone in the
parameter list).

  The VA_START protocol can be used to start a file anytime. This will turn
off playlist mode unless you send a playlist through this method, in which
case it will be started automatically.

  The DRAG'n'DROP protocol can be used to pass 1 or more filenames to the
player. If the dragndrop is performed on the playlist window, all passed
file(s) will be appended to current list. If you dragndrop a playlist on the
editor window it will be appended too. If you dragndrop on another window,
1 file will be played directly, many files will be played as a new list,
and a playlist will be read as a new list too.


IV/ Troubles ?
--------------

  THIS PLAYER DOESN'T WORK AS AN ACC UNDER PLAIN TOS !!! Because of the
weird memory handling for ACC under TOS, and because of the RAM amount
needed, we can't use a static memory model... So, here come a basic rule
if you want to use FalcAMP as ACC under GEM: don't start or leave any
program while the player is playing ! Do a double-stop before any program
start/exit... That will avoid buffer-overwritting and other weird bugs !
Sorry for this, we'll try to hack the TOS for next release...

  The player has been tested alot but some bugs can remain :( The plugins
can report errors (for example, the MP3 plugin may complain about a dsp
timeout), in this case, have a look at the plugin doc... The GEM interface
may only got troubles from plugins... The interface has been designed so that
the closer button of each window will bring you to main window if no other
one is available, and only the closer of main window will exit the program
(but ctrl+q is always available). That's a security I kept from the single
window version of the player, it's not a bug !
  With Magic 5, the keyboard may get sometimes mad if you move too much the
mouse, this is caused by a trouble in magic's keyboard interrupt rout... We
can't do anything about it ! This doesn't happen under TOS & Mint. However,
it hasn't been tested with Magic 6 yet...

  If you find any GEM Interface related bug, please email-me at this address:
deunstg@free.fr with at least the keyword 'famp' in the subject.

  Don't hesitate to visit http://falcamp.atari.org if you have troubles or if
you want to be sure to have the latest version (don't send a bug report if
you don't have the latest release !!! it will be ignored then...)
