* 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