Overview
Audio capture API allows you to capture audio from the device's built in microphone or input source.
Enabling the API
There are two methods of enabling the AudioCapture API:
- Include all ebapi modules
- Include only the required API modules
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, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html
, copy the file to the same directory as that index.html
and add the following line to the HTML's HEAD section:
<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 required modules
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
- : 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
- : 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>