File format AE7: ARMovie
========================

Start of file:

String          ARMovie
String          Movie name
String          date and copyright details
String          author and other details
String          video compression format identifier     [0 -> no video]
                Optional: in [] a parameter list of space separated numbers/strings
Decimal number  x size in pixels
                Optional: in [] the pixel aspect ratio expressed as x:y
                          for example, a PAL ITU 601 pixel shape is 15:16 (720:768)
                          while an NTSC ITU 601 pixel shape is 9:8 (720:640)
Decimal number  y size in pixels
Decimal number  z pixel depth in bits [16 or 8]
Decimal number  number of frames per second to project at
                (optionally followed by the start timecode)
String          sound compression format identifier     [0 -> no sound]
Decimal number  sound replay rate in Hz (or fractions of)
Decimal number  number of sound channels recorded ("reversed" if l<->r)
Decimal number  sound precision ("linear" if linear, "unsigned" if unsigned)
Decimal number  number of frames in a chunk
Decimal number  number of chunks NC (chunks start at 0!!!!)
                Optional: the word "forever" has the same effect as -loop
Decimal number  "even" chunk size in bytes
Decimal number  "odd" chunk size in bytes
Decimal number  offset to chunk catalogue CC
Decimal number  offset to "helpful" sprite
Decimal number  size in bytes of the "helpful" sprite info
Decimal number  offset to key frames                    [0/null -> no keys]
                other gunge as required

(all fields are ASCII text terminated by NewLine; spaces
ignored, arbitrary comment text after numeric field permitted)

byte CC: start of catalogue of chunks
         this has NC+1 entries of the form:
              file offset of chunk (maybe multiple of 1024)
              size of video data
              size of sound data (immediately after video data)
         arranged FO,BS;OS<newline> (spaces permitted except in numbers)

A 'fetcher' can be specified on the offset to chunk catalogue line by putting
in the keyword "fetcher" followed by the name of the fetcher to use. See
fetcher documentation. If a fetcher has been specified, the format of the
chunk catalogue could be anything, including not existing. An example would
be:

159845 (offset to catalogue) Fetcher [Rapid]

where the text is a comment apart from the Fetcher indication.

The 'key frame offset' points to a set of NC (not NC+1) blocks of data
containing x*y*z bits. These allow the decompression to start at a particular
chunk even if the decompressor used does not support starting anywhere.
Starting at the first chunk doesn't need a reference to the key frame offsets.

If the pixel depth is 8, then a palette may be provided by including the text
'palette <decimal number>' which gives the offset of the palette in the file
(the palette is stored as 256 triple bytes, r then g then b). If there is no
palette, then the data is taken as 0-255 greyscale.

A different colour model to RGB or YUV may be specified by putting the name of
the colour model in []s - for example '16 bpp colour model [YIQ]'. RGB is the
default colour model, YUV can be specified without []s. Both RGB and YUV refer
to 5R5G5B, 5Y5U5V 15 bit per colour entry specifications, but other colour maps
may allocate the bits differently such as 6Y5UV using 16 bits with 6 in Y and
5 in each of U and V and CYUV for CCIR scaled YUV.

If the sound format is 2, the name of the sound decompressor file follows after
a single space: '2 soundxxx'. Playing programs rely on this to find the
decompressor. If the video format is 15, the name of the video decompressor
file follows after a single space '15 video1'. All format 15 video
decompressors are stored in the same directory (Decomp15) in order to ease
clutter in the main ARMovie directory. Indirect names are administered solely
by Acorn Computers.

Example:
ARMovie
The Concert
(c) Notts University 1991
Created by Notts University, digitised by Acorn Computers
1
160 pixels
128 pixels
16 bits per pixel 
25 frames per second, start TimeCode 10:00:00:00/25
1
12000 Hz samples
1 channel
8 bits per sample (exponential)
50 frames per chunk
57 chunks forever
204080
192992
10580256 catalogue offset
512 sprite offset
20480 sprite size
105602 key frames offset

Compression format parameters
-----------------------------

A [ ] delimits some values which are specific to a particular format. For
example: 602 [5, 10, 20].

Initial Timecode
----------------

For editting purposes, the movie can have a Timecode indication. This is the
timecode of the start of the movie: the timecode of any particular frame is
calculated from it. The timecode has the format:

Timecode  10:00:00:00/30

where 'Timecode' is in any case; there is white space between it and the first
digit of the timecode and the rate at which the timecode is specified (if
different from the fps figure) is given after the /.

Multiple Sound Tracks
---------------------

The single video track can have an arbitrary number of sound tracks associated
with it. Extra sound track data for each sound parameter follows the sound
track marker "|" plus the sound track number. Different sound tracks can have
completely different parameters - compression format, sample rate, number of
channels, number of bits per sample. The first sound track is played by default
and does not follow a |1 marker - thus the first additional sound track has
parameters following a |2 marker.

Example:
ARMovie
The Concert
(c) Notts University 1991
Created by Notts University, digitised by Acorn Computers
1
160 pixels
128 pixels
16 bits per pixel 
25 frames per second
1                               |2   2 CELP1               |3  1
12000 Hz samples                |2   16000                 |3  20000
1 channel                       |2   2 channels            |3  2 channels
8 bits per sample (exponential) |2   16 bits per sample    |3  4 bits (adpcm)
50 frames per chunk
57 chunks
236080
228992
10580256 catalogue offset
512 sprite offset
20480 sprite size
105602 key frames offset

The catalogue entries are similarly marked:

              file offset of chunk (maybe multiple of 1024)
              size of video data
              size of sound data 1 (immediately after video data)
              |2
              size of sound data 2 (immediately after sound data 1)
         arranged FO,BS;OS|2 OS<newline> (spaces permitted except in numbers)

Playing sound tracks later than the first one uses more memory (the decompressor
reads the chunk up to and including the sound data it needs).

16 bit sound data is aligned to the next word.

Although it is possible to have multiple sound tracks in a file with no video,
it is probably better to have multiple ARMovie files instead.

A note about the ARMovie's file name
------------------------------------

The movie replay program adds the ARMovie$Suffix to any path name given to it:
it tries to open this file, then tries again with the original path name. (just
like the window manager with !Sprites, !Sprites22 etc). This allows a degree of
personalisation of replay invisible to all programs.
 
Therefore we recommend the follow standard suffix characters:

"2" a movie made at half the frame rate of its base movie
    this movie can be expected to be playable on less powerful machines
    (generalise if required!)

"S" a movie made with much smaller chunks than its base movie
    this movie can be expected to be playable on small memory machines (an "S"
    suffix movie may not work from a CD-ROM drive). For example if the base
    movie has 2 second chunks, then an "S" suffix might only have 1 second
    chunks.

"L" a movie made with much larger chunks than its base movie
    this movie will not work on CD-ROM, but can be copied from CD-ROM to
    a faster filing system (winchester, magneto-optic) and played. Such movies
    will usually require an ARM3 (or better) to replay them.

If two suffixes are available, then the 2 should come first.

Calling programs should use the shortest name possible.

A note about compression numbers
--------------------------------

The compression values allow for new video (de)compressors to be written in the
future. The Player program inspects the video value and, if it cannot process
the format (using the Decompress codes: see "DecompIf"), calls
<ARMovie$Dir>.DeComp<X>.!RunImage where <X> is the decimal string of the value
of the compression type. Thus new compression types can be added transparently.

Compression types are allocated as follows:

   0-99: Acorn
         video                                     audio
         0: no video                               0: no audio
         1: 'Moving Lines' compression             1: basic audio
         2: 16bpp uncompressed                     2: 'indirect' audio
         3: 10bpp YUV chroma horiz subsampled by 2
         4: 8bpp uncompressed [pixel depth=8]
         5: 8bpp YUV chroma horiz and vert subsampled by 2
         6: 6bpp YUV chroma horiz and vert subsampled by 4
         7: 'Moving Blocks' compression
         [all but type 4 have pixel depth=16]
         8: 24bpp uncompressed
         9: 16bpp YUV chroma horiz subsampled by 2 (YYUV8)    (uses YUV)
        10: 12bpp YUV chroma horiz and vert subsampled by 2   (uses YUV)
        11: 9bpp YUV chroma horiz and vert subsampled by 4    (uses 6Y5UV)
        12: ARMovie file containing pointer to real MPEG movie
        13: MPEG video data in ARMovie file
         [all pixel depth=24]
        14: Ultimotion
        15: 'indirect' video
        16: 12bpp YUV chroma horiz and vert subsampled by 2   (uses 6Y5UV)
        17: 'Moving Blocks HQ' compression                    (uses YUV)
        18: h263                                              (uses 6Y5UV)
        19: 'Super Moving Blocks' compression                 (uses 6Y5UV)
        20: 'Moving Blocks Beta' compression                  (uses 6Y6UV)
        21: 16bpp YUV chroma horiz subsampled by 2 (YUYV8)    (uses 6Y5UV)
        22: 12bpp YY8UVd4 chroma horiz subsampled by 2        (uses 6Y5UV)
        23: 11bpp 6Y6Y5U5V chroma horiz subsampled by 2       (uses 6Y5UV)
        24: 8.25bpp 6Y5UV chroma horiz and vert subsamp by 2  (uses 6Y5UV)
        25: 6bpp YYYYd4UVd4 chroma horiz and vert subsamp by 2(uses 6Y6UV)

100-199: EIDOS

200-299: Irlam instruments

300-399: Wild Vision

400-499: Aspex Software

500-599: Iota

600-699: Warm Silence Software

800-899: Small Users of compression numbers
         Allocated by Sophie Wilson (SWilson@nc.acorn.co.uk)
         800-809: Henrik Bjerregaard Pedersen

900-999: Innovative Media Solutions

Different compression types may have different sound compression (indeed, the
entire meaning of the sound compression field is defined by the video
compression type). However, if the sound compression is the same as one of the
other sound compression methods, then the same number should be used - and,
conversely, if a different sound compression method is being used, then a
different number should be used. (Whew, what a nasty sentence). Thus companies
should either use recognised sound compression numbers (and code...) or they
should restrict their sound compression numbers to the same range as their
video compression numbers.

Providing new sound compression formats should be done in format 2: please book
names for sound format 2 decompressors with Acorn.

Decompress formats
------------------

For any formats which use the Decompress Interface, in particular format 1,
the Acorn Moving Lines compression algorithm, there are some restrictions to
the format:

- the chunks should be consecutive: the !ARMovie.Player tries to load pairs of
  chunks in order to address CD-ROM access latency.

- the chunks are on CD-ROM sector boundaries, padded by zero.

!ARMovie.Player understands audio types 0, 1 and 2. In format 1 there are 10
sound formats:

8 bit linear unsigned mono or stereo
8 bit linear signed mono or stereo
8 bit exponential mono or stereo
16 bit linear signed mono or stereo
4 bit ADPCM (compressed 16 bit linear) mono or stereo

The software decompression of 4bit ADPCM requires output buffers the size of
the supporting machine's sound format - 8 bit ones on current machines. In
format 2 there is an arbitrary number of sound formats.

A note about Stereo sound
-------------------------

For a stereo sample, the left channel is the first sample, the right the
second, etc. If this is not the case, include the word "reversed" in the
number of channels field: "2 channels reversed".

WARNING: for type 1, audio type 1, Stereo 16 bits linear assumes that the
start of each sound chunk is word aligned.

