Overview

The Video object refers to video files that can be played back through an Output object. Videos are primarily aimed at mobile devices in a 3G network.
The Video object can refer to a single file only, or to a set of files that holddifferent variations of the video. In addition, a video generation engine can be referred to through a Video object, in order to embed dynamically rendered videos into an application.
The supported file formats depend on the underlying media platform that will do the final video processing, as well as the mobile device that plays back the video.

The Video object can only be used in the video channel.

The Object Definition below covers the configuration of the Video object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML refer to the VoiceObjectsXML Definition paragraph.

The Video object belongs to the object category Resources.

Dialog Flow Scenario

The following dialog flow demonstrates the use of video messages within a dating application. The Video object is linked in an Output object, together with an Audio object that represents a prompt that is played prior to the video:.

Object		Dialog Flow
		[ Okay, I found one matching candidate. Let's give her a chance to introduce herself. ]

 

i8  Note: Some media platforms do not allow to playback audio and video files in the same call and/or to use speech recognition in a video call. Some also restrict the number of video files per Output item to 1. For more information refer to the documentation of your platform.

Object Definition

The Definition of the Video object provides the following sections:

·          Video Resource
To specify an external video file.

·          Parameter Set
To specify an optional set of parameters to be passed to video generation engines.

·          Alternative Texts
To specify a text description of the video that will be shown in project documentation and the storyboard.

 

For information regarding additional object configuration refer to Precondition and Properties in this Object Reference.

Video Resource

The Video Resource section provides the following properties:

Property	Description
Location	Optional parameter to specify the location (using a Resource Locator object) of the video file to be used.
File	Defines the file name of the video file to be used. The name of the file can either be typed in or selected through a file browser by clicking the Browse button  to the right of the File field. The filename can also be provided dynamically during call time by assigning a Variable, Expression, Script, or Layer object. In Desktop for Web the Browse button  will only be displayed if the Resource Locator object is available and includes a physical path definition. Moreover the video file can be played by clicking the Play button  to the right of the File field. This will start the default media player associated with Internet Explorer and play the video file in this player. This button will only be displayed if the Resource Locator object is available and includes a URL definition without references to dynamic objects (Variable, Expression, Script, or Layer).
File prefix	Optionally specifies a prefix that is applied to the filename. Instead of providing a static value, the prefix can also be supplied by using a Variable, Expression, Script, or Layer object.
File suffix	Optionally specifies a suffix that is appended to the filename. Instead of providing a static value, the suffix can also be supplied by using a Variable, Expression, Script, or Layer object.
Random variations	Defines whether randomizing is enabled for the video file. To enable randomizing, set the Random variations property to a number between 2 and 99, by selecting an appropriate value from the drop-down list. If randomizing is enabled and different video files are provided with the specified filename extended by different numbers (e.g. teaser1.3gp, teaser2.3gp, teaser3.3gp), the server will randomly pick one of the available files with a random file extension between 1 and the selected number whenever the Video object is processed. The server ensures that all available video files are played before a repetition occurs. By default, the Random variations property is set to Disabled indicating that no randomization is used. For more information on randomization see the Output object in this Object Reference.
Video type	Sets the type of the video resource that is defined in the Video object. It can be one of Default, None, Video, and Video+Audio. Depending on the kind of content of the video file, you can set this to Video (meaning the file does not have any audio content) or Video+Audio (meaning the file holds video and audio information). This is a setting necessary for the media platform, which will be streaming the file to the caller's device. If you leave it at Default, the default setting from the Service object definition will be used. This makes sense if all of your files are of the same type (typically Video+Audio). You can optionally change the default setting at call time using the VIDEOTYPE function through an Expression object. Setting it to None means that no information on the content will be passed to the media platform. Instead of selecting one of the provided types from the drop-down list, the Video type can also be supplied by using a Variable, Expression, Script, or Layer object.
Extension	Specifies the video file extension. Instead of selecting one of the provided file extensions from the drop-down list, the extension can also be supplied by using a Variable, Expression, Script, or Layer object. If the filename already contains the extension, set this field to None. The complete filename for the video file is generated at call time according to the following formula: [prefix] + file + [suffix] + [random number] + [extension]

Parameter Set

The Parameter Set section is optional and relevant only for Video objects that refer to external video generation engines. Use it to define any number of parameters, all of which will be added to the final URL as CGI parameters, in order to control the engine if required.

 

This section provides the following properties:

Property	Description
Parameter	Specifies the value of the parameter. Possible parameter types are Variable, Collection, Expression, Layer, Resource Locator or Script objects, and constants. When using a Resource Locator object as a parameter, its URL definition is passed to the script. The field can be left empty to denote an empty value.
Alias	Optionally specifies the name of the parameter. If left empty, the reference ID of the object defined in the Parameter field will be used as the name. This means in particular that for constant values an alias needs to be defined (as they do not have a reference ID). Constant parameters without a defined alias are ignored.

If there is only one parameter (name + value) defined, it will get appended to the end of the full URL with the following syntax:

[Resource Locator] + [prefix] + file + [suffix] + [random number] + [extension] + “?name=value”

Example:

Suppose the file and extension are teaser.clip, the parameter name evaluates to bgimage and the value evaluates to background.gif. The resulting URL might look like this:

http://127.0.0.1:8081/VoiceObjects/Resources/teaser.clip?bgimage=background.gif

If more than one parameter is defined, they will be added like this:

[Resource Locator] + [prefix] + file + [suffix] + [random number] + [extension] + “?name1=value1&name2=value2&...”

Alternative Texts

The Alternative Texts section is mainly used to describe the content of the video file(s), typically a script of the audio part of the video. It will appear both in a storyboard export as well as project documentation. By default, it is not rendered into VoiceXML by the server, since none of the media platforms certified with VoiceObjects currently supports alternative text. Nonetheless, the <renderAltText> element in the MPDrivers.xml file can be set to true for a media platform to enable the rendering of alternative text.

 

The Alternative Text items specify the various texts for video variations, in case the Video object reflectsrepresents more than one file. The text entered into the Text field must not contain special characters such as quotation marks, apostrophes, ampersands, angle brackets etc. The alternative text can be typed in or can be set at call time by a Variable, Expression, Script, or Layer object.

In addition to the Text field, the following properties can be configured:

Property	Description
Label	Optional parameter to identify the alternative text item in a list.
Layer	Associates the alternative text item with a custom layer. This item is only eligible for playback if the layer evaluates to true at call time. If you reference Video objects in different Output items using different layer conditions, there is no need to also define the same layers in the Video object itself. If, on the other hand, different outputs are achieved by using a Layer (or Variable, Expression, Script) object within the resource locator definition of the Video object, you can define different alternative texts by associating items with the corresponding layer condition.
Language	Video objects can represent content in multiple languages through dynamic resource locators. The Language drop-down list allows you to specify a language for a video file, so that videos containing different languages can be incorporated into the Video object. When dealing with monolingual applications, this field can be ignored.
Input mode	Associates the alternative text item with a specific input mode. Leave this field at the default value if your application does not distinguish between voice and DTMF input in the wording of your application prompts. Otherwise, tag the item with the appropriate mode.
Variation	If randomizing is enabled, this field allows you to associate a text with a specific video variation number. If the Video object only refers to a single file, this can be left at the default value. Do not define multiple alternative text items with the same variation number (and the other settings being identical), as this may lead to unexpected behavior at call time. If you want to use the same alternative text for all randomized video files, you only need to define an alternative text for variation number 1.

VoiceObjectsXML Definition

The Video object is represented by the VoiceObjectsXML element <video>. It has seven attributes and one group of children.

In addition, the element has the standard attributes described in the XDK Guide.

The <video> element uses the embedded <altText> element.

Video

Attributes

·          location
Defines the location from where the video file is to be retrieved. Must be a reference to a Resource Locator object.

·          file
The file name of the video file, without extension. Can be a constant name, or a reference to a Variable, Expression, or Script object.

·          prefix
A prefix to be used together with the video file name.

·          suffix
A suffix to be used together with the video file name.

·          random
Indicates whether randomization should be used. Can be either disabled or an integer >= 2 specifying the number of variations in which the file is available. If not specified, defaults to disabled.
For details see Random variations above.

·          videoType
Specifies the type of video data to be played, which influences the MIME type with which the file is tagged. One of default, video, videoaudio, none. If not specified, defaults to default, which indicates that the default video type defined in the service is used.

·          videoFileExtension
Specifies the file extension for the video file as either a constant value or a reference to a Variable, Expression, or Script object. Legal constant values are none, 3g2, 3gp, avi, bmp, clip, gif, jpeg, jpg, m4v, mp4, mp4v, rtp. If not specified, defaults to 3gp.

The complete filename for the video file is generated at call time according to the following formula:

[prefix] + file + [suffix] + [random number] + [extension]

 

Children

·          <expression usage=”precondition”> or
<variable usage=”precondition”> or
<collection usage=”precondition”> or
<script usage=”precondition”>
Defines the precondition for the Video object.

·          ?<parameterSet>
Defines the parameter set.

·          *<altText>
Defines the corresponding alternative text(s).

 

Example

<video location=”#Video locator” file=”welcome” videoFileExtension=”3gp”/>

<video location=”#Video locator” file=”trailer” videoFileExtension=”mp4” random=”5”/>

ParameterSet

Children

·          +<item>
Defines the list of entries in the parameter set. The use of the alias attribute is optional when the object attribute is used, and required when the value attribute is used.

 

Example

<parameterSet>

  <item alias=”bgimage” object=”#BGImage”/>

  <item alias=”bgcolor” value=”blue”/>

</parameterSet>

Item

Attributes

·          object
Defines a reference to an object. If this attribute is defined, the value attribute must not be defined.

·          value
Defines a constant value. If this attribute is defined, the object attribute must not be defined.

·          alias
Defines the parameter alias.

 

Example

<item alias=”bgcolor” value=”blue”/>

AltText

The <altText> element defines the alternative texts to be used for the Video object. It may only occur embedded inside an <video> element.

The <altText> element has six attributes and contains text as a child.

 

Attributes

·          label
A text string providing a name for the alternative text.

·          random
Defines the variation (random index) to which this alternative text belongs. An integer >= 1. If not specified, defaults to 1.

·          language
Defines the language for which this alternative text is valid. Can be default or a valid language code (e.g. de-DE, en-US, etc.). If not specified, defaults to default.
Appendix A – Language Codes contains a list of all language codes available in VoiceObjects together with the respective language they represent.

·          inputMode
Defines the input mode for which this alternative text is valid. Can be default, voice, dtmf, or voicedtmf. If not specified, defaults to default.

·          layer
Defines the layer for the alternative text. Can either be a reference to a Collection, Expression, Script, or Variable object; or a layer state reference of the form “Layer=State” or “Layer!=State” where “State” is the label of a state for the layer “Layer”.

·          object
Optional reference to an Expression, Variable, or Script object that defines the alternative text.

 

Children

·          CDATA
The static alternative text itself. Note that the text may not contain special characters such as apostrophes, quotation marks, angle brackets etc.

 

Example

<altText language=”de-DE”>

  Bitte geben Sie Ihre Telefonnummer ein.

</altText>

 

<altText random=”1”> Sorry? </altText>

<altText random=”2”> Once more, please. </altText>

<altText random=”3”> I didn’t quite get that. </altText>

Object Interoperability

The following table contains all object types that can reference a Video object:

Icon	Object Name	Use Case Example
	Output	A Video object can be referenced within an autonomous or embedded Output object definition.
	List	A Video object can be referenced within the content formatting definition of a List object, to play back a video file as part of the List content.

Object Naming Conventions

In order to leverage the capabilities of the integrated documentation of VoiceObjects it is important to provide intuitive and self-explanatory object names and descriptions.

The name of a Video object should provide information about what is being played. The table below lists two examples:

Name	Description
Trailer	Plays a trailer for the motion picture.
Tutorial	Provides the caller with a tutorial on how to use the service.