Microphone

The Microphone object contains functions for recording audio from microphone.


Code Example:
<!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>


Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry PlayBook 1.0+
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.media.microphone.getSupportedMediaTypes Y Y Y       
blackberry.media.microphone.pause Y Y Y Y Y   
blackberry.media.microphone.record Y Y Y Y Y   
blackberry.media.microphone.stop Y 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 IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.media.microphone" /> Y Y Y Y Y   

Permission Elements (PlayBook and BlackBerry 10+)
You must declare the permission element(s) below in your configuration document:
- <rim:permit>record_audio</rim:permit>
Permits the app to record sound through the microphone without prompting the user.

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.

Functions

static String[] blackberry.media.microphone.getSupportedMediaTypes ()


Return the mime types that the record method supports

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


Supported Platforms
 - BlackBerry OS 5.0+


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

static void blackberry.media.microphone.pause ()


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.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+

static void blackberry.media.microphone.record (filePath : String, onCaptured: function(filePath : String), onError: function(errorCode : Number, errorMsg : String))


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


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+


Parameters
filePath full path to the file, specified in the form of file:// URL
onCaptured 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 This callback function is called if the recording has failed.

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

static void blackberry.media.microphone.stop ()


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.


Supported Platforms
 - BlackBerry OS 5.0+
 - BlackBerry PlayBook 1.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:41 GMT-0500 (EST)