Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

AudioCapture

Methods10
Methods - Class
getDefaultsetDefault
Methods - Instance
cancelgetAllPropertiesgetPropertiesgetPropertysetPropertiessetPropertystartstop
Properties3
Instance Properties
encoderfileNamemaxDuration
Examples2
Starting, Stopping And Canceling Audio CaptureSetting And Getting File Name
Remarks9
File NameAudio CaptureRestarting of Audio CapturePage RefreshPage NavigationDuration And File Name SettingsGet Property Or Get PropertiesGeneralSDCard Access

Audio capture API allows you to capture audio from the device’s built in microphone or input source.

Enabling the API

In order to use this API you must include the following extension in your build.yml

extensions: ["audiocapture"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

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.

Synchronous Return:

  • Void

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.
    • JavaScript: Rho.AudioCapture.cancel()
    • Ruby: Rho::AudioCapture.cancel()
getAllProperties
(CallBackHandler callback)

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

Parameters

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of all available properties

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getAllProperties(CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.AudioCapture.getAllProperties(CallBackHandler callback)
    • Ruby: Rho::AudioCapture.getAllProperties(CallBackHandler callback)
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.

Synchronous Return:

  • SELF_INSTANCE :

    Default object of Module.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.AudioCapture.getDefault()
    • Ruby: Rho::AudioCapture.getDefault()
getProperties
(ARRAY arrayofNames, CallBackHandler callback)

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 Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of properties I want to know about

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.AudioCapture.getProperties(ARRAY arrayofNames, CallBackHandler callback)
    • Ruby: Rho::AudioCapture.getProperties(ARRAY arrayofNames, CallBackHandler callback)
getProperty
(STRING propertyName, CallBackHandler callback)

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 Optional

Async Callback Returning Parameters: STRING

    Synchronous Return:

    • STRING :

      The property to return info about.

      : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.getProperty(STRING propertyName, CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.AudioCapture.getProperty(STRING propertyName, CallBackHandler callback)
      • Ruby: Rho::AudioCapture.getProperty(STRING propertyName, CallBackHandler callback)
    setDefault
    (SELF_INSTANCE: Rho::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: Rho::AudioCapture

      An instance object that is of the same class.

    Synchronous Return:

    • Void

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.AudioCapture.setDefault(SELF_INSTANCE: Rho::AudioCapture defaultInstance)
      • Ruby: Rho::AudioCapture.setDefault(SELF_INSTANCE: Rho::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

    Synchronous Return:

    • Void

    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.
      • JavaScript: Rho.AudioCapture.setProperties(HASH propertyMap)
      • Ruby: Rho::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

    Synchronous Return:

    • Void

    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.
      • JavaScript: Rho.AudioCapture.setProperty(STRING propertyName, STRING propertyValue)
      • Ruby: Rho::AudioCapture.setProperty(STRING propertyName, STRING propertyValue)
    start
    (HASH props, CallBackHandler callback)

    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. For iOS 22kHz 16bit Mono WAV file will be created. In Android, ruby callbacks are taking 20secs to fire.

      Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section
    • callback : CallBackHandler Mandatory

    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.

    Synchronous Return:

    • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.start(HASH props, CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.AudioCapture.start(HASH props, CallBackHandler callback)
      • Ruby: Rho::AudioCapture.start(HASH props, CallBackHandler callback)
    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.

    Synchronous Return:

    • Void

    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.
      • JavaScript: Rho.AudioCapture.stop()
      • Ruby: Rho::AudioCapture.stop()

    Properties

    encoder
    : STRING

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

    Possible Values (STRING):

    Constant: Rho.AudioCapture.ENCODER_AAC (For Ruby use "::" for all "." when referencing constants)
    String: AAC

    AAC low complexity. This is the default value. If wrong or no value is specified this value will be accounted.

    Constant: Rho.AudioCapture.ENCODER_AMR_NB (For Ruby use "::" for all "." when referencing constants)
    String: AMR_NB

    AMR narrow-band.

    Constant: Rho.AudioCapture.ENCODER_AMR_WB (For Ruby use "::" for all "." when referencing constants)
    String: AMR_WB

    AMR wide-band.

    Property 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.
      • JavaScript: Rho.AudioCapture.encoder
      • Ruby: Rho::AudioCapture.encoder
    fileName
    : STRING

    (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’.

    Property 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.
      • JavaScript: Rho.AudioCapture.fileName
      • Ruby: Rho::AudioCapture.fileName
    maxDuration
    : INTEGER

    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.

    Default: 20000

    Property 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.
      • JavaScript: Rho.AudioCapture.maxDuration
      • Ruby: Rho::AudioCapture.maxDuration

    Examples

    Starting, Stopping And Canceling Audio Capture

    Starting, Stopping and Canceling audio capture is same across all platforms.

    // Starting Audio Capture without settings. Callback is mandatory. Setting the file name at least once is also mandatory before invoking 'start' method.
Rho.AudioCapture.start({},mycallback);

// Starting Audio Capture with settings. Callback is mandatory.
// On successful recording the hash property  for fileName' in callback will return the complete file path with the filename.
// In Windows, for the below settings, it will return "file://\AudioCapture.wav".
Rho.AudioCapture.start({'fileName':"AudioCapture",'maxDuration':'15000'},mycallback);

// Stopping Audio Capture
Rho.AudioCapture.stop();

// Cancelling Audio Capture
Rho.AudioCapture.cancel();

                                
    #Starting Audio Capture without settings. Callback is mandatory. Setting the file name at least once is also mandatory before invoking 'start' method.
Rho::AudioCapture.start({},mycallback);

#Starting Audio Capture with settings. Callback is mandatory.
#On successful recording the hash property  for fileName' in callback will return the complete file path with the filename.
#In Windows, for the below settings, it will return "file://\AudioCapture.wav".
Rho::AudioCapture.start({'fileName'=>"AudioCapture",'maxDuration'=>'15000'},mycallback);

#Stopping Audio Capture
Rho::AudioCapture.stop();

#Cancelling Audio Capture
Rho::AudioCapture.cancel();
    Setting And Getting File Name

    In WM/WinCE, one can set the fileName with or without extensions. On retrieving, the fileName property will return the complete path with the extension name.

    // Setting fileName without extension
Rho.AudioCapture.fileName = "\\Application\\Audio1";

// The returned value is "\Application\Audio1.wav"
alert(Rho.AudioCapture.fileName);

// Setting fileName with extension
Rho.AudioCapture.fileName = "Audio2.wav";

// The returned value is "\Audio2.wav"
alert(Rho.AudioCapture.fileName);

                                
    #Setting fileName without extension
Rho::AudioCapture.fileName = "\\Application\\Audio1";

#The returned value is "\Application\Audio1.wav"
Alert.show_popup(Rho::AudioCapture.fileName);

#Setting fileName with extension
Rho::AudioCapture.fileName = "Audio2.wav";

#The returned value is "\Audio2.wav"
Alert.show_popup(Rho::AudioCapture.fileName);

    In Android, one can set the fileName with or without extensions. The extension depends on encoder. The directory should be present.

    // Setting fileName without extension
Rho.AudioCapture.fileName = "/sdcard/Audio/sample";

// The returned value is "/sdcard/Audio/sample";
alert(Rho.AudioCapture.fileName);

// Setting fileName with extension
Rho.AudioCapture.fileName = "/sdcard/Audio/sample.mp4";

// The returned value is "/sdcard/Audio/sample.mp4";
alert(Rho.AudioCapture.fileName);

                                
    #Setting fileName without extension
Rho::AudioCapture.fileName = "/sdcard/Audio/sample";

#The returned value is "/sdcard/Audio/sample"
Alert.show_popup(Rho::AudioCapture.fileName);

#Setting fileName with extension
Rho::AudioCapture.fileName = "/sdcard/Audio/sample.mp4";

#The returned value is "/sdcard/Audio/sample.mp4"
Alert.show_popup(Rho::AudioCapture.fileName);

    In iOS, one can set the fileName without extensions. The extension depends on encoder and will be automatically added. Currently supported WAV (16kHz, 16 bit, mono) IF you do not specify fullpath filename, then file will be placed to default folder. You can receive result fullpath filename in callback.

    #Setting fileName without extension
Rho.AudioCapture.fileName = "sample";

// The returned value is "sample";
alert(Rho.AudioCapture.fileName);

#Setting fileName with fullpath
Rho.AudioCapture.fileName = Rho.Application.userFolder + 'mysound';

// The returned value is (this is example for simulator) "/Users/MOHUS/Library/Application Support/iPhone Simulator/7.1/Applications/376D660D-B6C7-4E6E-8B69-38E7C681DAC5/Documents/apps/mysound";
alert(Rho.AudioCapture.fileName);


                                
    #Setting fileName without extension
Rho::AudioCapture.fileName = 'sample'

// The returned value is "sample"
Alert.show_popup(Rho.AudioCapture.fileName)

#Setting fileName with fullpath
Rho::AudioCapture.fileName = File.join(Rho::Application.userFolder,'mysound')

// The returned value is (this is example for simulator) "/Users/MOHUS/Library/Application Support/iPhone Simulator/7.1/Applications/376D660D-B6C7-4E6E-8B69-38E7C681DAC5/Documents/apps/mysound";
Alert.show_popup(Rho.AudioCapture.fileName)

    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 and iOS, the state will be persisted.

    Page Navigation

    Upon page navigation, the audio recording should be canceled.In iOS, the state will be persisted.

    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.