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.

BasicPlayer Service

axbp = http://www.axis.com/vapix/ws/BasicPlayer

Table of contents

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

Overview

This is the documentation for the first api draft; designed for the prototype of Axis Audio Player.

Examples

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

Play

cURL JSON Request
$ 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" } }'

Detailed Specification

Common Data Types

NewTrack

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:

To provide more information, the device may include the following optional fields:

Enumeration: StorageType

The following values are available:

Storage

Type containing path and storage type.

The following fields are available:

To provide more information, the device may include the following optional field:

Track

Definitition of a audio track.

The following fields are available:

To provide more information, the device may include the following optional fields:

Playlist

A playlist contains a list of tracks, and schedules to listen to.

The following fields are available:

Enumeration: PlayingMode

How the music is played

The following values are available:

Enumeration: PlayStatus

Shows which state the player is in.

The following values are available:

Enumeration: TrackType

The track type (ex. http, file)

The following values are available:

Enumeration: TrackCondition

Current state of a track. TODO: what is error?

The following values are available:

Play command

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 nameDescription
PlayRequestThis message contains:

  • "PlaylistId": Which playlist to play.
  • "TrackIndex": Which index to start at.

axbp:PlaylistId PlaylistId [0][1]
xs:unsignedInt TrackIndex [0][1]
PlayResponseThis message contains:

  • "NowPlaying": The item currently being played
  • "TrackIndex": Index of current track in current playlist.

axbp:Track NowPlaying [1][1]
xs:unsignedInt TrackIndex [1][1]
(extendable)
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

SetMode command

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 nameDescription
SetModeRequestThis message contains:

  • "Mode":

axbp:PlayingMode Mode [1][1]
SetModeResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetMode command

Get playing mode.

Table 3: GetMode command

GetMode
Access Class: READ_SYSTEM_SENSITIVE
Message nameDescription
GetModeRequestThis message shall be empty.
GetModeResponseThis message contains:

  • "Mode":

axbp:PlayingMode Mode [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

Stop command

Stop the music player. A subsequent Play will start the current track from the beginning.

Table 4: Stop command

Stop
Access Class: ACTUATE
Message nameDescription
StopRequestThis message shall be empty.
StopResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

Pause command

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 nameDescription
PauseRequestThis message shall be empty.
PauseResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

PlayNext command

Skip to next track.

See Play about potential failures.

Table 6: PlayNext command

PlayNext
Access Class: ACTUATE
Message nameDescription
PlayNextRequestThis message shall be empty.
PlayNextResponseThis message contains:

  • "NowPlaying": The new track to play
  • "TrackIndex": Index of current track in current playlist.

axbp:Track NowPlaying [1][1]
xs:unsignedInt TrackIndex [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

PlayPrevious command

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 nameDescription
PlayPreviousRequestThis message shall be empty.
PlayPreviousResponseThis message contains:

  • "NowPlaying": The new track to play
  • "TrackIndex": Index of current track in current playlist.

axbp:Track NowPlaying [1][1]
xs:unsignedInt TrackIndex [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetPlaylists command

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 nameDescription
GetPlaylistsRequestThis message contains:

  • "Ids": List of playlist ids or empty for all

axbp:PlaylistId Ids [0][unbounded]
GetPlaylistsResponseThis message contains:

  • "Playlists": List of playlists

axbp:Playlist Playlists [0][unbounded]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetTracks command

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 nameDescription
GetTracksRequestThis message contains:

  • "Ids": List of track ids or empty for all

axbp:TrackId Ids [0][unbounded]
GetTracksResponseThis message contains:

  • "Tracks": List of tracks

axbp:Track Tracks [0][unbounded]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetCurrentPlaylist command

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 nameDescription
GetCurrentPlaylistRequestThis message shall be empty.
GetCurrentPlaylistResponseThis message contains:

  • "Playlist": Current playlist

axbp:Playlist Playlist [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetCurrentTrack command

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 nameDescription
GetCurrentTrackRequestThis message shall be empty.
GetCurrentTrackResponseThis message contains:

  • "Track": Current track

axbp:Track Track [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

AddSchedule command

Add a schedule to a playlist.

Table 12: AddSchedule command

AddSchedule
Access Class: ACTUATE
Message nameDescription
AddScheduleRequestThis message contains:

  • "PlaylistId": Playlist to assign schedule.
  • "ScheduleId": Schedule Identifier

axbp:PlaylistId PlaylistId [1][1]
axbp:ScheduleId ScheduleId [1][1]
AddScheduleResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

RemoveSchedule command

Remove a schedule from playlist.

Table 13: RemoveSchedule command

RemoveSchedule
Access Class: WRITE_SYSTEM
Message nameDescription
RemoveScheduleRequestThis message contains:

  • "ScheduleId": Schedule Identifier

axbp:ScheduleId ScheduleId [1][1]
RemoveScheduleResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

CreateTrack command

Creates a new track. See NewTrack documentation.

Table 14: CreateTrack command

CreateTrack
Access Class: ACTUATE
Message nameDescription
CreateTrackRequestThis message contains:

  • "Track": The track to create

axbp:NewTrack Track [1][1]
CreateTrackResponseThis message contains:

  • "Track": The track created

axbp:Track Track [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

SetTrack command

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 nameDescription
SetTrackRequestThis message contains:

  • "Id": The track to modify
  • "Track": The information to set.

axbp:TrackId Id [1][1]
axbp:NewTrack Track [1][1]
SetTrackResponseThis message contains:

  • "Track": The updated track

axbp:Track Track [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

UploadTrack command

Uploads a new track.

Table 16: UploadTrack command

UploadTrack
Access Class: ACTUATE
Message nameDescription
UploadTrackRequestThis message contains:

  • "File": The file to turn into a track
  • "FileName": The file name

xs:hexBinary File [1][1]
xs:string FileName [1][1]
UploadTrackResponseThis message contains:

  • "Track": The track created

axbp:Track Track [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

CreatePlaylist command

Create a new Playlist.

Table 17: CreatePlaylist command

CreatePlaylist
Access Class: ACTUATE
Message nameDescription
CreatePlaylistRequestThis message contains:

  • "Name": Nice Name for the playlist
  • "TrackIds": List of trackIDs initially contained in Playlist

axbp:Name Name [1][1]
axbp:TrackId TrackIds [0][unbounded]
CreatePlaylistResponseThis message contains:

  • "Playlist": The playlist created

axbp:Playlist Playlist [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

RemovePlaylist command

Remove specified playlist.

Table 18: RemovePlaylist command

RemovePlaylist
Access Class: WRITE_SYSTEM
Message nameDescription
RemovePlaylistRequestThis message contains:

  • "Id": Playlist to remove

axbp:PlaylistId Id [1][1]
RemovePlaylistResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

RemoveTrack command

Remove specified track.

Table 19: RemoveTrack command

RemoveTrack
Access Class: WRITE_SYSTEM
Message nameDescription
RemoveTrackRequestThis message contains:

  • "Id": Track to remove

axbp:TrackId Id [1][1]
RemoveTrackResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

SetProxy command

Set proxy information for the player.

Table 20: SetProxy command

SetProxy
Access Class: WRITE_SYSTEM
Message nameDescription
SetProxyRequestThis message contains:

  • "ProxyServer": Server address

axbp:ProxyServer ProxyServer [1][1]
SetProxyResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetProxy command

Get the set proxy information.

Table 21: GetProxy command

GetProxy
Access Class: READ_SYSTEM_SENSITIVE
Message nameDescription
GetProxyRequestThis message shall be empty.
GetProxyResponseThis message contains:

  • "ProxyServer": Server address

axbp:ProxyServer ProxyServer [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

SetPlaylist command

Set playlist content and information for existing playlist. To create new playlist, see CreatePlaylist.

Table 22: SetPlaylist command

SetPlaylist
Access Class: WRITE_SYSTEM
Message nameDescription
SetPlaylistRequestThis message contains:

  • "Id": Playlist to modify
  • "Name": Nicename of playlist
  • "TrackIds": List of trackIDs contained in Playlist

axbp:PlaylistId Id [1][1]
axbp:Name Name [1][1]
axbp:TrackId TrackIds [0][unbounded]
SetPlaylistResponseThis message contains:

  • "Playlist": The resulting playlist

axbp:Playlist Playlist [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetPlayerStatus command

Table 23: GetPlayerStatus command

GetPlayerStatus
Access Class: READ_SYSTEM_SENSITIVE
Message nameDescription
GetPlayerStatusRequestThis message shall be empty.
GetPlayerStatusResponseThis message contains:

  • "PlaylistId": Id of current playlist
  • "TrackId": Id of current track
  • "TrackIndex": Index of current track in current playlist.
  • "Mode": Current playing mode.
  • "status": Are we playing/paused/stopped ?
  • "Storage": Pathways to storages
  • "FailedPlaylistId": Id of failed track or not.
  • "FailedTrackId": Id of failed track or not.

axbp:PlaylistId PlaylistId [1][1]
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 codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

SetPlayerVolume command

Table 24: SetPlayerVolume command

SetPlayerVolume
Access Class: WRITE_SYSTEM
Message nameDescription
SetPlayerVolumeRequestThis message contains:

  • "Volume": Volume for the player.

xs:unsignedInt Volume [1][1]
SetPlayerVolumeResponseThis message shall be empty.
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...

GetPlayerVolume command

Table 25: GetPlayerVolume command

GetPlayerVolume
Access Class: READ_SYSTEM_SENSITIVE
Message nameDescription
GetPlayerVolumeRequestThis message shall be empty.
GetPlayerVolumeResponseThis message contains:

  • "Volume": Current Volume of the player.

xs:unsignedInt Volume [1][1]
Fault codesDescription
env:Receiver
 ter:Action
  ter:Failure
...