Using ENCORE also known as XML Playback Status in DAD
ENCORE, also known as the Playback State DCL allows administrators to have DAD generate a XML file based for 'Now Playing' information. This data can then be sent to an HD Importer, a web site or other 3rd party software packages. The XML file can be sent via IP or written to a file.
Stations can define the amount of information being sent based upon the specific Library Database fields, Group association and event Triggers.
DAD uses the PLAYBACK STATE DCL as a means to enable, define and disable the creation of data. This DCL can be used in conjunction with any machine that supports a Playlist. For example, Playback Deck 1 or AirPLAY. DAD can also be configured to have multiple decks generate multiple XML files. By default, the XML file DAD generates will contain the next ten items in a playlist and the last three items that recently played.
The PLAYBACK STATE DCL will also intelligently 'look ahead' beyond the current playlist. In other words, if one reaches the end of the currently loaded Playlist, PLAYBACK STATE will query the Chain Event and 'look' for events in the next Playlist. If a Chain Event is not used, then it will simply loop to the top of the current Playlist.
To utilize the Playback State DCL and generate these XML files, one must have the options PLAYBACK STATE DCL and SERIAL I/O enabled on the security key.
|
|
NOTE: This document only discusses the ability to create XML files from DAD. The integration of the XML file into a web page or other streaming player is handled by the web designer or streaming integrator. |
Overview:
For DAD to generate a XML file there are a few items that need to be configured. Once DAD has been configured, it will output the file based on a set of rules in the PBKSTATE.INI file. This file typically lives in the \DAD\FILES\ directory of the Data share on the server. One can however, have this file in other locations and even with unique file names. This file is used to define the fields sent from DAD, the Groups DAD will output data for and the types of Triggers such as PLAY and STOP.
An administrator would next issue the PLAYBACK STATE DCL for the machine they are using along with options such as the XML file name and IP Address. This allows one to have DAD send the 'Now Playing' date directly to an external device.
When a Playlist is loaded into a machine such as AirPLAY, when DAD plays an audio cut, it will look at the PBKSTATE.INI file to determine if it should generate a data file. If so, it will then send that information out based upon the settings defined via the PLAYBACK STATE DCL.
When a new Trigger occurs such as a new cut being played, new data is created. This process is maintained until one disables the function via a DCL or exits DAD.
One should first state by setting up a PBKSTATE.INI file. This file is critical in the overall operation. If this file does not exist or has been improperly written, DAD will not output data. By default, DAD will look for this file in the DAD\FILES directory on the server and will assume that the file is named: PBKSTATE.INI.
Administrators have the option to change the INI file name and it's location. If this is done, it is important that one also modifies the workstation's CFI file to properly reflect these changes.
NOTE: For the purposes of this manual, the assumed file name will be PBKSTATE.INI and the location will be in \DAD\FILES. There is a sample file located in C:\DAD\FILES directory under the name PBKSTATEini (no extension).
A sample file is below:
; sample PBKSTATE.ini file for DAD Playback State XML generator
[Triggers]
PLAY=
;STOP=
;NEXT=
;LOAD=
;UNLOAD=
;ADD=
;DELETE=
;INSERT=
[Fields]
CUT=
TITLE=
LENGTH=
GROUP=
ARTIST=
ALBUM=
[Config]
Next Events = 0
Previous Events = 0
Min Length = 5.0
[Groups]
Songs=
Music=
;Sweepers=
;Sounds=
Details of the INI settings are as follows:
| INI Entry | Description |
| [TRIGGERS] | Triggers are events that occur in DAD. When DAD plays a cut, a PLAY trigger is issued. There are several valid Triggers: PLAY, NEXT, LOAD, UNLOAD, REFRESH, SUPERPLAY, ADD, INSERT, DELETE, TRANSITION, REPOSITION, CHANGE, RETURN, STOP and PAUSE. |
| PLAY= | A valid Trigger followed by an equals sign (no spaces) will cause DAD to use that Trigger as an event to generate data. |
| ;STOP= | When one uses a semi-colon in front of the Trigger event, it will be ignored. |
| [FIELDS] | Fields are the DAD Library Database fields that one can have send out as data. One would enter the field name followed by an equals sign (no spaces). |
| CUT= | |
| TITLE= | |
| [CONFIG] | The Config portion of this INI file allows the administrator to define how many of the Next events should be included in the data output as well as how many Previous events. These would be the cut that are in the playlist that have not played yet and the ones that have played. One can also set a minimum length for cuts. |
| Next Events = 0 | The number entered here will generate the respective number of 'next' events in the XML data output. Values are from 0 (currently playing cut only) to 9 (currently playing cut and next 9 elements in the playlist) |
| Previous Events = 0 | Values are from 0 to 3. 0 will not allow DAD to output any information about the last played cut. One can have DAD output up to the past three elements played. |
| Min Length = 5.0 | The Minimum length value allows one to set a time in seconds that an audio cut must be before DAD will generate the data file. This helps prevent short shotgun style cuts from generating them regenerating XML data quickly. Some external programs and devices have difficulty when multiple XML files are sent in a short period of time. |
| [GROUPS] | Here one can set which Group name should be used to allow DAD to generate the data output. For example if one enters SONGS, then only audio cuts that belong to the SONGS group will have their data generated. Cuts associated with other Groups will be ignored and will not cause DAD to generate data. |
| SONGS= | Only cuts from the SONGS group will generate the XML file output. |
| ;SWEEPERS | When one uses a semi-colon in front of the Group name, it will be ignored. |
Once the PBKSTATE.INI file has been established, one can then enter the file name and location into the DAD CFI file.
Under SETUP press the CFI and README button. Clicking on the <location>.CFI button will open the CFI file in Notepad allowing one to make changes.
In the [PLAYBACK] section, one can define which PBKSTATE.INI file DAD will use.
For example:
[PLAYBACK]
STATE_INI_FILE=F:\DAD\FILES\PBKSTATE.INI
By default, DAD will use PBKSTATE.INI in the \DAD\FILES directory on the data share of the server.
|
|
WARNING: If the PBKState.ini file is missing - PLAYBACK STATE will not work! |
Defining the PLAYBACK STATE DCL:
The PLAYBACK STATE DCL is what enables DAD to generate the XML data file. This command must be run before DAD will generate an output file. Administrators often place this command as the Startup Command for a machine. This way, when DAD starts, the command is always run. Details about setting up the Startup Command cut are below.
When preparing to use the PLAYBACK STATE DCL one must know what machine in DAD they will be using such as Playback Deck 1 or perhaps AirPLAY. They must also have on hand details about where the data output will go. In other words, does it need to be written to a file or should it be sent out to an IP Address and port. With these details, one can create the command.
From the Library screen press ADD then Command. Here one would give the cut a Cut Number along with any other needed info such as a Title. When presses Save & Close, they will be presented with the Command Cut (DCL) Editor screen. Here one can add their command to turn on PLAYBACK STATE.
There are many different options that one can use in conjunction with the PLAYBACK STATE DCL. The basic syntax is as follows:
PLAYBACK STATE <machine> <'filename.xml'> <port> <IP Address>
For example:
PLAYBACK STATE PBK1 'dad.xml' 4444 10.44.44.44
The above will generate a XML file when a Playlist is loaded into Playback Deck 1 and played. This data will be written to a file called DAD.XML and will be sent to port 4444 on IP Address 10.44.44.44.
To use ports under 1024 one must precede the port with a 'minus' sign such as -83
Based upon the basic syntax, one can use any of the following options:
For sending via UDP:
PLAYBACK STATE <machine> <'filename'> <port> <IP
Address> UDP
For example:
PLAYBACK STATE PBKx 'dad.xml' 4444 10.44.44.44 UDP
For generating a FILE only:
One can have Playback State simply generate a
file and NOT send the data out to an IP Addresss. This can be done by simply
entering:
PLAYBACK STATE PBKx 'filename.xml'
An example of this would be:
By default, the XML file will be created in the local workstation’s C:\DAD directory.
To have the XML file created in a specific drive, use [ ] around the drive letter.
For example:
PLAYBACK STATE PBK1 '[F]\DAD\FILES\DAD.XML'
To have the
XML file created on a UNC address, another example would be:
PLAYBACK STATE PBK1
'\\ENCOWEB\FTP\ENCORADIO\RADIO1.XML'
The above example will use the RADIO1.XML file on the \\ENCOWEB workstation in the FTP\ENCORADIO directory.
Disabling the PLAYBACK STATE DCL:
Administrators can disable the PLAYBACK STATE. This will prevent DAD from generating the data file. To disable, issue the DCL:
PLAYBACK STATE PBKx OFF
For example:
PLAYBACK STATE PBK1 OFF
To re-enable PLAYBACK STATE one would re-issue the original command. This will allow DAD to start generating the XML data again upon playback.
Sending XML Data via a Serial Connection:
One can send the XML file to a com-port for serial transmission.
|
|
CAUTION:
Administrators should be aware that the XML data
will
only be sent when an audio cut is played. Changes to the list or the XML
will not be sent via serial output.
Also, sending large amounts of XML data out serially could also cause delays in start of audio playback. Using a slower baud rate (i.e.: 9600) can affect the playback of audio. Audio will “wait” until ALL data is sent. |
For sending
via serial, the syntax of this command
would be this:
An example of this would be:
This will create the XML file called RADIO1 in the C:\DAD directory. If one would like to have the output file created in a different location, one could enter that as part of the command. For example:
PLAYBACK STATE PBK1 '[F]\DAD\FILES\RADIO1.XML'
One must also configure the
workstations CFI file and the workstations GPO file.
The following lines must be
set in the workstations CFI file. Under SETUP go to CFI and README then press
the CFI button. This open the CFI file in Notepad for editing.
|
|
NOTE: When editing the workstation's CFI file, please note that there are not any spaces before or after the equals sign. |
Under the [SERIAL] section one would define a Com Port.
COMn_INFO=<baud><parity><data
bits><stop bits>
Example:
COM2_INFO=115200 N 8 1
|
|
CAUTION: If one is going to use Serial as the means of transmission, one should exercise restraint with the amount of data sent. One should carefully review the configuration of the PBKSTAT.INI file as described above. If one were to limit the amount of data being sent, then one can reduce the amount of time of audio delay upon playback. |
[SEND_TEXT]
IO_x =<n>
Whereas: x equals ports A thorough Z and n
equals the Com Port number set in the COMn_INFO
statement.
For example:
[SEND_TEXT]
IO_B=2
Next one defines a SEND TEXT RULE. This is also under the [SEND_TEXT] section.
[SEND_TEXT]
RULES=X
filename.xml
Whereas: X
equals the IO_x output and filename.xml equals the XML file.
An example is
below:
RULES=B RADIO1.XML
If one needs to specify a path, it would be like the following:
RULES=B
C:\DAD\RADIO1.XML
After the CFI file has been properly set, next one must edit the workstations GPO file.
The GPO file allows the user to execute Commands based upon the logic of the audio card. In other words, when a machine such as Playback Deck 1 starts playback, it will use the PLAYBACK event in Channel Assignments. Typically that event is designated as PROGRAM. The same would be true for SEGUE PLAYBACK. When set for PROGRAM, DAD will perform the commands entered into the GPO file for that event on that particular output.
More information about GPO's can be found here.
Under SETUP one would go to CFI and README them select the GPO button.
The following lines must be
set in the workstations GPI file.
PGM_START OP C "SEND TEXT n FILENAME.XML"
Whereas:
OP = Audio Output device. (i.e.:
channel assignment output)
C = Command
"SEND TEXT n
FILENAME.XML" = Send Text DCL
with output IO port
Continuing to use the same example as defined above one would enter:
PGM_START 1
C "SEND TEXT B RADIO1.XML"
When audio assigned to
output 1 of the audio card and program status <as defined in channel assignments> is played
in the machine defined in the PLAYBACK STATE DCL, it will send the XML file out
the assigned Com Port.
If one were to
use multiple outputs
for a single playback machine, one can either configure each PGM_START output
or use: ANY_PGM_START (just like
PGM_START but "fires" at every start)
Example:
ANY_PGM_START C "SEND TEXT A [C]\DAD\FILES\RADIO1.XML"
Administrators should note that during a Segue transition data might NOT be sent. One should check the CFI file in the [SYSTEM] section for the line:
CHECK_FOR_START_GPO=TRUE
When set to TRUE, DAD is ignore the PGM_START durring a segue transition. To have DAD send the XML data out via the above described Serial method, one should change this value to FALSE. When set to FALSE, DAD will execute PGM_START logic regardless of the transition type.
To do this, press SETUP then CFI and README. Clicking on the CFI button will open the CFI for editing.
Under the [SYSTEM] heading find the following:
[SYSTEM]
STARTUP_COMMAND_CUT=<Cut
Number>
STARTUP_COMMAND_DELAY=30000
RECOVER_COMMAND_CUT=<Cut
Number>
RECOVER_COMMAND_DELAY =30000
For example:
STARTUP_COMMAND_CUT=99700
STARTUP_COMMAND_DELAY= 30000
The startup cut will be
executed 30 seconds after DAD is “up” all the way. One can adjust the delay
time accordingly. The recover cut should be used in case the program is
not exited “cleanly”. A power outage would be an example.
The XML
File structure:
NOTE: The data in the XML file will vary depending upon how the PBKSTATE.INI file is configured.
The structure of the XML file can be as follows:
<TRIGGER>
PLAY</TRIGGER>
<CURRENTTIME>
10/24/07 14:47:51</CURRENTTIME>
<PLAYLIST>
DISCOA</PLAYLIST>
<PLAY INDEX="0">
<CUTID>20722</CUTID>
<TITLE>Stomp</TITLE>
<LENGTH>4:05.0</LENGTH>
<GROUP>DISCO</GROUP>
<ARTIST>Brothers Johnson</ARTIST>
<ALBUM>THIS IS ALBUM</ALBUM>
</PLAY>
<PLAY INDEX="-1">
<CUTID>20723</CUTID>
<TITLE>McArthur Park</TITLE>
<LENGTH>0:14.8</LENGTH>
<GROUP>DISCO</GROUP>
<ARTIST>Donna Summer</ARTIST>
<ALBUM></ALBUM>
</PLAY>
<REMAINING>00:04:04
</REMAINING>
</PLAYBACKSTATE>
<TRIGGER>
PLAY</TRIGGER>
The <TRIGGER> event that causes an update of the XML file. Triggers can be: PLAY, NEXT,
LOAD, UNLOAD, REFRESH, SUPERPLAY, ADD, INSERT, DELETE, TRANSITION, REPOSITION,
CHANGE, RETURN, STOP and PAUSE.
<CURRENTTIME>
10/24/07 14:47:51</CURRENTTIME> is the current date and time of the file.
<PLAYLIST>
DISCOA</PLAYLIST>
is the name of the playlist that is loaded into the machine being
used.
<PLAY INDEX="0"> This refers to the order of the cuts in the playlist. "0" is the currently loaded cut which is also the currently playing cut. All subsequent cuts would start at "1". Play Index 1 is the ‘next cut to play’. DAD allows for a maximum of 10 cuts <0 thought 9>.
<CUTID>20722</CUTID>
<TITLE>Stomp</TITLE>
<LENGTH>4:05.0</LENGTH>
<GROUP>DISCO</GROUP>
<ARTIST>Brothers Johnson</ARTIST>
<ALBUM>THIS IS ALBUM</ALBUM> These
are DAD Library Database fields. The PBKSTATE.INI file was configured to output
these specific fields.
<PLAY
INDEX="-1"> This refers to the cut that ‘just played’. DAD
allows
for the last 3 cuts played to be ‘shown’.
<REMAINING>00:04:04
</REMAINING> This time value is updated
based on the trigger. When the cut begins play, it’s
length is entered. If the cut is paused, when the cut resumes play, the new
amount of time remaining for that cut is entered.