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