* 2. Main Features: ~~~~~~~~~~~~~~~~~~~ * 2.1 Tracks, Albums, Artists: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before I go on about the various things that you can do with AMPlay in any more detail, it is worth covering something which AMPlay currently assumes. AMPlay assumes that every Track comes from an Album, which is in turn by an Artist. Albums and Artists need to have names, and these names need to be obtained from somewhere. * 2.1.1 Establishing Names: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ AMPlay has two ways of establishing this information; 1. From the path and filename. (Pathname based naming) If, for example, I have a file; ADFS::IDEDisc.$.MP3.Crowded House.Woodface.Chocolate Cake/mp3 Then the track name can be worked out from the filename, while the Album is the parent directory, and the Artist is the parent directory of the album. By default, this is how new tracks are treated. It is also the fastest method (it doesn't involve reading the contents of the file), and is the most efficient to store (because we have to store the path to the file anyway). Some people have strong opinions on this point, but pathname based naming is recommended. (See 2.1.2, below, for why.) 2. From the MP3 ID Tag on the file, if any. (Tag based naming) The tag contains fields including a trackname (it calls it a songname, but not all MP3s are songs), album name and artist name. AMPlay stores this information internally, and does not need to re- read the tag each time it needs the name information for a given track. AMPlay can be configured to use this for new tracks. This is slower in terms of getting the information into AMPlay in the first place, and also requires extra data (the copy of the tag) to be stored per track, and so raises the memory requirements. The tag must be v1 or v1.1 format. v2 tags are not supported. Once the naming information is in the AMPlay database, it is edittable, resulting in a third possible source of information; 3. You enter the information manually. (path or tag, editted) New tracks can't use this by default. What method to use can be set on a per-track basis. You can mix and match tags, pathnames and editted versions freely. When editting naming details, you are not subject to the restrictions on name length that apply to the name fields within the tag, even if the naming details came from a tag. However, if you choose to write the information back to the tag, the names might be truncated. * 2.1.2 Boundary checking: ~~~~~~~~~~~~~~~~~~~~~~~~~~ AMPlay uses the naming information to determine boundaries - these are the points at which albums and artists begin and end. Albums may not span artists, so an album is effectively a grouping of tracks, while an artist - as far as AMPlay is concerned - is a grouping of albums, and therefore also a grouping of tracks. AMPlay scans for boundaries by checking each track in turn and comparing the artist and album names with those of its neighbour. If they differ, a boundary is declared, and the tracks on either side of it belong to different albums and possibly different artists. For boundary checking to work sensibly, either the naming information needs to be consistent, or the settings need to be relaxed such that inconsistencies are ignored. e.g. If one track has the artist name in upper case, and the next track by the same artist has that name in lower case, then AMPlay will declare an artist and album boundary at that point unless it is told to be case insensitive. Ignoring inconsistencies like this makes the checking slower. This is the main reason why tag-based naming is not recommended as the default - it requires not only that tracks be tagged, but that they be tagged consistently. Placing files in the same directory on disk guarantees that their pathname-based names will be consistent, but does not guarantee anything about their tags. To get the most out of AMPlay's features, the album and artist boundaries need to be accurate. How the boundary checker behaves is very closely related to how the database sort routines work, so the same options of case sensitivity etc apply to both. For more information on these options refer to the section 4.6. Naming issues are discussed further in several sections in the FAQ, notably in sections 6.2 and 6.20. ________________________________________________________________________ * 2.2 Features Overview: ~~~~~~~~~~~~~~~~~~~~~~~~ The individual features are covered in more detail below, but in many cases they interact. This brief overview covers how it all fits together. When AMPlay gets to the end of playing a track, it looks to see if there are more tracks queued to be played. If there are, it plays the next one from the queue. When changing from one track to the next, it adjusts the effective volume as needed, based on the relative track volume. If there are no more tracks in the queue, it calls a function to add more tracks to the queue. The function to add tracks determines whether it should be picking an artist, album or single track, and if it's an artist or album, how the tracks (and possibly albums) within it should be treated. It picks a candidate item (track/album/artist) from the post-filtered list. If the candidate is linked to by the previous item, it is rejected, and another one picked (to ensure that linked items always start with the first item in the linked sequence) until we get a candidate that passes the link test. It then generates a random number and checks whether the weighting on that item exceeds that number. If it does not, the candidate is rejected and another one picked, until one has passed both the weighting test and the link test. It then examines the history of recently played items to check whether the candidate item has been played recently. If the item has the Ignore Uniqueness flag set on it, then it passes this test automatically. The test for albums and artists is slightly complicated in that it will initially reject albums and artists where any of their tracks have been played recently. If that appears to be looping without finding a good candidate, it becomes more lenient, and will eventually allow albums/artists where some tracks have been played. This repeats until we get a candidate that has passed the link, weighting, and history tests. If the candidate makes it through these tests, it is finalised - it will be played. The function then adds the item to the queue, shuffling albums within artists, and tracks within albums or artists as appropriate to the playback order settings. As part of this, it honours the link to next settings, ensuring that any shuffling process keeps linked items together. If the item itself is linked to the next, then that is added to the queue in the same way. AMPlay then starts playing the next track from the newly extended queue of tracks. Filtering, linkage, playback order and relative track volume also apply when manually telling AMPlay to play a particular item. ________________________________________________________________________ * 2.3 Playback Order: ~~~~~~~~~~~~~~~~~~~~~ A major part of AMPlay has the job of deciding what to play next. You can tell AMPlay specifically what to play next, but when it runs out of tracks, albums or artists that you've told it to play, it either has to decide for itself or stop playing. It has many different modes that it can operate in, but it boils down to three questions which determine the playback order; 1. Do we care what order the artists are played in? - If so, in linear or random order? 2. Do we care what order the albums are played in? - If so, in linear or random/shuffled order? 3. What order should we play the tracks in - linear or random/shuffled? Questions 2 and 3 depend on the answer to their predecessor(s). There are 18 possible different sets of answers to these (although some combinations produce the same result). In the above; 'Linear' refers to the order that the items occur in the AMPlay database. By default this would be alphabetical order, but if sorting is disabled it would be the order in which tracks were added, or whatever order you've manually re-arranged things into. 'Random' refers to the selection of a single item at random. This applies if the item in question is the first thing we care about. 'Shuffled' refers to a group of items that have been shuffled into a randomised order. This happens for things inside something that has already been picked (e.g. we've picked an album, and are shuffling the tracks within it). e.g. Artists: Random Albums: Shuffle Tracks: Linear This would pick an artist at random, play all the albums by that artist in a shuffled order, but with the tracks within each album played in the order they occur in the database. Another term that is used elsewhere in the documentation is the 'Selection level'. In the above example, the selection is taking place at the artist level as that is the first thing to be chosen. If Artist is set to 'Ignore', then Album would become the selection level because Artists would take no part in the selection process. If both Artists and Albums are set to Ignore, then the selection takes place at the track level. Tracks cannot be ignored as there is no lower level to go to. The distinction between random and shuffled is worth bearing in mind, but it can be clumsy referring to albums or tracks as random/shuffled when either might apply, so in such cases, "random" is used as a shorthand for anything other than linear order. At no point is there an option for anything other than linear or not-linear, where not-linear is truly "random" if it is the selection level, or "shuffled" if the selection level is at some larger grouping. The situation; Artists: Ignore Albums: Ignore Tracks: Random is often referred to as 'random track mode'. All other modes have the tracks either shuffled or linear, so this mode stands out. The main window indicates the current playback order, and provides the interface to changing it - refer to section 3.1.2 for more details on this. Many things can dictate or influence the method by which tracks, albums and artists are selected - filtering, weighting, ignore uniqueness, link to next, as well as some overall options. Refer to section 2.2 for how these features interact. There is a final extra state for playback order - total chaos. This is enabled by ctrl+clicking on any of the order icons. This causes the playback order itself to change at random every time something is picked. It might pick an artist, then a single track at random, then the next album, shuffling tracks within it etc. (In practice this can give less variety than random track mode. Random track mode gives maximum variety - chaos mode gives a random amount of variety. Think about it.) Chaos mode is turned off by selecting any ordering option for any of tracks, albums or artists. ________________________________________________________________________ * 2.4 The History/Queue: ~~~~~~~~~~~~~~~~~~~~~~~~ As tracks are played by AMPlay, it stores a history of what has been played. This is available to allow you to go back and play the same sequence over again. The history is also used as part of the mechanism that avoids playing the same thing twice in close succession. Various features within AMPlay work by adding a sequence of tracks to the history, and setting the current history position to just before the start of the added sequence. This means that there may be things not yet played in the history - i.e. it acts as a queue of what to play next as well as a log of what has been played. The history/queue is accessible via three menus for Track, Album and Artist history. However, track history is all that really exists under the covers. The others are worked out from the track history. These menus are produced by clicking on the history menu buttons on the main window (to the left of the track, album and artist names), or from the AMPlay main menu, under History. The current position within the history is indicated by a tick. Note that there is a current history position even if there is no track currently playing. If you click next, the next item in the history will be played, or if there is no next item, a new one will be calculated using the current playback order, which may add one or more tracks to the history. Play will play the currently ticked item. The number of items in the history has a maximum (see section 4.6), after which the oldest entries will disappear from the list. By default this maximum is roughly equal to the number of tracks in the database, so the history can get quite long if you want it to. The first item in the menu is Clear History. For the other items; Clicking Select on an item will set that to be the current history position and start that item playing. Clicking Adjust will set the current history position to just prior to the clicked item, so that the one you clicked will be played when the current track ends. Clicking Shift+Adjust will remove the clicked item from the history. The history can be exported if you want to. Such history files (or manually generated ones) can be used to tell AMPlay to play tracks in a particular sequence (such files are called sequence files and are covered in more detail in section 5.4) Other operations on the history, such as removing all history entries for a particular track, album or artist, can be done from within the database editor. See section 3.4.4 for details on this. ________________________________________________________________________ * 2.5 The Goto Menus: ~~~~~~~~~~~~~~~~~~~~~ The Goto menus are a set of six menus that can be accessed by clicking Select or Adjust on the Track, Album and Artist entries on the main window. The Search results menu also counts as a Goto menu. - track select: menu of tracks in current album - track adjust: menu of tracks by current artist - album select: menu of albums by current artist - album adjust: menu of all albums - artist select: menu of all artists - artist adjust: menu of all tracks The menus that rely on what is currently playing will be empty if the player is stopped. The other menus are always available as long as there is at least one track in the database. For the items in the menu; - Clicking Select will play that item now. - Clicking Adjust will queue it without altering the current position in the history. - Clicking Shift+Adjust will queue it to be played when the current track ends. (i.e. it alters the current history position to just before the newly added item) If an album is clicked, then the tracks within it will be treated as for the current playback order (i.e. if the current playback order involves shuffling tracks, then they will be shuffled). Similarly, if an artist is clicked, then the albums (and within them, tracks), will be treated as specified by the current playback order. Tracks are just tracks, so if you click on one, that's what you get. Filtering is also taken into account - if an album or artist is clicked then only the tracks within it that pass the current effective filter will be played. Artists and albums that contain no tracks that pass the filter will either be greyed out or omitted from the menu entirely (configurable). Likewise for tracks. If the item you clicked on is between the current history position and the top of the history, then AMPlay will just slide up the history position as appropriate and either play the item from there (Select), or play it next (Adjust). If it was a track that was clicked on, it will also search back a short distance (number of tracks in current album) in the history, and if the track is there, will play it from there. This is so that if you are playing an album, and use the goto track menu to skip forward a few tracks within that album, it doesn't just add that track to the end of the history, but ensures that any remaining tracks are played. The format of the Goto Menus is configurable - see section 4.5 The Play/Queue action in the Database Editor functions in the same way as the Goto menus. See section 3.4.4 for more information. If using Adjust to play things later rather than immediately, a message will appear briefly on the main window to let you know that the request has been dealt with. ________________________________________________________________________ * 2.6 Filtering: ~~~~~~~~~~~~~~~~ The aim of filtering is to allow you to include all your tracks in the AMPlay database. You then set up a filter that just allows through the subset of tracks that you want have available to you at the time. You don't have to pay any attention to filtering if you don't want to - by default there is only one filter, and all tracks are allowed through it. If you leave the filter settings alone, everything you add to the database will be available. If a track is blocked by a filter, it doesn't mean that you can't play it. It just means that AMPlay won't pick it or include it when picking what to play next. If it was queued before being blocked, it will still be played. If you choose it manually (via the database editor, see later), it will be played. AMPlay can store information about up to 20 filters, some or all of which may be active at any one time. This allows you to create various groupings of tracks that you might want to have available together. Each filter can be given a descriptive name. The filters are additive - e.g. if track1 passes filter1 and track2 passes filter2, and both filter1 and filter2 are active, then both track1 and track2 are available. The combination of all the active filters is known as the current effective filter. As an example of what filtering is useful for; I have quite a few backing tracks in the database that I use for playing guitar over, but wouldn't want to come up when I'm just listening to music. I have a filter called Backing Tracks, and this allows through the backing tracks. When I want to use these, I just have to change which filters are active. This is better than having to re-add the files because AMPlay already has all the information it needs about those files - it has the name information cached, as well as the tag and duration information if it needs them. Toggling a few bits in a filter when adding them and a few bits later to decide which filter to use is a lot less work than having to re-read the mp3s themselves to work out this information. As another example, a lot of the stuff in our collection is fairly heavy metal, and not everyone's cup of tea. If we have guests round, it's easy to change to a filter that constrains AMPlay to just playing the more mellow stuff that is acceptable in the background. Each filter has an entry for each track, where the entry will be one of the following; - Never play - Play in linear modes only. - Play in isolation only. - Always play. "Never play" is self-explanatory. Tracks with this set are not allowed through that filter, and AMPlay won't pick them (but note that if multiple filters are active, a track only needs to pass one of them in order to be available). "Always play" is equally self-explanatory. Tracks with that set are allowed through the filter, and AMPlay is able to pick them. The other two mean that the track may or may not be allowed, depending on the current playback order (discussed in more detail in section 2.3.) "Play in linear modes only" means that the track is allowed through the filter if the current playback order is one that plays tracks within albums in the order that they occur with the database. Typically you would set this on tracks that are not actual pieces of music as such, but are joining pieces. My example of this is The Blind Guardian album, 'Nightfall in Middle- Earth'. This has a number of actual songs, but between each song is a short piece of speech or sound-effect that joins the songs together. These short pieces only make sense in the situation where the complete album is being played, with the tracks in the right order. In any other situation, they aren't wanted. So, the real songs in that album are set to 'always play', and the joining pieces are set to 'play in linear modes only'. This means, if I happen to change the order method to random tracks, it can still pick one of the real songs at random and play it, but will not be able to pick one of the joining pieces. "Play in isolation only" is pretty much the reverse of the above. I have an album which consists of nothing but remixes of the same track ('Go', by Moby). It's a bit much to listen to all of them at once, but I have no objection to any particular tracks - it's just in combination that they get boring. So, all the tracks in this album are set to 'play in isolation only'. This means that they will not be allowed through the filter for any playback order that results in the entire album being played in one go. Effectively this means that they are only allowed through the filter when the order method is random tracks (with albums and artists being ignored completely). This means that the number of tracks that can pass through the current effective filter may change depending on the playback order selected - you may see this on the main window when changing the playback order (it only displays this information if the total did in fact change). Filtering can only be set at the track level. Filters on albums and artists do exist, but are calculated and cannot be editted independantly of the tracks (i.e. if you change the filter on an album/artist via the database editor, this is just a shortcut for performing the same change on all the tracks in that album/artist). Throughout the rest of this documentation, there may be references to pre-filtered and post-filtered lists. This reflects the way AMPlay works internally - the pre-filtered list is the database of all the tracks that AMPlay knows about. The post-filtered list is just those tracks that pass through the current effective filter. Filtering applies to the process of picking what to play next - if you manually tell AMPlay to play a specific track, it will do so regardless of whether that track would be allowed through the filter. For albums and artists, if you manually tell AMPlay to play one, it will do so, but only those tracks within the album or artist that pass the filter will be played. If you tell AMPlay to play an album/artist, where no tracks are allowed through the filter, then no tracks are played. There are three ways of altering the filter settings on a track; - Using the database editor - see section 3.5. - Using the Search window - see section 3.2. - By creating a filter file, and dragging that onto AMPlay. See section 5.4 for the format of a filter file. For settings that affect all tracks, use the Filter Editor - see section 3.4 By default, multiple filters can be active concurrently. The effect of this is that anything that passes through any active filter is available to be played. i.e. an item must be blocked by all active filters in order to be effectively blocked. See the configuration section 4.9 for details on the 'prefer single filters' option to make this area behave closer to 1.5x. ________________________________________________________________________ * 2.7 Uniqueness, and ignoring it: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When AMPlay needs to pick another track/album/artist (as specified by the current playback order), then if it needs to do so in a linear order, it just picks the next item in the database. (Optionally, if it reaches the end of the database, it can go back to the start and carry on from there.) However, if it needs to select one at random, then it goes through a process whereby it tries to avoid picking things that have been played recently. This is a configurable parameter, but by default it will look back through the history of what has been played, for a number of entries equal to 75% of the items available to it. As it picks things at random, it checks to see whether they are in that most recent (up to) 75% of the history, and if so discards them. e.g. suppose there are 1000 tracks in the database, but the current filter is such that only 100 tracks are available in the post-filtered list. AMPlay would check the most recent 75 history entries (or the entire history, if it contains less than 75 entries). The above applies to the process of picking tracks. For albums and artists, which are collections of tracks, it gets a bit more complicated; If AMPlay needs to pick an album, it will start off testing every track in the album, in the hope of picking an album where none of the tracks in that album have been played recently. Sticking with the above example numbers, it's quite possible that you've been in random track mode recently, and the most recent 75 history entries contain at least one track from every available album. i.e. there may not be an album that hasn't had at least one track played recently. So, after 100 attempts (this is a hardcoded value at present) with no success, AMPlay aims lower, and looks for an album where the first track in the album hasn't been played recently. It carries on with that for 1000 attempts (also a hardcoded value). If it still hasn't found a suitable album, it goes back to checking every track in the candidate album, but this time it is looking for any album that has at least one track that hasn't been played recently. As there are 100 tracks available and we're only checking 75 history entries, there are 25 tracks out there that would allow their album to be chosen. An album should be chosed fairly quickly, but if after another 1000 attempts no suitable candidate has been found, it will give up and stick with the unsuitable candidate it was considering at the time. The same mechanism is used for picking artists at random. Uniqueness is not considered once AMPlay is at the stage of shuffling albums within the artist, or tracks within the album. Having discussed what uniqueness is, and what AMPlay does with it, we have the option to ignore it; Ignore Uniqueness is a flag that indicates to AMPlay that the item in question is one that you don't mind hearing frequently. i.e. If AMPlay selects an item at random, and that item has the ignore unique flag set, then it should go ahead and play it without regard to whether it has been played recently or not. This flag can be set on tracks, albums or artists, and exists independantly on each. (i.e. an album can have ignore unique set even if none of the tracks in it do). AMPlay only pays attention to the ignore unique flags that are relevant. i.e. if it is picking an album, the the flags on artists or tracks are not considered. There are three ways of altering the ignore uniqueness settings on a track; - Using the database editor - see section 3.5. - Using the Search window - see section 3.2. - By creating an ignore uniqueness file, and dragging that onto AMPlay. See section 5.9 for the format of an ignore uniqueness file. ________________________________________________________________________ * 2.8 Link to Next: ~~~~~~~~~~~~~~~~~~~ Link to Next is a way of telling AMPlay that a pair of items (tracks, albums or artists) go together and should not be separated. Setting Link to Next on a track means that whenever that track is played the track immediately after it in the database will be played next. If that also has the Link to Next flag set, then the next track will also be played, and so on. It's useful in the case where a piece of music has been encoded as more than one mp3 file. By setting Link to Next, you can ensure that this is played as a single piece of music rather than as the separate mp3s. It's also useful in the case of 'double' albums, where one sequence of tracks is supplied on two physical disks. By linking the albums together, it will be treated as a single album as far as playback is concerned (it still counts as two albums as far as menus etc are concerned). It is only of any real use if you are using some sort of random or shuffled mode. If you have everything set to linear, then everything gets played in the database order anyway and linking items would have no effect. Link to next has priority over filtering . If link to next is set on track 10, then when track 10 is played, track 11 will follow it, even if track 11 would not otherwise be allowed through the current effective filter. Generally, this isn't a problem, because you're unlikely to want to link two tracks, but then filter one of them. As far as the Goto Menus are concerned, you always start with whatever you clicked on in the menu. So, if you have linked track 2 to track 3, and track 3 to track 4, and you click on track 3 in the menu, it will play track 3, and then 4. It won't follow the link back to track 2 (this is by design, not a fault in the program). The random track picker however, will always start that sequence at track 2, and thereby play tracks 2, 3 and 4 in order. Linkage applies at the point where items are added to the history/queue - i.e. if something is already in the queue to be played, changing its link status won't change anything. Albums and artists can be linked in the same way as tracks, and independantly of any link setting at the track level. Note that a track cannot be linked with another track that is from a different album (i.e. can't link the last track in one album with the first track of the next). Similarly, the last album by an artist can't be linked with the first album by the next, and the last artist in the database can't be linked with anything. There are three ways of setting link to next; - Using the database editor - see section 3.5. - Using the search window - see section 3.5. - By creating a linkage file, and dragging that onto AMPlay. See section 5.7 for the format of a linkage file. ________________________________________________________________________ * 2.9 Relative Track Volume: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is a system that allows you to compensate for tracks/albums appearing quieter or louder than the average in your music collection. The player has a basic volume setting that is referred to as the player volume. To this is added the relative track volume. The end result is the effective volume at which the track is played. What other AMPlayer front ends report will be the effective volume. By default, the relative track volume is zero, which means that the player volume is used unchanged. If you set a +10 relative track volume on a particular track, and the player volume is 40, then the effective volume will increase from 40 to 50 while playing that track. The relative track volume can also be negative if you want to make that track quieter rather than louder. Using the main window volume control will adjust the player volume, although the effective volume changes as a result. If you had the player volume at 40, and the relative at 10 the effective would be 50. If you then reduce the player volume to 35, the effective would drop to 45. The AMPlayer volume range is 1 - 127. The effective volume is constrained to remain within this range. So, if the player volume is 100, and the track volume is +50, the effective volume is 127. AMPlay still remembers both the player and track components correctly, and just constrains the effective volume. The relative track volume must be in the range -63 to +63. If you adjust the volume using another AMPlayer front end this will adjust the effective volume. AMPlay knows what the track volume is, and will work back from this and adjust the player volume accordingly. There are three ways of setting up relative track volume; - Using the database editor - see section 3.5. - Using the main window - see section 3.1.2. - Using the search window - see section 3.1.2. - By creating a volume file, and dragging that onto AMPlay. See section 5.6 for the format of a volume file. ________________________________________________________________________ * 2.10 Weighting: ~~~~~~~~~~~~~~~~~ Weighting allows you to influence the random selection of items. All items (tracks, albums or artists) can have a weighting set that will increase or decrease the chances of that item being picked. (Or, more precisely, the chances of that item passing the weighting test.) The weighting that applies depends on what is being picked. i.e. if AMPlay is picking an album, it uses the album weighting, ignoring any artist or track weightings. A weighting can be from -7 to +7. A -7 weighting will still be picked occasionally, and a +7 weighting will still be rejected occasionally. Essentially an item weighted -7 will be picked and rejected 15 out of 16 times, and picked and accepted only 1 out of 16 times. For a +7 weighting, these numbers are swapped - rejected 1/16, accepted 15/16. There are three ways of setting up a weighting; - Using the database editor - see section 3.5. - Using the search interface - see section 3.5. - By creating a weighting file, and dragging that onto AMPlay. See section 5.8 for the format of a weighting file. ________________________________________________________________________ * 2.11 Custom Buttons: ~~~~~~~~~~~~~~~~~~~~~~ The main window has three buttons to the right of the volume control that can be assigned to run external programs, open directories, run commands etc. Separate actions can be defined for Select and Adjust clicks. For more information on how to tell AMPlay what to do with these buttons, refer to the configuration section 4.1. ________________________________________________________________________ * 2.12 Macros: ~~~~~~~~~~~~~~ Various parts of AMPlay let you alter the format in which information is displayed. The details of the format are specified by macros. A macro is simply a percentage sign, possibly followed by one or two modifier letters to control the output format, then a two letter combination to give the macro name. AMPlay expands the macro to give the information required. Any text that doesn't form part of a valid macro is passed through unchanged. e.g '%tn' would be expanded to the name of the track. When entering macros in AMPlayCfg, and AMPlay is running, interactive help will display what the macro currently expands to, if possible. * 2.12.1 Basic Macros: ~~~~~~~~~~~~~~~~~~~~~~ This is not a complete list, but covers all the macros you're likely to find useful on the main window or in the menus. +-----+------------------------------+----+---------------------------+ |Macro| Expands to |Any1| Info | +-----+------------------------------+----+---------------------------+ | %tn | trackname | y | from name format | | %bn | album name | y | from name format | | %an | artistname | y | from name format | | %pf | path to file | n2 | including filename/ext. | | %tc | track comment field | y3 | from name format | | %ty | track year field | y3 | from name format | | %te | track genre | y3 | from name format | | %tr | track genre number | y3 | from name format | | %th | track number within album | y34| from name format | +-----+------------------------------+----+---------------------------+ | %tt | tag trackname | n5 | All read from mp3 tag | | %bt | tag album name | n5 | | | %at | tag artistname | n5 | | | %mt | tag comment | n5 | | | %ge | Genre name | n5 | | | %gn | Genre number | n5 | Padded out to 3 digits. | | %it | tag track number | n5 | | +-----+------------------------------+----+---------------------------+ | %tb | track number within album | y4 | | | %ta | track number within artist | y | | | %tg | global track number | y | All padded to whatever | | %tp | track number within database | y | the maximum value for | | %ag | global artist number | y | that field is. | | %ap | artist number within database| y | | | %bg | global album number | y | | | %ba | album number within artist | y | | | %bp | album number within database | y | | +-----+------------------------------+----+---------------------------+ | %vv | base volume | y | In AMPlayer units | | %pv | player volume | y | | +-----+------------------------------+----+---------------------------+ | %el | track elapsed time | n | In mm:ss for current | | %re | track remaining time | n | track | | %du | track duration | n | | +-----+------------------------------+----+---------------------------+ | %td | track duration | y6 | In mm:ss for any track | | %ad | artist duration | y6 | In hh:mm:ss for any artist| | %ae | artist elapsed | n | current artist only | | %ar | artist remaining | n | current artist only | | %bd | album duration | y6 | In hh:mm:ss for any album | | %be | album elapsed | n | current album only | | %br | album remaining | n | current album only | | %pd | playlist duration | n | } | | %pe | playlist elapsed | n | } In dd:hh:mm:ss | | %pr | playlist remaining | n | } | +-----+------------------------------+----+---------------------------+ | %st | suffix for last numeric | y | e.g. st,nd,rd, or th | +-----+------------------------------+----+---------------------------+ | %in | menu index | y | Only used in menus | | %hi | history position | y | Only used in history menu | +-----+------------------------------+----+---------------------------+ Notes: 1 - This column refers to whether the macro can be used in reference to any track/album/artist, or is tied in some way to what is currently playing. e.g. remaining time in the current track is meaningless when applied to an arbitrary track. Generally speaking, macros that apply to the current track are only useful on the main window, and are not useful in menus, searches, the database editor or anywhere else. 2 - %pf returns the raw path to the file, without any text conversion. You therefore can't use the lower/upper/caps modifiers with it, and the AMPlay options of converting slashes, underscores, and lanman characters aren't applied to it. 3 - If the track uses pathname based naming, then there isn't a direct source of year, comment or genre information. The genre is unknown, and the comment will be the default comment string. The year will always come out as 2008. If you edit a pathname based name, you can change these from their defaults, in which case the information you provided will be returned. 4 - %th and %tb appear to do very similar things, but they may return different values. %tb returns the position of the track within the album. %th on the other hand returns the track number attribute that is stored for the track (if any). E.g. if the naming information came from a tag, then %th will return, for any track, the tag track number. e.g. If an album has 10 tracks, and each track is tagged with its track number, but you only add tracks 7, 8 and 9 to the AMPlay database then %th will return 7, 8 and 9 for each track respectively. %tb will return 1, 2 and 3. 5 - These are derived directly from the tag information on the currently playing track. They work even if the currently playing track is not set to get its naming information from the tag (i.e. it uses a pathname based name). 6 - Obviously, the track duration only makes sense in track menus, the album duration or no of tracks in album in album menus etc. * 2.12.2 Basic Modifiers: ~~~~~~~~~~~~~~~~~~~~~~~~~ l = lowercase u = UPPERCASE c = Leading Capitals On All Words w = Leading capitals on first word only. z = no leading zeros f = Only calculate for filtered tracks. Current filter applies. (only applies to artist, album and playlist durations, elapsed and remaining times, and sum totals.) x = Try to trim leading numeric information from the name. (e.g. change '01 - Trackname' to 'Trackname') n = Skip macro if name already starts with a numeric. (e.g. If %tn is '01 - Trackname', then %ntb would produce no output. If it was just 'Trackname' then %ntb would produce the tracknumber as output.) N and X are covered in more detail in section 2.12.5. Note that you should use one or the other (if at all), but not both. * 2.12.3 Macros in Practice: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This all probably sounds remarkably like chinese, but is actually very simple. Let's look at the default setting for the track information on the main window: "%tn (%zdu)" When AMPlay needs to display the track name in the top of the window, it looks at this, and replaces the "%tn" with the name of the currently playing track. The "%zdu" introduces modifiers. This is the "%du" macro with the "z" modifier added. The "%du" is replaced by the duration of the track, and the modifier "z" tells it not to include a leading zero. The parts of the string "%tn (%zdu)" which do not contain valid macros (the space and the parentheses) are passed through unchanged. If the currently playing track was Regulator, by Devin Townsend, from the Ocean Machine album, then the track name on the main window would display "Regulator (5:06)". Then it would look at the album, and see that it was being asked to display; "%bn" Which would be "Ocean Machine" in this case, and the artist is "%an" Which expands to "Devin Townsend". * 2.12.4 Modifiers in Practice: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The modifiers can be used to control the formatting to a finer degree. They are placed between the % and the rest of the macro name. For example, the "l" and "u" modifiers can be used to force AMPlay to display the output from the text based macros in all UPPER or all lower case. "c" can be used to produce output in Leading Capitals, and "w" can be used for Leading capitals on the first word only. As covered above, the z modifier suppresses leading zeroes. l,u,c,w therefore apply only to text, while z applies only to numbers. Try %ltn, %lan and %lbn for a more minimalist look. The "f" modifier is used to tell AMPlay to use the post-filtered list for its calculation, rather than the pre-filtered one. e.g. If some tracks in the current album are not allowed through the current filter, then %bd will give the total duration of all the tracks in the album. However, %fbd will give the total duration of only those tracks that pass the filter and make it into the post-filtered list. Having got this far, it's probably best to try things and see what you get. Also, note that interactive help will show you on the fly what the macro expands to, so long as AMPlay is running. * 2.12.5 Advanced Modifiers: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The two advanced modifiers are "n" and "x". They are both aimed at solving the same problem, but take different approaches to it. The problem is this; %tb gives the track number within the current album. This is not necessarily the number that the track had on that album. If, like me, you have some albums where the track names were not numbered when they were generated, you may find that the tracks now play in alphabetical order rather than the original order. AMPlay does not know what the original order was, so it cannot correct this, and just displays the number the track now has within the album. To keep to the earlier example, "%tb - %tn (%zdu)" would give "09 - Regulator (5:06)". This is all very well, and we now have track numbers displayed against the track names, but what happens when we start playing a track that already has a track number as part of the actual name of the track? A mess, that's what: "09 - 09 Scarred (9:27)". (Having jumped into the Dream Theater part of the database). This is because "%tn" itself expands to "09 Scarred", and we stick an extra "09 - " on the front. There are two possible solutions to this problem; - Only include the track number in cases where the trackname does not include one. This is what the N modifier tries to do. - Trim the numeric information from the trackname in some way. This is what the X modifier tries to do. Either of these is sufficient in itself. Trying to use both together is counterproductive. There is also an FAQ on the tracknumber problem - see section 6.21. The N Modifier ~~~~~~~~~~~~~~ If you include the "n" modifier in a track/album/artist number macro, and the track/album/artist name starts with a numeric, the macro is ignored completely. So, while "%tb - %tn (%zdu)" gives the above mess, "%ntb %tn (%zdu)" gives " 09 Scarred (9:27)" - much nicer. This allows you to add track numbers only to tracks that don't already have them. This works ok as far as it goes, but you'll notice that whereas before we had "09 - Scarred", we now have " 09 Scarred". We've lost the hyphen from the middle, and gained a leading space. We also have problems if the track name starts with a numeric that isn't anything to do with the track number (e.g. Green Day's "86"). The X Modifier ~~~~~~~~~~~~~~ The x modifier is a more sophisticated approach, and works as follows; - It looks at the left hand edge of the track/album/artist name. - If this contains a number, it carries on reading numbers from the left hand edge until it has either read three numbers, or run into a character that isn't a number, or the end of the name. - It works out the numeric value of this number, and compares it with the track within album, album within artist, or artist within database number as appropriate. - If this matches, it strips the number that it read, plus any non-alphanumeric characters that follow from the left hand edge of the name. The first alphanumeric character that it hits stops this trimming. Extra characters can be specified that will also stop the trimming (e.g. for tracknames that start with a punctuation character such as a left bracket) In our example, it would take "09 Scarred", read the 0, then the 9, and combine that to give a string "09". The numeric value of this is 9, which matches the track number within the album. It would therefore strip off the "09", and the characters that follow it, until the "S" which would stop the trimming. The resulting string is "Scarred". We can then come up with a macro sequence that works for pretty much anything - "%tb - %xtn (%zdu)". This will give identically formatted output irrespective of whether the trackname has the track number in it or not. It also means that tracks formatted in "01 Trackname" format are displayed as "01 - Trackname", which improves consistency. Notes; - The x modifier fails if not all the tracks in an album are present in the database. If, for example, I hadn't added all the Dream Theater tracks to the database, The track with the name "09 Scarred" might not have been the ninth track in the album, in which case its position within the album would have been displayed anyway. If, for example, it was the eighth track in the album, it would have been displayed as "08 - 09 Scarred". This is another reason to add all tracks, but filter the ones you don't want at the moment. - It also fails if the track name starts with a non-alphabetic character that isn't in listed in the options (the default list of non-alphabetics that will stop trimming is '([{./\') - Not a failure as such, but note that the X modifier is applied fairly early in the string processing sequence, before any text conversion options are applied (these are discussed in section 4.2.3.) This means that options that convert underscores to spaces, and the like, do not apply until after the X modifier has done its work. Note that if you are using X, you should not be using N in the same string. For example; "%ntb - %xtn" will always come out to just " - Trackname". N will suppress the %tb, while X will trim the number from the front of the trackname. Always use one or the other. X is more CPU intensive, and is probably not a good idea to use in menus, otherwise the menu will take a moment to open (particularly if there are a large number of items on it). N is relatively quick, and much more suitable for use in the menus. * 2.12.6 Advanced Macros: ~~~~~~~~~~~~~~~~~~~~~~~~~ These are additional macros that are supported by the macro expander, but aren't likely to be useful to most users of AMPlay, so I've moved them into a separate section for reference only. Generally, they're either used internally by AMPlay for various panes in the database editor, or are useful for external applications that communicate with AMPlay via its API (e.g. AMPlayRCG). If you're developing an application that talks to AMPlay via its API, then you may find some of these useful. +-----+------------------------------+----+---------------------------+ |Macro| Expands to |Any | Info | +-----+------------------------------+----+---------------------------+ | %tx | track extension | y | from path to file | | %yt | tag year | n | | | %gf | tag flags | n | | +-----+------------------------------+----+---------------------------+ | %sr | sum total of tracks | n | } | | %sa | sum total of artists | n | } | | %sb | sum total of albums | n | } Not padded | | %sc | sum total of tracks in album | y | } | | %sd | sum total of tracks in artist| y | } | | %se | sum total of albums in artist| y | } | +-----+------------------------------+----+---------------------------+ | %pc | elapsed percentage of track | n | } 0-100 | | %pt | remaining percentage of track| n | } | +-----+------------------------------+----+---------------------------+ | %tv | Relative track volume | y | | | %bv | Average r.track vol in album | y | | | %av | Average r.track vol in artist| y | | | %tw | Random track weight | y | | | %bw | Random album weight | y | | | %aw | Random artist weight | y | | | %tl | Track link status | y | } | | %bl | Album link status | y | } 'Linked' or 'Not Linked'| | %al | Artist link status | y | } | | %tu | Track Ignore Unique status | y | } 'Ignore Unique' | | %bu | Album Ignore Unique status | y | } or | | %au | Artist Ignore Unique status | y | } 'Normal' | +-----+------------------------------+----+---------------------------+ | %?a | Use filter 1 for %tf/%bf/%af | na1| } | | %?b | Use filter 2 for %tf/%bf/%af | na1| } | | ... | ... | ...| } Produces no output. | | %?s | Use filter 19 for %tf/%bf/%af| na1| } | | %?t | Use filter 20 for %tf/%bf/%af| na1| } | | %?x | Current filter for %tf/bf/af | na2| Numeric 1-1-20 | +-----+------------------------------+----+---------------------------+ | %tf | Track Filter status | y3 | } | | %bf | Album Filter status | y3 | } See footnotes for format| | %af | Artist Filter status | y3 | } | +-----+------------------------------+----+---------------------------+ | %#a | Name of filter 1 | na4| | | %#b | Name of filter 2 | na4| | | ... | ... | ...| | | %#s | Name of filter 19 | na4| | | %#t | Name of filter 20 | na4| | +-----+------------------------------+----+---------------------------+ | %bi | Bitrate (in kbits/sec) | n | | | %mo | Stereo mode | n | | | %ve | MPEG Version | n | from frame buffer. | | %vl | MPEG Layer | n | | | %vc | Channels | n | | | %hz | Sample Frequency (in Hz) | n | | +-----+------------------------------+----+---------------------------+ | %vs | AMPlay version string | n | As in Program Info window | | %va | AMPlay API version | n | | +-----+------------------------------+----+---------------------------+ | %ss | status string | n | e.g. Playing, Paused etc | +-----+------------------------------+----+---------------------------+ | %% | actual percentage sign | y | % will also work as long | | | | | as it isn't a valid macro | +-----+------------------------------+----+---------------------------+ 1. Unlike all other macros, %?a to %?t do not expand to anything. They just change a variable within the macro expander which controls which filter the %tf, %bf and %af macros use for their expansion. 2. Unlike the other %? macros, this does produce output. It displays the current filter that would be used by %tf, %bf or %af. 3. Track filter can be one of 'Never', 'Linear', 'Isolated' or 'Always. Album and artist filters can have the same states, plus 'Multiple', which indicates an album/artist that contains a mixture of 'linear' and 'isolated' tracks, but no 'always' tracks. 4. These expand to the name of the specified filter. The applicability to any track is 'na' because these are global values. The filter name does not vary with the track number specified. Putting all this together, asking AMPlay to expand the following string; Filter: %#b %?b(%?x) %tf Might produce the output; Filter: Soundtracks (2) Linear ________________________________________________________________________ Copyright © 2008 Mike Sandells, mike@mikejs.com Last Modified: 30.05.2008