Microphone

The Microphone object contains functions for recording audio from microphone.

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook

View Supported Platform Table

APIOS 5.0OS 6.0OS 7.0PlayBookRipple
getSupportedMediaTypes Y Y Y   
pause Y Y Y Y 
record Y Y Y Y 
stop Y Y Y Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:


You must declare the feature element(s) below in your configuration document:

Feature IDOS 5.0OS 6.0OS 7.0PlayBookRipple
<feature id="blackberry.media.microphone" /> Y Y Y Y 

You must declare the permission element(s) below in your configuration document:


Permission Elements (PlayBook Only)
- <rim:permit>record_audio</rim:permit> Permits the app to record sound through the microphone without prompting the user.

Note: Declaring the permission element(s) below in your configuration document is optional.
- <rim:permit>access_shared</rim:permit> Any references to files/directories under "shared" folder (e.g. music) requires this permission to be set.

API Summary


getSupportedMediaTypes

static String[] getSupportedMediaTypes()

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Return the mime types that the record method supports

Sample values: "audio/amr", "audio/wav"



Code Example(s)

function printSupportedTypes() {
        var types = blackberry.media.microphone.getSupportedMediaTypes();
        var alertMsg = "";
        for(var i = 0; i < types.length; i++) {
            alertMsg += types[i] + " ";
        }
        alert(alertMsg);
}

pause

static void pause()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - BlackBerry PlayBook

Description

Pauses/resumes recording.

If the microphone is in recording mode, calling pause() would cause recording to pause. If the microphone is paused, calling pause() would cause recording to resume.


record

static void record(filePath : String, onCaptured : function, onError : function)

Supported Platform(s)

 - BlackBerry OS 5.0+
 - BlackBerry PlayBook

Description

Records audio from the microphone.

If the specified format is not supported on the device, an error is passed to the onError callback with the message "Unsupported record encoding type". The supported recording formats are:

  PlayBook BB OS 5.0, 6.0 (GSM) BB OS 5.0, 6.0 (CDMA) BB OS 7.0
Supported Formats: WAV WAV, AMR AMR WAV, AMR
Bit Depth: 16 16 16 16
Sampling Rate: 44,100Hz 8,000Hz 8,000Hz 8,000Hz
Channels: 1 1 1 1



Parameter Type Description
filePath String full path to the file, specified in the form of file:// URL
onCaptured function(filePath : String) This callback function is called when the application has successfully recorded the audio and saved it to the requested file.

filePath: The file path that points to the created audio file.
onError function(errorCode : Number, errorMsg : String) This callback function is called if the recording has failed.

errorCode: The error code for the error.
errorMsg: The error message for the error.

stop

static void stop()

Supported Platform(s)

 - BlackBerry OS 5.0+
 - BlackBerry PlayBook

Description

Stops recording, this causes the recorded audio data to be saved to the file. The onCaptured callback function passed in record will be invoked when the audio file has been saved to disk.


Code Example(s)

<!DOCTYPE html>
<html>
<head>
<link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/ui-lightness/jquery-ui.css" rel="stylesheet" type="text/css"/>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5/jquery.min.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
<script type="text/javascript">
var mic = blackberry.media.microphone;
var isPaused = false;

function record() {
  try {
    // NOTE: access to shared folder requires "access_shared" permission on config.xml
    mic.record(blackberry.io.dir.appDirs.shared.music.path + '/' + document.getElementById('filename').value, testSuccess, testError);
    $("#record").button("option", "disabled", true);
    $("#pause").button("option", "disabled", false);
    $("#stop").button("option", "disabled", false);
  } catch (e) {
    alert('Record, e:' + e.message);
  }
}

function pause() {
  isPaused = !isPaused;

  if (isPaused) {
    $("#pause").button("option", "label", "Resume");
  } else {
    $("#pause").button("option", "label", "Pause");
  }

  try {
    mic.pause();
  } catch (e) {
    alert('Pause, e:' + e.message);
  }
}

function stop() {
  try {
    mic.stop();
    $("#record").button("option", "disabled", false);
    $("#pause").button("option", "disabled", true);
    $("#stop").button("option", "disabled", true);
  } catch (e) {
    alert('Stop, e:' + e.message);
  }
}

function testSuccess(filePath) {
  alert("Recorded successfully! File: " + filePath);
}

function testError(errorCode, errorMessage) {
    if(errorMessage == "Unsupported record encoding type") {
        alert("try recording an .amr audio file");
        return;
    }
  alert('error code:' + errorCode + ' error message:' + errorMessage);
}

</script>
<script type="text/javascript">
$(document).ready(function() {
  $("#record").button();
  $("#pause").button({ disabled: true });
  $("#stop").button({ disabled: true });

  $("#record").bind("click", record);
  $("#pause").bind("click", pause);
  $("#stop").bind("click", stop);
});
</script>
</head>
<body>
<p>File Name: <input type="text" id="filename"></p>
<button id="record">Record</button>  
<button id="pause">Pause</button>  
<button id="stop">Stop</button>
</body>
</html>
Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:18 GMT-0500 (EST)