AudioCapture

Enterprise Browser 2.5

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

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.

      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>