How it Works
Qsonix
Loading...
Integration
User Manual
32 pgs363.96 Kb0

Qsonix Integration User Manual

Qsonix Integration Guide
Updated 5/13/2009
Table of Contents
Play [Zone] ............................................................................................................................................. 7
PlaySeq [Zone] [SequenceNumber] ............................................................................................................. 7
Stop [Zone] ............................................................................................................................................ 7
PauseSet [Zone #] [Setting] ........................................................................................................................ 7
PauseToggle [Zone #] ............................................................................................................................. 7
Next [Zone #] {TrackCount} ........................................................................................................................ 7
Previous [Zone #] {TrackCount} .................................................................................................................. 8
Cue [Zone #] [CueLocation] ......................................................................................................................... 8
Volume [Zone #] [VolumePercentage] ............................................................................................................ 8
VolumeUp [Zone #] [Amount] .................................................................................................................... 8
VolumeDown [Zone #] [Amount] ................................................................................................................ 9
MuteToggle [Zone #] .............................................................................................................................. 9
MuteSet [Zone #] [MuteValue] ..................................................................................................................... 9
RepeatToggle [Zone #] ........................................................................................................................... 9
RepeatSet [Zone #] [RepeatValue] .............................................................................................................. 10
Shuffle [Zone #] ................................................................................................................................... 10
NowPlaying [Zone #] [Action] .................................................................................................................. 10
Preview [Zone #] [TrackID] ....................................................................................................................... 10
QueueItem [Zone #] [Location] [ObjectType] [ObjectID] .................................................................................... 10
QueueItemPlaylist [PlaylistID] [Location] [ObjectType] [ObjectID] ..................................................................... 11
MoveItemPlaylist [PlaylistID] [FromSequenceNumber] [ToSequenceNumber] ....................................................... 11
RemoveItemPlaylist [PlaylistID] [SequenceNumber] ...................................................................................... 12
Shutdown........................................................................................................................................... 12
Restart ............................................................................................................................................... 12
Get Zonename [Zone] {UserData} ......................................................................................................... 15
Get SystemStatus {UserData} ................................................................................................................ 15
Get ZoneVisibility ............................................................................................................................... 16
Qsonix Integration Guide
Page | 2
Get_Albums [PageNumber] [PageSize] {UserData} ......................................................................................... 16
Get_Artists [PageNumber] [PageSize] {UserData} ........................................................................................... 16
Get_Genres [PageNumber] [PageSize] {UserData} ......................................................................................... 17
Get_Periods [PageNumber] [PageSize] {UserData} ......................................................................................... 17
Get_Playlists [PageNumber] [PageSize] {UserData} ........................................................................................ 18
GetFor_NowPlaying [Zone] [TrackCount] {UserData} .................................................................................... 18
GetFor_Search [SearchTerm] [PageNumber] [PageSize] {UserData} .................................................................... 19
GetFor_StylesForGenre [GenreID] [PageNumber] [PageSize] {UserData} ........................................................... 20
GetFor_AlbumsForArtist [ArtistID] [PageNumber] [PageSize] {UserData} ............................................................. 21
GetFor_AlbumsForGenre [GenreID] [PageNumber] [PageSize] {UserData} ........................................................ 21
GetFor_AlbumsForStyle [GenreID] [PageNumber] [PageSize] {UserData} ........................................................... 22
GetFor_AlbumsForPeriod [PeriodID] [PageNumber] [PageSize] {UserData} ......................................................... 22
GetFor_TracksForAlbum [AlbumID] [PageNumber] [PageSize] {UserData} .......................................................... 23
GetFor_TracksForPlaylist [PlaylistID] [PageNumber] [PageSize] {UserData} ............................................................... 24
GetDetails_Album [AlbumID] {UserData} .................................................................................................. 25
GetDetails_Artist [ArtistID] {UserData} ....................................................................................................... 25
Feedback TrackChange [On/Off] .......................................................................................................... 26
Feedback TrackPosition [On/Off] .......................................................................................................... 27
Feedback RepeatChange [On/Off] ........................................................................................................ 27
Feedback PlaylistChange [On/Off] ........................................................................................................ 28
Feedback PlaystateChange [On/Off] ..................................................................................................... 28
Feedback Volume [On/Off] ................................................................................................................... 28
Feedback All [On/Off] .......................................................................................................................... 28
Feedback GetValue ............................................................................................................................ 29
Queue [Zone #] [Location] ....................................................................................................................... 31
Qsonix Integration Guide
Page | 3
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.
10/19/2005
Added QUEUEITEM command to support directly queuing objects by ID number.
06/1/2007
Added QUEUEITEMPLAYLIST command to support directly queuing objects by ID number to. Added another Feedback parameter (volume).
10/1/2007
Removed old protocol no longer support in current firmware Support for Q110 (4-Zone) unit added
5/15/2008
Added documentation for SetFeedback command. Removed SELECTPLAYLIST command – no longer implemented Removed SORTRESULTS command – no longer implemented Added full library browsing functions including “GET_xxx”, “GETFOR_xxx”, “GETDETAILS_xxx”
commands.
8/18/2008
Updated document format Added instructions for TCP/IP support Added Cover Art Documentation
11/9/2008
Added return fields to GET_PERIODS: TotalTracks, TotalDuration, TotalDurationAsString Added new command: GETFILTERED_ALBUMS Added AvailableAlpha to the response for GET_ARTISTS and GETFILTERED_ALBUMS
12/2/2008
Added the REMOVEITEMPLAYLIST command.
Qsonix Integration Guide
Page | 4
5/13/2009
Added the MOVEITEMPLAYLIST command. Added the PREVIEW command. Added the CUE command.
Qsonix Integration Guide
Page | 5
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. Serial configuration can be set by accessing the Integration tab under System Settings in the Qsonix software.
Ethernet Communications
The Qsonix system also supports access via a TCP connection using the same communication protocol found in this document. The default port number for TCP communications is 5031. This port number can be configured by accessing the Integration tab under the System Settings in the Qsonix software.
Command Structure
Commands sent to Qsonix systems will always end in a carriage return (ASCII 13). If a sequence of characters is sent to the unit without ending in a carriage return (an incomplete command), it will be ignored. The unit will wait up to 5 seconds for the command to be completed (by sending additional characters including a carriage return) before clearing the input buffer and ignoring the incomplete command.
A typical command will include a verb and one or more parameters. Parameters are always separated from each other and from the verb by a space (ASCII 32). For example, the command to begin playback for Zone 1 is “Play 1” and the command to set the volume for Zone 2 to 50% is “Volume 2 50”. Command verbs are not case sensitive but are typically specified in proper case for ease of readability. Some commands support optional parameters. Optional parameters are always last in the list of parameters and they can be provided to give a more specific command. For example, the Next command will cause the playback to skip to the next track in the now playing list for the specified zone. The Next command can also skip forward by more than one track with a single command (example: “Next 2 5” will skip playback of Zone 2 forward by 5 tracks). When optional parameters are omitted, a default value that is specified in the command description will be used.
Some parameters will be full strings (such as a track title) that may include spaces within the parameter. These parameters will be enclosed in double-quotes. For example, the return status message indicating the currently playing track will return the track title currently playing: Feedback CurrentTrack 1 “Here Comes the Sun” indicates that Zone 1 is currently playing the track Here Comes the Sun.
Most commands include a parameter that specifies on which zone the command should operate. The Zone parameter must be a numeric value equal corresponding to the zone the command should operate on. This must be less than the number of zones supported by the system (typically 1 to 4). A value of 0 can be used to indicate that the command should operate on the “current zone”. The current zone is the
one that is current displayed in the lower right corner of the screen in the “Now Playing” area. The current
zone in this area is also indicated by the color coding in the user interface.
The command reference below will show verbs in boldface and parameters will be shown by name in italics surrounded by square brackets (ex: [Zone #] or [Volume Percentage]). Optional parameters are shown in italics and surrounded by braces (ex: {# of tracks}).
Qsonix Integration Guide
Page | 6
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
SequenceNumber
Playback will jump to this sequence number in the playback queue for the zone specified. Tracks in the playback queue are numbered sequentially starting at 0 (the first track is sequence number 0).
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Setting
Must be ON or OFF to indicate the new state of pause
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Playback Control Commands
Play [Zone]
DE SC R I P T I O N
Plays the currently selected track for the specified [Zone}.
PARAMETE R S
PlaySeq [Zone] [SequenceNumber]
DE SC R I P T I O N
Skips playback to the specified sequence number in the play queue.
PARAMETE R S
Stop [Zone]
DE SC R I P T I O N
Stops playback for the specified [Zone}.
PARAMETE R S
PauseSet [Zone #] [Setting]
DE SC R I P T I O N
Sets the pause state of playback for the specified Zone.
PARAMETE R S
PauseToggle [Zone #]
DE SC R I P T I O N
Toggles between paused and un-paused state for playback for the specified [Zone}.
PARAMETE R S
Next [Zone #] {TrackCount}
DE SC R I P T I O N
Skips playback forward by {TrackCount} tracks for the specified [Zone}.
Qsonix Integration Guide
Page | 7
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.
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.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
CueLocation
Specifies where the current cue point of the current track should be set. This should be an integer value specifying the number of seconds from the start of the track.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
VolumePercentage
Specifies the new volume setting desired in terms of a percent of full volume. The value must be an integer value between 0 and 100.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
PARAMETE R S
Previous [Zone #] {TrackCount}
DE SC R I P T I O N
Skips playback backward by {TrackCount} tracks for the specified [Zone].
PARAMETE R S
Cue [Zone #] [CueLocation]
DE SC R I P T I O N
Cues into the current track to the number of seconds specified by [CueLocation].
PARAMETE R S
Volume [Zone #] [VolumePercentage]
DE SC R I P T I O N
Sets the volume for the specified [Zone] to the [VolumePercentage] specified. To turn the volume up or down (not set a discreet value, see the VolumeUp or VolumeDown command instead).
PARAMETE R S
VolumeUp [Zone #] [Amount]
DE SC R I P T I O N
Increases the volume for the specified [Zone] by the [Amount] specified.
The VolumeUp 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. Note that if the value specified would cause the volume setting to be greater than 100, the volume will be set to 100 instead. For instance, if the volume is currently set to 50% and the VolumeUp command is issued with an Amount parameter of 70, the volume will be set to 100% (instead of 120%).
PARAMETE R S
Qsonix Integration Guide
Page | 8
Amount
Specifies the amount of volume change desired. The playback volume change amount is specified in terms of percent (0 to 100%).
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Amount
Specifies the amount of volume change desired. The playback volume change amount is specified in terms of percent (0 to 100%).
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
MuteValue
Specifies the desired new state of mute. The value must be either On or Off.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
VolumeDown [Zone #] [Amount]
DE SC R I P T I O N
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. Note that if the value specified would cause the volume setting to be greater than 100, the volume will be set to 100 instead. For instance, if the volume is currently set to 50% and the VolumeDown command is issued with an Amount parameter of 70, the volume will be set to 100% (instead of 120%).
PARAMETE R S
MuteToggle [Zone #]
DE SC R I P T I O N
Toggles the mute setting for the specified [Zone]. For a discreet version of this command, see MuteSet.
PARAMETE R S
MuteSet [Zone #] [MuteValue]
DE SC R I P T I O N
Sets the mute setting for the specified [Zone] to a discreet value specified by the [MuteValue] parameter.
PARAMETE R S
RepeatToggle [Zone #]
DE SC R I P T I O N
Toggles the repeat setting for the specified [Zone]. For a discreet version of this command, see RepeatSet.
PARAMETE R S
Qsonix Integration Guide
Page | 9
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.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
Action
Specifies what action should be taken on the specified zone‟s now playing playlist. Action must be one of the following values:
ClearAll – Clears all tracks from the playlist ClearPlayed – Clears all tracks that have completed playing from the playlist
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
TrackID
Specifies the track that should be previewed.
Zone #
Specifies which zone should be acted upon. Must be 0 or a valid zone number.
RepeatSet [Zone #] [RepeatValue]
DE SC R I P T I O N
Sets the repeat setting for the specified [Zone] to a discreet value specified by the [RepeatValue] parameter.
PARAMETE R S
Shuffle [Zone #]
DE SC R I P T I O N
Shuffles the now playing list of tracks for the specified [Zone]. The shuffle operation will randomly resort all tracks in the now playing list. If the zone is currently playing a track, that track will be moved to the top of the list and will continue playing while all other tracks below it will be shuffled randomly.
PARAMETE R S
NowPlaying [Zone #] [Action]
DE SC R I P T I O N
The NowPlaying command is used for actions that affect the Now Playing playlist for the specified [Zone].
PARAMETE R S
Preview [Zone #] [TrackID]
DE SC R I P T I O N
Play a short preview of the track specified by [TrackID] in the zone specified by [Zone]. When the preview is completed, playback will return to its previous state.
PARAMETE R S
QueueItem [Zone #] [Location] [ObjectType] [ObjectID]
DE SC R I P T I O N
Allows adding of items 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.
PARAMETE R S
Qsonix Integration Guide
Page | 10
Loading...
+ 22 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use