record element
Last Updated: 08-17-2005
VoiceXML 2.0
Records user input.

Syntax

<record
beep = "boolean"
cond = "ECMAScript_Expression"
dtmfterm = "boolean"
expr = "ECMAScript_Expression"
finalsilence = "string"
maxtime = "string"
maxtimeexpr = "ECMAScript_Expression"
modal = "boolean"
name = "string"
type = "string"
/>

Attributes
beep
One of the following values:
false No beep is played before recording begins.
true A beep is played before recording begins.
cond
A condition that must evaluate to true for the element to be selected by the form interpretation algorithm (FIA). If this condition evaluates to false or the variable associated with the name attribute has a defined value, the element is not visited.
dtmfterm
One of the following values:
false DTMF input from the user is ignored.
true The recording is terminated when the user presses a key.
expr
An ECMAScript expression that supplies the initial value for the form item variable associated with this element. If the expression evaluates to something other than null or ECMAScript undefined, the element will not be visited until the form item variable is explicitly cleared.
finalsilence
The interval of silence that indicates the end of speech in seconds (s) and milliseconds (ms). The default value is 2s.
maxtime
The maximum recording time in seconds (s) or milliseconds (ms). The maximum limit is 1800 seconds (30 minutes). The default value is 1800s.
maxtimeexpr
An ECMAScript expression evaluated at runtime to be used instead of the maxtime attribute.
modal
One of the following values:
false Enables speech and DTMF grammars scoped to the form, document, and application during recording.
true Disables higher level speech and DTMF grammars during recording.
name
The name of the variable that stores a reference to the recorded data. If the attribute is not specified, the interpreter creates a hidden, anonymous variable to store the result.
type
The MIME format of the user recording. If the type attribute specifies anything other than "audio/wav" or "audio/x-wav", the interpreter throws error.unsupported.format.

Shadow variables

The record element exposes the following shadow variables.

name$.termchar
The key pressed by the user, if any, to stop recording. The dtmfterm attribute must be set to true. The value is null if dtmfterm is set to false or finalsilence elapses before the user presses a key.
name$.duration
The length of the recording in milliseconds.
name$.size
The size of the recording in bytes.
name$.maxtime
True if the record element specifies a maxtime or maxtimeexpr attribute value and the specified interval is exceeded before recording ends, false otherwise.
Parents
form

Children
audio, catch, enumerate, error, filled, grammar, help, noinput, nomatch, prompt, property, value

Remarks
The maxtime and maxtimeexpr attributes are mutually exclusive.
You can play the recorded audio by setting the value of the expr attribute of the audio element to the value of the name attribute of the record element.
The variable stores a reference to the recording within the scope of the dialog that contains the record element. Although you can assign a reference to the recording to an ECMAScript variable for the purposes of sharing the recording between scopes, in order to post the audio to a Web server, you must first assign the recording to a record element. Include the record element's name in the namelist of a submit, subdialog, or data element. Set the method attribute to "post", and set the enctype attribute to "multipart/form-data."
If the user disconnects before properly terminating the recording, the recording is lost.
The recording created by the record element contains a Resource Interchange File Format (RIFF) header.
The Tellme VoiceXML interpreter only supports DTMF bargein when executing the record element. To achieve functionality similar to record that allows speech bargein, use a field element in conjunction with the recordutterance property.
Prior to revision 3, the maxtime shadow variable is not defined and the dtmfterm attribute default value is false.
Examples

The following example asks the user to record a personal greeting for a fictitious voice message system. The recording is played back to the user, and, if the user consents, the recording is submitted to a server-side script (via a subdialog) where it is further processed and saved to disk. To use this sample, make sure the server-side script has permissions to write the recorded audio to your Web server's hard disk.

<?xml version="1.0"?>
<vxml version="2.1"
 xmlns="http://www.w3.org/2001/vxml">
   <!-- fictitious user id. this should be established 
       through a sign in module --> 
   <var name="uid" expr="'12345'"/>

   <form id="record_greeting">
      <!-- the resulting recording is stored in the variable personal_greeting
        the content cannot be copied into another variable. you may only
        submit it to the server via the named variable -->
      <record name="personal_greeting" 
            maxtime="60s" dtmfterm="true" beep="true">
         <prompt>
            At the tone, please record your personal greeting. 
            When you're done, press pound.
         </prompt>

         <!-- if the user doesn't say anything 
            within finalsilence, catch the noinput -->
         <noinput>
         Sorry. I didn't hear you. Now returning to the main menu.
         <exit />
         </noinput>

         <filled>
             <!-- demo record shadow variables -->
             <log>recording size = 
                   <value expr="personal_greeting$.size"/> bytes.</log>
             <log>recording duration = 
                   <value expr="personal_greeting$.duration"/> milliseconds.</log>
             <log>dtmf key = <value expr="(personal_greeting$.termchar 
                   ? personal_greeting$.termchar : 'none')"/></log>
             <log>maxtime = 
                   <value expr="personal_greeting$.maxtime"/>.</log>
         </filled>
      </record>

   <!-- confirm that we should commit the new recording -->
      <field name="conf">
         <prompt>
            Here's what callers will hear.
            <break size="small"/>
            <audio expr="personal_greeting"/>
            If you are happy with this greeting, say yes.
            If you would like to re-record your greeting say no.
            Otherwise, say cancel.
         </prompt>

         
         <grammar mode="voice"
         root="root_rule"
         tag-format="semantics/1.0"
         type="application/srgs+xml"
         version="1.0"
         xml:lang="en-US">
                  <rule id="root_rule" scope="public">
                           <one-of>
                                    <item>
                                             <one-of>
                                                      <item>
                                                               yes
                                                      </item>
                                                      <item>
                                                               ok
                                                      </item>
                                                      <item>
                                                               yeah
                                                      </item>
                                             </one-of>
                                             <tag>out.conf = "yes";</tag>
                                    </item>
                                    <item>
                                             <one-of>
                                                      <item>
                                                               no
                                                      </item>
                                                      <item>
                                                               nope
                                                      </item>
                                             </one-of>
                                             <tag>out.conf = "no";</tag>
                                    </item>
                                    <item>
                                             <one-of>
                                                      <item>
                                                               cancel
                                                      </item>
                                             </one-of>
                                             <tag>out.conf = "cancel";</tag>
                                    </item>
                           </one-of>
                  </rule>

         </grammar>

         
         <catch event="noinput">
            Recording canceled. 
            Now returning you to the main menu.
            <exit />
         </catch>

         <catch event="nomatch">
            Please say yes to establish the new greeting, 
            say no to re-record, or say cancel to quit.
         </catch>

         <filled>
            <if cond="'no' == conf">
               <clear namelist="personal_greeting conf"/>
               <goto next="#record_greeting"/>
            <elseif cond="'cancel' == conf"/>
               <exit />
            <else/>
               saving your personal greeting
            </if>
         </filled>
      </field>

      <!-- submit the data to the fictitious voice mail server -->
      <subdialog name="oResult" src="http://www.telco.com/greetings/upload.cgi" 
         namelist="personal_greeting uid" method="post">
         <filled>
         <if cond="oResult.code">
           Greeting saved
         <else/>
           Error saving greeting
           <log><value expr="oResult.msg"/></log>
         </if>
         </filled>
      </subdialog>
      
      <!-- FOR TESTING: play the greeting on the server -->
      <block>
         <audio expr="uid + '.wav'">your greeting</audio>
      </block>
      
   </form>
</vxml>

The following PERL CGI script accepts recorded audio data, writes it to a file on the HTTP server, and returns a VoiceXML document. The VoiceXML document consists of a subdialog that returns a status code and a message indicating success or failure.

#!/usr/local/bin/perl -w

# Need CGI.pm module.
# See http://stein.cshl.org/WWW/software/CGI/cgi_docs.html for usage.

use strict; 
use CGI::Carp qw(fatalsToBrowser); 
use CGI qw(:standard :html3); 

my $oReq = new CGI();

print "Content-Type: text/xml\n\n"; 

my $bSuccess = 1;
my $msg = "";

# grab recording from "personal_greeting" param. 
my $recording = $oReq->param("personal_greeting");  
# grab user id from uid param.
my $uid = $oReq->param("uid");  

# save recording to file named after user's id
my $outPath = "$uid.wav";
$! = 0; # clear i/o errs
open(OUT, ">$outPath");
if ($! != 0)
{
   $bSuccess = 0;
   $msg = $!;
}
else
{
   while (<$recording>) 
   { 
      print OUT $_; 
   } 
   close(OUT); 
}

WriteSubdialog($bSuccess, $msg);

# write back to the VoiceXML interpreter
sub WriteSubdialog
{
   my ($code, $msg) = @_;
   
print <<EOF;
<vxml version="2.0">
   <var name="code" expr="$code"/>
   <var name="msg" expr="'$msg'"/>
   <form>
      <block>
         <return namelist="code msg"/>
      </block>
   </form>
</vxml>
EOF
}

The following PHP script accepts recorded audio data, writes it to a file on the HTTP server, and returns a VoiceXML document. The VoiceXML document consists of a subdialog that returns a status code and a message indicating success or failure.

<!-- Contributed by Scott Schreckengaust -->
<?php
$msg = "";
$code = 1;
$tmpFile=$HTTP_POST_FILES['personal_greeting']['tmp_name'];
if (is_uploaded_file($tmpFile)) 
{
  $wavfile="wav/".date("YmdHis").".wav";
  copy($tmpFile, sprintf("%s",$wavfile));
  $msg = "audio saved";
} 
else 
{
  $code = 0;
  $msg = "unable to save audio";
}

echo "<vxml version="2.0">";
echo "<form>";
echo "<var name=\"code\" expr=\".$code\"/>";
echo "<var name=\"msg\" expr=\"'.$msg'\"/>";
echo "<block>";
echo "<return namelist=\"code msg\"/>";
echo "</block></form></vxml>";
?>

The following Java Server Page (JSP) accepts recorded audio data, writes it to a file on the HTTP server, and returns a VoiceXML document. The VoiceXML document consists of a subdialog that returns a status code and a message indicating success or failure.

// Processing multi-part/form-data with JSP 
// Contributed by Jon Baer 
// You'll need the following servlet class: 
// http://www.servlets.com/cos/javadoc/com/oreilly/servlet/MultipartRequest.html 
 
import javax.servlet.*; 
import javax.servlet.http.*; 
import java.io.*; 
 
public class UploadServlet extends HttpServlet { 

   public void doPost(HttpServletRequest req, HttpServletResponse res) 
      throws ServletException, IOException 
   { 
      // Get output stream. 
      ServletOutputStream out = res.getOutputStream(); 
   
      MultipartRequest multi = new MultipartRequest(req, "/home/server/recordings/"); 

      // Send a response back to VXML client. 
      res.setContentType("text/xml"); 
      out.println("<?xml version=\"1.0\"?>"); 
      out.println("<vxml version=\"2.0\"><form><block>");
      out.println("<var name=\"code\" expr=\"1\"/>");
      out.println("<var name=\"msg\" expr=\"'audio uploaded'\"/>");
      out.println("<return namelist=\"code msg\" /></block></form></vxml>"); 
      out.flush(); 
      out.close(); 
   }
}

The following Microsoft Active Server Page (ASP) uses a third-party component to accept recorded audio data, writes it to a file on the HTTP server, and returns a VoiceXML document. The VoiceXML document consists of a subdialog that returns a status code and a message indicating success or failure.

<% @LANGUAGE="JScript" %>
<!--
   Software Artisan has an ASP component called 
   SA-FileUp v.3.17, written specifically to handle 
   multipart/form-data. You can get an evaluation copy at 
   http://www.softwareartisans.com/softartisans/saf.html. Developers
   who decide to use this component can use the following 
   ASP script to handle posted <record> data: 
--> 
<% 
   var oUpload = Server.CreateObject("SoftArtisans.FileUp");
   oUpload.SaveAs("C:\temp\upload.wav");
%>
<vxml version="2.0">
   <var name="code" expr="1"/>
   <var name="msg" expr="'Total Bytes Written: <% =oUpload.TotalBytes %>'"/>
   <form>
      <block>
         <return namelist="code msg"/>
      </block>
   </form>
</vxml>


The following Cold Fusion (CFM) script accepts recorded audio data, writes it to a file on the HTTP server, and returns a VoiceXML document. The VoiceXML document consists of a subdialog that returns a status code and a message indicating success or failure.

<CFFILE ACTION = "Upload"
 FILEFIELD = "personal_greeting"
 DESTINATION = "C:\temp\"
 NAMECONFLICT = "OVERWRITE">
<vxml version="2.0">
   <var name="code" expr="1"/>
   <var name="msg" expr="'audio saved'"/>
   <form>
      <block>
         <return namelist="code msg"/>
      </block>
   </form>
</vxml>


See Also
tellme.field.recordutterance
[24]7 Inc.| Terms of Service| Privacy Policy| General Disclaimers