
AMPlay 2.03
~~~~~~~~~~~

Contents:

 1. Introduction

    1.1.  What is AMPlay?
    1.2.  Installation
    1.3.  Getting Started for new users
    1.4.  About the documentation
    1.5.  Requirements
    1.6.  What's new in this version?
    1.7.  Upgrading from a previous version
          1.7.1. Upgrading from 2.0x
          1.7.2. Upgrading from 1.5x
          1.7.3. Upgrading from versions older than 1.5x
    1.8.  Tidying up after upgrading  
   
 2. Main Features

    2.1.  Tracks, Albums, Artists
          2.1.1. Establishing Names
          2.1.2. Boundary Checking
    2.2.  Features Overview
    2.3.  Playback Order
    2.4.  The History/Queue
    2.5.  The Goto Menus
    2.6.  Filtering
    2.7.  Uniqueness, and ignoring it
    2.8.  Link to Next
    2.9.  Relative Track Volume
    2.10. Weighting
    2.11. Custom Buttons
    2.12. Macros
          2.12.1. Basic Macros
          2.12.2. Basic Modifiers
          2.12.3. Macros in Practice
          2.12.4. Modifiers in Practice
          2.12.5. Advanced Modifiers
          2.12.6. Advanced Macros
   
 3. Interface

    3.1.  Player
          3.1.1. The Player Metaphor
          3.1.2. Main Window
          3.1.3. Previous and Next
          3.1.4. Playback Messages
          3.1.5. Mini Window
    3.2.  Search
          3.2.1. Search Tips
    3.3.  Filter Editor
    3.4.  Database Editor
          3.4.1  Statistics
          3.4.2  Currently Playing Information
          3.4.3  Selected Item Information
          3.4.4  Editable Attributes
          3.4.5  Naming
    3.5.  Export
    3.6.  Main Menu Structure
    3.7.  The Iconbar Icon
   
 4. Configuration

    4.1.  Player
          4.1.1  Playback Order
          4.1.2  Behaviour
          4.1.3  Player Window
    4.2.  Display
          4.2.1  Main Window
          4.2.2  Database Editor
          4.2.3  Text Processing
    4.3.  Custom
          4.3.1  Custom Buttons
          4.3.2  Iconbar Icon actions
    4.4   Skin
    4.5.  Menus
          4.5.1  Menu Formats
          4.5.2  Other menu options
    4.6.  Database
          4.6.1  Naming
          4.6.2  Adding Tracks
          4.6.2  Database optios
    4.7.  Actions
          4.7.1  Events
          4.7.2  Sorting / Boundary Checking
    4.8.  State
    4.9.  Other
          4.9.1  Errors
          4.9.2  Advanced options

 5. File formats

    5.1.  Markers
    5.2.  Optimisation
    5.3.  Playlists
    5.4.  Filters
    5.5.  Sequences
    5.6.  Volume
    5.7.  Link to Next
    5.8.  Weighting
    5.9.  Ignore Unique
    5.10. Options
    5.11. State
   
 6. Frequently Asked Questions (FAQ)

    6.1.  What is the position with AMPlay and RISC OS 5?
    6.2.  Why is Read MP3 ID Tag for all tracks off by default?        
    6.3.  How can I improve the speed at which tracks are added?   
    6.4.  Why are some tracks still listed as 0 seconds?               
    6.5.  Why is relative track volume not proportional?
    6.6.  Why is AMPlay so big?                                        
    6.7.  Why so many file formats?
    6.8.  Why doesn't the saved state use the normal file formats?
    6.9.  Why can I not move tracks outside their album etc?           
    6.10. Why must tracks be adjacent to appear in the same album?     
    6.11. Can I rename artist, albums or tracks?                       
    6.12. Why is zero-padding inconsistent on the Find Tracks menu?    
    6.13. Where did all the keyboard shortcuts go?    
    6.14. What are all the adjust-click actions?                       
    6.15. How do I clear the database and start again?                 
    6.16. What happens if the AMPlay and AMPlayCfg versions differ?
    6.17. Can I control AMPlay from the command line, or an obey file?
    6.18. How scalable is AMPlay?
    6.19. What do the things in []s mean on the program info window?
    6.20. Can the custom buttons perform 'internal' actions?
    6.20. What's going on with track numbering?

 7. Messaging API
    7.1.  AMPlay_Command (&563C0)
    7.2.  AMPlay_Request (&563C1)
    7.3.  AMPlay_Ack (&563C2)
    7.4.  AMPlay_ChangingState (&563C3)
    7.5.  AMPlayCfg_ChangingState (&563C4)
    7.6.  AMPlayCfg_Command (&563C5)
    7.7.  AMPlayCfg_Ack (&563C6)
    7.8.  Reply by file
    7.9.  Compatibility
    7.10. Example Applications
          7.10.1  Raw format
    7.11  Changing options via the API
    7.12  Future APIs
    
 8. Miscellaneous

    8.1.  Co-existence with other AMPlayer applications
    8.2.  AMPlayRCG
    8.3.  AMPlayCmd
    8.4.  Internationalisation
    8.5.  Skinning
    8.6.  The to-do list
    8.7.  Known bugs/quirks
    8.8.  Troubleshooting Common Problems
    8.9.  Other information
    8.10. Credits
    8.11. License
          8.11.1  Preamble
          8.11.2  License text
    8.12. Web Resources
   
 9. Changelog

    9.1.  v2.00  (30.10.2005) 
    9.2.  v2.00a (31.10.2005)
    9.3.  v2.02  (15.05.2008)
    9.4.  v2.03  (30.05.2008)
 
________________________________________________________________________

* 1. Introduction:
~~~~~~~~~~~~~~~~~~

* 1.1 What is AMPlay?:
~~~~~~~~~~~~~~~~~~~~~~

It's a desktop player for MP3 music files, using the AMPlayer module.

It contains a number of features specifically aimed at dealing with
very large collections of MP3s ('large' in this context is many
thousands or even tens of thousands).

In particular, it understands that there is more to an MP3 collection
than a simple list of tracks. A track generally comes from a collection
of tracks that we call an album, and is generally by a particular
artist. AMPlay recognises this, and builds a database of tracks where
each track has an associated album and artist. Many features of AMPlay
are only possible because of this - most actions can be applied to
albums or artists as well as tracks, and many settings can also
be set at the album or artist level. Albums and artists also provide a
useful grouping of tracks, allowing attributes of multiple tracks
to be editted together.

________________________________________________________________________


* 1.2 Installation:
~~~~~~~~~~~~~~~~~~~

!AMPlay can be copied to wherever you wish to put it on your hard disk.

Although AMPlay will run without it, in order to configure AMPlay,
you will need to install/upgrade AMPlayCfg. Refer to the ReadMe file
in the AMPlayCfg directory for details on doing this.

Note that AMPlay 2.03 requires AMPlayCfg 2.03 to be installed. Older
versions of AMPlayCfg will report errors if you try to use them with
AMPlay 2.03.

See also the requirements section.

________________________________________________________________________


* 1.3 Getting Started for new users:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run !AMPlay. You should see the player window appear in the bottom
left of your desktop. You can drag MP3 files onto this window (or the
icon bar icon) to add them to the database - by default it will also
start playing automatically.

Once AMPlay is loaded, double clicking on an MP3 file will start the
file playing, and add its details to the database if they aren't
there already.

You can also drag directories containing MP3 files, or text files
containing the full paths to the MP3 files. (Before starting a large
import of 1000's of files, see section 6.3 in the FAQ - it will work,
but there are some things you can do to make it faster).

If you receive a message that a module can't be located or is too old,
refer to the requirements section.

AMPlay supports interactive help by default, for both windows and menu
entries.

If it does not start playing, refer to section 8.8 - Troubleshooting.
There are a couple of simple reasons why this might happen.

Before you can configure AMPlay, you'll need to have installed
AMPlayCfg. Refer to the Installation section above.


________________________________________________________________________


* 1.4 About the Documentation:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If using a text editor that supports a ListOfFound function, you can do
a List of Found for the "*" character to produce a clickable menu to the
sections within this document.

The documentation is intended to be comprehensive, not because AMPlay is
difficult to get to grips with, but to ensure that there is something to
refer to if you do run into problems or want to see what you can do with
it. You don't need to read the help to get anywhere, but it's here for
reference should you need it.

________________________________________________________________________


* 1.5 Requirements:
~~~~~~~~~~~~~~~~~~~

AMPlay requires;

- RISC OS version 3.7 or later.
- ABCLibrary 4.15 or later.
- AMPlayer 1.39 or later.
- CallASWI 0.03 or later (Not needed on RISC OS version 5).
- AcornURI 0.12 or later (not essential).

It also needs to be running on a system with enough processing power
for the AMPlayer module to be able to decode MP3s in realtime at
sufficient quality. In practice, this makes a StrongARM RiscPC the
minimum spec, although the faster ARM7500FE based machines might just
about suffice with some tweaking of the AMPlayer options. 

If your system does not already have ABCLibrary 4.15 or later, a copy
is supplied with AMPlay in the OnlyIfNeeded.ABCLib directory. Refer
to the ReadMe in that directory for installation instructions.

AMPlayer is used by AMPlay for the decoding of the MP3 file to sound.
It is available from http://www.amplayer.org. Unless there's a newer
official version than 1.39, Iyonix users should download the
unofficial 32-bit version.

If your system requires CallASWI, and does not already have 0.03 or
later, it can be downloaded from http://www.iyonix.com/32bit in the
!System updates section.

AcornURI is used by AMPlay for the email and web buttons on the
program information window. As this is not critical, no error is given
if it can't be loaded - the buttons in question just won't work. An
updated AcornURI can be downloaded from http://sudden.recoil.org/others

If any of the required modules are no longer available from their
authoritative sources, a copy of the current version is supplied
in the 'OnlyIfNeeded' directory. This means that AMPlay should
always be useable even if modules that it requires are no longer
obtainable.

Unlike the 1.x versions, AMPlay 2.x does not require WBModules.

AMPlay has been tested on RISC OS Select (4.37), and RISC OS 5
(5.11). It is 26/32-bit neutral.

AMPlay will make use of a Choices directory if the boot sequence you
are using provides one (any recent boot structure should do so). If no
Choices directory is available, AMPlay will use its application
directory for storing settings and the tracks database, in which case
it won't run from a read-only archive or CD. If choices are
available, it stores its settings in choices.audio.mp3.amplay2

Interaction between AMPlay and AMPlayCfg requires access to !Scrap.
AMPlay will create its own subdirectory inside scrap. It tidies this
up itself on startup.

The memory requirements for AMPlay will vary depending on the size of
the database you create, but with the default settings it uses about
2MB. AMPlayer will also claim some memory for its playback buffer -
this can be configured. Refer to the documentation for the AMPlayer
module itself for more details on this.

________________________________________________________________________


* 1.6 What's New in this Version?:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2.03 is a minor update from 2.02, fixing a few minor bugs and adding a few minor improvements (mostly related to skin handling)

Changes between 2.03 and 2.02;

- Redesigned main window and sprite set, to provide larger icons, and
  reduced risk of mis-clicking etc. This redesigned skin is now the
  default - the previous skin is still supplied with AMPlay as 'Small
  Blue'. NB. as well as having larger buttons, the new default skin
  has the artist, album and track rows the opposite way round to the
  way they were previously. The new skin has artist above album above
  track, and uses the track field to display AMPlay messages.

- Various fixes/improvements to skin handling;

  - Calculation of when to scroll text in the track, album or artist
    fields is now done correctly. Previously it was roughly right by
    accident for the default skin, but noticeably wrong for others.

  - Clicking on the progress bar to set the position within the track
    now works properly in all cases, rather than only when the window
    is against the left edge of the screen.

  - Custom buttons of type 'Other Application' now display the right
    icon.

  - The "Locating..." message is now "Locating (to x:xx of y:yy)",
    where x:xx is the target time, and y:yy is the total duration of
    the track.

  - Skins can now specify which field should be used for displaying
    AMPlay messages.

- Fixed bug with the goto menu for albums by the current artist. In
  some cases, only the first album was being displayed.

- Very large total durations are now displayed correctly on the
  database statistics window. The limit is now 2^31 seconds (roughly 68
  years), rather than 2^31 centiseconds (roughly 250 days).

There are also changes to AMPlayCfg;

- Skin settings now have a pane in the options all to themselves.

- Skin previews and descriptions are now available (the skin has to
  provide these)

- When run manually, or from AMPlay, AMPlayCfg now remembers its window
  position, and which pane was selected.

- When run from Configure, AMPlayCfg opens under the mouse pointer, (as
  recommended by the Style Guide).

For information about earlier versions, and for more detailed
information on the above changes, refer to the changelog (section 9).

________________________________________________________________________


* 1.7 Upgrading from a previous version:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If upgrading from 2.0x to 2.03, follow the instructions in
section 1.7.1.

If upgrading from 1.5x to 2.x, then you should note that 2.00 was a
complete rewrite, and the internal structure bears little resemblance
to older versions. I recommend renaming your existing !AMPlay directory
(ideally removing the '!' from the front so that RISC OS no longer
treats it as an application). Then just copy the new version into place.


* 1.7.1 Notes on upgrading from v2.0x:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Retain a backup copy of your existing version if you wish, then copy !AMPlay 2.03 over the top of your existing version.

Note that AMPlayCfg has also changed. To upgrade that, simply follow
the original installation instructions for it. As with AMPlay, it is
simply newer versions of existing files.


* 1.7.2 Notes on upgrading from v1.5x:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Rename your existing !AMPlay directory, and copy the new version into place. Install AMPlayCfg using the instructions supplied with it.

AMPlay 2.x is able to read the 1.5x state format, as long as 1.5x had
the 'binary state format' option turned on (which it was by default).

Note that because the internals are very different, there is quite a
lot of processing work to do in converting the 1.5x saved state into
the formats that 2.x uses. Loading a 1.5x state can therefore take
quite a while particularly for large numbers of tracks, and
particularly if you were using tag based naming in 1.5x.

The following items in the 1.5x state are ignored;

- Window positions.
- Find history.
- Format strings related to the old playlist editor or find windows.

These are generally because there is no sensible mapping between the
old and new environments, or because the information is now stored in
a different format.

The 1.5x database is imported, but the following items may not have
the same meaning in 2.x that they did in 1.5x;

- Linkage settings. Linkage on the last track in an album is no longer
  used to link albums together (there's a separate linkage attribute at
  the album level now).

- Filtering. In 1.5x, a track that has linear disabled, and random
  enabled is imported into 2.x as a track set to 'play in isolation
  only'. This is the closest available option, but isn't quite the same
  thing.

- Weighting. In 1.5x, weighting was only settable at the track level,
  with albums and artists having an effective weighting that was the
  average of their tracks. In 2.x, the weighting can be set
  independantly at the track, album and artist levels. The 1.5x
  information is imported into the 2.x track weighting, but the 2.x
  album and artist weightings will be left at their default.

- Iconbar actions. Not all of the old actions have direct equivalents.
  Anything that doesn't match up with something in the new version is
  ignored, and will remain at whatever the 2.03 default is.


* 1.7.3 Notes on upgrading from versions before v1.50:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can't, or at least not directly. 2.x does not handle any state
format prior to the 1.5x binary format. If you have a saved state in
1.4x or earlier, and want to use it in 2.x, then you'll have to upgrade
to 1.5x first. If you're on a system that requires 32-bit code, then
Aemulor is your only option (1.53 is known to run OK under Aemulor, but
it's quite slow), or perform the upgrade on a 26-bit system and copy
the saved state across.

Alternatively, start with a 2.x clean state, and add your tracks etc as
if you were a new user.

________________________________________________________________________


* 1.8 Tidying up after upgrading:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- AMPlay 1.53 stored its Genre information in !AMPlay.Resources.Genres.
  In 2.x, it's moved to !AMPlay.Resources.UK.Genres. If upgrading from
  an earlier version where you've manually modified the genres file, you
  may want to copy it across from your renamed copy, but note that the
  file supplied with 2.x contains more genres than previous versions.
 
________________________________________________________________________
Copyright  2008 Mike Sandells, mike@mikejs.com
Last Modified: 30.05.2008