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