                            ********************
                            *  FalcAMP  v1.20  *
                            ********************
                      > Plugin: Icecast and Shoutcast <
                            Version:        1.12
                            Released: 31/12/2005

           Audio MPEG Layer 3 player for Atari Falcon 030 computers
             By Denis "STGhost" HUGUET and David "Splash" CARRERE
                                 -----------
                                 Sector One
                                  1998-2006


  Sector One is proud to present this new plugin for our MP3 player for Atari
Falcon 030 computers.


Table Of Contents:

  I  / What are Shoutcast and Icecast ?
  II / System requirements
  III/ The player
  IV / Features
  V  / Known bugs and limits of this version
  VI / What's new in this version ?
  VII/ Contact authors



I/ What are Shoutcast and Icecast ?
-----------------------------------

  These are 2 methods of broadcasting audio data in MP3 format. These 2
kinds of servers provides a kind of internet radio service ;) MP3 has
become one of the most used audio format in the world. As it has been
developped especially to obtain a rather good quality at low bitrates, it
perfectly fits this radio broadcasting system. You can find more infos
on http://www.shoutcast.com and http://www.icecast.org (you'll also find
URLs of stations on these sites).


II/ System requirements
-----------------------

 This plugins needs:
- a Falcon 030
- 2.4 megabytes of free ram
- a STIK compatible internet stack
- an internet connection
- a new mintnet version (which still requires gluestik though)

 Optionnal but recommended:
- accelerated Falcon (CT1, CT2, Nemesis an Afterburner are known to work)
- external audio clock (CD, DAT or dual)
- using plip or ethernet instead of a serial-port modem


III/ The player
--------------

  Well, we spent again alot of time on this main plugin. This plugin will
allow you to play broadcasted MP3 datas:

 -only layer 3 is supported
 -MPEG 1, MPEG 2 and MPEG 2.5 streams are supported
 -Mono, Stereo and Dual-channel files are accepted, not Joint-Stereo.
  (Joint-Stereo files will be played as mono automatically)
 -your connection is fast enough for the incoming flow of the server.
 -sent datas are not severly damaged (simple error-recovery built-in)

  If the file is recognized, the player will prepare the replay according to
the commands from the interface.

  The decoder is partly interrupt based, so it should run rather well 
under any environment. But, remember that it will use a lot of available
CPU time on high quality streams.

  Because of the internet structure, the plugins has to buffer incoming
datas to cope with delayed stream packets. This will cause long init and
stop delays when using this plugin. It will take more memory. We had to
use a non-interrupted 030 decoder that prepares a queue of half-decoded
blocks for the DSP. This will cause a delay in the volume change control
linked to that queue (blocks with new volume won't reach DSP immediately).
We'll try to modify this behaviour by moving the volume control on DSP
side for next release. Please keep in mind that any GEM action will prevent
the plugin kernel to be called, what will quickly dry up the queue !

  Please keep in mind that both processors, even though they're working in
parallel, need to synchronize so if you have not a correct replay (noises into
the sound most of the time, and slowed tempo) it means that one of the
processor is too slow...either you're doing too much things in parallel
on the 030 side or the dsp is simply too slow (should only happen if you
don't use an audio clock on a standard Falcon for playing an MPEG 1 stream
at 44Khz or 48kHz).

  However, if you want to high quality MP3 streams on a standard Falcon, you
should avoid big screen resolution because this may cause some slowdown
of the replay. This should be very important if you have a VGA screen on
your Falcon. You can either keep a large screen by shrinking the number
of colours or use a small screen with a lot of colours...


IV/ Features
-------------

  Basically, the DSP decoder is identical to the MP3 plugin. Only the
interrupt system has been organized differently...

  Here's a summary of the features supported:

-External audio clocks automatically detected and used (dual clocks and FDI
 recognized too) (contact us if some clock isn't well recognized)
-Linear sample interpolation to convert MPEG replay frequency to Falcon
audio frequency. Useful only if you have not an external clock.
-Fake ID3 tag v1.0 generated on the fly according to server's informations
-Displays details about the stream format in the file info window (along with
 the fake ID3 tag). These infos are based on the first received frame, but it
 supports format-changes on the fly (except for frequency)
-Variable bitrate supported (but I've not seen a station that uses it yet)
-CPU speed boards accepted and recommended (especially if you don't have
  any external audio clock and you want to play 44.1kHz or 48kHz stereo
  files).
-Severe error recovery: to cope with possible sync errors with the stream,
 a very severe sync system has been used to avoid detection of a wrong
 stream format. It should handle small structural errors by resynchronizing
 quickly (just like the MP3 plugin) with a glitch limitation system.
- DSP timeout has been lowered so that a DSP crash can be detected faster.
 The delay should be 4 seconds before a timeout warning to the gem interface
- Preliminary joint-stereo computations added on 030 side, it will reduce the
 load of the DSP part for this kind of file. But no JS replay yet !
- The player computes the minimum number of IMDCT required to replay the
 file with the best accuracy. This allows the DSP decoder to work faster with
 Stereo files (up to 7% faster). This is helpful for a 32Mhz DSP and hardly
 slows down the 030 side.
- Completely new requantizing method used giving a better accuracy !!!
- Half interrupted decoders, be aware of not doing too many blocking GEM
 actions... else the stream will have to be resynchronized
- Displays the filling of the half-decoded block queue in the position slider
- Delayed volume control (CPU side)
- You can make FalcAMP directly called by CAB for shoutcast & icecast
 stations. Just go to 'External Programs' in CAB and associates *.M3U,PLS
 to FalcAMP and check the VA_START box. Don't forget to select the path
 to FalcAMP and to save your settings. This is only useful in multitasking
 environment of course.
- No serial trouble as with MP3 plugin (hopefully :)


V/ Known bugs and limits of this version
-----------------------------------------

- There may still be some DSP timeouts or unexpected troubles...

- If you're getting alot of datas from serial port, this may cause some
slowdowns in the decoder... That was the only way of avoiding the corruption
of all incoming datas that occured in previous version.

- 1-level http redirection supported (a '302 Moved Temporarily' reply)

- If you try to listen a stream with a too high bitrate, you may get
 transfer trouble. Here's a simple rule to be sure your connection is
 fast enough:
   connection_speed * 8 /10 = maximum_possible_bitrate
  for a 33600 bauds modem, you have a maximum mp3 bitrate of 26880 bps
  (which rounds up to 24 kbps as closest value). As mp3 is an already
  compressed format, modem compression doesn't help much !

- Joint-stereo encoding scheme is not yet available but should come soon.
Everything in the code is ready for it but because of some other bugs, we
had no time to finish that. These files will be played in mono for now...

- We did our best to make this player works with 16Mhz 030/32Mhz DSP. Most
of the time, the file will be replayed correctly, even if it could use most
of the available time of your Falcon. But problems are possible sometimes
with 44kHz and 48Khz stereo MP3 files, resulting in a kind of echo effect or
adding noisy clicks. If you have a 50Mhz 030/50Mhz DSP, you should never have
this kind of problem !
 Anyway, to let standard Falcons users listen to all MP3, we added a special
"Standard Falcon" mode, which will output Joint stereo and Stereo files as if
they were mono. A 32Mhz DSP has then enough time to process the file at
correct rate. This special mode is activated using the "Force Mono output"
setup of the GEM interface.
 The DSP decoder has become very fast and should be able to handle most
stations. No test has been done with high bitrate stations !

-=> Bug reports <=-

  We tried to make this software system friendly, and to prevent any
unexpected freezing of your computer. But, please, keep in mind that we
cannot guarantee a complete reliability. You have been warned !

  For bug reports, please send an email to STGHOST or SPLASH, using more
or less the following model. See Contact section for our email addresses.
Try to fill it with maximum accuracy.

FAMP's standard bug report:
~~~~~~~~~~~~~~~~~~~~~~~~~~~

a- Executable files and configuration

 My FalcAMP GEM version is the: _____, CAST.PLG version is: _____ and
plugin filesize is ______ bytes.
(check plugin infos in GEM interface to get plugin version)

 Hardware configuration of your Falcon: model, memory, and additional
hardware (clocks, faster CPU/FPU/DSP, enhanced sound system, ...).

 Software configuration of your Falcon (when you found FAMP's bug, else the
most frequently used): TOS version, additonal OS, inet stack, connection
speed...

b- station

A bug occured with this URL : ...
Stream's bitrate is: ___ kbps

Displayed infos are: ...

Kind of error:

-> FalcAMP give me the following error message:
-> FalcAMP is blocked/crashed
-> The sound is not correct.
-> ...
 Here is a short description of what occured.


VI/ What's new in this version ?
--------------------------------

 The plugin has been renewed since previous version to clean up connection
handling and support properly faster falcon (like 100MHz CT60 one). However
some strange behaviour have been spotted with gluestik and to solve that,
a preliminary version with direct mintnet support has been developped.
This separate version still requires gluestik for address resolving and
the Icecast title streaming is not yet converted to mintnet. Both version
of the plugin can't be activated at same time, you have to modify file
extensions to enable/disable them (only .PLG will be loaded).

 Here are the changes made since 1st release of this FalcAMP CAST plugin:
- Resynced decoder code with main plugin
- Cleaned up connection code
- Reworked architecture to save memory while inactive
- Support for faster falcons
- 2 flavors : the original stik version and a beta mintnet version
- Added a faster protocol initiator
- Now supports more stations (esp. live365 ones)
- Can handle stations that don't provide bitrate
- Updated dsp engine to same version as mp3 plugin
- Fixed the station change freeze-bug
- some instability possibly added in case of stream loss :/


VII/ Contact authors
--------------------

  Who did what in this plugin:

STGHOST (030 part)       deunstg@free.fr
 Inet code, tag update, stream bufferings, scalefactor decoding, fast Huffman
 decoding, clock detection, IMDCT estimation, joint-stereo precomputing, error
 recovery and many weeks of debugging...

SPLASH (DSP part)        dcarrere@worldnet.fr
 Sound system init, MFI system, DMA-DSP transfer, new requantisation,
 antialiasing butterflies, IMDCT, polyphase filerbank, linear interpolation,
 and many more weeks of debugging...

This is a 100% assembler product, based on AMP 0.71, AMP 0.76, MPEGA and ISO
MPEG sourcecodes, that we completely changed, improved, and optimized for the
Falcon 030.

  We'd like to thank:

-Tomislav Uzelac for spreading his sources of AMP
-Stephane Tavenard for giving us his sources of MPEGA
-Dan Ackerman for his help on inet coding and for stik2 !
-All people who supported and helped us to remove bugs
-All people who believed in us...

  We decided to spread this software as a freeware. We did it for the fun,
and also because we were dying to listen MP3 radios on our Falcon ! Also,
maybe we did it because people used to say that it would be probably
impossible to do, and we were convinced that it was possible.
  Anyway, because of the huge work we put into this player, we're expecting
-at least- some support and aknowledgements, and -at most- some money if you
think it's worth the price. If you use FalcAMP often, please, do not forget
us... It may speed-up the release of next version ! :-)

Have fun !
