
* 8. Miscellaneous:
~~~~~~~~~~~~~~~~~~~

* 8.1 Co-Existence with other AMPlayer related apps:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ControlAMPlayer, AMPlayer (the original front end), !Amp, DigitalCD,
ROTunes, etc.

  These work fine, with the following caveats;

  - Ensure that only one application is set up to handle choosing what
    track to play next. In other words, if you are using Auto Queueing
    in AMPlayer, turn off Autonext in AMPlay, or vice versa.

  - If AMPlay is to display sensible information about the currently
    playing track, then it either needs to have started it playing from
    its own database, or the file must be tagged (AMPlay will 
    automatically use the tag information for files started by other
    players).

  - Tracks which are started playing by other front end applications
    will not appear on the AMPlay history.

  - If AMPlay's Autonext function is enabled, you cannot use a different
    front end to stop the playback entirely. Stopping the track with a
    different front end will cause AMPlay to move to the next track.
    (This can be useful in some circumstances, of course - it means
    that the stop keypress in ControlAMPlayer can be used as a Next
    button for AMPlay).

  - When using AMPlay changes from one track to the next, other front
    ends may display the track being changed to before it has actually
    started playing.

  - I've mentioned DigitalCD above, but it's worth noting that this
    does not use the AMPlayer module by default, but must be configured
    to do so.

AMSpectre.

  Works fine.

AMP16.

  Works fine.

________________________________________________________________________


* 8.2 AMPlayRCG:
~~~~~~~~~~~~~~~~

AMPlayRCG (AMPlay Remote Control Gateway) is a remote control
application for AMPlay - the idea is that you run it on the
same machine as AMPlay, and communicate with it over the network.

AMPlayRCG communicates via input and output files, and relies on 
whatever existing network filesystem you prefer - sharefs, lanman,
samba, nfs etc. It doesn't care what the protocol is.

The input files contain commands specifying AMPlay API messages in
a text based format. AMPlayRCG sends these messages to AMPlay, and
passes back the replies.

Rather than clutter up an already large AMPlay download, AMPlayRCG is
separately downloadable from my web site. More documentation is
included with it. This entry in the AMPlay documentation is so that you
have some idea of what it does.

See also section 7 of this documenation on the messaging API.

Note that it is only half of the solution to the remote control
problem - you still need something at the other end to send requests to
AMPlayRCG to be passed on to AMPlay. In my case this is a little batch
file, and is included with AMPlayRCG, mostly for demonstration
purposes. I do intend to write proper RISC OS and windows clients for
this at some point.

Note that v2.00 of AMPlayRCG is the minimum version required to
communicate with AMPlay 2.00 and later.

________________________________________________________________________


* 8.3 AMPlayCmd:
~~~~~~~~~~~~~~~~

AMPlayCmd is a little BASIC program that allows you to control AMPlay
from the command line, from obey files etc.

Its purpose is to allow you to use your favourite shortcut or launcher
program to control AMPlay. AMPlay itself has keyboard shortcut
support, but this only works when AMPlay has the input focus. Many
launcher apps can assign actions to keyboard events even when they
don't have input focus, and these can be assigned to AMPlayCmd
commands.

The AMPlayer module itself has a command line interface, and you can
do a great deal with it. AMPlayCmd is not intended as a replacement
for it, but as a supplement to it, when using the !AMPlay application
as a front end to the module. There are some areas where AMPlay
differs, and some things that are specific to AMPlay itself that the
back end module doesn't know about.

The following parameters are recognised. They are not case sensitive.

-play                   : Play (playonplay applies if already playing)
-pause                  : Pause toggle
-pause_on               : Pause on
-pause_off              : Pause off
-autonext               : Autonext cycle
-autonext_always        : Set autonext to always
-autonext_never         : Set autonext to never
-autonext_history       : Set autonext to within history
-rewind                 : Rewind by 1% [1]
-rrewind                : Rewind by 10% [1]
-forward                : Fast Forward by 1% [1]
-fforward               : Fast Forward by 10% [1]
-restart                : Restart current track (doesn't unpause) 
-restart_unpause        : Restart current track (unpause if paused)
-next                   : Next track [2]
-forcenext              : Next track after top of history
-previous               : Previous track [2]
-previous_track         : Previous track in history 
-previous_album         : Previous album in history
-previous_artist        : Previous artist in history
-previous_track_inlist  : Previous track in playlist
-previous_album_inlist  : Previous album in playlist
-previous_artist_inlist : Previous artist in playlist
-next_track             : Next track via normal selection method
-next_album             : Next album via normal selection method
-next_artist            : Next artist via normal selection method
-next_track_inlist      : Next track in playlist
-next_album_inlist      : Next  in playlist
-next_artist_inlist     : Next track in playlist
-volume_up              : Increase volume by volumeincrement [3]
-vvolume_up             : Increase volume by 2xvolumeincrement [3]
-volume_down            : Decrease volume by volumeincrement [3]
-vvolume_down           : Decrease volume by 2xvolumeincrement [3]
-volume_track_up        : Increase relative volume by volumeincrement
-vvolume_track_up       : Increase relative volume by 2x above
-volume_track_down      : Decrease relative volume by volumeincrement
-vvolume_track_down     : Decrease relative volume by 2x above
-quitamplay             : Quit AMPlay, saving state if applicable
-quitnostate            : Quit AMPlay, without saving state
-savestate              : Save state
-sort                   : Sort database

-expand:[string]        : Expands the specified string. [4]
-raw:[string]           : Sends a raw command. [5]
-xraw:[string]          : Sends a raw command, no reply. [5]

-help                   : Display brief help
-verbose                : Display details of each message sent [6]


[1] AMPlayer offers the AMLocate command to go to a particular point
in a track. This takes a +/- parameter of mm:ss to specify the amount
to move, or an absolute parameter of mm:ss to specify the point to go
to. AMPlay however, uses rewind and fast forward proportional to the
length of the track, hence these command line options.

[2] 'next' and 'previous' correspond to the generic 'next' and
'previous' buttons on the main window. These are broadly similar,
but not identical, to the next_track and previous_track commands.
See section 3.1.3 for the differences.

[3] This is roughly equivalent to AMVolume +/-x, where x is the
volume change you want. See also AMVolume x, which specifies the new
volume exactly. The command line options here are present for
symmetry with the relative track volume options (which AMVolume
doesn't know about), and to allow the volumeincrement variable to be
set in one place only.

[4] If using the expand parameter, it must be the last parameter
specified. Everything after it is taken as the string to be expanded.

[5] This is a raw API message in the format either;

cmd#abc#xyz#pqr

or

req#abc#xyz#pqr

Where;

cmd - specifies that an AMPlay command is to be sent.
req - specifies that an AMPlay request is to be sent.

abc - the command/request to send.
xyz - first parameter to the command/request
pqr - second parameter to the command/request.

e.g.

amplaycmd -raw:cmd#pau#tog

would send a command to toggle the pause status.

For full details on what is possible here, refer to section 7 on the
messaging API.

Also, this format (# separated) is the same as that used by AMPlayRCG,
so some parts of the documentation for that will be relevant.

-xraw does exactly the same as -raw, but tells AMPlay not to bother
replying. It can therefore produce no text output at all, which is
what you'd want if running it on a keyboard shortcut or similar.

[6] To make much sense of these details, you'll need to refer to
section 7 of the AMPlay documentation, covering the AMPlay
messaging API.


Parameters may be combined up to a point. Specifying the same
parameter more than once won't have any extra effect - only one
message will be sent. Also note that some actions are implicit (e.g.
any next or previous track/artist/album operation will unpause the
player). You could however do the following;

AMPlayCMD -next_track -pause -volume_up

If multiple command line parameters are specified, then the order in
which the messages are sent may not match the parameter order. This
may be fixed in a later version.

The -raw, -xraw and -expand parameters are best not combined with
anything else, other than -verbose (which must go before them).
________________________________________________________________________


* 8.4 Internationalisation:
~~~~~~~~~~~~~~~~~~~~~~~~~~~


Currently, only UK resources are supplied with AMPlay. However, AMPlay
has been written with internationalisation support in mind, and where
possible, text seen by the user is fetched from a messages file in a
country specific directory, located using the resfind mechanism.

Unfortunately, while I can just about get by in German, my language
skills aren't up to the job. If anyone is able to provide translated
versions of (even part of) the resources, then they would be gratefully
received, and incorporated into future versions.

Note that text used in the saved files (markers, keywords etc), the
API, and in the search block format is not internationalised.

Also, the DrWimp library has its error messages hardcoded in English.
Therefore errors that arise in the library itself rather than in AMPlay
will always be in English. (Such errors would include things like out
of memory errors when attempting to grow the dynamic area etc).

AMPlayCfg has internationalised support in the same way that AMPlay
does. The other apps and utilities (AMPlayCmd, AMPlayRCG, AMPlayAPI
etc) largely have hardcoded messages.

________________________________________________________________________


* 8.5 Skinning:
~~~~~~~~~~~~~~~

AMPlay supports a rudimentary skinning system. This may be developed
further in later versions.

Currently, there are two parameters that can be set;

Skinsdir - defines the directory in which skins will be looked for.
Skin - defines which skin to use.

A skin is itself a directory, and the name of the skin is the name of
the directory.

In order to be considered valid;

- Skinsdir must exist, and must contain a skin called 'Default', as a
  minimum.
- Any skins (including 'Default') must contain !Skin, Sprites and
  Templates files.
- The !Skin file must contain a skinver variable that AMPlay considers
  compatible, together with variables that specify the progress bar
  details (position on window, length, and size of progress bar marker).

The default is within AMPlay itself, i.e.;

Skinsdir=!AMPlay.Skins (note - no trailing dot)
Skin=Default

Files:
!AMPlay.Skins.Default.!Skin
!AMPlay.Skins.Default.!Preview
!AMPlay.Skins.Default.Sprites
!AMPlay.Skins.Default.Templates

The default skin file contains (ignoring comments);

skinver=203
progbar_x=14
progbar_y=-224
progbar_length=580
marker_xsize=20
marker_ysize=20
messages=artist
Description=Default skin. Redesigned with larger buttons.

These specify, in turn;

- The version of the skin format the skin conforms to. AMPlay supports
  a range - it has a preferred and a lowest compatible version number.
- The offset from the left edge of the window for the start of the
  progress bar.
- The offset from the top of the window for the upper edge of the
  progress bar (RISC OS considers the top left of the window to be the
  origin, so y values within the window are always negative).
  (All distances are in OS units, typically 2 OS units = 1 pixel.)
- The length of the progress bar.
- The progress bar marker width.
- The progress bar marker height.
- Which field on the main window to display AMPlay messages in.
- The description for that skin to use in AMPlayCfg.

The progress bar always goes from left to right, and always has a
marker (i.e. you can't currently get it to use a slider).

If AMPlay does not consider the current skin configuration valid, it
will revert to its internal default one.

It is recommended that you do not edit the internal skin (because it
will be overwritten on upgrades, and because AMPlay may crash if you
corrupt it). If you want to alter the appearance of AMPlay, you should
copy the default skin to Custom (or whatever you want to call it), and then either modify the !skin, sprites and templates accordingly, or supply your own created from scratch. Likewise, although the Small Blue skin is not critical, it is likely to be overwritten when upgrading to newer versions of AMPlay. It is recommended to copy it and alter the copy, rather than altering the original.

Currently, AMPlay assigns functions to the icon numbers that the
default skin has. Therefore, if you design a new set of templates from
scratch, you must ensure that the button you intend to be the play
button has the same icon number as the play button in the default skin, and so on. It is therefore probably easier to modify a copy of an existing skin than to
create from scratch.

The skin only includes the main and mini versions of the player window.
Everything else uses the standard RISC OS design.

The skin contains no user-displayed text - all the text that is ever
displayed on the main window comes either from macros or from AMPlay's
messages file - there is no text in the templates themselves. The skin
is therefore independant of the internationalisation support.

Note that although the main database is stored in a dynamic area, the
window templates and sprites for AMPlay are stored in its wimpslot. If
you create a custom skin that is noticeably larger than the default,
you may need to increase the wimpslot setting in the !run file. (In
practice, there's probably quite a bit of room spare.)

2.03 and later offer the ability for a preview sprite to be used in
AMPlayCfg. This allows you to get an idea of what the skin looks like
without having to select it and restart AMPlay. The preview sprite is
optional (as is the description field), but if you want to provide one,
the details needed are;

- Sprite file must be called !preview, and sit in the directory
  alongside !skin.
- The sprite itself must be called 'preview'.
- The sprite should be no more than 450x250 pixels, and no more than
  500KB.
- By convention, the preview is only of the main window, but there is
  nothing preventing you combining images of the main and mini windows
  on the same preview sprite.
- By convention, the preview does not include the window furniture.

The default and other provided skins include preview sprites and
descriptions.

________________________________________________________________________


* 8.6 The To-Do list:
~~~~~~~~~~~~~~~~~~~~~

AMPlay is still being developed.

The version number is of the form a.bcx, where

a = Major version. Only likely to change on complete rewrite or after
    enough incremental changes that it is a substantially different
    animal.

b = Minor version. Changes with significant feature improvements.

c = Minor sub-version. Changes with minor feature improvements and bug
    fixes.

x = Letter suffix (e.g. 2.00a). Indicates a bug-fix only release with
    no changes to documented behaviour.


2.04 should have;

- Fixes for bugs discovered in 2.03

2.10 might have;

- Multitasking for folderscan, search, export and possibly for state
  load and save.
- Ability to change skin without restarting.
- API extensions to allow API commands to open AMPlay windows
- Extensions to autonext to offer the ability to
  - Stop after X tracks, albums or artists.
  - Stop after X minutes.
  - Stop at time X.
- Transient file support (i.e. tracks that remove themselves once
  played)
- Keyboard shortcuts
- History editor
- Change search 'first match only' to 'first N matches'.

(None of this is carved in stone - some of these may not happen, or
may not happen in the releases indicated. However, these are the
directions I plan on heading in.)

The source is available, so if you want to add these features or any
other features, feel free...

________________________________________________________________________


* 8.7 Known Problems/Quirks:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Changing panes in the database editor or AMPlayCfg causes it to jump
  to the front.

- There is some obscure combination of circumstances, generally
  involving playing external tracks (i.e. AMPlay is displaying info
  about a track that isn't in its database) which results in the fast
  forward and rewind buttons being greyed out when they shouldn't be.

  I've seen this several times, but been utterly unable to reproduce it
  when monitoring the exact sequence of steps. If you see this, pausing
  and unpausing will clear it. If you can work out what you did to
  cause it, please let me know...

- There have been some instances where operations that start a different
  track playing (Next, Forcenext, Previous Album, etc) fail to unpause.
  i.e. You're on one track, paused. Clicking next takes you to another
  track, but it starts paused on the new track.

  I think most cases of this particular bug are resolved. However, it
  is still triggerable if you click next while AMPlay is locating
  within a track during startup. (Clicking next during a locate is
  fine at other times).

- Operations (pause, play etc) that take place while AMPlay is in
  the process of changing from one track to the next may be ignored.

The AMPlay page on my website has a section listing bugs that have been
found or reported since release (and possibly workarounds for them).

________________________________________________________________________


* 8.8 Troubleshooting Common Problems:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unable to add tracks to the database:

- The most likely reason for this is that the tracks have a filetype
  and/or file extension that is not among those that AMPlay will allow
  in the database. The default is to only allow files of type 1ad, and
  only allow files with either "mp3" as an extension (e.g.
  filename/mp3) or no extension at all.

  These settings are configurable, and optional. See section 4.5 and the
  entries for Included Filetypes and Included Extensions.

  Note that filetype BF8 is the filetype for mpeg video files, NOT
  audio. AMPlay cannot play video files, and therefore does not allow
  files of type BF8 to be added to the database. If you have audio
  mpeg files with a filetype of BF8, then the correct solution is to
  type them correctly (1AD), and fix whatever mechanism typed them
  incorrectly (probably your mimemap file).


Incorrect album, artist or track names appear, but it plays correctly:

- If using pathname based naming, this can happen if the full filenames
  don't conform to the configured naming scheme. By default, AMPlay
  assumes that the leafname of the file is the trackname, the parent
  directory gives the album name, and the parent of that gives the
  artist name. If this is the case, use the naming editor to correct
  the names, or read the naming details from the tag.

- Another possibility with pathname based naming is that the files have
  been renamed, and the corresponding changes made in the state files,
  but the cached information has not been updated. In this case a
  Refresh Names should recalculate the information correctly.

- If using tag based naming, this just means that the tags on the file
  are incorrect. Edit the names in the naming editor, and use the
  'write tags' option to update the files with the correct information.
  (You'll need to turn on the 'overwrite existing tags' option too.)
  Note that tags have strict limitations on the length of the track,
  album and artist names. What you're seeing as an incorrect name may
  simply be truncation of the name to fit it into the tag.

  In that latter case where the 'correct' name won't fit into the tag,
  just edit the name to correct it, but don't bother writing it back
  to the file. AMPlay allows much longer limits on the fields, and
  only truncates things to fit into the tag when updating the tag.


AMPlay starts up, moves to the position within the track that the saved
state indicates, and instead of starting to play from that point, moves
on to the next track:

- This can happen if you've set the AMPlayer$FileBuffer to zero (as
  described in the FAQ), in order to improve performance for reading
  information from large numbers of tracks. If you forget to set it back
  afterwards, the described symptom can happen.


On startup, AMPlay generates the error "Not enough memory in heap", or other memory related error:

- This can happen if you configure AMPlay to use a skin that requires
  considerably more memory than the default one. To fix this, edit
  !AMPlay.!Run and increase the wimpslot settings.
  
________________________________________________________________________


* 8.9 Other information:
~~~~~~~~~~~~~~~~~~~~~~~~

This section covers anything not covered elsewhere - generally because
it is more background information on how the feature works than
necessary information about how to use it.

- String handling and conversions are applied in the following order:

  - The macro is expanded, with the n, x and z modifiers applying during
    the expansion process.
  - The expanded macro then has the various conversion options applied
    to it (slashes to dots, spaces to underscores, space before caps,
    lanman and nfs).
  - This then has the other modifiers (c,l,u,w) applied to it.

  The upshot of this is that any text in the main window, database
  window or menus that isn't the output of a macro will not be
  affected by the conversion options.

  I.e. %tb_%tn will come out as 01_TrackName, irrespective of what
  the convert underscores to spaces option is set to. Any underscores
  in the string that %tn expands to will be converted, any that are
  in the original string will remain.

  The order also means that the space before caps processing occurs
  before any modifiers that might alter the case.

  Conversions only apply when expanding a macro.

- For the record, all the mp3 tracks referred to in this documentation
  are taken from albums that I have bought and own.

________________________________________________________________________


* 8.10 Credits:
~~~~~~~~~~~~~~~

Thomas Olsson for writing the original AMPlayer.

Justin Fletcher and Robin Watts for continued development of the
AMPlayer module, and for testing and feedback on various versions.

Dane Koekoek, Andy Wingate, John Duffey, Alex Cleater and Malcolm Boura
for various help or feedback while developing 1.x.

Nico ter Haar for advice on making AMPlayCfg slot in as a plugin to
RISCOS Configure. The document on this subject by Richard Hallas was
also useful here. (I take the blame for any areas where it still doesn't quite match the style guide ...)

Ray Favre for DrWimp (and the many and various contributors to it).

Lisa Nelson for assistance and encouragement with both features and
implementation, for proofreading the docs (although any remaining
mistakes are my own), and also for copious tea.

________________________________________________________________________


* 8.11 License:
~~~~~~~~~~~~~~~

* 8.11.1 Preamble:
~~~~~~~~~~~~~~~~~~

The application contains routines derived from the DrWimp library. These
are covered by their own license documents. The relevant sections are;

[...]

  Distribution of the Dr Wimp package (and programs constructed using
  the DrWimp library) by third parties:

  Freeware.

  The DrWimp library may be distributed for free and without the
  documentation, examples, utilities, etc. if it is being used as part
  of a freeware product. (It would be nice if your documentation
  acknowledged Dr Wimp - and don't forget that my web-site has a page
  for links to your Dr Wimp applications, if you let me know .....)

[...]

  The DrWimp library may be reproduced in part if crunching and
  mangling utilities such as !BSquasher and !MakeApp are used,
  otherwise it must be reproduced in whole, complete with its opening
  REMs containing the Conditions of Use and the copyright banner.

[...]

Conversation with Ray Favre (the maintainer of DrWimp) has confirmed
that compiling using the ABC compiler from Castle is allowed, and is
treated in the same was as crunching would be.

It's also worth noting that the DrWimp library was modified slightly in
the process of creating AMPlay. These modifications have been discussed
with Ray and are done with his permission. The modified library is
included with the source download, and my changes have also been
submitted to Ray for inclusion in future versions. (The changes are to
fix some issues that would otherwise prevent compilation, and resolve a
memory leak with dynamic menus).


* 8.11.2 License Text
~~~~~~~~~~~~~~~~~~~~~

This application is Freeware. There is no charge for using this
application. You may copy it, and distribute it as widely as you
like with the following restrictions:

  - Only the complete application is distributed. Portions of this
    application may not be distributed either separately, or as part
    of another product.

  - It must be distributed unmodified.

    You may produce modified versions, but they must be derived from the
    AMPlay source materials, available separately, and covered by their
    own license.

  - You may not claim parts of the application as your own work.

  - No charge other than media and postage costs is made for this
    application.

  - I take no responsibility for any damage that arises to your
    system as a result of running this application. There is no
    warranty of any kind.

The source code for this application is available, but is not included
in this archive. It is downloadable from my website as a separate
file, and contains its own license file.

________________________________________________________________________


* 8.12 Web Resources:
~~~~~~~~~~~~~~~~~~~~~

The latest version of AMPlay, together with anything else I may have
cobbled together in the meantime should be available from;

http://www.mikejs.com/

Probably in the RISC OS section.

The distribution site for AMPlayer is;

http://www.amplayer.org/


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