
* 5. File Formats:
~~~~~~~~~~~~~~~~~~

* 5.1 File Markers:
~~~~~~~~~~~~~~~~~~~

A marker is something that AMPlay can use to determine how to treat a
plain text file or an AMPlay file (&1b3). The marker must be in the
very first line of the file in order to work properly.

Eight markers are understood by this version of AMPlay;

[playlist]
[sequence]
[filter]
[links]
[volume]
[weight]
[ignoreunique]
[options]

A marker can be anywhere in the first line, and is not case sensitive.
The first character of the line must be a # character.

A typical first line might be;

# AMPlay 2.00 [Playlist].

Not all files are required to have markers at the start. There is a
configuration option to tell AMPlay how to interpret files with no
marker. However, this can only be used on the formats that are
effectively just a list of filenames (playlist, sequence, links and
ignoreunique). The other formats need extra information in the file,
and so a marker is required.

There is a further filetype (&1b2, AMPlayCf) for options files.
AMPlayCf files are handled by AMPlayCfg on double click, while AMPlay
files (&1b3) are handled by AMPlay itself . An options file can be of
either type, but is saved as &1b2 from AMPlayCfg.

________________________________________________________________________


* 5.2 Optimisation:
~~~~~~~~~~~~~~~~~~~

All the file formats make the assumption that the files listed in them
occur in the same order in the file as they do in AMPlay's database.
(The only exception being playlist files whose purpose is to add things
to the AMPlay database.)

When searching for tracks to match a path in the file being imported to
a track number, AMPlay starts searching from the track number it matched
previously (starting initially from 0).

If it hits the end without matching, it will start searching again from
the beginning until it gets back to its start point.

The upshot of this is that files being loaded don't _have_ to list their
files in the same order as they occur in the database, but the file will
import a lot faster if they do.

________________________________________________________________________


* 5.3 Playlists:
~~~~~~~~~~~~~~~~

One of the design criteria for AMPlay was that it should be able to
make use of files that are easy to generate with other tools. A
playlist is therefore a simple list of raw RISC OS pathnames;

Sunfish::Glod.$.Mp3.Ocean Machine.Biomech.01 - Seventh Wave/mp3
Sunfish::Glod.$.Mp3.Ocean Machine.Biomech.02 - Life/mp3
Sunfish::Glod.$.Mp3.Ocean Machine.Biomech.03 - Night/mp3
Sunfish::Glod.$.Mp3.Ocean Machine.Biomech.04 - Hide Nowhere/mp3
Sunfish::Glod.$.Mp3.Ocean Machine.Biomech.05 - Sister/mp3
Sunfish::Glod.$.Mp3.Ocean Machine.Biomech.06 - 3 A/M//mp3

Or whatever...

The list may include environment variables, paths, whatever you like.

Any line starting with a # character is assumed to be either a comment
or a marker, and will not be interpreted as a filename. Blank lines are
also ignored.

The playlist format differs from all the other formats listed in this
document in that it lists files which are not already known to AMPlay,
and provides a mechanism for telling AMPlay about such files.

All the other formats documented here contain paths to files that are
already in the AMPlay database.

________________________________________________________________________


* 5.3 Filters:
~~~~~~~~~~~~~~

A filter file is again very similar to the playlist format. It consists
of a list of the full paths to files that are already in the database,
with a marker in the first line to tell AMPlay to treat it as a filter
rather than as a playlist.

See section 2.4 for more information about what filters are and how they
work.

As generated by AMPlay, a filter file will comprise a header to
identify which filter slot is being editted, what name to give that
filter, and the default state of tracks with regard to that filter.

It then lists the filenames that differ from the default status, with a
statement on the preceding line to indicate their status.

e.g.

A typical filter file might start;

# AMPlay 2.00 [Filter].
# Filter Slot: 1
# Filter Name: SomeFilter
# Default: Always

Line 1 is the normal marker, telling AMPlay that this file
contains filter information.

Lines 2 and 3 tell AMPlay which filter slot the following information
relates to, and what name to give that filter. A slot must be specified,
but the name is optional (if absent, the existing name is retained).

Line 4 tells AMPlay the default settings to be used for newly
added tracks in that filter. The possible values are;

# Default: Always
# Default: Never
# Default: Isolated
# Default: Linear


These lines comprise the header. There are some requirements here;

- The slot number must be first, with the others following in any order.

- Only the slot number is mandatory - the others are optional. If not
  specified, the existing name and default settings survive.

The header is followed by;

- Lines indicating the filter state to be applied to the tracks
  that follow.
- Lines containing the full path to a file already known to AMPlay.

e.g.

# State: Linear
ADFS::Greebo.$.MP3.Artist.Album.Track1/mp3
ADFS::Greebo.$.MP3.Artist.Album.Track2/mp3
# State: Isolated
ADFS::Greebo.$.MP3.Artist.Album.Track3/mp3
# State: Never
ADFS::Greebo.$.MP3.Artist.Album.Track4/mp3
etc

The possible values of state are the same as that for Default.

As saved from AMPlay, only those tracks that differ from the default
are listed, but you can include such things in manually created filter
files (e.g. to force particular tracks back to the default setting).


Notes;

- A filter file can contain information about multiple filter slots;

  # AMPlay 2.00 [Filter].
  # Filter Slot: 1
  # Filter Name: SomeFilter
  # Default: Always
  # Load: Fast
  # State: Linear
  files...
  etc
  # Filter Slot: 2
  # Filter Name: AnotherFilter
  # Default: Always
  # Load: Fast
  # State: Never
  more files...

  i.e. just start a new header, and carry on.

- If the Default state is anything other than 'Never', then the filter
  is added to the available filters list (if it isn't already there).

- Filter status is only changed for tracks that are listed in the
  filter file. All other tracks retain their existing filter settings.

- AMPlay assumes that there are no duplicates in the database. Only the
  first match is processed.

- Nothing in the file is case sensitive, or sensitive to trailing,
  leading or internal spaces;

  # Default: Always
  
  and
  
  #default:always
  
  Are both valid. However, markers must be the only thing on their line;
 
  # Default: Always (enable all tracks by default)
 
  is not a valid marker, and would be ignored.

- As mentioned above, when saving filters from AMPlay, it only lists
  tracks that differ from the default. This normally means that filter
  files are quite small and import quickly. However if the default for
  new files does not match the majority of existing files, then the
  filter file could end up quite large.

________________________________________________________________________


* 5.5 Sequences:
~~~~~~~~~~~~~~~~

A sequence file is exactly the same as a playlist file, but with a
marker at the top to tell AMPlay to treat it as a sequence, not a
playlist.

It contains a list of the full paths to files that are already in the
playlist. AMPlay will match up the entries in the sequence file with
playlist entries, and will then play the files from the playlist in the
order that they occur in the sequence file.

This works by populating the track history with the files in the
appropriate order, and then setting the current point in the history to
be the start of the added sequence.

A side effect of this is that you can't load a sequence longer than the
configured maximum history size (the files after that point in the
sequence will be ignored).

If you save out the history, this is saved as a sequence file that can
be re-loaded.

There is one extra thing that can be in a sequence file - checklinks;

# Checklinks: True
# Checklinks: False

This is an optional keyword, and is false by default.

Normally when loading a sequence, the link to next status of the tracks
in question is ignored. This is because (in the case of an exported
history), they are likely to be already listed, and honouring their
link status would result in duplicate entries.

If a sequence file has a marker to set checklinks to true, then all
files listed after that point will have their link to next status
honoured. A subsequent checklinks line can turn this off again.

________________________________________________________________________


* 5.6 Volume:
~~~~~~~~~~~~~

Again, a list of files as in the playlist file, but with a marker
telling AMPlay to treat it as volume information.

See section 2.9 for more information on relative track volume.

As with the filter file, there are extra commands you can place in the
file to affect the way it behaves.

A typical file might start;

# AMPlay 2.00 [Volume].

This would be followed by blocks of tracks preceded by a vol command
specifying the relative volume for those tracks;

# vol: 20
file1
file2
file3
# vol: -5
file4
file5

etc.

The vol marker can take values from -63 to +63, and is not case
sensitive, or picky about spaces in the command;

 # vol:-5

 and

 # Vol: 45

 are both valid.

________________________________________________________________________


* 5.7 Link to Next:
~~~~~~~~~~~~~~~~~~~

Again, a list of files as in the playlist file, but with a marker
telling AMPlay to treat it as link to next information.

See section 2.8 for more information on Link to Next.

As with the filter file, there are extra commands you can place in the
file to affect the way it behaves.

A typical file might start;

# AMPlay 2.00 [Links].
# LinkType: Track

This would then be followed by a list of all tracks on which the
link to next flag should be set.

This might be followed by;

# LinkType: Album

Then a list of _tracks_. The tracks specify which album is to have its
link to next flag set.

Similarly;

# LinkType: Artist

Followed by tracks that specify the artist to have the link to next
flag set.

Only one track is listed for each Album or Artist. For files exported
from AMPlay, it will be the first track in the album or artist, but any
track will do.

Link to next files can contain one other command;

# Replace

This must go after the linktype, but before any tracks are listed. It
causes any existing link to next flags of the relevant type
(track/album/artist) to be cleared before the file is processed further.

If this is absent, then existing flags are left alone.

________________________________________________________________________


* 5.8 Weighting:
~~~~~~~~~~~~~~~~

Again, a list of files as in the playlist file, but with a marker
telling AMPlay to treat it as weighting information.

See section 2.10 for more information on weighting.

This has items in common with the link to next file format, and the
relative volume format.

A typical file might start;

# AMPlay 2.00 [Weighting].
# WeightType: Track

This would be followed by blocks of tracks preceded by a weighting
command specifying the weighting for those tracks;

# Weight: 4
file1
file2
file3
# Weight: -5
file4
file5

etc.

As with link to next, a # Replace keyword can follow the weighttype,
and any existing weightings are then set to zero before processing the
file further.

The weight command can take values from -7 to +7, and is not case
sensitive, or picky about spaces in the command.


________________________________________________________________________


* 5.9 Ignore Unique:
~~~~~~~~~~~~~~~~~~~~

This is very similar to the link to next format;

See section 2.7 for more information on uniqueness.

As with the filter file, there are extra commands you can place in the
file to affect the way it behaves.

A typical file might start;

# AMPlay 2.00 [IgnoreUnique].
# IgUniqType: Track

This would then be followed by a list of all tracks on which the
ignore uniqueness flag should be set.

As with link to next, there can then be

# IgUniqType: Album
tracks...
# IgUniqType: Artist
tracks...

The # Replace command can also follow the type statement, as for the
other formats.

________________________________________________________________________


* 5.10 Options:
~~~~~~~~~~~~~~~
 
AMPlay's option file is plain text, and if you want to edit that
directly rather than using the Options window there is no
particular reason not to.

As with the other file formats, # at the start of the line indicates
a comment.

When saving an options file from AMPlayCfg, comments in the file are
now retained. Any options which are not specified in the file are then
appended to the end with a comment from AMPlayCfg to say that it has
done so.

Nothing in the options file is case sensitive, or sensitive to trailing
or leading spaces, except for the album and artist separator strings
which could conceivably need leading or trailing hardspaces.

Note that AMPlayCfg will strip out obsolete options that only apply to
1.5x or earlier (it does this because the file is being saved to a new
choices directory, leaving the old one intact for 1.5x to read if it
wants to).

________________________________________________________________________


* 5.11 State:
~~~~~~~~~~~~~

A saved state consists of a number of files, between them storing
various current settings, as well as the AMPlay database itself;

state      - The current options, window positions and currently playing
             track and position.  It also contains information about
             what is stored in the other files.
trackdb    - Track attributes, other than the path to the file.
tlistdb    - Current post-filtered track list
searchdbi  - Index to searchdb
searchdb   - Search history (search blocks wadded together)
pathdb     - DB of paths to files. For files in the default directory,
             only a sub string is stored.
namedbi    - Index to namedb
namedb     - Extended name blocks, wadded together. All editted names
             and names derived from tags are stored here.
historydb  - Track history.
blistdb    - Current post-filtered album list.
artistdb   - Artist attributes
alistdb    - Current post-filtered artist list.
albumdb    - Album attributes.

The state, and the pathdb are text-readable, the rest are binary, and
are generally straight dumps of memory blocks. For details of the
format of these these files, refer to the documentation included
with the source.

There are few user-serviceable parts inside here.

You can, with caution, edit pathdb manually. Do not add or remove
lines. If using pathname based naming, with uneditted names, you may
need to do a refresh names afterwards.

The state files are stored in <Choices$Dir>.Audio.MP3.AMPlay2.db_[ver],
where [ver] is the format version for the database. Currently this is
200, as although AMPlay is now at 2.03, no changes to the database
format have been made.

If you have the option to keep a backup of state files enabled, every
time an operation would overwrite one of the files in db_200, it is
first copied into db_200.Backup. Only one backup is kept. 

________________________________________________________________________
Copyright  2008 Mike Sandells, mike@mikejs.com
Last Modified: 30.05.2008