Copyright (c) 2010-2012 by Axis Communications AB. All rights reserved. PRELIMINARY and CONFIDENTIAL - under NDA (Non-Disclosure Agreement). THIS DOCUMENT IS PROVIDED "AS IS," AND THE CORPORATION AND ITS MEMBERS AND THEIR AFFILIATES, MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THIS DOCUMENT (INCLUDING ANY LAWFUL MODIFICATIONS THEREOF) ARE SUITABLE FOR ANY PURPOSE; OR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT (INCLUDING ANY LAWFUL MODIFICATIONS THEREOF), WHETHER OR NOT (1) THE CORPORATION, MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR (2) SUCH DAMAGES WERE REASONABLY FORESEEABLE, AND ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THIS DOCUMENT. THE FOREGOING DISCLAIMER AND LIMITATION ON LIABILITY DO NOT APPLY TO, INVALIDATE, OR LIMIT REPRESENTATIONS AND WARRANTIES MADE BY THE MEMBERS AND THEIR RESPECTIVE AFFILIATES TO THE CORPORATION AND OTHER MEMBERS IN CERTAIN WRITTEN POLICIES OF THE CORPORATION.
2 Overview
2.1 Examples
2.1.1 Play
3 Detailed Specification
3.1 Common Data Types
3.1.1.1 NewTrack
3.1.1.2 Enumeration: StorageType
3.1.1.3 Storage
3.1.1.4 Track
3.1.1.5 Playlist
3.1.1.6 Enumeration: PlayingMode
3.1.1.7 Enumeration: PlayStatus
3.1.1.8 Enumeration: TrackType
3.1.1.9 Enumeration: TrackCondition
3.1.2 Play command
3.1.3 SetMode command
3.1.4 GetMode command
3.1.5 Stop command
3.1.6 Pause command
3.1.7 PlayNext command
3.1.8 PlayPrevious command
3.1.9 GetPlaylists command
3.1.10 GetTracks command
3.1.11 GetCurrentPlaylist command
3.1.12 GetCurrentTrack command
3.1.13 AddSchedule command
3.1.14 RemoveSchedule command
3.1.15 CreateTrack command
3.1.16 SetTrack command
3.1.17 UploadTrack command
3.1.18 CreatePlaylist command
3.1.19 RemovePlaylist command
3.1.20 RemoveTrack command
3.1.21 SetProxy command
3.1.22 GetProxy command
3.1.23 SetPlaylist command
3.1.24 GetPlayerStatus command
3.1.25 SetPlayerVolume command
3.1.26 GetPlayerVolume command
This is the documentation for the first api draft; designed for the prototype of Axis Audio Player.
This section will show common use cases for this service. The general concepts are discussed and details are handled in the detailed specification. The section
$ curl --anyauth -s "http://root:pass@172.25.9.215/local/player/api" -d'{ "Play": { "PlaylistId": "416c6c55-706c-6f61-6465-6446696c6500", "TrackIndex": 0 } }'$ curl --anyauth -s "http://root:pass@172.25.9.215/local/player/api" -d'{ "Play": {} }'
$ curl --anyauth -s "http://root:pass@172.25.9.215/local/player/api" -d'{ "Play": { "PlaylistId": "416c6c55-706c-6f61-6465-6446696c6500" } }'
Definition of a new track.
Definition: Present, a string which has length > 0. If Username is present, Password must also be present.
If URI starts with http:// and Username and Password are both present, then requested URI when played will be: http://Username:Password@rest_of_uri
Username empty or null means no authentication.
The following fields are available:
Type containing path and storage type.
The following fields are available:
Definitition of a audio track.
The following fields are available:
A playlist contains a list of tracks, and schedules to listen to.
The following fields are available:
How the music is played
The following values are available:Shows which state the player is in.
The following values are available:The track type (ex. http, file)
The following values are available:Current state of a track. TODO: what is error?
The following values are available:Play a playlist.
If no playlist is supplied this will unpause a previously playing track.
If a TrackIndex is supplied, music will start playing from that index.
If a PlaylistId is supplied, but no TrackIndex; the first track in that playlist will start playing.
If no playlist is currently loaded (i.e. GetCurrentPlaylist returns special playlist with id "4e554c4c-2020-2020-2020-202020202000") and no PlaylistId is suplied, this request will fail.
Table 1: Play command
Play | Access Class: ACTUATE | |
Message name | Description | |
PlayRequest | This message contains:
xs:unsignedInt TrackIndex [0][1] | |
PlayResponse | This message contains:
xs:unsignedInt TrackIndex [1][1] (extendable) | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Set playing mode. The change of mode will not take place until the current track is played until end, or the PlayNext request is issued.
Table 2: SetMode command
SetMode | Access Class: WRITE_SYSTEM | |
Message name | Description | |
SetModeRequest | This message contains:
| |
SetModeResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Get playing mode.
Table 3: GetMode command
GetMode | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetModeRequest | This message shall be empty. | |
GetModeResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Stop the music player. A subsequent Play will start the current track from the beginning.
Table 4: Stop command
Stop | Access Class: ACTUATE | |
Message name | Description | |
StopRequest | This message shall be empty. | |
StopResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Pause the music player. A subsequent Play will start the current track from the position it was paused at.
Table 5: Pause command
Pause | Access Class: ACTUATE | |
Message name | Description | |
PauseRequest | This message shall be empty. | |
PauseResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Skip to next track.
See Play about potential failures.
Table 6: PlayNext command
PlayNext | Access Class: ACTUATE | |
Message name | Description | |
PlayNextRequest | This message shall be empty. | |
PlayNextResponse | This message contains:
xs:unsignedInt TrackIndex [1][1] | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Skip to previous track. This is equivalent to PlayNext if PlayingMode is set to Random.
See Play about potential failures.
Table 7: PlayPrevious command
PlayPrevious | Access Class: ACTUATE | |
Message name | Description | |
PlayPreviousRequest | This message shall be empty. | |
PlayPreviousResponse | This message contains:
xs:unsignedInt TrackIndex [1][1] | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Return currently stored playlists. Multiple playlist can be selected by supplying a list of PlaylistIds. If no PlaylistIds are supplied all stored playlists are returned.
Be sure to compare the length of the supplied list of PlaylistIds with the returned list of Playlists. If there are no track with a requested PlaylistId it will be silently ignored. This means the returned list might be shorter than what is requested.
Table 8: GetPlaylists command
GetPlaylists | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetPlaylistsRequest | This message contains:
| |
GetPlaylistsResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Return currently stored tracks. Multiple tracks can be selected by supplying a list of TrackIds. If no TrackIds are supplied all stored tracks are returned.
Be sure to compare the length of the supplied list of TrackIds with the returned list of Tracks. If there are no track with a requested TrackId it will be silently ignored. This means the returned list might be shorter than what is requested.
Table 9: GetTracks command
GetTracks | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetTracksRequest | This message contains:
| |
GetTracksResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Return the currently loaded Playlist.
Whenever no real playlist is loaded a special kind of playlist with id "4e554c4c-2020-2020-2020-202020202000" is returned. This signifies "No playlist loaded" and it is not possible to play this playlist.
Table 10: GetCurrentPlaylist command
GetCurrentPlaylist | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetCurrentPlaylistRequest | This message shall be empty. | |
GetCurrentPlaylistResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Return the currently loaded Track.
Whenever no real track is loaded a special kind of track with id "4e554c4c-2020-2020-2020-202020202000" is returned. This signifies "No track loaded" and it is not possible to play this track.
Table 11: GetCurrentTrack command
GetCurrentTrack | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetCurrentTrackRequest | This message shall be empty. | |
GetCurrentTrackResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Add a schedule to a playlist.
Table 12: AddSchedule command
AddSchedule | Access Class: ACTUATE | |
Message name | Description | |
AddScheduleRequest | This message contains:
axbp:ScheduleId ScheduleId [1][1] | |
AddScheduleResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Remove a schedule from playlist.
Table 13: RemoveSchedule command
RemoveSchedule | Access Class: WRITE_SYSTEM | |
Message name | Description | |
RemoveScheduleRequest | This message contains:
| |
RemoveScheduleResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Creates a new track. See NewTrack documentation.
Table 14: CreateTrack command
CreateTrack | Access Class: ACTUATE | |
Message name | Description | |
CreateTrackRequest | This message contains:
| |
CreateTrackResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Changes information stored in existing track.
All NewTrack fields except URI, Username and Password will be ignored.
To update URI of auth protected track, one must re-send authentication information (security). Otherwise authentication will be disabled.
Modifying the currently playing track will stop playback.
Set track works only for http tracks.
Table 15: SetTrack command
SetTrack | Access Class: WRITE_SYSTEM | |
Message name | Description | |
SetTrackRequest | This message contains:
axbp:NewTrack Track [1][1] | |
SetTrackResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Uploads a new track.
Table 16: UploadTrack command
UploadTrack | Access Class: ACTUATE | |
Message name | Description | |
UploadTrackRequest | This message contains:
xs:string FileName [1][1] | |
UploadTrackResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Create a new Playlist.
Table 17: CreatePlaylist command
CreatePlaylist | Access Class: ACTUATE | |
Message name | Description | |
CreatePlaylistRequest | This message contains:
axbp:TrackId TrackIds [0][unbounded] | |
CreatePlaylistResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Remove specified playlist.
Table 18: RemovePlaylist command
RemovePlaylist | Access Class: WRITE_SYSTEM | |
Message name | Description | |
RemovePlaylistRequest | This message contains:
| |
RemovePlaylistResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Remove specified track.
Table 19: RemoveTrack command
RemoveTrack | Access Class: WRITE_SYSTEM | |
Message name | Description | |
RemoveTrackRequest | This message contains:
| |
RemoveTrackResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Set proxy information for the player.
Table 20: SetProxy command
SetProxy | Access Class: WRITE_SYSTEM | |
Message name | Description | |
SetProxyRequest | This message contains:
| |
SetProxyResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Get the set proxy information.
Table 21: GetProxy command
GetProxy | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetProxyRequest | This message shall be empty. | |
GetProxyResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Set playlist content and information for existing playlist. To create new playlist, see CreatePlaylist.
Table 22: SetPlaylist command
SetPlaylist | Access Class: WRITE_SYSTEM | |
Message name | Description | |
SetPlaylistRequest | This message contains:
axbp:Name Name [1][1] axbp:TrackId TrackIds [0][unbounded] | |
SetPlaylistResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Table 23: GetPlayerStatus command
GetPlayerStatus | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetPlayerStatusRequest | This message shall be empty. | |
GetPlayerStatusResponse | This message contains:
axbp:TrackId TrackId [1][1] xs:unsignedInt TrackIndex [1][1] axbp:PlayingMode Mode [1][1] axbp:PlayStatus status [1][1] axbp:Storage Storage [0][unbounded] axbp:PlaylistId FailedPlaylistId [0][1] axbp:TrackId FailedTrackId [0][1] | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Table 24: SetPlayerVolume command
SetPlayerVolume | Access Class: WRITE_SYSTEM | |
Message name | Description | |
SetPlayerVolumeRequest | This message contains:
| |
SetPlayerVolumeResponse | This message shall be empty. | |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |
Table 25: GetPlayerVolume command
GetPlayerVolume | Access Class: READ_SYSTEM_SENSITIVE | |
Message name | Description | |
GetPlayerVolumeRequest | This message shall be empty. | |
GetPlayerVolumeResponse | This message contains:
| |
Fault codes | Description | |
env:Receiver ter:Action ter:Failure | ... |