* 7. Messaging API: ~~~~~~~~~~~~~~~~~~~ This document covers the messaging API used by AMPlay and AMPlayCfg. It could be used by other applications to control AMPlay. If you aren't a programmer, this section probably isn't of much interest to you. Indeed, the AMPlayCfg stuff is only likely to be useful if you feel like playing with the AMPlay source itself. The source download for AMPlay includes a sample app for communicating with AMPlay using the API. The AMPlayCmd utility included with AMPlay is also a useful source of example code. These are all user messages (type 17). AMPlay's officially registered message block is &563C0 - &563FF. All strings referred to are CR terminated. * 7.1 AMPlay_Command (&563C0): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +20 flags +24 Command +28 parameter 1 +32 parameter 2 +36 parameter 3 AMPlay_command is for immediate commands that will affect the state of the player. Normally, an AMPlay_Ack is returned to the sending task, to indicate success or failure (and why it failed). Optionally, it can write a file into PipeFS with the result (see reply by file, below). The parameters may be optional, depending on the command used. The parameters may contain strings or integers, again depending on the command used. The command is always a string. Flags: Flags are sent at +20 in the message block. Bit: Meaning if set: 0: Don't bother replying. 1: Reply by file instead of by message see below for more details of reply by file. 8: v2xx format understood. MUST BE SET. other bits should be zero. Bit 8 must be set in the flags in order for the message to be processed further by AMPlay. The reason for this is that v1.5x of AMPlay used a different mechanism here (the flags and command number were combined in a single word). Any 1.5x message that AMPlay 2.x receives will not have bit 8 set, and AMPlay will reply with a not supported error code using the 1.5x reply format (which also differs from how 2.x would normally reply). This avoids 1.5x command potentially being executed with different meanings by 2.x The AMPlay_ack returned will indicate success/failure only. This is because commands are telling AMPlay to do something, rather than asking it for particular information. For that, see AMPlay_request Commands: The command is sent at +24 in the message block. A command consists of a string of up to three characters, CR terminated (so that it occupies 4 bytes at most). Commands are not case sensitive, and are hardcoded - i.e. they are not fetched from the messages file, and therefore are not language dependant. Recognised commands Command Meaning Parameters. PLA Play 1 PAU Pause 1 STP Stop No REW Rewind 1 FWD Forward 1 PRE Previous 1 NXT Next 1 AUT Autonext 1 VUP Volume Up 2 VDN Volume Dn 2 VST Volume Set 2 RPT Repeat item 1 RST Restart Track 1 PTR Previous Track 1 NTR Next Track 1 PAL Previous Album 1 NAL Next Album 1 PAR Previous Artist 1 NAR Next Artist 1 ORD Change playback order 2 STF Set exclusive filter 2 MDF Modify single filter 3 SAF Set absolute filter 2 LD Pass file/dir to be loaded 1 STA Save state No CLR Clear history No REF Refresh 1 SRT Sort No DIE Quit 1 PAI Play any item 3 QAI Queue any item 3 FAI Alter filter status of any item 4 WAI Alter random weighting of any item 3 LAI Alter link status of any item 3 UAI Alter ignore unique for any item 3 AVT Alter relative volume of any track 3 RTA Refresh time on any item 2 RDB Remove any item from the database 2 RHT Remove any item from the track history 2 SWP Swap adjacent items 2 OPT Save options file 1 SPL Save playlist 1 TST Testing No Command details; PLA, PAU, STP, REW, FWD, PRE, NXT, AUT: These correspond to the main window buttons. Default behaviour is the same as a select click on the corresponding button. STP takes no further paramters. PAU and LOP take a further parameter in +28. This must be one of; OFF ON TOG And indicate what to do - e.g. to pause, unpause, or toggle the existing state, whatever it may be. PLA, REW, FWD, PRE, NXT take a further parameter in +28. This must be one of; NRM MOD This indicates whether to take the normal or the modified action. Modified in the case means adjust-click behaviour. For REW and FWD, normal behaviour is to move in units of 10% of the current track length. Modified behaviour is to move in units of 1% of the track length, for fine tuning. For PLA, PRE and NXT, again NRM refers to the select click action, while MOD specifies the adjust click behaviour. AUT is a special case as it has three possible states. It requires a parameter in +28 which must be one of; ALW NVR INH CYL CYR These mean Always, Never, In history, cycle left, and cycle right. VUP, VDN, VST: Parameter 1 must be one of BAS REL Indicating whether it is the base volume or the relative track volume you wish to edit. For VUP, VDN, parameter 2 must be NRM or MOD, as above. NRM modifies the volume in multiples of volumeincrement. MOD modifies the volume at double the normal rate. For VST, parameter 2 is an integer containing the new volume. The range varies depending on whether it is a base or relative volume being passed. Base volumes must be 0>127, while relative volumes must be in the range -63>+63. RPT: Paramater 1 must be one of ON OFF TRK ALB ART CYL CYR ON enables repeat at the current selection level. The others either disable repeat, or enable it at the specified selection level. CYL and CYR cycle through the options in the same way that clicks on the main window icon do. RST, PTR, NTR, PAL, NAL, PAR, NAR: These all take NRM or MOD as their parameter 1. RST means restart track, and currently has no corresponding main window button (although it is a playonplay option, and and adjust-click action for the play button). NRM for it means just to rewind to position 0, and make no other changes. MOD tells it to do that, but also to unpause the track if it was paused. The others listed here correspond to the previous and next buttons that are associated with the track, album and artist rows on the main window (as distinct from the row of buttons at the base of the window). NRM refers to the normal select click action (move within history if possible). MOD refers to the adjust-click behaviour of moving within the database instead. ORD: This takes a string in its parameter 1, which indicates which playback order you wish to change. This must be one of; CHA TRK ALB ART CHA turns chaos mode on, and takes no further parameters. The others then take a further string in parameter 2. This must be one of; LIN RND IGN If parameter 1 is TRK, then IGN is not allowed in parameter 2. This is because while albums and artist can have a playback order of ignore, tracks always have to be either linear or random. To turn chaos mode off, just set the playback order to one of the other states. STF, MDF, SAF: These are all methods for altering which filters are currently available, or active. They all take the same parameter 1 - a string which must be one of; ACT AVL and indicates whether it is the available filter set or the active filter set that we wish to modify. STF takes an integer in parameter 2. This integer must be a number from 1 to 20 (inclusive). The corresponding filter will be activated or made available (depending on parameter 1), and all the others turned off. MDF is similar to STF - if takes an integer in parameter 2, indicating which filter is to be operated on. Parameter 3 then indicates what is to be done to it, using the ON, OFF, TOG mechanism described above. SAF takes an integer in parameter 2. This integer is a bit mask, where bits 0-19 correspond to filters 1-20 (other bits should be 0). This specifies the new state of the active or available filters word within AMPlay. At least one bit must be set. Notes: MDF and STF differ in that STF affects all filters - it turns a specified one on, and everything else off. MDF allows you to turn particular filters on or off without affecting the state of the others. Similarly, SAF affects all filters. There is currently no equivalent of SAF that allows multiple filters to be altered. Any attempt to activate a filter that is not in the available filters list will result in a 'disabled' error being returned. Some operations may therefore require several calls - an AMPlay_Request call to read the current status, a call to make a specified filter available, and then one to activate it. Changes to the available filter that remove an active filter are allowed, as long as at least one filter is left active. e.g. if filters 1,2 and 3 are available, and filters 1 and 2 are active, then a call to make filter2 the only available filter will succeed, and implicitly inactivate filter 1. If filter 1 was not active in the first place, the operation would fail with a 'disabled' error. LD: This takes no parameter 1 or parameter 2, but does take a parameter 3. This isn't as weird as it sounds because parameters 1 and 2 are limited to 4 bytes, whereas parameter 3 is limited only by the overall size of the message block (around 200 bytes in practice). Parameter 3 contains the filespec or dirspec. AMPlay then responds as if the specified item had just been dragged onto it. It can contain variables, but it must resolve to a single object (i.e. mp3$dir is fine, mp3$path might cause undefined behaviour.) STA, CLR, SRT: These take no further parameters. REF: This takes parameter 1 only. This must be one of; TIM BND NAM These indicate Time, Boundaries and Names, and correspond to the menu options with the same function. DIE: This takes parameter 1 only. This must be one of; NRM MOD This indicates whether to save state on exit (NRM) or not (MOD). PAI, QAI, FAI, WAI, LAI, UAI, AVT, RTA, RDB, RHT, SWP: These all take the same infomation in parameter 1; TRK ALB ART This indicates whether the item is a track, album or artist. Parameter 2 then specifies which track, album or artist. This is an integer, and provides the number in the AMPlay database of the item in question. Use -1 to specify the current track, album or artist (if any - an error will be returned if there is no track playing) Parameter 3 then provides any details needed. PAI, QAI, RTA, RDB, RHT, SWP - no further details needed. LAI, UAI - ON, OFF or TOG. At this point we make use of a pseudo parameter 4, at offset 40. I.e. we no longer assume parameter 3 is one long string but continue to deal with each word in turn. WAI, AVT - Parameter 3 contains either SET or CHG, and specifies whether to set an absolute weight/volume or whether to modify the existing value. Parameter 4 then contains an integer specifying either the new value, or the change to be made. Weights must be in the range - 7 to +7, volumes in the range -63 to +63. FAI - Parameter 3 contains an integer from 1-20 specifying which filter is to be editted. Parameter 4 then contains one of NVR, ALW, ISO, LIN. This specifies the new state for the given filter. Notes; The track,album and artist numbers required are the pre-filter numbers, also known as the global number. A mapping from particular tracks to particular numbers can be obtained by either calling AMPlay repeatedly to request the details of each track in turn via macro expansion, or, asking AMPlay to dump out the playlist to file, and examining that. However, it is probably most likely to be useful in cases where you want to alter the current track, album or artist, in which case specify -1 as the item number. For linkage, ignore uniqueness etc, the attributes exist independently on albums, artists etc as well as at the track level. For filtering and relative track volume however, they exist only at the track level. In such cases, performing the operation at the album or artist level is just a way to get the operation performed on multiple tracks. When changing weights or volumes, the resulting weight or volume is constrained within the normal allowed ranges. Attempts to set a value outside the normal range will result in an error. Attempts to change a specific track album or artist to a value outside the allowed range will also result in an error. However, if changing the relative track volume on an album, say, as long as the change is plausible, even if any tracks within the album would have overshot the end, no error is returned. The offending tracks are silently constrained. (e.g. if a one track in an album has a volume of +50, and the album is told to change by +20, that track will end up with +63, but no error is returned because the request was plausible - +20 may have been added to the other tracks in the album successfully). SWP swaps the item with the one below it in database terms. If you want to swap track 5 with track 6, you would call SWP with 6 as the track number. As with the interface in the database editor, you cannot move tracks outside their album, or albums outside their artist (an 'outside range' error will be returned). SPL Parameter 3 indicates the filename to save the playlist to. (Note - this is all there is at present. Future versions of the API may offer some or all of the functionality of the export interface). OPT Parameter 3 indicates the filename to save as. This is used by AMPlayCFG if it is started manually, to get the current state of the options from the running copy of AMPlay. TST This is a simple test command. It takes no parameters, and does nothing. However, it is a valid command, and so will generate a 'success' reply. Can be useful while testing. It's also a useful test of whether you're talking to a copy of AMPlay that understands the v2 message formats ________________________________________________________________________ * 7.2 AMPlay_Request (&563C1): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (Formerly known as AMPlay_Status) +20 flags +24 Command +28 optional parameter 1 +32 optional parameter 2 +36 optional parameter 3 This is used to request information about AMPlay's current state, or specific items via macro expansion. The reply will come back as an AMPlay_Ack by default unless reply by file is requested. Don't forget SWI AMPlayer_Info will return a lot of information about current status at the mp3 level - elapsed time etc, and doesn't have the delays involved in sending a message and waiting for the reply. Use this only if you want information about the AMPlay front end.) Flags: Flags set sent at +20 in the message block. Bit: Meaning if set: 0: Don't bother replying. 1: Reply by file instead of by message see below for more details of reply by file. 8: v2 and later understood. MUST BE SET. other bits should be zero. Commands: The command is sent at +24 in the message block. A command consists of a string of up to three characters, CR terminated (so that it occupies 4 bytes at most). Commands are not case sensitive, and are hardcoded - i.e. they are not fetched from the messages file, and therefore are not language dependant. Recognised commands Command Meaning Further parameters. STS Request status 1 MAC Expand Macro 3 Command details: STS: Parameter 1 indicates what area we are interested in; AVR - AMPlay version information API - AMPlay API information SRC - AMPlay search information STA - AMPlay state information OPT - AMPlay options information SKN - AMPlay skin information PLR - General player information FLT - Filter information ORD - Playback order information MAC: Parameter 1 must be one of; CUR ATC ATM ATN This specifies how the track for which the macro expansion is to be relative to is determined. CUR = current track. 'No track playing' is returned if there is no current track. (Note - not a no current track error). ATC = Any track, using the current track number, if any. Middle track of database if there is no current track. ATM = Any track, using the middle track of the database. ATN = Any track, using track N, specified in parameter2. Some explanation required here: Some macros are intrinsically tied to the currently playing track (elapsed time, for example), and make no sense otherwise. The macro expansion function inside AMPlay knows this, and needs a parameter to tell it whether it is ok to expand such macros. So, parameter1=CUR will expand macros in the for-current-track-only list, while parameter1=anythingelse will ignore them. When determining the middle track in the database, it always rounds up, so if there are only two tracks in the database, it always picks the latter. For any of the totals macros, the track specified doesn't actually matter. Clearly, if you are interested in a particular track, album or artist, you need to specify the track via ATN. Parameter 2 is empty, unless parameter 1 is ATN, in which case parameter 2 is an integer containing the track number. Parameter 3 contains the string to be expanded. ________________________________________________________________________ * 7.3 AMPlay_Ack (&563C2): ~~~~~~~~~~~~~~~~~~~~~~~~~~ This is sent by AMPlay to tasks that send it "AMPlay_Command"'s or "AMPlay_Request"'s, unless they request reply by file instead. It is used to return basic success/failure information, and can also return other items, such as the results of string expansion. The layout is the same in all cases; Flags at +20 Response at +24 Response at +28 Response at +32 Response at +36 Whether the response is a string or an integer will vary, but in general, the response (if any) at +36 will always be a string, the rest will vary. +20 This is always returned in response to any command or status request. It is a bitfield, where the bits reflect error/success bit 0 - set if success, unset if error. bit 1 - set if response at +24 is valid bit 2 - set if response at +28 is valid bit 3 - set if response at +32 is valid bit 4 - set if response at +36 is valid (always a string, if present) bit 5 - set if response at +24 is a string (integer if unset) bit 6 - set if response at +28 is a string (integer if unset) bit 7 - set if response at +32 is a string (integer if unset) bit 8 - error: unrecognised command. bit 9 - error: unrecognised parameter for command. bit 10 - error: file not found bit 11 - error: file wrong type. bit 12 - error: outside range bit 13 - error: disabled. bit 14 - error: no current track. bit 15 - error: no tracks in database Other bits undefined, should be unset. If bit 0 is set, then bits 1-7 indicate what else is being returned. If bit 0 is unset, then bits 1,2,3,5,6,7 should be 0, and bits 8-13 indicate the error details. bit 4 may still be set indicating textual information has also been provided. (e.g. to indicate the filename to which a file not found error refers) The 'no current track' error is also returned in the case where there is a track playing, but it was started by a different front end. In that case, AMPlay has no connection between that track and an entry in its tracks database, and so cannot perform operations on it (such as relative track volume). The 'disabled' error occurs if you try to do something that is specifically disallowed. e.g. activate a filter that is not available, or make unavailable a filter that is active. In general terms, it occurs when you try to alter the state of something that would be greyed out if you tried to do it through the graphical interface. For a reply to AMPlay_Request, STS, AVR: +24 - AMPlay version. (integer) +28 - Application status (bitfield). bit0 for production release. bit1 indicates a public beta. bit2 indicates a private beta. bit3 indicates an alpha. bit4 indicates a user-customised version other bits reserved, must be 0. +36 - AMPlay version string, as on program info window. (a public beta would be a test version uploaded to the website for anyone to download. A private beta might be sent in email to test a specific problem. Alpha versions are my own works in progress, and are not normally released. Custom versions are, in accordance with the license agreement, user-modified versions that the user wishes to release widely. It is possible that a custom version might also be a beta/alpha) For a reply to AMPlay_Request, STS, API: +24 - AMPlay API version (integer) +28 - AMPlay API lowest compatible version. This is because - if the next version of AMPlay extends the api (which is quite likely), the api version number will increase. However, if these are purely extensions and contain no changes to existing behaviour, then existing apps will still be able to talk using v200 as described here. So, v210 of the api would specify 210 at +24, but 200 at +28, indicating that there is nothing in 200 that is not supported, just extra things that 210 can do. For a reply to AMPlay_Request, STS, SRC: +24 - AMPlay search version (integer) +28 - AMPlay search lowest compatible version. This specifies the acceptable formats of search block. As search blocks are not yet passable via API commands, this isn't of much use yet. For a reply to AMPlay_Request, STS, OPT: +24 - AMPlay options file version (integer). Version that AMPlay writes. +28 - AMPlay options lowest compatible version. This specifies the acceptable formats of options file. For backwards compatibility, a version of 0 corresponds to files that have no version number. For a reply to AMPlay_Request, STS, STA: +24 - AMPlay state version (integer) +28 - AMPlay state lowest compatible version. As above, but for the state file format. Current version, and lowest compatible version. For a reply to AMPlay_Request, STS, SKN: +24 - AMPlay skin version (integer) +28 - AMPlay skin lowest compatible version. As above, but for the skin format. Current version, and lowest compatible version. (You can't directly read the name of the currently configured skin, but as AMPlay cannot currently change skin without restarting, this information can be read from the options file.) For a reply to AMPlay_Request, STS, PLR: +24 - Integer. Bitfield indicating status; bit0:stopped bit1:playing bit2:paused bit3:fastforwarding bit4:rewinding bit5:queueing bit6:track history available bit7:database contains at least one track (some combinations make sense, some don't - paused and fastforwarding means that it is heading for a target time, and will be paused when it gets there) If bit0 is set, bits1-5 should be unset. bit2 set implies bit1 set bits 3 and 4 are mutually exclusive +28 Integer. Bitfield indicating status; bits0-7: base volume bits8-15: relative volume bit21: loop status bit22: 0=autonext never 1=autonext of type specified in bit23 bit23: (if bit22=1) 0=autonext within history 1=autonext always. bit24: set if track repeat active bit25: set if album repeat active bit26: set if artist repeat active Remaining bits currently unused. For a reply to AMPlay_Request, STS, FLT: +24 Integer. Bitfield where bits 0-19 indicate which filters are available. +28 Integer. As above, but indicating which ones are active. +32 String. One of; LIN ISO ALW This indicates which filter setting is currently being used. (it's decided based on the playback order.) Note that bit0 = filter1 etc. For a reply to AMPlay_Request, STS, ORD: +24 String. +28 String +32 String. The strings are all one of LIN, RND, IGN or CHA. +24 specifies the track playback order, +28 specifies the album, +32 specifies the artist. +24 therefore can never be IGN as the track playback order has to be linear or random. If chaos mode is active, then all three strings will be CHA. For a reply to an AMPlay_Request, MAC; +24 Integer. 0-static result, indefinite 1-static result, as long as current track remains current 2-dynamic result So, 0 tells the calling application that the result will not change until the string to be expanded changes (unless tracks are added to / removed from the database etc) 1 tells it that the result will change if the current track changes 2 tells it that it is changing rapidly (e.g. it contains a remaining/elapsed time that is changing every second). Generally, applications should not repeatedly re-expand the same string unless it is dynamic. +28 Integer. Normally 0. A +ve value indicates that the macro expansion produced too long a string. The value indicates the number of characters trimmed from the right hand edge to fit the reply in to the message block. The calling application might therefore use this to either indicate the truncation to the user, or possibly break the string to be expanded down into smaller segments that are in themselves expandable without truncation. +36 String. This contains the result of the macro expansion. ________________________________________________________________________ * 7.4 AMPlay_ChangingState (&563C3): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is broadcast by AMPlay on startup, and on quit. AMPlayCfg listens for this, to work out whether AMPlay is running and is a new enough version to support messages. AMPlayCfg also calls AMPlay_Request when AMPlayCfg starts to determine if a new enough AMPlay is already running. AMPlayCfg needs to know this information to work out whether to tell AMPlay that options have been changed, or just update the config files for AMPlay to re-read on next run. It contains; +20: Flags. +24: Integer. AMPlay version +28: Integer. AMPlay API version. +32: Integer. Lowest compatible API version +36: Integer. AMPlay options file version that AMPlay writes. +40: Integer. Lowest compatible options file version The flags word has the following meanings; bit: Meaning if set. 0: Starting up (shutting down if unset) other bits currently unused. ________________________________________________________________________ * 7.5 AMPlayCfg_ChangingState (&563C4): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is broadcast by AMPlayCfg on startup, and on quit. AMPlay listens for this, to work out whether AMPlaycfg has been started by the user (as opposed to being launched from AMPlay). AMPlay checks through the list of running tasks to see whether it is already running when AMPlay starts (there not being a version problem here). AMPlay only uses this information to keep the button on the main window in the correct state. In v2.00 AMPlaycfg also broadcasts this when it received an AMPlay_changing state that indicates that AMPlay has just started. This allows AMPlay to know that a copy of AMPlayCfg is already running, and what it's version information is. It contains; +20: Flags. +24: Integer. AMPlayCFG version +28: Integer. AMPlayCFG API version. +32: Integer. Lowest compatible API version. +36: Integer. AMPlay options file version that AMPlayCfg writes. +40: Integer. Lowest compatible options file version The flags word has the following meanings; bit: Meaning if set. 0: Starting up (shutting down if unset) other bits currently unused. ________________________________________________________________________ * 7.6 AMPlayCfg_Command (&563C5): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is broadcast by AMPlay when it wants to make a running copy of AMPlayCfg either load an options file, or bring its window to the front. It contains; +20: Flags. +24: Command (three character string, CR terminated.) +32: String. (if command requires it) Flags: Bit: Meaning if set: 0: Don't bother replying. 8: v2 API understood. MUST BE SET. Other bits unused. Commands: LOA FRN LOA: This tells AMPlayCfg to load the file specified at +32, and bring itself to the front. FRN This just tells AMPlayCfg to bring its window to the front, without taking any other action. ________________________________________________________________________ * 7.7 AMPlayCfg_Ack (&563C6): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ AMPlayCfg returns this in response to AMPlayCfg_Command messages, unless those messages set the flag to not bother replying. It comprises; Flags at +20 Flags is a bitfield, where the bits reflect error/success bit 0 - set if success, unset if error. bit 8 - error: unrecognised command. bit 10 - error: file not found bit 11 - error: file wrong type. (i.e. same as AMPlay_ack flags, but a reduced set as only certain ones are relevant.) 'File wrong type' is returned if it is asked to load a file that is not of type 'AMPlay', 'AMPlaycf' or text. No error is returned if the file contains no recogniseable options. ________________________________________________________________________ * 7.8 Reply by file: ~~~~~~~~~~~~~~~~~~~~ Normally, AMPlay replies to an incoming message by sending a message back to the application the message came from. AppA sends an AMPlay_Command or AMPlay_Request to AMPlay, and AMPlay sends an AMPlay_Ack to AppA. This is fine if AppA is a normal wimp task, and capable of receiving messages. If however, is is running in a taskwindow, it has no way of receiving messages (the taskwindow itself gets them, and they never reach the task running inside the taskwindow). Reply by file is an alternative way for AMPlay to respond. Instead of sending an AMPlay_Ack to the task that sent the message, it writes the result to a file Pipe::$.AMPlayOut. The output comprises each returned parameter that would have been sent in the Ack. i.e. A flags word, followed by whatever returned information the flags word indicates. Integers are written to the output as strings. e.g. A reply to an AMPlay_Request, MAC, ATC, 0, %tn might be; 23 1 0 04 - Epitaph AMPlayCfg does not support reply by file. (Note that this format is not the same as that used in 1.5x) ________________________________________________________________________ * 7.9 Compatibility: ~~~~~~~~~~~~~~~~~~~~ The API in 1.5x of AMPlay is not compatible in any way with that in 2.x. Commands are now named instead of numbered, and the flags word is now separate from the command word rather than hiding information in the high bits of the command. I took the decision to make it incompatible when it became clear that the 1.5x API made quite a few assumptions about filtering behaviour (and playback order and a few other things) that were no longer valid. This meant that 2.x was going to be incompatible in significant ways anyway, and therefore it provided an opportunity to resolve any outstanding issues with it. To do it properly, in other words. The use of named instead of numbered commands and parameters opens up the 'raw' format for AMPlayCmd commands, and allows AMPlayRCG to offer the full range of API functionality to its clients, without having to know what the full range of commands and parameters actually is. i.e. it makes it much easier for such things to act as a passthrough that places no limits on the content. AMPlayCmd can also do just about anything that the API makes available without having to understand it itself. If AMPlay 2.x receives a 1.5x style message (as indicated by bit8 not being set in the flags word), it will reply in 1.5x style format with an unrecognised command error. Similarly, if you send a 2.x style message to 1.5x, you'll get back an unrecognised command error in 1.5x format. This will look like this; +20 Integer. A value of 8 indicates unrecognised command. This can be detected because this corresponds to bit 3 set, with everything else 0. i.e. bit 0 is unset, indicating an error, but none of the error bits (8 onwards) are set. A version that speaks 2xx of the API would never return this. It's worth noting that compatibility gets a bit fuzzy in some areas. Suppose v210 of AMPlay contains no changes to the API, but does extend the range of macros supported. In that case a call to expand a macro would work on one version of AMPlay and not the other even though the API implementations are identical. Where you get into relying on other features within AMPlay, you may need to take the AMPlay version itself into account. That said, AMPlay provides two pieces of version information for the API - the current API version, and the lowest version with which it is compatible. e.g. a version 210 which added extra commands, but included the entire 200 API unchanged, would declare itself as 210, compatible with 200. ________________________________________________________________________ * 7.10 Example Applications: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The AMPlayRCG application uses the API to communicate with AMPlay. AMPlayCfg also makes (fairly minimal) use of it. AMPlayCmd uses the API, and also uses the reply by file mechanisms to retrieve the results of macro expansion. The source for all of these is available. AMPlayCmd is included with AMPlay, and is not crunched or otherwise compressed. AMPlayRCG is a separate download from my website. None of these make full use of every API call - in particlar AMPlayRCG operates as a pass through and has very little understanding of the data it passes on (although it does have to understand AMPlay's replies). * 7.10.1 Raw format: ~~~~~~~~~~~~~~~~~~~~ AMPlayCmd and AMPlayRC have a 'raw' mode which allows a string to be passed that contains the command and parameters separated by # characters. e.g. cmd#pau#tog would send a command to toggle the pause status. Fields that are entirely numeric are assumed to be integers and passed as such. This is covered in more detail in the AMPlayCmd (section 8.3) and AMPlayRCG documentation (included with AMPlayRCG). When using the raw format, they are not limited to the API version that was current when they were produced - they can handle just about any subsequent extensions or additions. There is also the AMPlayAPI app, available as part of the source archive. This contains generic code for sending and receiving messages, although all the parameters are manually entered. However, it provides a useful piece of scaffolding for testing API functionality. ________________________________________________________________________ * 7.11 Changing options via the API: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Possibly obvious, but worth noting. There is no API for directly setting AMPlay options. If your client wishes to change options, then it should write a temporary file in the options file format, containing just the options that need changing, filetype it as AMPlaycf, and pass it to AMPlay using the load file mechanism. A header including the text '[options]' will also work if you want to leave the file with the text filetype. AMPlayCfg uses this mechanism to update the running copy of AMPlay with the changed options. ________________________________________________________________________ * 7.12 Future APIs: ~~~~~~~~~~~~~~~~~~~ Future versions of AMPlay may extend the range of commands available. They may also extend the parameters available for particular commands. However, there are no changes planned that would alter the structure of the API in an incompatible way. If such a thing were to happen, the version in which this change occurred would report its API version as the lowest compatible version. Particular things that are currently conspicuously absent from the api; - The search mechanisms cannot be accessed from the API. - There is no way to get to the export functionality via the API. - The naming method for the tracks cannot be changed via the API. Similarly, the re-read tags and write tags options are not available via the API. (The naming details themselves also cannot be editted via the API, but this is likely to remain the case). ________________________________________________________________________ Copyright © 2008 Mike Sandells, mike@mikejs.com Last Modified: 30.05.2008