* 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 .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