Qsonix Integration Guide Updated 5/13/2009
Table of Contents Table of Contents ........................................................................................................................ 2 Revision History ........................................................................................................................... 4 Introduction................................................................................................................................. 6 Serial Communications ............................................
Get_Albums [PageNumber] [PageSize] {UserData}......................................................................................... 16 Get_Artists [PageNumber] [PageSize] {UserData} ........................................................................................... 16 Get_Genres [PageNumber] [PageSize] {UserData}......................................................................................... 17 Get_Periods [PageNumber] [PageSize] {UserData}................................................
Revision History 10/5/2005 Response to GET NOWPLAYING command results changed. Added Sequence as a new returned field to the NOWPLAYING response. Also, IsCurrent field now returns either a 1 or 0 value instead of only returning if the value is 1. FEEDBACK CURRENTTRACK and FEEDBACK NEXTTRACK responses now include the Sequence field. Added new command “GET SYSTEMSTATUS” that can be used to check the availability of the system as well as retrieve the current system software version.
/13/2009 Added the MOVEITEMPLAYLIST command. Added the PREVIEW command. Added the CUE command.
Introduction This document describes how to communicate with Qsonix Digital Media Management Systems using either RS-232 Serial or TCP/IP communications. Serial Communications The rear panel of the Qsonix systems unit has a standard DB-9 serial port labeled “Serial”. Typical connection to this port requires use of a standard RS-232 null modem cable. Qsonix systems support communications between 9600 to 38400 baud, 8 data bits, 1 stop bit, no parity, no flow control.
Playback Control Commands Play [Zone] DESCRIPTION Plays the currently selected track for the specified [Zone}. PARAMETERS Zone # Specifies which zone should be acted upon. Must be 0 or a valid zone number. PlaySeq [Zone] [SequenceNumber] DESCRIPTION Skips playback to the specified sequence number in the play queue. PARAMETERS Zone # Specifies which zone should be acted upon. Must be 0 or a valid zone number.
PARAMETERS Zone # Specifies which zone should be acted upon. Must be 0 or a valid zone number. TrackCount Specifies the number of tracks to skip forward. This parameter is optional and the default value is 1. Previous [Zone #] {TrackCount} DESCRIPTION Skips playback backward by {TrackCount} tracks for the specified [Zone]. PARAMETERS Zone # Specifies which zone should be acted upon. Must be 0 or a valid zone number. TrackCount Specifies the number of tracks to skip forward.
Amount Specifies the amount of volume change desired. The playback volume change amount is specified in terms of percent (0 to 100%). VolumeDown [Zone #] [Amount] DESCRIPTION Decreases the volume for the specified [Zone] by the [Amount] specified. The VolumeDown command is used to set the volume to a value relative to the current setting, so the Amount value must be between 1 and 100.
RepeatSet [Zone #] [RepeatValue] DESCRIPTION Sets the repeat setting for the specified [Zone] to a discreet value specified by the [RepeatValue] parameter. PARAMETERS Zone # Specifies which zone should be acted upon. Must be 0 or a valid zone number. RepeatValue Specifies the desired new state of repeat. The value must be either On or Off. Shuffle [Zone #] DESCRIPTION Shuffles the now playing list of tracks for the specified [Zone].
Location Specifies where the item specified should be added to the now playing queue. Location must be one of the following values: End – Add selected item to the end of the playlist Next – Add selected item to the playlist immediately after the current track Now – Add selected item to the playlist immediately after the current track and then immediately call track next so that the queued track will start playing immediately. Clear – Clear the playlist and then add the selected item.
FromSequenceNumber The sequence number of the item to be moved within the playlist. ToSequenceNumber The sequence number within the playlist where the item should be moved to. RemoveItemPlaylist [PlaylistID] [SequenceNumber] DESCRIPTION Removes the track with the specified [SequenceNumber] from the playlist specified by [PlaylistID]. PARAMETERS PlaylistID Specifies which playlist should have the items added.
Two-way Commands Various commands are provided for the purposes of retrieving data from the server or to receive feedback of current server status. All commands that are requests of the server to return data will conform to a standard response format. The response will always include a header that can be used to identify what type of data is being returned to the client. Data returned will use standard delimiters to aide in parsing the resulting information.
Int16 – a 16-bit integer value (maximum value of 32,767) uInt8 – an unsigned 8-bit integer value (maximum value of 256) User Data Each of the commands in this section support an optional UserData parameter. This is always the last parameter in the command and must be a string. The UserData parameter cannot contain spaces. The data supplied in the UserData parameter will be returned in the response header as the last field in the header.
Get Zonename [Zone] {UserData} DESCRIPTION Used to retrieve the user-specified name assigned to each of the zones in the system. PARAMETERS Zone Specifies the zone to retrieve the name for. Must be a valid zone number. uInt8 RESPONSE DEFINITION ZONENAME[UserData][ZoneNumber][ZoneName] ZoneNumber The number of the zone. Int16 ZoneName The user-specified name of the zone. String(50) Get SystemStatus {UserData} DESCRIPTION Used to check the availability of the server.
StylesCount Total number of styles currently stored on the system. Int32 PlaylistCount Total number of playlists currently stored on the system. Int32 FriendlyName The friendly name of the machine set by the user in the configuration area. String(50) Get ZoneVisibility DESCRIPTION Used to check the availability of a zone of the server. PARAMETERS Zone Specifies the zone to retrieve the name for. Must be a valid zone number.
PARAMETERS PageNumber Specifies the page number to be retrieved. Int32 PageSize Specifies the number of rows in each page. Int32 RESPONSE DEFINITION GET_ARTISTS[PageNumber][TotalPages][TotalArtists][UserData][ArtistID][ArtistName] [AlbumCount] PageNumber The page number being returned. Int32 TotalPages Indicates how many pages are available at the page size specified. Int32 TotalArtists Count of the number of artists in the library.
[AlbumCount][TrackCount][Duration][DurationAsString] PageNumber The page number being returned. Int32 TotalPages Indicates how many pages are available at the page size specified. Int32 TotalPeriods Count of the number of periods in the library. Int32 PeriodID Unique period identifier for the period being returned. Distinct years have a period ID that is simply the year. Decades have a period ID that prepends a 1 to the decade (for example, 1980s has a period ID of 11980).
will be returned to indicate tracks that are queued up to play in the future. If there are no future tracks or less than TrackCount number of future tracks, then less rows may be returned. PARAMETERS Zone Now Playing tracks will be returned for this zone. uInt8 TrackCount Specifies the number of rows to return. This is how many tracks in the future will be returned (includes the current track).
][ObjectID][MatchString] SearchTerm The search term that was searched for. String(255) PageNumber The page number being returned. Int32 TotalPages Indicates how many pages are available at the page size specified. Int32 TotalResults Count of the number of matches available. Int32 ObjectType The type of object that this search result pertains to. Valid values are: TRACK, ALBUM, ARTIST, GENRE String(20) ObjectID The unique identifier of the object matched.
GenreName The name of the style. String(100) AlbumCount The number of albums that are associated with the style. Int32 GetFor_AlbumsForArtist [ArtistID] [PageNumber] [PageSize] {UserData} DESCRIPTION Retrieves a list of albums for the specified artist. PARAMETERS ArtistID The unique artist ID to retrieve a list of albums for. Int32 PageNumber Specifies the page number to be retrieved. Int32 PageSize Specifies the number of rows in each page.
TotalPages Indicates how many pages are available at the page size specified. Int32 TotalAlbums Count of the number of albums returned. Int32 AlbumID The unique album ID for the album being returned. Int32 AlbumTitle The album title. String(100) AlbumArtistID Unique artist identifier for the artist that is the primary artist on the album. Int32 AlbumArtistName Name of the primary artist for the album. String(255) Year The release year of the album.
leading 1 to the id, ex: 11980 will return results from 1980 through 1989 inclusive). Int16 PageNumber Specifies the page number to be retrieved. Int32 PageSize Specifies the number of rows in each page. Int32 RESPONSE DEFINITION GETFOR_ALBUMSFORPERIOD[PeriodID][PageNumber][TotalPages][TotalAlbums][UserData][A lbumID][AlbumTitle][AlbumArtistID][AlbumArtistName][Year][TrackCount] PeriodID The period ID of the albums being returned. Int16 PageNumber The page number being returned.
DurationAsString Duration of the track. This is returned as a formatted string value (ex: 1:23:45). String(10) OutputIsPlayingT hisTrack This field can be used to determine if the returned track is currently playing in any of the playback zones. Note that this is a multi-valued field and will contain a delimited list of all zone numbers that are currently playing this track.
GetDetails_Album [AlbumID] {UserData} DESCRIPTION Retrieves details for the specified album. PARAMETERS AlbumID The unique album ID to retrieve detailed information for. Int32 RESPONSE DEFINITION GETDETAILS_ALBUM[RequestedAlbumID][UserData][AlbumID][AlbumTitle][AlbumArtistID] [AlbumArtistName][ReleasedYear][Genre][Styles][Flags] RequestedAlbumID The album ID of the details being returned. Int32 AlbumID The album ID for the track being returned. Int32 AlbumTitle The album title.
Genre The genre associated with this album. String(100) Styles This is a multi-valued field that returns a delimited list of all styles associated with this album. String(512) Flags This is a multi-valued field that returns a delimited list of all album flags associated with this album. Examples of album flags include: LIVE, INSTRUMENTAL, EXPLICIT LYRICS String(512) System Feedback Qsonix systems are capable of sending a variety of feedback data including playback status, currently playing track, etc.
SequenceNumber This number is unique within a playlist and indicates this tracks order within the playlist. Since a playlist can contain a track more than once, this provides an alternative to track ID to uniquely identify a particular instance of a track within a playlist. Int32 Feedback TrackPosition [On/Off] DESCRIPTION Enabling this type of feedback will cause a feedback message to be sent any time the track position changes. During playback, this will result in one message being sent every second.
Feedback PlaylistChange [On/Off] DESCRIPTION Enabling this type of feedback will cause a feedback message to be sent any time the Now Playing queue changes for a particular playback zone. PARAMETERS On/Off Specifies whether to turn the specified type of feedback on or off. Valid values include: ON, OFF. String(3) RESPONSE DEFINITIONS FEEDBACKNOWPLAYINGCHANGED[ZoneNumber] ZoneNumber The number of the zone that this feedback applies to.
PARAMETERS On/Off Specifies whether to turn the specified type of feedback on or off. Valid values include: ON, OFF. String(3) Feedback GetValue DESCRIPTION Returns a message that contains the current feedback settings.
Cover Art Image Support Access to album cover art images is provided via HTTP using the built-in web server on the system. By using the available query string parameters to build a full cover art image URL, a jpeg bitmap can be retrieved from the server for any album in the system. URL http:///WebServices/CoverArtImage.aspx QUERYSTRING PARAMETERS AlbumID If specified, the cover art returned will correspond to the Album with the ID specified.
Deprecated commands Queue [Zone #] [Location] This command has been replaced by the QueueItem command starting in version 2.4.8. DESCRIPTION Adds the currently selected item to the Now Playing playlist for the specified [Zone]. The location in the current playlist that the item will be inserted is determined by the value of the Location parameter. The Location parameter is optional and if not specified, the default is End. Valid values for Location are listed below.
[ZoneNumber] GET NOWPLAYING [ZoneNumber] GET NOWPLAYING [ZoneNumber] GET NOWPLAYING [ZoneNumber] GET NOWPLAYING [ZoneNumber] GET NOWPLAYING [PageSize] NEXT PREVIOUS LAST CURRENT PAGESIZE commands. As with PLAYLISTS, the basic command “GET NOWPLAYING” will return the first page of tracks from the now playing list. The PAGESIZE command can be used to set the number of playlists returned per page (specified by the PageSize parameter).
