CQSL Integrated Audio Player

Make/Model	Device Version	Connection Type
CQSL/AudioPlayer	DirectShow 9/Quick Time7	N/A

Description:

This driver controls the Charmed Quark integrated audio player, which is a headless player designed to support single or multi-zone audio playback. This player operates completely in the background, so there is no interface and you do not have to be logged into the machine for it to operate. It is designed specifically for CQC's needs, to play back audio from the driver itself, and to support multi-zone audio playback from any CQC supported media repository by loading multiple instances of the driver.
This driver can use either a DirectShow based audio engine, or a QuickTime based engine. The primary reason you would want to use the QuickTime engine is if you use the iTunes repository driver and have copy protected audio that you have downloaded from the iTunes online store. Only the QuickTime engine can play those files. Note that even if you rip CDs via iTunes, those files will generally be in the form of MPEG4 files, which the DirectShow engine cannot play unless you install an MPEG4 DirectShow codec that allows this. This is generally worth doing, since you want to use the DirectShow engine where possible, due to the lower overhead, quicker response, and less third party software required.
NOTE: You must have at least DirectX 9 or QuickTime 7 or higher installed on the machine where the actual driver will be running, i.e. where the CQCServer that it is loaded into will be running, because that's where the actual playback occurs from and this player uses the media features of the DirectShow or QuickTime. If you have WMP10 or WMP11 installed then the required DirectShow components are already installed as part of that product. Otherwise, if you want to avoid the requirement for WMP 10/11 (for instance you are on Windows 2000), you can just install the DirectX 9 SDK.
NOTE: If you are going to be playing protected iTunes files, you must have iTunes installed and authorized on the machine(s) where the audio player driver is installed.
Installation:
When you load the driver you will be presented with a number of prompts that allow you to adjust the configuration or defaults of the driver. These are discussed in the tablet below.
Prompt Description
Default Repository As with all standard CQC media renderer drivers, you will indicate the default media repository that the driver instance should be associated with (i.e. the one to which it will go to look up the media information on any media cookies you send to it.)
Audio Device Select the audio device you want this driver instance to use. If you install multiple driver instances, each should have its own audio device. Don't select default devices.
Zone Number For your own use in automation logic, you can embed a zone number in the driver that you can later use in your actions to automatically figure out which zone number you are dealing with.
Initial Volume The initial volume (0 to 100%) that the driver should set when it first loads up.
Audio Engine As discussed above, you must select the Quick Time or DirectShow engine to use for playback.
Quick Time Port If you select QuickTime, you provide an IP port number that that instance will use to talk to the Quick Time audio server. Select a unique port for each driver instance you load on a given host.
Cookies and Playback:
There are three types of media related cookies, title set, collection, and item, and two fields that you can write them to in order to play their associated media data. The following table indicates what happens in each case.
Field Title Cookie Collection Cookie Item Cookie
EnqueueMedia Adds the items of the first collection of the title set to the end of the playlist Adds the items of this collection to the end of the playlist Add this one item to the end of the playlist.
PlayMedia Clears the current list, then sets the list to the items of the first collection of this title set. Clears the current list, then sets the list to the items of this collection. Looks for this item in the current list. If found, makes it the active item. Else ignores it.
This driver supports three different play-ist modes, set via the PlaylistMode field. They are:
Normal. The player moves to the next item in the list when it completes the current one, and wraps around when it hits the end.
Jukebox. The player moves to the next item in the list when it completes the current one, but it removes each item as it plays it.
Shuffle. The player selects the next item to play randomly, continuously playing from the current playlist.

Quirks and Limitations:

Because of the fact that Quick Time is not multi-thread capable on the Windows platform (meaning only one instance of it can run in a given program), if you use the Quick Time engine, each driver instance will spawn off a CQCQTAudSrv program that actually does the playback. The driver will talk to that program and ask it to start, stop, load a new file, etc... So there is considerably more overhead involved when using the iTunes/QuickTime combination.
When you are presented with a list of audio devices to select from, they are from the local machine you are installing on. The query for the available audio devices has not yet been 'remoted', so it cannot show you the devices from the actual target machine that you are loading the driver into. So, for now, you must install this driver from the machine where it is being loaded. You also must use the local console to do so, because RDP seems to 'virtualize' the list of audio devices and only presents you with a single, magical RDP audio device.

Connection Details

There are no connection issues because the player is integrated into the driver itself.

Driver Fields

This section lists the fields that the driver makes available, their types, minimum and maximum values, etc...
Name
Type
R/W
Description/Limits
ActiveRepository String R This field indicates the moniker of the repository driver that this player driver instance is currently associated with. Any cookies that you send this driver must be from that repository.
ClearnPlaylist Bool W Any write to this field will clear the current playlist.
CurColArtist String R If artist information was available in the associated repository, this field will indicate that artist name of the collection that contains the currently playing item.
CurColCookie String R The cookie for the collection that contains the currently playing item, if any.
CurColName String R The name of the collection that contains the currently playing item, if any.
CurDescr String R If description information was available in the associated repository, this field will contain the description information.
CurItemArtist String R If per-item artist information was available in the associated repository, this field will indicate that artist name of the currently playing item.
CurItemCookie String R Indicates the item cookie of the playing item, if any. If none, then it will be empty.
CurItemName String R If item information was available in the associated repository, this field will indicate the name of the item currently selected/playing in the player. For movies, there will be one faux item that represents the whole movie.
CurItemTime Time R If item playing time information was available in the associated repository, this field will indicate the elapsed time for the current item, in the standard Time field format.
CurItemTotal String R If item length information was available in the associated repository, this field will indicate the full item length in seconds.
CurLabel String R If label/studio information was available in the associated repository, this field will indicate that label name.
CurTitleCookie String R Indicates the title cookie of title set that contains (indirectly) the item currently playing, if any.
CurTitleName String R Indicates the name of the title set that contains (indirectly) the item currently playing, if any.
CurYear Card R If year information was available in the associated repository, this field will indicate the release year of the playing title.
DelPlaylistItem String W Write the item cookie of the item you wish to remove from the drivers current play list.
EnqueueMedia String W Write a title, collection, or item cookie to this field to play media. This will add the indicated items to the currently playing list. See the 'Cookies and Playback' section above for details.
Mute Bool R/W Get or set the mute state of the player. Write True to mute and False to unmute.
PBPercent Card R The percentage of the currently playing media that has completed playback so far. This is generally used to drive progress bars on user interfaces. It will be zero if no media is playing.
PlayMode String R Indicates the current playing mode. This is an enumerated field with the values: Unknown, Play, Stop, Pause.
PlayMedia String W Write a title, collection, or item cookie to this field to play media. This will empty any currently playing items, and set the current list to the items indicated by the passed cookie. See the 'Cookies and Playback' section above for details.
PlayerStatus String R A read only field that provides information about the status of the player intended for human consumption.
PlaylistMode String R/W Get or set the playlist mode. This mode controls how the player manages the play list with respect to selecting the next item to play and dealing with items that it has finished playing. The values are: Normal, Jukebox, and Shuffle. See the main driver notes above for details.
PLItemCnt Card R The current number of items in the players playlist.
PLSerialNum Card R This is bumped anything the current playlist is changed. It is for use by clients that need to know when the list changes.
SetRepository String W This field allows you to change the repository with which this renderer driver is associated. The primary use of this field is to reuse the same touch screen interface to manage multiple repositories. Any items in the current playlist are removed and the new repository name is stored.
Transport String W Provides transport control over the player. This is an enumerated field with the values: Next, Pause, Play, Prev, Stop.
Volume Card R/W Get or set the player's volume. It is a percentage, so the value should be from 0 to 100.
ZoneNumber Card R This value is set from the zone number prompt value you provide when loading the driver. The intention is to allow you to create generic automation logic that can determine the zone number just given the driver moniker.

Prompt	Description
Default Repository	As with all standard CQC media renderer drivers, you will indicate the default media repository that the driver instance should be associated with (i.e. the one to which it will go to look up the media information on any media cookies you send to it.)
Audio Device	Select the audio device you want this driver instance to use. If you install multiple driver instances, each should have its own audio device. Don't select default devices.
Zone Number	For your own use in automation logic, you can embed a zone number in the driver that you can later use in your actions to automatically figure out which zone number you are dealing with.
Initial Volume	The initial volume (0 to 100%) that the driver should set when it first loads up.
Audio Engine	As discussed above, you must select the Quick Time or DirectShow engine to use for playback.
Quick Time Port	If you select QuickTime, you provide an IP port number that that instance will use to talk to the Quick Time audio server. Select a unique port for each driver instance you load on a given host.

Field	Title Cookie	Collection Cookie	Item Cookie
EnqueueMedia	Adds the items of the first collection of the title set to the end of the playlist	Adds the items of this collection to the end of the playlist	Add this one item to the end of the playlist.
PlayMedia	Clears the current list, then sets the list to the items of the first collection of this title set.	Clears the current list, then sets the list to the items of this collection.	Looks for this item in the current list. If found, makes it the active item. Else ignores it.

Name	Type	R/W	Description/Limits
ActiveRepository	String	R	This field indicates the moniker of the repository driver that this player driver instance is currently associated with. Any cookies that you send this driver must be from that repository.
ClearnPlaylist	Bool	W	Any write to this field will clear the current playlist.
CurColArtist	String	R	If artist information was available in the associated repository, this field will indicate that artist name of the collection that contains the currently playing item.
CurColCookie	String	R	The cookie for the collection that contains the currently playing item, if any.
CurColName	String	R	The name of the collection that contains the currently playing item, if any.
CurDescr	String	R	If description information was available in the associated repository, this field will contain the description information.
CurItemArtist	String	R	If per-item artist information was available in the associated repository, this field will indicate that artist name of the currently playing item.
CurItemCookie	String	R	Indicates the item cookie of the playing item, if any. If none, then it will be empty.
CurItemName	String	R	If item information was available in the associated repository, this field will indicate the name of the item currently selected/playing in the player. For movies, there will be one faux item that represents the whole movie.
CurItemTime	Time	R	If item playing time information was available in the associated repository, this field will indicate the elapsed time for the current item, in the standard Time field format.
CurItemTotal	String	R	If item length information was available in the associated repository, this field will indicate the full item length in seconds.
CurLabel	String	R	If label/studio information was available in the associated repository, this field will indicate that label name.
CurTitleCookie	String	R	Indicates the title cookie of title set that contains (indirectly) the item currently playing, if any.
CurTitleName	String	R	Indicates the name of the title set that contains (indirectly) the item currently playing, if any.
CurYear	Card	R	If year information was available in the associated repository, this field will indicate the release year of the playing title.
DelPlaylistItem	String	W	Write the item cookie of the item you wish to remove from the drivers current play list.
EnqueueMedia	String	W	Write a title, collection, or item cookie to this field to play media. This will add the indicated items to the currently playing list. See the 'Cookies and Playback' section above for details.
Mute	Bool	R/W	Get or set the mute state of the player. Write True to mute and False to unmute.
PBPercent	Card	R	The percentage of the currently playing media that has completed playback so far. This is generally used to drive progress bars on user interfaces. It will be zero if no media is playing.
PlayMode	String	R	Indicates the current playing mode. This is an enumerated field with the values: Unknown, Play, Stop, Pause.
PlayMedia	String	W	Write a title, collection, or item cookie to this field to play media. This will empty any currently playing items, and set the current list to the items indicated by the passed cookie. See the 'Cookies and Playback' section above for details.
PlayerStatus	String	R	A read only field that provides information about the status of the player intended for human consumption.
PlaylistMode	String	R/W	Get or set the playlist mode. This mode controls how the player manages the play list with respect to selecting the next item to play and dealing with items that it has finished playing. The values are: Normal, Jukebox, and Shuffle. See the main driver notes above for details.
PLItemCnt	Card	R	The current number of items in the players playlist.
PLSerialNum	Card	R	This is bumped anything the current playlist is changed. It is for use by clients that need to know when the list changes.
SetRepository	String	W	This field allows you to change the repository with which this renderer driver is associated. The primary use of this field is to reuse the same touch screen interface to manage multiple repositories. Any items in the current playlist are removed and the new repository name is stored.
Transport	String	W	Provides transport control over the player. This is an enumerated field with the values: Next, Pause, Play, Prev, Stop.
Volume	Card	R/W	Get or set the player's volume. It is a percentage, so the value should be from 0 to 100.
ZoneNumber	Card	R	This value is set from the zone number prompt value you provide when loading the driver. The intention is to allow you to create generic automation logic that can determine the zone number just given the driver moniker.