Proposal for extensions to Replay AE7 format
Pete Goodliffe
28 Jan 1998
--

Codec parameter strings
-----------------------

To accomodate type 2 sound compressors (Encode/Decode) that need extra
parameters in order to work, we will extend their entry 0 interfaces to add
meaning to r1.

r1 will be set to zero if no extra codec parameters are supplied (i.e. the
codec uses its sensible defaults, or it doesn't require extra parameters).
It is otherwise a pointer to a string, the format of which is dependant on
the compression type.

Existing codecs will be given r1=0, which will not effect their operation.

In order that replay files may contain this extra information passed through
r1, the 'sound compression format identifier' AE7 header line syntax is
extended.

Example:

        ...
        2 mpeg-II [params] | 2 gsm | 1 sound format
        ...

In this case r1 will point to the null terminated string "params" when the
Encode/Decode entry 0 is called for the first sound track.

The second and third sound track encoders will be called with r1=0 for their
entry 0.

The exit condition of entry 0 is also extended to involve r1. In this case
it returns 0 or a pointer to an error block. This may be used to signify
incorrect parameter strings.

Thus the full format of Encode/Decode entry 0 is:

entry 0: initialise for encoding/decoding
                on entry
                        r0: sample frequency in Hz for information
                        r1: 0 if no parameter string
                            or pointer to parameter string, null terminated
                on exit
                        r0: workspace size required
                        r1: 0 or pointer to error block


Format of MPEG layer I and II codec parameter strings
-----------------------------------------------------

This describes the format of the parameter string accepted by the type 2
codecs 'mpeg-I' and 'mpeg-II'. The MPEG encoder reads and acts upon
information in this string, however the decoder can do without it and the
playback code does not actually need it.

The string consists of a series of characters representing a parameter
followed by a value for that parameter. These are listed below with their
defaults (which are used if the parameter is not specified or no parameter
string is passed to the encoder). The parameters can be set in any order.

        -----------------------------------------------------------
        token   meaning                 values          default
        -----------------------------------------------------------

        m       channel mode            [j]             s/m   
        p       psychoacoustic model    [1|2]           2
        b       total bitrate (kbs)     integer         384
        d       de-emphasis             [n|5|c]         n

        c       copyright flag          [0|1]           0     
        o       original flag           [0|1]           0     
        e       error protection        [0|1]           0     
        -----------------------------------------------------------

For example, the header file for an ARMovie passed to Join may contain a
sound format line thus

        ...
        2 mpeg-II [b128mjp1] sound format
        ...

Additionally, MPEG encoding is only designed for input data with a sample
rate of 32000, 44100 or 48000 Hz. If data of another rate is provided, the
encoder will work to the nearest given value.

       The default value is set according to whether Encode/Encodex2 are
        used. The only valid channel mode string possible is therefore "mj",
        and this, obviously, can only be used in stereo mode.

       These values have no real use and are only included for
        completeness.
