
* 3. Interface:
~~~~~~~~~~~~~~~

* 3.1 Player:
~~~~~~~~~~~~~

* 3.1.1 The Player Metaphor:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a fairly esoteric thing to be talking about, but I think it's a
quite important thing to get right:

AMPlay tries to be consistent about directions.

The idea of a playlist gives rise to a list of items with the earlier
items in the list at the top and the later ones at the bottom.
Therefore, when AMPlay wishes to indicate moving to a later track,
album or artist, it uses a down arrow.

Similarly the up arrow is used to indicate movement to a previous
track, album or artist.

Left and right therefore remain to indicate movement within the
currently playing track.

Notes

- Although this metaphor works with the default configuration, the
  order of items in the history menus is configurable. If the 'reverse
  history menu' option is enabled, then the history menus no longer fit
  it.

________________________________________________________________________


* 3.1.2 Main Window:
~~~~~~~~~~~~~~~~~~~~

The appearance of the main window will vary depending on the configured
skin. The skin can change the window layout completely, not just the
bitmaps used on the buttons. However, regardless of the skin, clicking
Select on the main window close icon will close the window as normal,
but clicking Adjust on it will close the entire app.

A diagram of the main window with the default skin would look something
like this;

   U  T  S  R  Q        N  O  P        V  W
   1  2                             6  A  3
   1  2                             5  9  3
   1  2                             4  8  3
   BBBBBBBBBBBBBBBBBBCBBBBBBBBBBBBBBB     7
   D  E  F  G  H  I  J  K  L              M

With the skin used in versions prior to 2.03, the diagram looks
something like this;

   1 2                               4  7  8 3
   1 2                                  5  9 3
   1 2                                  6  A 3
   BBBBBBBBBBBBBBBBBBCBBBBBBBBBBBBBBBBBBBBBBBB
   D E F G H I J K L   M   N O P Q R S T U V W


The same buttons are referred to by the same letter or number in each
case. Their descriptions are given below. Unless otherwise indicated,
the menu button opens the AMPlay main menu.


1. These are the buttons for moving to a previous item. From the top,
   these are previous track, album, artist.

   - Click Select to move to the previous item in the history.
   - Click Adjust to move to the previous item in the database.
   (These are the same thing unless you're using one of the
   random or shuffled modes).

   NB. See also the overall "previous" and "next" buttons. (I,J), and
   section 3.1.3.

2. These buttons produce a menu of previous items to go to. Again,
   tracks at the top, then albums, then artists.

   - Click any mouse button to open the menu of previous items.

   On the menu that appears, click Select on an item to play it now,
   Adjust to play it when the current item ends, or Shift+Adjust to
   remove it from the history.
   
3. These are the buttons for moving forwards. Track, album, artist,
   as before.

   - Click Select to move to the next item in the history or,
     if already at the end of the history, to pick the next item
     from the database. 

   - Click Adjust to move to the next item in the database, regardless
     of whether there are still items in the history to be played.

   NB. See also the overall "previous" and "next" buttons. (I,J), and
   section 3.1.3.

4. This displays information about the currently playing track.
   Depending on the skin settings, other messages from AMPlay may
   appear here. (The default skin sends messages here.)

   - Click Select to open the goto menu for tracks in the current album.
   - Click Adjust to open the goto menu for tracks by the current
     artist.

   These menus will be empty if there is no track playing.

   See section 2.5 for more information on the Goto menus.

5. This displays information about the currently playing album.
   Depending on the skin settings, other messages from AMPlay may
   appear here.

   - Click Select to open the goto menu for albums by the current
     artist.
   - Click Adjust to open the goto menu for all albums in the database.

   If there is no track playing, then there is no current artist, so the
   first of these menus will be empty.

   See section 2.5 for more information on the Goto menus.

6. This displays information about the currently playing artist.
   Depending on the skin settings, other messages from AMPlay may
   appear here. (The 'Small Blue' skin sends messages here.)

   - Click Select to open the goto menu for all artists in the database.
   - Click Adjust to open the goto menu for all tracks in the database.

   These menus should always be available as long as there is at least
   one track in the database.

   See section 2.5 for more information on the Goto menus.

7. This displays the elapsed time for the currently playing track.

   - Click Select to cycle through elapsed, remaining and total times.

8. This indicates whether the track playback is linear or
   random/shuffled. If it is highlighted, then selection is taking
   place at the track level (i.e. albums and artists are both being
   ignored)

   Click any mouse button for a pop-up menu of possible track order
   options, including chaos mode (which affects album and artist
   ordering as well). Chaos mode is turned off by selecting any other
   option.

9. This indicates whether albums playback is linear, random/shuffled,
   or ignored.(shuffling within the album would be indicated by the
   track indicator above).

   Click any mouse button for a pop-up menu of possible track order
   options, including chaos mode (which affects album and artist
   ordering as well). Chaos mode is turned off by selecting any other
   option.

A. This indicates whether albums playback is linear, random/shuffled,
   or ignored.(shuffling within the album would be indicated by the
   track indicator above).

   Click any mouse button for a pop-up menu of possible track order
   options, including chaos mode (which affects album and artist
   ordering as well). Chaos mode is turned off by selecting any other
   option.
 
B. This is the track progress bar. Clicking anywhere on this bar will
   cause the player to move to that point in the track. If the track is
   paused, this will not unpause it.

C. Progress bar marker. This indicates how far through the current
   track AMPlay is. The marker is highlighted when fast forwarding or
   rewinding.

D. Play.
     - Starts playing if stopped.
     - Unpause if paused.
     - Pauses if already playing. (Configurable)
   Additionally, if there is a track playing, an Adjust click will
   restart the track, unpausing if needed.

E. Pause.
     - Pause/Unpause.
   
F. Stop.
     - Stop.
   
G. Rewind.
   Moves backwards in the track.
   - Click Select to move in units of 10% of the track length.
   - Click Adjust to move in units of 1% of the track length.
   
H. Fast Forward.
   Moves forwards in the track.
   - Click Select to move in units of 10% of the track length.
   - Click Adjust to move in units of 1% of the track length.
 
   For both Fast Forward and Rewind, the adjust-click option is
   probably of more use when the track is Paused, unless it's a
   very long track.

   Fast Forward and Rewind do not unpause the track.
 
I. Previous.
   - Click Select to move to the previous track in the history.
   - Click Adjust to move to the previous track in the database.
   (These are the same thing unless you are using a random mode).
   
J. Next.
   - Click Select to move to the next track in the history.
     If already at the top of the history, a new track, album
     or artist will be picked based on the playback order.
   - Click Adjust to pick a new track, album or artist based on the
     playback order, overriding any remaining items in the
     history.
   
K. Autonext.
   Sets whether the player should start playing another track when
   it gets to the end of the current one.
     Autonext never = symbol is downward arrow onto solid line.
     Autonext in history = symbol is downward arrow onto dotted line.
     Autonext always = symbol is double downward arrow.

   Click any mouse button for a pop-up menu of possible autonext
   options.
   
L. Repeat.
   This determines whether AMPlay should move on to other items, or
   repeat the currently playing track, album or artist. It has four
   possible states;

   Off - Symbol is a straight line, arrow pointing right.
   Repeat Track - symbol is a narrow loop, arrow pointing left.
   Repeat Album - symbol is a medium loop, arrow pointing left.
   Repeat Artist - symbol is a large loop, arrow pointing left.

   Click any mouse button for a pop-up menu of possible repeat options.

M. Volume.
   - Click (and hold) Select to increase the player volume.
   - Click (and hold) Adjust to decrease the player volume.
   - Hold Shift to increase or decrease at a faster rate.
   - Hold Ctrl to alter the relative track volume instead of the player
     volume.
   - Hold Ctrl+Shift to alter the relative track volume at a faster
     rate.

   Note that the AMPlayer module may take a moment or so before the
   volume change takes effect (the playback buffer needs to be emptied
   before you can hear the difference).
   The artist info icon will display the volume for a brief time after
   you change it. The number is in the range 1-127.
   The basic rate at which the volume increases or decreases is
   configurable.

N. This is custom button 1. Refer to the configuration section 4.1 to
   assign actions to this button. By default this button has no
   actions assigned.

O. This is custom button 2. Refer to the configuration section 4.1 to
   assign actions to this button. By default this button has no
   actions assigned.

P. This is custom button 3. Refer to the configuration section 4.1 to
   assign actions to this button. By default this button has no
   actions assigned.

Q. Open options.
   This button launches AMPlayCfg to allow AMPlay to be configured.
   This icon is highlighted if AMPlayCfg is running.
   Clicking this while AMPlayCfg is running will update AMPlayCfg
   with the current effective settings.

R. Search.
   Opens the Search window. See section 3.2. This icon is
   highlighted if the Search window is open.
   Using Adjust will alter the settings in the search window for quick
   goto. See section 3.2.2 for details on this.
 
S. AMPlay Information.
   This opens the database editor, and switches it to one of the
   information panes.
   - Click Select to switch to the Currently Playing information pane.
   - Click Adjust to switch to the Database Statistics pane.

T. Filters.
   - Click Select for a menu of currently active filters.
   - Click Adjust to open the filter editor.

   The menu of active filters also has a menu item to open the filter
   editor.

   See section 3.3 for more information on the Filter Editor. Note that
   to alter the filter settings for specific tracks, albums or artists,
   you need to use the database editor.

   This icon is highlighted if the Filter Editor window is open.

U. Edit Database.
   - Click Select to open the Database Editor on the Edittable
     Attributes pane.
   - Click Adjust to do the above, but also select the currently
     playing artist, album and track.
   See section 3.4.

   This icon is highlighted if the Database Editor window is open.

V. Always on top.
   - Click Select to toggle whether the main window is always on top.

   Note that the mini window and main window always on top settings are
   independant.

W. Toggle size.
   - Click Select to change to the mini window.

   Note that the last positions of the mini and main window are stored
   independantly. The mini window will open where it last was, not where
   the main window was.

________________________________________________________________________


* 3.1.3 Previous and Next:
~~~~~~~~~~~~~~~~~~~~~~~~~~

AMPlay has several different buttons related to the general function of
moving to the previous or next item. In particular, there are generic
"previous" and "next" buttons - part of the row of buttons along the
bottom of the main window, and there are also item-specific "previous"
and "next" buttons that apply to tracks, albums or artists, and are at
either end of the track, album and artist rows.

These do similar, but not identical, things. In general, the item-
specific ones behave like this;

- Move within history by default
- Move within database if Adjust-clicked, or if the end of the history
  is reached.
- Move in units of whatever item they are associated with - track,
  album or artist.

While the generic ones behave like this;

- Move within history by default.
- Use configured playback order to pick new items if Adjust-clicked, or
  if the end of the history is reached.
- When within the history, move in units of single tracks.
- When Adjust-clicked or at the end of the history, move in units of
  whatever the current selection level is (which in turn depends on the
  configured playback order).

The mini window only has the generic "previous" and "next" buttons
(which behave the same as on the main window).
  
________________________________________________________________________


* 3.1.4 Playback messages:
~~~~~~~~~~~~~~~~~~~~~~~~~~

The following messages may be displayed in the artist info part of the
main window.


"Locating... (to x:xx of y:yy)"

This means that the AMPlayer module is searching through the file
looking for the point you requested. This usually only occurs on fast
forward - when rewinding it generally already knows the exact position.
X:xx indicates the target point in the track, y:yy is the track
duration.


"Only Track History available."

This appears if no tracks are allowed through the current filter, but
you've already played some tracks.

There are no files available to be picked if you try to go to the next
track - whether it goes directly or randomly, however you can still use
the previous and next buttons to move with the track history.


"No tracks available."

As above, but without the track history.


"Queuing next track..."

This appears when all of the currently playing track has been decoded
by the module, but the decoded sound is still working its way through
the audio buffer. AMPlay has already told AMPlayer about what track to
play next.

When AMPlay is in this state (which should last no more than a few
seconds), the displayed trackname may correspond to the end of the
track that you are still hearing, but the Goto menu produced by
clicking on the track will be applicable to the track that the module
is waiting to play. Pause, fast forward and rewind will be ignored in
this state.


"Added Track 1234 to the history."
"Added Album 123 (12 tracks) to the history."
"Added Artist 12 (123 tracks) to the history."
"Track 1234 will be played next."

These appear when a track, album or artist is added to the history,
but is not to be played immediately. This occurs when adjust-clicking
on items in either the Goto menus, or using the Queue action in the
database editor.

The "will be played next." message occurs when queueing an item that
is already present in the history, either between the current history
position and the top, or immediately before the current history
position. This message indicates that nothing was queued, but that the
position within the history was adjusted to play the item that was
already queued. Note that the message refers to tracks, even if the
item queued was an album or artist.


"No tracks allowed through filter"

This appears when you try to play an artist or album using the Playlist
Editor, but there are no tracks in the album or artist that pass
through the current filter.

"No tracks added."
"1 track added."
"xx tracks added."

These appear after dragging a directory onto AMPlay, and indicate how
many items were added to the database as a result of scanning that
directory.


"Volume: zz"
"Volume: xx + yy = zz"
"Volume: xx - yy = zz"

These appear when the current effective volume changes. The first of
these is what would happen normally, the second and third are what
is displayed if a relative track volume is set on the current track.
xx is the player volume, yy is the relative track volume and zz is the
effective volume.


"Started ADFS::HardDisc4.$..."
"Opened ADFS::HardDisc4.$..."

This is displayed when launching a program or opening a directory via
the custom buttons on the main window.


"AMPlayCfg started, Version OK"
"AMPlayCfg started, Version INCOMPATIBLE"
"AMPlayCfg started, Version UNRECOGNISED"
"AMPlayCfg is not installed."
"AMPlayCfg - Wrong Version."
"AMPlayCfg closed."

These all relate to AMPlayCfg. The first three apply to the case where
AMPlayCfg is at least version 2.00. In this case AMPlay can communicate
with it via the API and determine whether it is compatible with the
options file versions that AMPlay is compatible with.

The fourth one indicates that AMPlay was not able to find AMPlayCfg to
launch it. This means that AMPlayCfg has not been seen by the filer.

The fifth one indicates that AMPlayCfg exists, but appears to be a 1.5x
version. In this case, AMPlayCfg is not started.

The last one indicates that AMPlayCfg has closed.

AMPlayCfg is covered in section 4.


"Loaded X file".

This indicates that AMPlay has loaded a file of the type specified. X
may be options, linkage, volume, etc.


"Paused", "Stopped", "State Saved", "Filter blah selected", etc should
be self-explanatory.

________________________________________________________________________


* 3.1.5 Mini Window:
~~~~~~~~~~~~~~~~~~~~

The mini window is a much cut down version of the main window with some
of the icon positions moved around.

It contains the following icons that work exactly as they do on the
main window;

- Play
- Pause
- Stop
- Rewind
- Fast Forward
- Previous
- Next
- Elapsed Time
- Always on top toggle
- Toggle size

Note that the mini-window always on top flag is independant of the
main window always on top flag.
________________________________________________________________________


* 3.2 The Search Window:
~~~~~~~~~~~~~~~~~~~~~~~~

Enter the text you wish to search for in the box at the top, then
choose from the menus;

- Whether you are searching for track(s), album(s) or artist(s).

- Whether you want to search all tracks, albums or artists known to
  AMPlay, or to limit the search to just those items that pass through
  your current filter settings.

- What attribute of the track album or artist to include as part of the
  search. Some standard common ones are included here - the raw path to
  the file on disk, the track name, album name or artist name. The
  'complete name' is the track, album and artist name combined.
  Finally, for more advanced searches, you can specify a macro to be
  expanded to look in.

- Whether to apply the action to items that match your search term,
  those that don't match it, or just the first match.

- What action to perform on the items that match.


There are also options of;

- Performing a raw search. Raw in this case refers to whether to
  perform any text conversions before searching. E.g. if a track is on
  a lanman98 filesystem, and contains ;= as part of the filename,
  AMPlay will convert this to a @ character. These conversions take
  processing time, so by performing a raw search, performance is
  considerably improved. However, note that including characters such
  as @ in your search term will not find a match, unless you turn raw
  search off again. (Path to file is always raw, as conversions are
  never applied to this under any circumstance).

- Converting spaces in your search term to hardspaces before searching
  (ordinary space characters are not valid in RISC OS filenames, but
  are generally replaced with hard spaces by either the application or
  the OS. This means that hard spaces tend to show up in names derived
  from the path to the file).

- Making the search case sensitive.

Click Search to perform the search.

The remainder of the window may be used to define details about the
chosen action. It will be greyed out unless the relevant action is
chosen.

Actions:
~~~~~~~~

- Create Menu will create a goto menu style menu out of the items
  selected by the search. As with a goto menu, a select click on an
  item will play it now, an adjust click will queue it for later.

- Queue. This just puts the results straight into the queue, for
  playing later.

- Play. As above, but also starts playing them now.

- Remove from database. This removes the items entirely.

- Remove from history. This removes any references to the items from
  the track history.

- Refresh time. This causes AMPlay to refresh its idea of what the
  track duration is.

- Export. This will pop up a save box to save the results. See the help
  on the export window for various formats in which the results can be
  exported.

- Set filter. This requires further details to be set - the area below
  the action selector will allow you to select which filter to set, and
  what value to set it to.

- Change relative track volume. Again, more details required. You can
  select a relative track volume from -63 to +63. The 'set' tick box is
  used to indicate whether you wish to set the items to the value you
  specify, or whether you wish it to be added to the existing value.

- Change random weighting. As above, but for the random weighting.

- Set link to next. The details section allows you to specify what to
  set it to. i.e. this action can turn link to next off as well as on,
  depending on the tick box under details.

- Set ignore uniqueness. As above, but for the ignore uniqueness flag.


Notes;
~~~~~~

- The menu by the search text allows you to retrieve the 16 most recent
  searches.

- Although the search interface allows you to search for tracks, albums
  or artists, some of the actions apply to attributes that exist only
  at the track level. Relative track volume, for example, has no real
  meaning at the album or artist level - it just knows about the
  average of the tracks it contains.

  If you search for artists or albums, the action will apply to the
  artist or album if it is possible to do so, or to all the tracks
  within that artist or album if the action in question is one that can
  only be applied to tracks.

- Relative track volume on tracks is constrained between -63 and +63.
  Similarly, random weighting must be in the range -7 to +7. If, as a
  result of a search operation, the action would push the value outside
  that range, it will be silently kept within the allowed range. No
  error is reported.


* 3.2.1 Search Tips:
~~~~~~~~~~~~~~~~~~~~

- Performance varies depending on the amount of text processing
  involved, and how much work is involved in performing the action. A
  case sensitive search is significantly faster - in many cases if you
  wish to search on 'something', and do not know whether it has a
  leading capital letter, a case sensitive search with 'omething' as
  the search term will be faster (but be careful that it doesn't match
  additional items).

  Raw searches are a lot faster.

  Track, album and artist names are slower. 'Complete' is much slower
  still (because it involves three separate expansions). Entering your
  own macro will take as long as the complexity of that macro involves.
  There is no extra overhead just because it's a manually entered
  macro - entering %tn is exactly the same as selecting 'Track name'
  from the menu.

- Complete name is actually an expansion of "%an:%bn:%tn". You can
  therefore search for "some:text", which would match a track where the
  track name starts with "text" and the album name ends with "some".

- As an example of a custom macro, using %td, and searching for "10:"
  will find all tracks that are between 10:00 and 10:59 minutes long.

- The search looks for the search text anywhere in the expanded string.
  If, e.g. you're searching for 'cde', then a track called 'abcdef'
  will be counted as a match. If you want to ensure a match at the
  start or end of a name, use a custom macro, and prefix/suffix both it
  and your search term with a character that is unlikely to occur in
  real tracks. e.g. use a custom macro of "$%tn", and search for
  "$cde". This will cause the above example to no longer match.


* 3.2.2 Quick Goto:
~~~~~~~~~~~~~~~~~~~

If the search window is opened with an Adjust-click, the following
options are selected;

Look for: Set to tracks, albums or artists, based on the current
selection level.

Apply to: First Match only.

Action: Queue

This allows you to easily enter a search string to quickly queue
another item of the same type that is currently playing.

________________________________________________________________________


* 3.3 Filter Editor:
~~~~~~~~~~~~~~~~~~~~

The Filter Editor can be opened either from the button on the main
window, from the Filters... entry in the main menu, or by a Ctrl+Adjust
click on the iconbar icon (the latter being configurable).

The filter editor has information about the 20 filters that can be
defined. By default, all but one of these will be greyed out.

For each filter, the following icons are provided (from left to right);

Avail
Active
Name
Default
CopyTo
Reset

Avail
  This must be ticked before you can do anything else with the filter.
  It will not allow you to make a filter unavailable if it the only
  Active filter.
  Filters that are available appear in the filters menu.

Active
  This indicates which filters currently apply to the database. The
  active filters determine which tracks are present in the post-
  filtered list.

Name
  This is simply a descriptive name for the filter. Internally, filters
  are stored by their number, which is reflected in their position on
  the filter editor window. Filter names do not have to be unique,
  although this is recommended to avoid confusion.

Default
  These indicate what filter settings for each filter newly added
  tracks will receive. Typically, you might have one filter set that
  contains all tracks, and other filter sets that only contain small
  subsets. In that case, you would want to tick the defaults for that
  filter only, and leave the others unticked.

CopyTo
  This is greyed out unless you have more than one available filter.

  On clicking the CopyTo button for one filter, a menu will open
  listing all the other available filters. Clicking on the filter you
  want to copy to will copy all track specific filter settings to that
  filter. Any existing settings in the filter you choose as the
  destination for the copy will be lost.

Reset
  This will reset all the track specific settings for that filter to
  whatever the default values for that filter are.

The filter editor (and menu) will behave differently depending on the
option 'prefer single filters'.

If enabled, this option makes filtering behave more like it did in
AMPlay 1.5x. Specifically, with it enabled, clicking Select on a
filter in the filter menu, or on the Active tick box, will activate
that filter, and deactivate all the others. Adjust would allow you to
activate a filter, without affecting the status of the others.

If 'prefer single filters' is disabled (the default setting), then this
behaviour is reversed.

________________________________________________________________________


* 3.4 Database Editor:
~~~~~~~~~~~~~~~~~~~~~~

The database editor is opened either by clicking on the button on the
main window, or from the Edit option in the database menu.

This window contains everything that you can do on a per-track, album
or artist basis, together with statistics on the database, and
information about the currently playing database item.

The database editor has 5 panes for dealing with different areas of the
AMPlay database;

- Database Statistics
- Currently Playing Information
- Selected Item Information
- Edittable Attributes
- Naming

The first three of these just present information, and cannot be
altered.

The Edittable attributes pane covers all the standard item attributes
(filtering, link to next, relative track volume) etc.

The Naming pane allows you to choose what naming methods to use for each
item, to edit the naming information, and to perform tag operations such
as writing the naming information back to the file on disk.

Above the panes are four entries with pop-up menus. The top one of these
selects which pane is displayed. The other three allow a particular
track, album or artist to be selected. Not all of the panes make use of
a selected item, so this may be greyed out in some cases.

There is also an icon to the right that indicates whether the currently
selected item is a track, album or artist.

________________________________________________________________________


* 3.4.1 Database Statistics:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This window displays various information about the AMPlay database.
Total numbers of tracks, albums, artists, their total durations, and
the total of items with particular attributes set (e.g. total number
of tracks with "link to next" set).

In all cases except relative track volume and filtering, such
attributes can be set on an album or artist independently of the
tracks within it. e.g. an album can have "ignore uniqueness" set,
while the tracks within it do not.

Unlike other AMPlay windows, the details here do not automatically
refresh whenever something changes (certain things will trigger a
refresh, but not everything that would cause the statistics to change
will do so). To manually refresh the information, just pick Database
Statistics again from the pop-up menu.

Items that may require more detailed explanation;

- The history row indicates how many history entries there are in the
  history database for tracks, albums, artists, and how long the
  history would take to play if you started it at the beginning.
  (The duration is the overall total, and ignores the current position
  within the history.)

- The "unique tracks in history" box is a count of how many tracks
  have the 'track is present within history' flag set on them. This
  is an internal AMPlay flag, and is not directly related to the
  total history entries.

- The "% Tracks in history" entry further down is percentage of the
  total number of tracks that have the 'track is present within
  history' flag set on them. i.e. it also is not directly related to
  the total history entries.

e.g. in an extreme case, assume you have 100 tracks in total, and
100 history entries, but each history entry is for the same track.
In this case history entries would be 100 tracks, but unique tracks
in history would be 1. The % tracks in history would be 1%

- Ext. Names is a count of how many tracks have an extended name
  block associated with them. Extended name blocks are used to store
  the naming information for tracks where;
  - The naming information was initially read from a Tag, or
  - The naming information started out as pathname based and has
    since been editted.

  i.e. Tracks using pathname based naming, which have not had their
  details editted manually, will not have an extended name block. All
  other tracks will.

Notes;

- You may have more albums or artists listed in the history than in the
  database. This is not a bug - the number of artists and albums in the
  history is the result of going through the track history and counting
  how many times adjacent tracks come from differing albums or artists.
  If you run AMPlay in random track mode for a while, you may end up
  with nearly as many artists and albums in the history as there are
  tracks, but the same album and artist will be represented many times.
  The database indicates how many unique albums and artists there are,
  the history does not and counts duplicates.

- The Rel. Volume line is an indication of how many tracks have a
  relative volume that differs from the default (0). It does not
  indicate what that volume is, or whether it was an increase or
  decrease in volume. Likewise the weighting line does not take into
  account what the weighting is, just a count of the non-defaults.

- The memory statistics are for information only, and only refer to
  the AMPlay Database dynamic area that is visible in task manager,
  not the wimpslot or the AMPlay Library dynamic area. Generally, the
  largest free block will be quite small. If you add large numbers of
  tracks to the database, or do a sort, it may grow. This is not
  usually a problem, but if running AMPlay with large numbers of tracks
  (100,000 tracks and above), you may need to keep an eye on it and
  possibly increase the dynamic area size (see section 4.6.3 on this
  option, and section 6.18 for the FAQ on large databases).

________________________________________________________________________


* 3.4.2 Currently Playing Information:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- The top section lists numbers within AMPlay's database. e.g. If
  Unfiltered Track is N, then this is the Nth track in the database.
  The "in Alb" and "in Art" headings indicate the number of the item
  within its album or artist.

  e.g. It might tell you that the currently playing track is track
  1234, that it is track 5 within its album, and track 15 within its
  artist. The album is 56, which is album 2 within its artist. The
  artist is 21.

  The filtered line is the same information again, but taking
  filtering into account.

- The duration headings are for the Track, Album and Artist
  respectively (I've tried to get the columns to line up, but the
  duration boxes need to be a bit wider).

- If the currently playing track does not pass through the filter,
  then its filtered duration is 0:00. This may seem a bit odd for the
  currently playing track (which clearly does have a non-zero
  duration), but without this the filtered durations for the album and
  artist would make no sense.

  Typically this only occurs if you manually play something that does
  not pass through the filter, or you alter the filter status after the
  track/album/artist has started playing.

- The AMPlay info section should always be visible while a track is
  playing. The MP3 Frame info may not be available for the first second
  or so of a track. This means that as one track ends and another
  starts you may very briefly see AMPlay information for the later
  track, and MP3 frame information for the earlier one

The path to file is a clickable button, and will open the filer
window where the MP3 is located. Click with adjust to open the parent
of that (if different).

________________________________________________________________________


* 3.4.3 Selected Item Information:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This displays a similar range of information to the 'currently playing
information' pane. However it differs in that the information it
displays is related to what item is selected in the menus above the
pane, and in that it can display information about albums or artists as
well as information about particular tracks. It also does not include
MP3 frame information as that is only known for the current track.

As with the currently playing information window, the path to file is
clickable (if a track is selected), and will open the directory
containing the track in question. An adjust-click will open the parent
of that directory.

All numbers refer to positions within AMPlay's database.

Different sections will be greyed out depending on whether it is a
track, album or artist that is selected. e.g. The 'number of tracks' in
item field is meaningless if a track is selected, but meaningful if an
album or artist is selected.

The abbreviation 'No. in Alb.' means the number of the track within the
album. Similarly, 'No. in Art.' refers to the number of the track/album
within the album/artist.

________________________________________________________________________


* 3.4.4 Edittable Attributes:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This contains all edittable attributes of the selected item, other than
naming (which has its own tab).

It is divided into three sections - General, Filters, and Actions.

Different options may be available depending on whether the selected
item is a track, album, artist or the entire database. Many options
cannot be applied to the entire database in one go, or are not
meaningful in that case (e.g. adjusting relative volume of all tracks
is pointless).


General
~~~~~~~

This contains;

- Relative track volume: The current value is displayed, and up/down
  buttons can be used to adjust it. If an album or artist is selected,
  the value shown is an average of the tracks contained in that album or
  artist, and this will be indicated. In that case, using the up/down
  buttons will add or remove 1 from all the tracks affected (keeping
  within the -63-+63 range), and recalculate the average. Relative track
  volume is discussed in more depth in section 2.9

- Random weighting: This indicates the current weighting, and has
  up/down buttons to change it. This can be set at track, album or
  artist level, and so is never an average. This must be in the range
  -7 to +7. Random weighting is discussed in more depth in section 2.10

- Link item to next: This allows you to see or set the linkage on the
  item. This is discussed in more depth in section 2.8. Note that
  linkage set on the last track in the album, last album in the artist
  or last artist in the database has no effect, although the interface
  will let you do it.

- Ignore Uniqueness: This allows you to see or set the ignore
  uniqueness flag. This allows the item to be picked by AMPlay even if
  it has been played recently, and is discussed in more depth in
  section 2.7.

- Naming: This indicates the current naming method for the track.
  Clicking change takes you to the naming pane, covered in more detail
  in 3.4.5, below.

Filters
~~~~~~~

This has 20 tickboxes, with the name of the filter by each one. The
status of the item in each filter is indicated.

Each button has one of 5 states;

- Never (no tick)
- Always (a simple tick)
- Isolation only (A small tick with the random/shuffle symbol)
- Linear only (A small tick with the linear symbol)
- Mixed. (A combination of the linear and isolation symbols)

For tracks, only the first four of those apply.

For albums and artists, Mixed indicates that the album/artist contains
some tracks with isolation only set, and some with linear only set, but
no tracks with always set. This means that there will always be
something in that album which is playable, regardless of the playback
order, but it will be different tracks in each case. You can't put an
album or artist into the 'mixed' state, and any changes made at the
album or artist level will change it into one of the other four.

Filtering only exists at the track level. The filters on albums and
artists are calculated by ORing the track level filters together.

If the selected item is an album or artist, and you click one of the
filter buttons, it changes to the next state (e.g. if it was never, it
changes to always), and that new state is applied to all the tracks in
the album or artist. i.e. all tracks within the album/artist end up
with the same setting for that filter.

Clicking with Adjust cycles through the states in the opposite order.

Filtering is covered in more depth in section 2.6


Actions
~~~~~~~

These aren't attributes as such, but this seemed the best place to put
them.

From here you can do the following to the selected item:

- Play: Plays the item now.
- Queue: Adds the item to the queue. By default it makes no change to
  the history position. Shift+click to force the queued item to be
  played next.
- Remove: This removes the item from the database. This is not an
  easily reversible operation. Use with caution. Confirmation is
  required if the operation would remove all items from the database.
- Remove history: This scans the track history, and removes any history
  entries that refer to the selected item.
- Move up/Move down: These move the selected item up or down within the
  database, allowing you to manually sort items into your preferred
  order. You can only move tracks within albums, albums within artists,
  or artists within the database. The buttons will be greyed out if the
  item cannot be moved in one or other direction. Note that doing a
  sort will re-order things without regard to any manual changes you
  make.
- Refresh time: This causes the duration to be re-read for the tracks
  within the selection.
- Export: This opens the export window, defaulting to custom options to
  export the selected item. Refer to section 3.5 for more details on
  the export interface.

________________________________________________________________________


* 3.4.5 Naming:
~~~~~~~~~~~~~~~

This pane has three sections;


Naming Method;
~~~~~~~~~~~~~~

This allows you to change the method used to determine naming
information for the tracks included in the current selection.

AMPlay can obtain naming information either by extracting it from the
pathname of the file, or by reading the ID3 tag (if any) on each file.

Clicking change will apply your choice.

Note that reading the ID3 tags of large numbers of files can be time
consuming, particularly if they are on slow filing systems.

Also note that if you have manually editted the naming details of any
tracks in the selection, this information will be lost - when the
change is applied, all tracks will end up with either the contents of
the tag, or the default pathname derived name.

This section also indicates the current naming scheme in use. This will
indicate whether the tracks in the current selection use tag-based,
pathname-based, or some of each. It also indicates whether any manual
edits have taken place since, with an extra warning that editted
information will be lost if you reset the naming method of an editted
track.

Notes;

- If you tell AMPlay to use tag based naming for a given track, but the
  track does not actually have a tag, it will remain set to pathname
  based naming.


Edit Names
~~~~~~~~~~

This allows you to edit the naming details of the selected range of
tracks.

If you have selected a track, then all fields are edittable.

If you have selected an album, then the track name and track number
fields are greyed out. The album and artist names are edittable. The
other fields will be greyed out or not depending on whether they vary
within the album. e.g. If all the tracks in the album have the same
year attribute, then the year will be edittable. If there is a mixture
of years, the year field will grey itself out.

If you have selected an artist, then much the same applies as for
albums, except that the album field is also greyed out.

Editting is not available if the entire database is selected.

For the Comment, Genre, and Year fields, if they vary within the
selection, they will grey out, but there is a tick box next to them
called 'Edit' that allows you to force them into the edittable state.
This allows you to, e.g. impose a consistent year on all the tracks in
an album.

There are two buttons below all this - Original and Apply Edit.

Apply Edit takes whatever changes you've made in the edittable fields,
and applies them to each track in the selection. Any fields which are
not edittable (i.e. are greyed out) are left intact with their existing
value. i.e. You can edit the album name of all the tracks in the album,
without affecting any other naming information about each track.

If you have started making changes to the fields, and wish to go back
to the current settings, click Original. Note that Original does not
undo the effects of Apply.

Notes;

- The various text conversion options apply to naming information,
  whether it came from a pathname or not. Therefore, even if it came
  from a tag, if you have lanman conversions enabled, the string ';+'
  will be shown as '&', and so on for the other conversion options.

- See also the FAQ on track numbering (section 6.21).


Tag Actions
~~~~~~~~~~~

Re-Read tags is useful in the case where you used tag based naming with
AMPlay, and have since updated the tags on the files themselves, using
some other tool. Normally, AMPlay reads the tag once, and caches the
contents so that it does not have to touch the file again in normal
use except when actually playing it.

This button tells AMPlay that, for the tracks in the selection, it
should re-read the tag information and update its cached copy.

There is an option to preserve editted information - i.e. if the cached
copy of the tag has been manually editted, don't overwrite it with the
tag from the file. This can be useful for cases where the naming
information doesn't fit into the limited length strings of the tag.

Re-read tags is greyed out if there are no tracks in the current
selection whose naming information came from a tag. (i.e. they all use
pathname based naming of some form.)


Write tags allows you to write the naming information that AMPlay has
back into the ID tag on the file. There are two options here;

- Overwrite existing tag.
- Write pathname information to tag.

Neither is selected by default, but you must select at least one of
them for the Write Tags button to do much.

The reason for this is that unless you have 'write pathname...'
selected, it will only write the tag of tracks that use tag based
naming. All such tracks already have a tag, so unless you have
'overwrite existing tag' selected AMPlay will leave the existing tag
alone.

Notes;

- Selecting write pathname information to tag, with overwrite tag
  unticked will result in adding a tag to all the tracks that don't
  currently have one.

- Writing a tag can take as long, or longer, than reading the tag. If
  there are a large number of tracks in the selection, and tags really
  are being written (i.e. it's overwriting, or most of the tracks
  aren't already tagged), then it can take a long while.

- AMPlay writes tag format 1.1, including the track number within
  album. Both 1.0 and 1.1 formats are readable (AMPlay uses the
  AMPlayer module for reading tags). v2.0 format tagging is not
  supported in any form.

- Files must be writeable by the user for write tags to work.

- There is currently no option to rename files according to their
  AMPlay name (e.g. to edit a pathname based name and then update the
  actual pathname with the editted version).

________________________________________________________________________


* 3.5 Export:
~~~~~~~~~~~~~

This allows various information to be exported from AMPlay into a plain
text file. In most cases these files are suitable for re-importing into
AMPlay at a later date, e.g. to re-play the same sequence of files, or
to re-apply particular filter settings.

You can also export in a custom format to get lists out of AMPlay for
just about any other purpose - If you want a text file with all your
artists listed, with the entire artist duration, then this is where
you'd get it.

The various menus on this window are (from the top);

- What to export;

  - Playlist (Simple listing of filenames)
  - History (The sequence of tracks that have been played)
  - Filter
  - Relative volume
  - Random weight
  - Links
  - Ignore unique
  - Custom

  If Filter is selected, then the 'Which Filter?' menu becomes
  available, allowing you to choose which filters to export (All,
  currently active or currently available).

  If Custom is selected, the items in the custom details section in the
  lower half of the window are available. (They are greyed out
  otherwise).

  The filter etc file formats are covered in more detail in section 5. 


Custom export:

- For Each.

  The output will contain one line for each item exported. The 'For
  Each' menu selects what is considered to be an 'item' for purposes of
  export. Do you want the information on a per track, album or artist
  basis? There are also options of generating output per history entry
  (i.e. track history - album and artist history cannot currently be
  exported directly).
  
  The search results and selected item option will normally be greyed
  out unless the export window was launched by either the Search
  window, or the Database editor window.

- Include

  This only applies if 'for each' is set to tracks, albums or artists.
  It defines whether all tracks, albums or artists are included, or just
  those that are allowed through the current filter settings.

- Export

  This defines what information you want about each item. The path to
  file, track name, album name, artist name or complete name are
  standard options, or you can enter a custom macro to be expanded for
  each item. The standard options are just quick ways of selecting a
  particular macro - picking 'track name' produces the same results as
  picking 'macro' and entering '%tn'. Complete name is the macro
  '%an:%bn:%tn'.

The actual export takes place when you drag the icon to the destination
window.

________________________________________________________________________


* 3.6 Menus:
~~~~~~~~~~~~

The main menu structure is as follows. Certain sections may be greyed
out if there are no tracks in the database.

           
Info -     RISC OS standard, basic information about the program. The
           info window has buttons to launch mail or web locations.
           (Adjust clicks on these buttons will send the URL in question
           to the keyboard buffer)
           The version of the AMPlayer module is also reported.

Export -   Opens the Export window. See section 3.5 above.

Player -   Opens the player window, or brings it to the front if open

           Play            }  Standard options - these do the same thing
           Pause           }  as the corresponding button on the main
           Stop            }  window. If applicable, Select/Adjust work
           Previous        }  as they would on the main window.
           Next            }  They will be ticked or greyed out in the
                           }  same way that the main window buttons are.

           Restart         -  Has no main window icon, but is a play on
                              play action.

           Playback Order  -  Leads to a sub-menu to set the playback
                              order for tracks, albums or artists.
                              These are the same menus available from
                              the main window buttons.

           Auto Next       -  Sub-menu for auto-next options.
                              These are the same menus available from
                              the main window buttons.

           Repeat          -  Sub-menu for repeating options.
                              These are the same menus available from
                              the main window buttons.

           Increase Vol    }  Equivalent to one click with Select or
           Decrease Vol    }  Adjust on the main window volume control.
                           
           Toggle Size     -  Change from the Main window to the Mini
                              window, and vice versa.

           Save State      -  Saves the current state of the player,
                              including the database.

Database - Opens the Database Editor window.

           Sort            -  Sorts the database. See section 2.13.
                              
           Edit            -  Open the Database Editor window,
                              and selects the edittable attributes pane.
                              
           Statistics      -  Opens the Database Editor window,
                              and selects the database statistics pane.
                              
           Filter          -  Opens the Filter Editor window.

           Refresh         -  This leads to a sub-menu with options to:
                              Names - This clears all the cached name
                              information for track, album and artist
                              names. This has no effect on tag based
                              names or editted pathname based names.
                              It also includes the boundary scan, below.
                              Boundaries - Scan the database comparing
                              the album and artist names for each track
                              to find where each album and artist starts
                              and ends.
                              Track Times - This re-reads the track
                              durations.
                                                            
           Search          -  Opens the search window. See section 3.2
                              for more information.

History -  Sub menu items to open the history menus for Track, Albums,
           or artists. The "Clear History" item at the top of each
           will remove all items from the history menu.
           
Options -  Launches AMPlayCfg.

Help    -  Launches the documentation.
           
Quit    -  Quit, with a sub-menu to not save the state when quitting.

________________________________________________________________________


* 3.7 The Iconbar Icon:
~~~~~~~~~~~~~~~~~~~~~~~

The actions for the iconbar icon are configurable (see section 4.3).
The defaults are;

Select                - Open main window
Adjust                - Launch AMPlayCfg
Shift + Select        - Open Database Editor (edittable attributes)
Shift + Adjust        - Open Database Editor (database statistics)
Ctrl + Select         - Open Search Window
Ctrl + Adjust         - Open Filter Editor
Shift + Ctrl + Select - Pause Track
Shift + Ctrl + Adjust - Next Track

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