====== < audio > ======

===== Description =====

The <audio> element plays an audio file.  If the file cannot be played, the content of the <audio> element is played instead.  The alternate content may be text, speech markup, or another <audio> element.

===== Syntax =====

<code>
<audio
src="URI"
expr="ECMAScript_Expression"
fetchtimeout="time_interval"
fetchhint="prefetch" | "safe"
maxage="time_interval"
maxstale="time_interval">
alternate text
</audio>
</code>

===== Attributes =====

|src|Src is the URI of the audio file.  Either src or expr is required.|
|expr|Expr is an ECMAScript expression for the URI of the audio file.  If the src attribute is specified, it takes precedence over this attribute.  If <audio> contains this attribute that evaluates to null, this element will be skipped, including its alternate content.  Either src or expr is required.|
|fetchtimeout|This attribute indicates the time interval to wait for an audio file to be fetched before playing the alternate content. This is optional.|
|fetchhint|Fetchhint defines when the audio file should be retrieved. This is optional. \\ * prefetch - the file can be fetched when the document is loaded. \\ * safe - the file is fetched only when needed, never before prefetch. \\ * stream - allows audio streaming with HTTP.|
|maxage|This attribute indicates the maximum time in seconds that this document will use this audio file before fetching another copy. This is optional.|
|maxstale|This attribute indicates the maximum time in seconds that this document will use an audio file.|

===== Parents =====

<code>
<audio>, <block>, <catch>, <choice>, <enumerate>, <error>, <field>, <filled>, <if>, <initial>, <menu>, <noinput>, <nomatch>, <object>, <prompt>, <record>, <subdialog>, <transfer>
</code>

===== Children =====

<code>
<audio>, <value>, <enumerate>, Speech Markup (SSML)
</code>

===== Extensions =====

If "dial" is added as a URI prefix it will initiate DTMF generation.

Example:

<code>
<audio src="dial:123" /> or <audio expr="'dial:'+number" />
</code>

If the file is prefixed with “uri,” the Asterisk application will use this audio file base.  Audio files are stored in /var/lib/asterisk/sounds, and the filename is passed without this extension.

If the file has an extension of h263 or h264, a video clip is generated in the background during an audio-only prompt.  Note: the video will have no sound. (feature disabled for the moment)

Example:

<code>
<audio src="background.h263" />
</code>

If the file is a video clip with the 3gp or mp4 formats (see sip.fontventa.com), then the video clip will play on video phones.

Example:

<code>
<audio src="video.mp4" />
</code>

If the URI is prefixed also with “uri:rstp://…”, then the interpreter will plays the RTSP video stream.  Example: ''<audio src=__GESHI_QUOT__uri:rtsp:'' //''server.com/samples/video.mp4__GESHI_QUOT__ /> ''

If the property “control” is set to “true” (<property name=”control” value=”true”/>), the GSM and wav prompt can be controlled with VCR type controls like DTMF keys.  (See the control keys configured in the configuration file). Start position can be set adding “:” and the value of the offset. After the prompt the position can be get with the object “offset” (see the tag <object>).

Example:

<code>
<audio src="samples/video.wav:1235" />
</code>

If the URI is prefixed with “cli:”, then the interpreter will execute the command in the src/expr attribute (remember that this attribut don't support space, so replace them by underscore (“ “ → “_”). The Asterisk module disable the CLI execution by default. Enable it if needed by setting the parameter  cli in the general section to “yes”.

Example:

<code>
<audio src="cli:stop_now" />
</code>

If the URI is prefixed with “exec:”, “application:” or “app:”, then the interpreter will execute the application and the parameters specified in the src/expr attribute.

Example:

<code>
<audio src="application:saynumber(123)" />
</code>

If the URI is prefixed with “record:”, then the interpreter will try to find a file in the record directory. If you are using the mark option, the files will be separated by folders set with the 'mark' value.

Example:

<code>
<audio src="record:myrecord.wav" />
</code>

If the URI is prefixed with “uri:”, then the interpreter will try to find a file in the Asterisk audio base, this executes something like Playback(demo-echotest). The value after the prefix is the reference of a prerecorded audio file in the asterisk /var/lib/asterisk/sounds/. You can set or not the asterisk extension/format (.gsm or .wav for example).

<code>
<audio src="uri:demo-echotest" />
</code>

===== Limitations/Restrictions =====
<code>
None.
</code>

===== Example Code =====
<code>
<?xml version="1.0"?>
<vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
 <form>
  <block>
   <prompt>
    Playing the recorded message
   </prompt>
   <audio src="thankyou.wav">
    Reading this if thankyou.wav is not found
   </audio>
  </block>
 </form>
</vxml>
</code>