AMPlayer 1.39 Release Notes
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is release 1.39 of AMPlayer; for full technical details of what has
changed please see the Changes file in this directory.

AMPlayer is a family of MP3 playback modules/decoding systems based on
an optimised decoder core, implemented in a mix of C and assembler.

Version 1.33 saw various important changes:

 * SharedSound support
 
 * Streaming interface
 
 * New FP version

 * New selector module

 * AMPapp
 
 * New distribution format

 * Significant speedups
 
 * Multiple Instantiation

Version 1.35 saw some more:

 * Tidied multiple instatiation.
 
 * Revised memory usage.
 
 * Various bugs fixed.
 
 * 'User' sound system added (to allow 'decode but not play' operation).

Version 1.36 introduced:

 * Bug fix for AmpApp.
 
 * Bug fix for 8 bit sound.
 
 * Speed improvements for FP version.

Version 1.37 introduced:

 * More speedups.
 
 * Improved instance handling.
 
 * Transient file playback

Version 1.38 introduced:

 * Bug fixes for stream handling.
 * Many internal optimisations and improvements.

Version 1.39 introduced:

 * Various bug fixes.

SharedSound support
~~~~~~~~~~~~~~~~~~~

This section currently only applies to users with 16 bit sound on their
machines. If you have an 8bit sound system then SharedSound will
(currently) not operate at all and AMPlayer will behave exactly as
older versions have.

Previously AMPlayer would claim the entire sound system, stopping any
other sounds being generated. As from 1.33 onwards AMPlayer will use
the SharedSound module (if it is loaded) to allow multiple sound system
claimants at the same time.

Some users have noticed a degradation in Sound quality caused by the
introduction of this facility. This degradation is due to the fact that
the system sound frequency no longer tracks the frequency requested by
AMPlayer, but rather stays constant. This is a consequence of the way
SharedSound works, but can be easily alleviated.

In most cases MP3s are recorded at 44.1kHz (or an integer subdivision
of this rate). By setting the sound system frequency to run at this
speed all aliasing problems disappear, leaving perfectly mixed audio.

To set the sound frequency to 44.1kHz use the following command:

   SYS "Sound_SampleRate",3,20

[This assumes a standard RISC PC 16 bit sound system].

Some versions of SharedSound (notably that present in RISC OS 4) are broken
in that they do not spot the frequency changes. Therefore after executing
the previous command, it may be necessary to *RMReinit SharedSound and
*RMReinit AMPlayer.

In any event if you want to revert to the old behaviour, simply kill the
SharedSound module before loading AMPlayer.


Streaming Interface
~~~~~~~~~~~~~~~~~~~

Old versions of the AMPlayer module could only play from a file. Version
1.33 introduces a streaming interface whereby data can be fed to AMPlayer
in memory blocks. This is intended to facilitate the implementation of
systems such as SHOUTcast in an efficient manner.

Details of the new streaming interface can be found in the example Frontend
distribution.


New FP version
~~~~~~~~~~~~~~

Previously 2 variants of the AMPlayer module have been available, AMPlayer
and AMPlayer6. AMPlayer operates on machines with a long multiply operation
available, whereas AMPlayer6 relies on macros to implement this long
multiplication in terms of standard multiplications.

As from 1.33 we introduce a new variant AMPlayerFP that makes use of the
floating point unit present in ARM7500FE based machines to do these long
multiplications. This is still not fast enough to allow full bitrate
operation on ARM7500FE based machines, but does allow modem speed clips
to be played, thus opening the route to a SHOUTcast implementation in
future.


New selector module
~~~~~~~~~~~~~~~~~~~

With this proliferation of new versions it was getting increasingly hard
for applications programmers to load the right variant for the machine
they were on. We have therefore introduced a new module that automatically
loads the correct variant of the module.

Simply performing:

 *RMEnsure AMPlayer 1.35 RMLoad System:Modules.Audio.MP3.AMPlayer
 *RMEnsure AMPlayer 1.35 Error AMPlayer 1.35 cannot be found!

Will load the correct version. Please note that programmers shipping
new Frontends for AMPlayer should NOT include the AMPlayer module
within their application, but should load it from the !System directory
as shown above.


AMPapp
~~~~~~

Current solutions for decoding (rather than playing) MP3 files have
sometimes worked in a less than ideal manner. To address this we have
provided a command line build of the decoder called AMPapp. This is
available as a separate download.


New distribution format
~~~~~~~~~~~~~~~~~~~~~~~

As the AMPlayer family has grown it has become necessary (or at least
desirable) to split it into more than one distribution. The current
distributions are as follows:

 * Module Distribution: This contains the basic set of AMPlayer modules.
   Anyone wanting to do playback using AMPlayer will need this distribution.
   They will probably also want a frontend; either the example frontend
   supplied with AMPlayer or any of the other alternatives available on the
   net.

 * Example Frontend: This is the example frontend. While sufficient for
   many peoples use its main task is to demonstrate what is possible.
   Documentation on the AMPlayer modules API is included here.

 * AMPapp Distribution: This contains the command line MP3->PCM/WAV decoder.

These distributions contain a new license that outlines their
use/redistribution status. Basically it is intended to allow free
redistribution and to encourage future development while ensuring
that developments remain free.


Significant Speedups
~~~~~~~~~~~~~~~~~~~~

AMPlayer 1.33 has benefitted from having significant sections recoded in
assembler. This has lowered the CPU usage significantly, and we now believe
AMPlayer to be the most efficient RISC OS MP3 player currently available.


Multiple Instantiation
~~~~~~~~~~~~~~~~~~~~~~

It is now possible to multiply instantiate AMPlayer. Coupled with the
SharedSound system describe earlier this means that (subject to CPU
and memory constraints) several MP3s can now be played at the same time.
This facility is significantly better than in previous versions, and should
allow AMPlayer to be used as a generic decoding resource. Contact the
AMPlayer developers <amplayer@armware.dk> for more information.


Decode-but-not-play interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For systems (such as Flash decoders) that need to decode MP3 data, but have
control over the playback itself, AMPlayer has grown a 'User' sound system.
This enables controlling applications to capture the output from a decode
and to play it back itself.
