Short:  mpeg.device for Delfina DSP
Author: Smack/Infect! (Michael Henke)
Type:   mus/play

$VER: delfinampeg.device 1.3 (Thu 14-Jun-2001)


 #features
   -plays MPEG audio files with almost no CPU load
    (Delfina's DSP56002 does all the decoding and playback)

   -standard "mpeg.device" API
    (code based on melodympeg.device by Thorsten Hansen)

   -free software
    (full source code included, of course)



 #requirements
   -CPU 68020+
   -Delfina DSP board



 #changes since previous release
   -new email address
   -little code optimizing
   -fixed a quite unobvious bug in the cleanupDelfina() routine
    this avoids the "noisy deadlock" when seeking inside a file in AMPlifier
    using delfina.library 4.14 (personally, I can tolerate the "fake crash"
    bug of 4.14 but I *hate* the "sudden freeze" problem of the 4.16ß libs)



 #how to use it
   Copy delfinampeg.device to your "devs:" drawer and configure an application
   program to make use of it, for instance:

   AMPlifier    http://www.katodev.de
       Configuration -> Audio I/O -> MPEG audio player -> Decoder
       MPEG device:    delfinampeg.device
       Unit:           0
       Buffersize:     128 (recommended, use any value you want)
       Blocksize:      16  (recommended, use any value you want)
       set Layer I/II and Layer III to "Hardware" decoding

   Frogger      http://frogger.rules.pl
       use the option ADECODER with mode DELFINA

   AmigaAMP     http://www.amigaamp.de
       get the "MHI driver for mpeg.device" from Aminet: mus/play/mhimdev.lha
       follow the installation instructions in the README file

   Especially owners of the slower Delfinas (i.e. Lite) might be interested
   in the configuration options of delfinampeg.device, which can be used to
   sacrifice some playback quality in order to reduce DSP load. The device
   reads them from the environment variable DELFINAMPEG during OpenDevice().
   The options are:

   L2MONO...........mp2 files: decode left channel only
   L2RATE <number>..mp2 files: play at specified rate (given in kHz)
   L3MONO...........mp3 files: decode left channel only
   L3RATE <number>..mp3 files: play at specified rate (given in kHz)

   The given playback rate is automatically rounded to the nearest available
   Delfina rate (16, 27, 32, 48 kHz; Delfina 1200/Plus: 12, 24, 36, 48 kHz).
   example:
   > setenv DELFINAMPEG l3rate 32 l2mono
     (play mp3 files at 32 kHz, force mp2 decoding to mono)
   > copy ENV:DELFINAMPEG ENVARC:
     (save settings to disk)



 #known problems
   -use the latest (beta?) delfina.library - the README of DelfMPEG contains
    a list of known bugs in the library.

   -the MPEG decoding routines are taken from DelfMPEG, so the same
    restrictions apply here:
     -only MPEG-1 layer II and III audio files are supported.
     -the decoding routines need a lot DSP processing power, especially
      mp3 playback might overburden the slower Delfinas (i.e. Lite).
      try the config options listed above if you get "stuttering" sound,
      because that can be the result of the DSP decoding data too slowly.

   -equalizer and visual effect plugins of AMPlifier are currently not
    supported. this is not a feature of the mpeg.device. AMPlifier needs to
    copy the decoded audio data back from the sound board to main memory,
    which it can only do with the Melody boards but not (yet) with Delfina.



 #acknowledgements
   delfinampeg.device uses ideas/code from:
   -MPEG Audio Layer II decoder by Fredrik Noring and Tomas Berndtsson
    (an mp2 player for Atari Falcon, DSP56K code)
   -amp11 by Niklas Beisert (clean and fast C++ code)
   -FalcAMP by Denis "STGhost" Huguet and David "Splash" Carrere
    (an mp3 player for Atari Falcon, DSP56K code)
   -reference code by MPEG Software Simulation Group ("the original" C code)
   -melodympeg.device by Thorsten Hansen



 #author
   mailto: smack42@web.de

   delfinampeg.device - mpeg.device for Delfina DSP
   Copyright (C) 2000, 2001  Michael Henke

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA