AMPlayer

This SWI is used to play or queue a file for playback. When starting play transiently, the current play is unchaged and only the new instance is affected.

This SWI is used to stop playback, or start the skip to the queued file.

This SWI is used to pause or resume playback. When paused, decoding to the output buffer continues, but at a much reduced rate. There is no sound output.

Pause mode may also be cancelled by stopping. If SWI AMPlayer_Stop is used to cut to the next file, or if a different file is started, pause mode will continue to be in effect, freezing the new file at the start of the file. This can be used to ensure that playback starts at the instant of calling AMPlayer_Pause (as opposed to calling SWI AMPlayer_Play, which can have a delay while opening the file etc).

This SWI locates the position of the target time, and continues playback (or pausing) from there. This has no effect unless the status is either Playing, Locating or Paused. This may take some time, and the playback buffer may empty (which will mute the sound).

The time given here corresponds to the elapsed time returned from SWI AMPlayer_Info. This is true even when the elapsed time is wrong. So when, at time X, the Info call returns the wrong time Y, giving time Y to this call will still start playing at the right time X.

Playback can only start on a frame boundary, so the resolution of the start point is around 2 cs (for 128kbit/sec, 44.1kHz frames).

This call will return information about the current state of the player.

When locating, the current time can be read from the file info block, as it moves toward the target time returned in R4.

This call might be made from BASIC with :

SYS "AMPlayer_Info",,"" TO ,Filename$,FIB%

This will set Filename$ to either "" or the filename. Similarily, FIB% will be 0 if there is no info at this stage, or a pointer to it if there is.

There is a brief period when the status might be returned as Locating (2) or Playing (3), but where there is no valid FIB or FRIB, because the first frame has yet to be read.

This SWI is used to configure various aspects of the AMPlayer module's operation.

This SWI is used to read or write the main volume level of the player.

This control call is used to read or write the size of the audio buffer used by AMPlayer to store decoded data. The size can be specified in bytes or in blocks. It is recommended that you use the blocks size to be compatible with the system variable usage, and to ensure that similar amounts of data are buffered in future.

If the buffer isn't currently created, this controls how large it will be when it eventually is. If it exists, OS_ChangeDynamicArea is used to change the size. This may fail with an error, even if some of the job was done (this can happen when reducing the size, as the amount that can be released depends on what is currently being played). This effect is greatly reduced in AMPlayer 1.29 and later.

If it succeeds, the sound may be broken up slightly. On versions of AMPlayer prior to 1.29, this will always cause at least one 'jump' in the playback.

This SWI call is used to set the stack check level used when a callback occurs

When receiving a callback, the SVC stack depth is checked to see if the kernel is reasonably unthreaded. By using this call, you can control what is considered "reasonable". The default value is currently 64, i.e. if there are more than 64 words on the stack by the time of the callback, a new callback will be registered later instead. Setting this too low will cause the player to stall, and you can only stop it by killing the module (or putting the level back up).

It is not expected that users of the AMPlayer API will need to use this SWI.

This control call is used to control ID3v2 processing within the player.

ID3v2 processing is quite intensive and can have a performance hit, especially when compressed frames are used.

This SWI is used to enable or disable the processing of ID3v2 tags by the AMPlayer module.

When disabled, no ID3v2 processing at all is performed - the tags are merely skipped. This will improve performance when such tags are encountered.

This SWI is used to enable or disable specific frames or groups of frames for processing through the service interface.

A single character frame name will select all frames starting with that character. Three character frame names select the ID3v2.2 and earlier frames that match. Four character frame names select the ID3v2.3 and ID3v2.4 frame explicitly.

Claimants of the ID3v2 service should enable the frames they wish to see, and disable them when they no longer require them.

This SWI is used to read or write the transiency flag for an instance. Transiency has no meaning for the base instance, but for created instances, it means that when playback completes, the instance will be destroyed automatically.

This SWI is used to read or write the 'decimation threshold'. AMPlayer will normally decode data at full accuracy. If the 'decimation threshold' frequency is met or exceeded, the module will apply automatic decimation to the output.

The initial decimation value is based on the version of the module in use (for AMPlayer, this is 1000000, for AMPlayerFP, it is 22050, and for AMPlayer6 it is 0). This can be overridden by setting the AMPlayer$DecimationThreshold variable to a number before starting the module. Setting the decimation threshold of the base instance will set the variable to the same value.

On builds that do not support decimation, the calls are ignored, and reading the decimation always returns 1000000.

This SWI is used to register or deregister plugins.

This SWI attempts to return useful information about the file given. The more bits you set in R0, the slower it gets, as it requires more of the file to be read. In particular, requesting the ID3 tag information means seeking to the end of the file, which may be very slow on some filing systems (like DATFS).

Therefore, it sometimes makes sense to make 3 calls:

1. With R0=&000, to get the size of the buffers.
2. With R0=&001, to read the quick things and determine whether the file is interesting at all.
3. With R0=&004, to read only the ID3 tag fields.

Remember to read the buffer sizes first. These information blocks will no doubt be extended, and if you assume the old size, your program will stop working when a new AMPlayer module comes out. Just read the size, and your program will continue to work for eternity. You don't need to supply a frame info pointer in R3 unless bit 0 is set.

This SWI is used to start streamed input, ready for playback.

Called by a streaming application to get a Stream Handle. Most streamers will start the stream paused and feed data in until the buffer full flag (see SWI AMPlayer_StreamInfo) is set.

Note: The combination of Queue and Start Paused may not work.

This SWI is used to inform the AMPlayer module that no more data will be supplied to the stream. This does NOT release outstanding buffers that have been passed to AMPlayer. If you need to get these back, call AMPlayer_StreamClose, then SWI AMPlayer_Stop.

Called by a streamer application to pass a block of data to AMPlayer. All but the first word may be considered read-only and must be in interrupt sharable space (i.e. in a dynamic area, module area, sprite pool etc, NOT in the application). By calling this SWI, the application must guarantee that it will keep the buffer around (and unchanged) at least until AMPlayer sets the usage word to zero.

The streamer application should monitor the first word of the buffers it has previously passed in to see when it gets set to 0 to allow reuse. Buffers will be released strictly in the same order they were passed in.

The metadata list blocks must be kept intact for the same length of time as the data blocks, and can be considered 'released' by AMPlayer when their corresponding data blocks are.

Metadata blocks are in the following format:

It is envisaged that there will be a SWI added later to allow metadata to be supplied for non-streaming sources.

This SWI is called by a streaming application to monitor the state of the decoder. Typically a streamer will start a stream up paused and feed it data. The streamer application will then wait until the stream becomes active, and until either the output buffer becomes full, or until it runs out of buffer space itself. Then it can unpause the stream knowing that the maximum amount of buffering is in use.

This SWI is called by streaming applications to discover when meta-data provided by the application has been 'passed' by the decoder and is now active.

This SWI is called by applications to read meta-data passed to the AMPlayer module. Every element of meta-data is tagged with a 'key' which is used to return its value.

This SWI is used to determine what sound systems are available on the current machine, and to select a different sound system. Its most common use is to select the User sound system for streaming output data.

This SWI is used to take data from the 'user' sound system. Initially, users would call with R2 = 0, to determine where to read data from. They then take use from this address up to the limit supplied. Subsequently, the call this SWI again to inform AMPlayer how much data has been read. AMPlayer will only remove data after it has been informed that it has been read.

Decoding will continue in the background. It may be necessary to delay processing if no data is ready. Data can only be generated on callbacks. It may, therefore, be necessary to wait for a moment or so for the decode to function.

VU-bars are inactive when use user sound state is in use.

Callers should note that only complete frames fed in will produce any output - not all the input stream may be used.

This SWI is used control instances of AMPlayer. You should use it in preference to directly creating instances of the AMPlayer module yourself. Consult the reason code descriptions for more details.

This SWI is used return the instance handle of the current instance of AMPlayer. This may be used to discover the handle of the preferred instance such that the preferred instance may be changed to allow fading from one track to another. It is not expected that this call be used often.

This SWI is used create a new instance of the AMPlayer module. This instance may be used in exactly the same manner as any other, if SWIs are directed at it. Set bit 31 of any SWIs flags to direct the call to the instance whose handle is in R8.

This SWI is used destroy an instance of the AMPlayer module. You should destroy instances when you have no further use for them, to free up resources and processing time.

This SWI is used to enumerate the instances currently in use by AMPlayer. A 'visualisation' application might use this call to select what source to provide a representation of.