To communicate with the TTS-1e via VTP a VTP User Account will need to be set up. Create a New User and assign a password in the fields provided. When creating a VTP User in the Universe Properties the user name and password fields are limited to 16 characters, are case sensitive and must not contain spaces.
If the connection to the MS-1 or MS-1e is broken and any of the following commands are attempted to be sent a "HOST_CONNECTION_LOST" XML message will be returned.
Command |
Argument |
U |
Username |
Provide the username as a string of ASCII characters. Case sensitive.
Command |
Argument |
P |
Password |
Provide the username as a string of ASCII characters. Case sensitive.
Command |
Argument |
A |
Authorize |
Request authorization using the username/password pair previously provided. If the pair is valid the response will be “SUCCESS” otherwise it will respond with “FAILURE”.
| Example Sequence with XML Responses |
Connection Accepted U admin P admin A <?xml version="1.0"?><Status Command="A"><State>AUTH_SUCCESS</State></Status> |
Any page that is activated via VTP is comprised of a sequence of paging elements. A TTS-1e paging element must be an audio file (.WAV), a text element or an end of sequence marker. A Repeat number and time is also able to be specified. Live pages are not able to be triggered via VTP, only audio files or text elements are permissible.
In addition to the paging elements, a VTP triggered page must have a Zone/s allocation, as well as Preamble and Priority level selection, and finally an ID number. The method for defining elements is shown below, zone allocation is shown under Zone Definition and Page Execute commands are shown under the X S command.
As a VTP triggered page consists of elements, we must define the order of the audio files using an element number. This must be is in the range 0-23, and must be in sequential order. This by default means the maximum number of file elements that can be triggered as a single VTP paging event is 24.
Prior to sending an Elements command, the Voice and language need to be defined using the V Command.
Note: A single Vocia page has a maximum system limit of two minutes. Any part of a message that exceeds this time will be lost.
Command |
Argument |
Command |
Argument |
E |
n |
e |
Wav filename |
Where n is the element number, a value of 0 to 23
Wav filename – Ensure this audio filename exists already on the MS-1e otherwise an error will occur when the page is executed. A list of available .WAV files can be queried using the Q A command (see VTP Query Commands). The audio file folder location is specified as part of the VTP command so any audio file names are required to be preceded by the /vociawavs/ directory path (and/or their corresponding sub-directories). The filename should not be put in quotation marks, even if it contains spaces.
Command |
Argument |
Command |
Argument |
E |
n |
S |
text |
The S command will convert the specified text into an audio file. This file is then sent to the MS-1 as part of the paging sequence to be executed.
Where n is the element number, a value of 0 to 23
Where text is the text that needs to be converted into a audio file and played by the MS-1e as part of the page sequence.
| Command | Argument |
| E n | z |
This element is the end-of-sequence marker. There is no need to send this command if all elements (0->24) have been defined, however it must be included if all 24 elements are not defined.
Command |
Argument |
Z |
1 2 3 |
Where n1 n2 … is a list of zones as decimal numbers each separated by a space.
Command |
Argument |
R N |
Quantity (number) |
Quantity can be specified between 1 and 9999.
Command |
Argument |
R T |
time (seconds) |
The time will be specified in seconds and must be less than or equal to 43200 (12 hours).
Command |
Argument |
Argument |
Argument |
Argument |
X S |
pre |
priority |
id |
queue |
The X S Command is used to execute the custom Recorded Page Code. It specifies the Preamble, Priority and unique ID of the Page which will contain the previously defined Elements.
pre defines what the Page will be preceded by
pre = Y Page will be preceded by preamble
pre = N Page will not be preceded by preamble
pre = P Page will be preceded by preamble (same as above)
priority = This parameter defines the priority of the page (used for resolution of access to zones) and is in the range 1 and the numerical value below the Emergency Priority Threshold specified in the Universe dialog. The Q E command can be used to query the threshold.
Example:
Emergency Priority Threshold |
Normal Paging |
Emergency Paging |
101 (default) |
(Low) 1-100 (High) |
(Low) 101 - 255 (High) |
5 |
(Low) 1-4 (High) |
(Low) 5 - 255 (High) |
252 |
(Low) 1-251 (High) |
(Low) 252 - 255 (High) |
id = This is an id number provided by the client which the system will use to identify individual page requests when informing the client of progress of an individual page. A number range from 0 to 32767 is supported and each ID sequence should be unique.
queue = This is an optional argument and can either be Y to allow the message to be queued if the destination zones are busy, or N if the message should not be queued and should fail immediately if any of the destination zones are busy. It will default to Y when it hasn’t been specified.
| Example Sequence with XML Responses |
v
donna en-us |
Command |
Argument |
X T |
sequence id |
sequence id must refer to a configured TTS-1e sequence. It is a three digit number and can be queried by using a Q T query.
If a configurable text element (other than Read Only and Drop Down List text elements) exist in the selected Sequence but has not been modified, the title for that particular Element will be used for conversion and a XML response of "UNADJUSTED_TEXT_CONVERTED" message will be generated.
Command |
Argument |
Argument |
V |
voice |
language |
Specify the voice and language used to convert the text elements. A list of installed voices can be queried using the Q V Command.
The system will store a list of zones to be used with subsequent page requests. This list of Zones remains current for all future page requests until overridden by a future zonelist definition. All zones are zone numbers in the system to which you are connected. Remote zones of interlinked systems cannot be accessed via this method – access to remote systems must be made to the RPI of those systems directly.
Where n1 n2 … is a list of zones as decimal numbers each separated by a space.
Command |
Argument |
Z |
1 2 3 |
If the selected page code has pre-configured auto-repeat parameters these will override those specified using VTP commands.
By default the number of repeats will be set to 0 implying no repetition of announcements. The repeat count will persist for all subsequent pages. It would be necessary to set the repeat count back to 0 if repetition was no longer required.
K – Reboots a device
C – Request state of control handle
Command |
Argument |
Q T |
not needed |
Returns a list of the available configured text to speech sequences on the TTS-1e. Each item in the list consists of a sequence ID followed by the sequence name.
The response to an audio file list query command will be as follows:
<?xml version="1.0"?><Query Command="T"><TTSSequences count="SequenceCount">
<TTSSequence id="SequenceId">SequenceName</TTSSequence>
...
<TTSSequence id="SequenceId">SequenceName</TTSSequence>
</TTSSequences></Query>
"SequenceCount" is the number of available TTS sequences,
"SequenceName" is the name of the sequence.
Command |
Argument |
Q V |
not needed |
The response will be:
<?xml version="1.0"?><Query Command="V"><TTSVoices count="VoiceCount">
<TTSVoice><Name>VoiceName/Name><Language>VoiceLanguage</Language></TTSVoice>
…
</TTSVoices></Query>
"VoiceCount" is the number of available tts voices,
"VoiceName" is the name of the sequence
"VoiceLanguage" is the language.
The VTP service will provide progress status for the currently active paging announcement via TTS VTP. This information can be used to provide the VTP client with feedback as to the progress of the announcement in the paging system. The Page Progress Responses section defines the allowable page progress responses. This facility can be turned on and off using the ‘S’ command and is turned off by default.
Command |
Argument |
S |
On/Off |
S ON - Enable the transmission of paging progress status.
S OFF - Disable the transmission of paging progress status.
S ALL - Enable detailed paging progress mode. Sequence element progress will be reported in addition to the standard page progress. See the PAGE_ELEMENT_X for formatting of the Sequence element response. Use the 'S ON' or the 'S OFF' command to disable the detailed paging progress mode.
The page progress responses will be as follows:
<?xml version="1.0"?>
<Status Command=X>
<Id> Page event id </Id>
<State> Page progress state </State>
</Status>
Where
Page event id is the id number associated with the page when it was executed
Page progress state will be one of the following paging states.
PAGE_NEW_REQ - Page request accepted
PAGE_FAILED - Page failed for some reason
PAGE_COMPLETE - Page completed normally
PAGE_TIMEOUT – Page play-out delayed longer than the store duration
PAGE_ACTIVE - Page is currently being played back the first time
PAGE_ELEMENT_X ('S ALL' mode only) – The Sequence element X (where X is 0-23) is currently being played back as part of this page. The preamble if configured is considered sequence element P.
PAGE_AR_WAITING_FOR_REPEAT_INTERVAL – The page is currently waiting to be re-queued for playback once the repeat interval has expired.
PAGE_AR_ACTIVE – Repeating page is currently being played back as part of an auto repeating announcement.
PAGE_OVERIDDEN - Page was overridden by a higher priority announcement
PAGE_TRUNCATED - Page was truncated because it exceeded the maximum page duration
Command |
Argument |
J |
state |
State shall be
ON - Turns on Zone status updates (updates occur anytime the status of a Zone changes)
OFF - Turns off Zone status updates
POLL - Will provide the status of all of the Zones in the World
Example |
<?xml version="1.0”?> <Status Command="J"> <Zone id=”1” state=”IDLE”/> <Zone id=”2” state=”IDLE”/> <Zone id=”3” state=”IDLE”/> <Zone id=”4” state=”IDLE”/> <Zone id=”6” state=”5”/> <Zone id=”12” state=”5”/> </Status> |
The state of a zone can either be IDLE or it will be the numeric priority that is active in that zone in the range 1 to the Emergency Paging Threshold – 1. For example if the Emergency Paging Threshold is 101, the numeric priority will be in the range 1 to 100.
The response for a Zone Status POLL command will be in the same format as a zone status update above, however it will contain all of the Zones configured in a World.
It should be noted that Emergency Paging and/or Emergency Message playback can cause an audio output channel that has been assigned to both a Zone and an Emergency Zone to become unavailable for custom page code playback. As the relationship between Zone and Emergency Zone assignment is complex (Zone and Emergency Zones can overlap) any emergency activity will not be reflected in the zone status information provided (the emergency system operation is intended to occur at the highest level of priority).
The 'M' command supports turning on/off system mute status updates. System mute status updates will be sent anytime the state of system mute changes.
Command |
Argument |
M |
state |
State shall be
ON - Turns on system mute status updates
OFF - Turns off system mute status updates
Example |
<?xml version="1.0"?> <Status Command=M> <SystemMute>N</SystemMute> </Status> |
A full-stop will terminate the VTP session and close the socket.
Command |
Argument |
. |
not needed |
A third party application using VTP may need to access certain aspects of the MS-1e /TTS-1e configuration. For example it may be necessary to render a list of destination Zones or Page Codes on a user interface. The VTP Configuration Query commands can be used for this purpose. All other commands are listed in the MS VTP protocol documentation. Commands unique to TTS VTP are listed below.