VIXML - Video Interactive XML

VIXML, or Video Interactive XML is a scripting language designed for IVR sessions with 3G video calls. It also works with standard voice calls.

A VIXML page is specified within an XML document by a list of objects between <vixml> and </vixml> tags. The VIXML interpreter works its way sequentially through the objects, rendering graphics and playing sound as necessary.

<vixml>
  objects ...
</vixml>

To ensure correct syntax, VIXML documents can also be created via the XML schema http://www.vivatel.com.au/VIXMLSchema.xsd

A video IVR session has an audio and a video channel, while a voice session only has an audio channel. Some VIXML objects attempt to lock these channels, sometimes instantaneously, like when an image is specified, or for a period of time, like when text is spoken by the speech synthesizer. The VIXML interpreter will stop at any object that is unable to obtain a lock, then proceed once the channel becomes available.

Each object has optional attributes, and some may include a text value. For example, the following XML tag sets the background colour to red.

<defaults bgcolour="red" />

while this object will say hello my friend with a male Scottish accent.

<speech voice="cmu_us_awb_arctic_hts">hello my friend</speech>

Note that whenever a voice is set for the speech synthesizer, it will persist for the duration of the call. This is one of the few attributes that is not reset when a new page is loaded.

URLs within VIXML objects may be either absolute (e.g. http://www.darkside.com/test/image.jpg) or relative (image.jpg or /test/image.jpg). However, for relative addresses to work, the URL of the referring page must contain a trailing slash if it's the default file for its directory (e.g. http://www.darkside.com/test/).

There are also special URLs that can be referenced from link and timeout objects.

• system://hangup This causes the call to terminate immediately.
• system://signal?dtmf=NNN When connected to another party via the call command, this will send them a sequence of one or more DTMF digits. This is useful when the other party is an IVR.

All pages loaded by VIXML will have a duration variable appended to their URL. This contains the duration of the call so far, in milliseconds. It can be useful in situations where a call has to be terminated after a certain length of time.

In addition, all pages will have a session variable appended. This is an integer, unique to every call.

Start page

The start page of a VIXML session will be passed three HTTP GET variables, type, localPhone, and remotePhone if it is known. The value of type will be either video or voice. If caller-ID is suppressed, then remotePhone will not be specified. The phone numbers will be in E.164 format where possible (e.g. 61410402221), but for numbers that aren't accessible internationally the local format will be used (e.g. 1800555236).

The duration and session variables will also be set for the start page. Note, however, that the duration on the start page will always be zero.

Since the start page will probably need to be a dynamic script to handle these variables, it is unlikely to have a .xml suffix. To be safe, the generated page should have a Content-Type of text/xml or application/xml, although this isn't enforced.

VIXML objects

The complete list of VIXML objects is as follows.

The defaults tag is used to set the background colour and default attributes for the objects that follow.

The image tag is used to load an image from a URL and display it on the screen at the specified position at the specified size. Images that are not the same resolution as the specified size will be scaled to fit. Supported image formats are JPEG, GIF, PBM, PGM, and PPM. For images from remote servers, JPEG format is preferred because it uses less bandwidth. For images hosted locally, PPM is preferred because it requires less processing.

The text tag displays text on the screen. The text is contained within a bounding box, and when the width of the text exceeds the width of the bounding box it wraps to the next row.

Note that if the text contains the HTML special characters &, <, or >, or a character value greater than 127, then those characters will have to be replaced with HTML escape sequences. The relevant sequences are &amp;, &lt;, &gt;, and &#128; respectively.

The speech tag causes the text to be spoken in a synthesized voice.

The link tag is used to specify links to other VIXML documents. These are triggered by DTMF key presses. Note that the VIXML interpreter goes through the list of objects sequentially, so links should appear at the start of the script if they are to be active the whole time.

The timeout tag will cause the interpreter to pause for the specified number of milliseconds. If there is a URL specified, it will then attempt to jump to that page.

If the background attribute is set to true, the interpreter will immediately jump to the next command and run the timeout in the background. When the timeout expires, the url (if specified) will be called in background mode. VIXML scripts called in background mode do not interfere with the main application, but run independently. They are useful for playing periodic beeps and hanging up calls at a pre-scheduled time. Note that background mode commands that try to display visual information are ignored. If a timeout command is executed during background mode with its background attribute set to false, its URL will take control from the main application.

The input tag is used collect a sequence of DTMF key presses that will be passed to another VIXML script via HTTP GET. Note that the destination URLs can contain variables (e.g. http://www.vivatel.com.au/scripts/test.php?user=mkwan), in which case the input variable and its value will be appended to the URL.

The stream tag is used to play an audio stream, a video stream, both an audio stream and a video stream, or an audio-video stream. Note that streams will be buffered for a quarter second before playing. If both an audio and video stream are specified, they will be synchronized.

Audio streams can be read from wav files (MIME type audio/x-wav), mp3 files (MIME type audio/mpeg), and raw format au files (MIME type audio/basic). Note that the raw format is 16-bit signed 16kHz samples in little-endian order, and is specific to this application. This is not the Sun Microsystems 8kHz u-law format.

The capture tag is used to capture the stream of audio/video being sent to/from the remote phone. It is usually used to capture audio and video being sent from the phone, but can also record what the phone is receiving, or the audio in both directions. The only limitation is that transcoded video being sent to the phone cannot be captured because it is never available as decoded frames within the session.

When the capture tag is encountered, the address of the remote capture script specified in the url attribute is called with the following HTTP GET parameters.

When called, the remote capture script should immediately start reading from the address passed through in the url parameter. If it fails to connect to the URL within 60 seconds the capture will be aborted.

By default the captured inbound stream is encoded as MPEG video, but different formats, including audio-only, can be requested with the contentType attribute.

Normally when capture begins, all input is buffered then sent as fast as the connection will allow once the remote capture script connects and starts downloading the stream. This is ideal for recorded-message applications where all input must be captured. However, for applications where the stream must be processed in real time, setting the realtime attribute to true will disable buffering and ensure that stream data will be sent as soon as it is received from the remote handset. Note that this will result in the loss of some data if the capture script is slow to connect or the connection is too slow to support the stream.

Capture ends when another capture tag is encountered with a different URL or the call ends. If the new capture URL is not an empty string, then a new capture will begin immediately to that URL.

Note that the captured data does not always strictly conform to the format of the specified content type. Many audio and video formats have headers that specify the length of the clip, but because the data is streamed the header must be sent before the length is known, so dummy values are used. Some players can cope with this, others can't. There may be some trial-and-error involved in finding a format that works.

The call tag is used to link a call to another handset, a SIP-capable softphone, or a streaming media source such as a webcam. A number of URL callbacks are provided to handle the various outcomes.

When the phone parameter is specified, an outbound call is made to that phone number. This call is charged at the usual outbound rate. When that call is answered, the two phone calls are tied together like a regular person-to-person call.

Alternatively, the conference parameter can be used to tie two or more existing calls together. The parameter can be any string, and when two calls specify the same value they will be linked together. Note that the engagedURL and rejectedURL parameters are not used in this case.

A third option is to specify the phoneConference parameter. This will initiate an outbound call to the phone number, unless a call to that number is already in progress. In that case, it will connect immediately to that call in conference mode.

Note that when a remote party is called using the phoneConference parameter they will always be the first party in the resulting conference. This differs from the phone parameter, where the caller is always the first party. This is important when the conference type is Broadcast or OneToMany.

Five different conference types are possible, which affect the behaviour of video in a conference with three or more parties.

• Normal. The first party to connect will send video to all the other parties. The second party to connect will send to the first.
• OneToMany. Video works the same as Normal mode.
• FollowSpeaker. The current speaker will send video to all the other parties. The previous speaker will send to the current one.
• SplitScreen. The screen is divided up to show all other parties simultaneously, up to a maximum of 31.
• Broadcast. The first party to connect will send video to all the other parties. Nothing will be sent to the first party. This is the recommended conference type when the first party is a streaming media URL.

In Broadcast mode, audio is sent from the first party to all other parties. No audio is sent to the first party or between the other parties. OneToMany mode is similar, except that audio from the second party is sent to the first party. In all other modes audio will be shared among participants. They will hear audio from all parties except themselves.

When a participant leaves the conference, all parties move up one place unless there is only one participant left, in which case the conference ends. The conference also ends if the type is OneToMany or Broadcast and the first party leaves.

A call ends when another call tag is encountered with a different phone number or conference, or the conference ends. If the new phone number or conference is not an empty string, then a new call will begin immediately.

Most of the URL callbacks are self-explanatory, except for preambleURL. This is called when the call connects and, unlike other VIXML scripts, is played to the other party, not the caller. It plays until it reaches the end, then connectedURL is called and the call proceeds as usual. This callback is designed for situations when the called party needs to be briefed about the caller before speaking to them.

Note that the VIXML preamble script should only play audio and display static images. Pre-encoded mpeg4 video clips will not work, and other video formats will not play reliably.

The application tag is used to run applications written in third-party scripting languages. Currently supported formats are Java and Flash.

Examples

Here is a simple script that requests a 16-digit credit card number.

<vixml>
  <defaults bgcolour="#e0e0e0" beepDuration="250" fontColour="green" />
  <text font="bold" x="0" y="16" halign="centre" wordWrap="true">
    Enter your credit card number
  </text>
  <text x="0" y="56" halign="centre" wordWrap="true">Press # to delete, * to cancel</text>
  <speech voice="cmu_us_slt_arctic_hts">Please type in your credit card number</speech>
  <input name="ccnumber" acceptLength="16" acceptURL="http://www.mysite.com/cc.php"
        deleteKeys="#" cancelKeys="*" cancelURL="http://www.mysite.com/ccCancel.php?reason=user"
        timeoutDelay="20000" timeoutURL="http://www.mysite.com/ccCancel.php?reason=timout"
        visible="true" y="112" halign="left" />
</vixml>

Here is the same script generated using the VIXML schema.

<?xml version="1.0" encoding="UTF-8"?>
<tns:vixml xmlns:tns="http://www.vivatel.com.au/VIXMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.vivatel.com.au/VIXMLSchema VIXMLSchema.xsd ">
  <tns:defaults bgcolour="#e0e0e0" beepDuration="250" fontColour="green" />
  <tns:text font="bold" x="0" y="16" halign="centre" wordWrap="true">
    Enter your credit card number
  </tns:text>
  <tns:text x="0" y="56" halign="centre" wordWrap="true">Press # to delete, * to cancel</tns:text>
  <tns:speech voice="cmu_us_slt_arctic_hts">Please type in your credit card number</tns:speech>
  <tns:input name="ccnumber" acceptLength="16" acceptURL="http://www.mysite.com/cc.php"
        deleteKeys="#" cancelKeys="*" cancelURL="http://www.mysite.com/ccCancel.php?reason=user"
        timeoutDelay="20000" timeoutURL="http://www.mysite.com/ccCancel.php?reason=timout"
        visible="true" y="112" halign="left" />
</tns:vixml>