Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

AudioCapture Module

The AudioCapture Module captures audio files from the default microphone device.

Syntax

audioCapture (Module) <META> Syntax

<META HTTP-Equiv="AudioCapture" content="[method / parameter]">

<META HTTP-Equiv="AudioCapture" content="AudioSaveEvent:url('[jsFunction | url]')">
AudioCapture JavaScript Object Syntax:
By default the JavaScript Object 'audioCapture' will exist on the current page and can be used to interact directly with the audioCapture.
To Invoke audioCapture methods via JavaScript use the following syntax:
audiocapture.method();

e.g. audioCapture.start();
To Set audioCapture parameters via JavaScript use the following syntax:
audiocapture.parameter = 'value';
remembering to enclose your value in quotes where appropriate.

e.g. audioCapture.duration = 'value';
To Set audioCapture return events via JavaScript use the following syntax:
audiocapture.event = JavaScript Function;

e.g. audioCapture.audioSaveEvent = 'doFunction(%json)';

For more details on the event syntax and parameters see the Retrieval Events page.
To set multiple EMML parameters / events on a single line use the following syntax: audiocapture.setEMML("[Your EMML Tags]");

e.g. audioCapture.setEMML("duration:value;audioSaveEvent:url('JavaScript:doFunction(%json)');start");
AudioCapture Ruby Object Syntax:
By default the Ruby Object 'AudioCapture' will exist on the current page and can be used to interact directly with the AudioCapture. All Methods, Parameters and Events are the same as JavaScript, however, notice 'AudioCapture' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()'
To Invoke AudioCapture methods via Ruby use the following syntax: AudioCapture.method()

e.g. AudioCapture.start
To Set AudioCapture parameters via Ruby use the following syntax: AudioCapture.parameter = 'value' remembering to enclose your value in quotes where appropriate.

e.g. AudioCapture.duration = 'value'
To Set AudioCapture return events via Ruby use the following syntax: AudioCapture.event = url_for(:action => :event_callback)

e.g. AudioCapture.audioSaveEvent = url_for(:action => :audiocapture_event_callback)

For more details on the event syntax and parameters see the Retrieval Events page.

To access the event parameters in a Ruby callback function, you reference the @params object within the callback function. This object is simply a ruby hash {"parameter1 name" => "parameter1 value", "parameter2 name" => "parameter2 value", ...}

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description Default Value
start Starts capturing audio until either 'stop' is received, or 'duration' is reached (i.e. until the buffer is full). N/A
stop Stops capturing audio and either saves the file locally, or transfers it to a remote server N/A
cancel Stops capturing audio and discards any captured audio data N/A

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Name Possible Values Description Default Value
duration:[Value] Milliseconds Specifies the number of milliseconds of audio to capture, defining the size of the capture buffer. This is also the maximum number of milliseconds of audio to capture when the 'start' method is called if not interrupted with the 'stop' method. The duration cannot be set to less than 1000 milliseconds, if a value of less than 1000 milliseconds is specified, the interval will be defaulted to 20000 milliseconds. 20000
destination:[Value] Fully qualified URL or file name. Supports HTTP, FTP and File protocols. Sets the destination path and name for the captured WAV file. See Remarks N/A
username:[Value] String The username for the HTTP or FTP server if required No username
password:[Value] String The password for the HTTP or FTP server if required No password
name:[Value] String compliant with Windows Naming restrictions When the audio capture completes a file is saved in the root directory of the device (package directory in case of Android). This parameter is used to specify the filename when storing the file locally. AudioCapture
codec:[Value] "AAC", "AMR_NB" or "AMR_WB" The Audio Encoder can be specified through this attribute. Note This is only on Android "AAC"

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.

audioSaveEvent

The Audio Save Event is called when the captured audio has been successfully transfered to the specified destination. When a capture is started with the HTTP protocol, the destination server message is returned. When it is called with the FTP protocol, either ‘OK: File Sent’, ‘OK: File Received’ or ‘ERROR’ is returned. This tag should be used in conjunction with the Start method.

ID Name Description
1 transferResult Success or failure of transfer, see note above.

Multi Instance

When multiple RhoElememts applications are running the following considerations should be made: Only the foreground RhoElements application is given access to capture audio, when an application is sent to the background any capture that is in progress will be canceled and it will automatically relinquish control of the Audio hardware. When brought back to the foreground, an application previously using the audio capture will have its previous configuration (eg. name etc.) reapplied to the plug-in automatically. Please note that any file transfer that is in progress continues even if the application is sent to the background.

Remarks

Rhodes Applications

If your application is a ‘Rhodes’ application then AudioCapture will create a WAV format file with 22050 Hz 16 bit MONO. The destination property only supports a local path. The Code and Username/Password properties are not used. If your application is ‘rhoelements’ type application, then AudioCapture is automatically added to the application. If your application is built for Android and your application is ‘rhoelements’ type and you do not setup ‘non_motorola_device’ capability, then the AudioCapture native extension is removed from the application automatically because in this case, the application already has Zebra rhoelements extension with implementation of the same AudioCapture API.

Buffer full

Once duration has been reached the audio file will be saved or transferred. Calling ‘stop’ once this has occurred will have no effect.

Audio Encoder

Not all the audio encoders are supported on all the platforms. The encoders AAC, AMR_NB and AMR_WB are supported only on Android and the encoder WAV is supported only on Windows. The output file format for AMR_NB and AMR_WB encoders is 3GPP and for AAC encoder is MP4.

File Storage Error

An Audio Capture will fail if there is not sufficient space on the device’s file system to store it.

Setting up a Transfer to a remote HTTP or FTP location

Audio Capture is designed to be configured before any transfer is made to a remote location. If the ‘Destination’ parameter is specified as either HTTP or an FTP location the ‘destination’ / ‘username’ / ‘password’ parameters can not be guaranteed to stay the same after the capture has completed, therefore configure your destination for each capture.

Format of the Destination URL

The protocol, port number, username (optional) and password (optional) are all derived from the URL string and should be specified in the following manner: [protocol]://[username]:[password@]Server[:Port]FileNameAndPath. FTP Example: ftp://admin:root@192.168.1.1:2500/Folder/Cap.wav. HTTP Example: http://admin:root@192.168.1.1:8080/Folder/Upload.aspx. File Example: file://\path\Cap.wav. Remember to also wrap your URL with url(‘’) when being used as part of a meta tag, as shown in the examples above.

Requirements

RhoElements Version 2.2 or above
Supported Devices All devices
Minimum Requirements Microphone
Persistence Not Persistent - Changes to this module will not persist when navigating to a new page.

HTML/JavaScript Examples

The following META Tag example performs a 30 second capture. The resulting audio file will be transferred to a server via HTTP and an alert will inform the user whether or not the transfer succeeded.

<META HTTP-Equiv="AudioCapture" Content="duration:30000">
<META HTTP-Equiv="AudioCapture" Content="Destination:url('HTTP://192.168.1.1:80/Uploaded/upload.aspx')">
<META HTTP-Equiv="AudioCapture" Content="AudioSaveEvent:url('javascript:alert('%s');')">
<META HTTP-Equiv="AudioCapture" Content="start">

The following JavaScript will start and stop an audio capture respectively when onStart and onStop are called with a 60 second limit:

<script>
  function onStart()
  {
    audioCapture.duration = '60000';
    audioCapture.start();
  }

  function onStop()
  {
    audioCapture.stop();
  }
</script>

The following JavaScript will start a 30 second audio capture when onStart is called:

<script>
  function onStart()
  {
    audioCapture.duration = '30000';
    audioCapture.start();
  }
</script>
Back to Top