AudioCapture Module - Zebra Technologies TechDocs

Overview

AudioCapture API permits the capture of audio from a built-in microphone or input source on the device.

Enabling the API

There are two methods of enabling the AudioCapture API:

Include all ebapi modules or
Include only the API modules you need

For either of these methods, you'll need to include files from the /Enterprise Browser/JavaScript Files/Enterprise Browser directory on the computer that you installed the Enterprise Browser.

Include all JS API modules

To include all JS APIs, you must copy the ebapi-modules.js file to a location accessible by your app's files and include the JavaScript file in your app. For instance, to include the modules file in your index.html, with the file in the same directory as your index.html, you would add the following line to the section of your index.html:


<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

Note: that the pathing for this file is relative to the current page.

This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.

Include only the modules you need

To include single APIs, you must first include the ebapi.js in your HTML as well as the API file you want to use. For instance, to use the AudioCapture API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.


<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.audiocapture.js"></script>

The ebapi.js file is necessary for all single API inclusions.

Methods

cancel()

Cancel audio recording. During recording if 'cancel' method is called, the status of recording will be 'cancel' in the callback returning parameter of 'start' method. No file is saved. In android, it will delete the file if it exists.

Parameters

callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.cancel()
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.cancel()

getAllProperties()

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

: STRING

Returns

Synchronous Return:

HASH : Map of all available properties
- : STRING

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getAllProperties()
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.getAllProperties()

getDefault()

This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.

Parameters

callback : CallBackHandler

Callback

Async Callback Returning Parameters: SELF_INSTANCE

Returns

Synchronous Return:

SELF_INSTANCE : Default object of Module.

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.AudioCapture.getDefault()

getProperties(ARRAY arrayofNames)

This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

Parameters

arrayofNames : ARRAY
List of properties I want to know about

Object : STRING

callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

: STRING

Returns

Synchronous Return:

HASH : Map of properties I want to know about
- : STRING

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getProperties(ARRAY arrayofNames)
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.getProperties(ARRAY arrayofNames)

getProperty(STRING propertyName)

This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

Parameters

propertyName : STRING
The property to return info about.
callback : CallBackHandler

Callback

Async Callback Returning Parameters: STRING

Returns

Synchronous Return:

STRING : The property to return info about.

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.getProperty(STRING propertyName)
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.getProperty(STRING propertyName)

setDefault(SELF_INSTANCE: EB.AudioCapture defaultInstance)

This method allows you to set the attributes of the default object instance by passing in an object of the same class.

Parameters

defaultInstance : SELF_INSTANCE: EB.AudioCapture
An instance object that is of the same class.
callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Class Method: This method can only be accessed via the API class object.
- EB.AudioCapture.setDefault(SELF_INSTANCE: EB.AudioCapture defaultInstance)

setProperties(HASH propertyMap)

This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

Parameters

propertyMap : HASH
Map of properties I want to set

Object : STRING

callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.setProperties(HASH propertyMap)
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.setProperties(HASH propertyMap)

setProperty(STRING propertyName, STRING propertyValue)

This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

Parameters

propertyName : STRING
The one property name that I want to set
propertyValue : STRING
The one property value that I want to set
callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.setProperty(STRING propertyName, STRING propertyValue)
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.setProperty(STRING propertyName, STRING propertyValue)

start(HASH props)

Starts capturing audio until either 'stop' is received, or 'maxDuration' is reached. The successful recording will set 'ok' as the status. An unsuccessful recording will set 'cancel' or 'error' as the status in the callback returning parameters. If 'cancel' method is called during recording, 'cancel' status will be set in the callback returning parameters. In order to restart the audio capture, if the audio capturing is already in process, it is mandatory to call 'stop' or 'cancel' method before calling 'start' method again.

Parameters

props : HASH
Map of Audio Capture properties to be set. Valid `properties` for this parameter are the properties available to this API module. Check the property section for applicable properties.
callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

status : STRING
Whether or not the audio recording was successfully captured, status will be 'ok' or 'cancel' or 'error'.
message : STRING
If 'status' == 'error', then message contains error message. In all other cases, it will remain empty.
fileName : STRING
If 'status' == 'ok', then contain full file path with the file name of recorded audiofile. In all other cases, it will remain empty.

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.start(HASH props)
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.start(HASH props)

stop()

Stop audio recording. During recording if 'stop' method is called, the status of recording will be 'ok' in the callback returning parameter of 'start' method. The file is saved in user provided location.

Parameters

callback : CallBackHandler

Returns

Synchronous Return:

Void

Platforms

Android
Windows Mobile
Windows CE

Method Access:

Instance Method: This method can be accessed via an instance object of this class:
- myObject.stop()
Default Instance: This method can be accessed via the default instance object of this class.
- EB.AudioCapture.stop()

Properties

encoder

Type

STRING

Description

Encoder to compress recorded audio. In Android devices, the supported encoder type is dependent upon device hardware and vendor.

Values

Possible Values (STRING):

Constant: EB.AudioCapture.ENCODER_AAC - String: AAC AAC low complexity. This is the default value. If wrong or no value is specified this value will be accounted.
Constant: EB.AudioCapture.ENCODER_AMR_NB - String: AMR_NB AMR narrow-band.
Constant: EB.AudioCapture.ENCODER_AMR_WB - String: AMR_WB AMR wide-band.

Access

Instance: This property can be accessed via an instance object of this class: myObject.encoder
Default Instance: This property can be accessed via the default instance object of this class.
- EB.AudioCapture.encoder

Platforms

Android

fileName

Type

STRING

Description

(Required) This parameter is used to specify the file name. The file name should be set at least once before calling 'start' method, otherwise the 'start' method will update the callback 'status' as 'error'.

Access

Instance: This property can be accessed via an instance object of this class: myObject.fileName
Default Instance: This property can be accessed via the default instance object of this class.
- EB.AudioCapture.fileName

Platforms

Android
Windows Mobile
Windows CE

maxDuration

Type

INTEGER

Description

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. The default value is 20,000 milliseconds.

Params

Default: 20000

Access

Instance: This property can be accessed via an instance object of this class: myObject.maxDuration
Default Instance: This property can be accessed via the default instance object of this class.
- EB.AudioCapture.maxDuration

Platforms

Android
Windows Mobile
Windows CE

Remarks

File Name

In Windows, to store the file in a particular location, specify the path with the file name. Mentioning the extension name with the file name is optional. Only *.wav files are supported. If the path is not specified with the file name, the captured file is stored in the root directory of the device. In Windows and Android, if the folder is not present, it should be created manually for storing the file in that location. In Android, the file extension depends on encoder value. If it is AAC, the extension should be '.mp4'. In all other cases, it is of '.3gpp'. If only filename is specified, it will be saved in the root directory of external storage.

Audio Capture

In Windows & Android, Audio capture will not be started, if the file name is set to null. File will not be saved for invaild file name. It will return error in the callback returning parameters with the valid reason.

Restarting of Audio Capture

Audio recording will not be restarted, if the audio recording is already in process. In order to restart the audio capture, stop or cancel method need to be invoked before invoking start method.

Page Refresh

If the page is to be refreshed, the audio recording should be canceled. In Android, the state will be persisted.

Page Navigation

Upon page navigation, the audio recording should be canceled.

Duration And File Name Settings

The default values will be applied for duration if no values are provided by the user. If values are provided then it will apply the user provided values. Later if values are not provided then it will apply the last provided values for the same. The settings for duration and file name will not be applied if the audio capture is already started and in progress. In android, there might be slight omit of recording data initially.

Get Property Or Get Properties

In Windows, 'getProperty' or 'getProperties' for fileName will return the complete path along with the extension name. For example: If file name was set to '\Application\AudioCapture', then 'getProperty' or 'getProperties' will return '\Application\AudioCapture.wav'. If file name was set to 'AudioCapture', then 'getProperty' or 'getProperties' will return '\AudioCapture.wav'. In Android, the fileName will return whatever is set with or without extension.

General

On Quitting of the Application, Android will save the data in the file and gracefully exit. In Android, during suspend/resume or screen timeout the audio will keep on recording.

SDCard Access

Extensions which came from RhoElements (i.e. AudioCapture) that could possibly write files to external storage will require "write SD card" permissions as part of the extension's AndroidManifest. You cannot remove the ability to write to the SD card as it would cause the extension to malfunction. Therefore, the capability has already been granted on build, and any capability added by you will be ignored. This being the case, the following extensions will always be able to write to the SD card by default.

Examples

Capturing and Playing Audio

This example will show how to capture audio from your device to a file and then play that audio file. Note that this example assumes that your ebapi-modules.js file is located in the same folder as the HTML that is evoking it.


<head>
    <script src="http://192.168.1.28:8080/target/target-script-min.js#anonymous"></script>
    <script type="text/javascript" charset="utf-8" src="../apis/EnterpriseBrowser/ebapi-modules.js"></script>

    <title>Audio Capture API Example</title>

    <script>
        audioFile = null;

        function captureAudio(){
            display.innerHTML = 'Capturing...'
            EB.AudioCapture.start({fileName:   'testCap',
                                                         maxDuration: 5000}, captureCallback);
        }

        function captureCallback(params){
            if (params['status'] == 'ok'){
                display.innerHTML = 'Captured Audio File: ' + params['fileName'];
                audioFile = params['fileName'];
                audioFile = audioFile.substr(7); // Remove 'file://' from the beginning of the fileName
            }
            else{
                display.innerHTML = 'Audio Not Captured';
            }
        }

        function playCapturedAudio(){
            if(audioFile){
                EB.Mediaplayer.start(audioFile);
            }
            else{
                alert("No audio captured yet.");
            }
        }

    </script>
</head>
<body>
    <h1>AudioCapture API Example</h1>
    <div id="display"></div>
    </br>
    </br>
    <button onclick="captureAudio()">Capture Audio</button>
    <button onclick="playCapturedAudio()">Play Captured Audio</button>
</body>