Capture

Capture

Provides access to the audio, image, and video capture capabilities of the device.

Objects

Methods

Scope

The capture object is assigned to the navigator.device object, and therefore has global scope.

// The global capture object
var capture = navigator.device.capture;

Properties

Methods

Supported Platforms

Permissions

Android

app/res/xml/plugins.xml

<plugin name="Capture" value="org.apache.cordova.Capture"/>

app/AndroidManifest.xml

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Bada

manifest.xml

<Privilege>
    <Name>RECORDING</Name>
</Privilege>

BlackBerry WebWorks

www/plugins.xml

<plugin name="Capture" value="org.apache.cordova.capture.MediaCapture" />

www/config.xml

<feature id="blackberry.system"  required="true" version="1.0.0.0" />
<feature id="blackberry.io.file" required="true" version="1.0.0.0" />

iOS

App/Supporting Files/Cordova.plist

<key>Plugins</key>
<dict>
    <key>Capture</key>
    <string>CDVCapture</string>
</dict>

webOS

No permissions are required.

Windows Phone

Properties/WPAppManifest.xml

<Capabilities>
    <Capability Name="ID_CAP_MEDIALIB" />
    <Capability Name="ID_CAP_MICROPHONE" />
    <Capability Name="ID_HW_FRONTCAMERA" />
    <Capability Name="ID_CAP_ISV_CAMERA" />
    <Capability Name="ID_CAP_CAMERA" />
</Capabilities>

capture.captureAudio

Start the audio recorder application and return information about captured audio clip file(s).

navigator.device.capture.captureAudio( 
    CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);

Description

This method starts an asynchronous operation to capture audio recordings using the device's default audio recording application. The operation allows the device user to capture multiple recordings in a single session.

The capture operation ends when either the user exits the audio recording application, or the maximum number of recordings, specified by the limit parameter in CaptureAudioOptions, has been reached. If no value is provided for the limit parameter, a default value of one (1) is used, and the capture operation will terminate after the user records a single audio clip.

When the capture operation is finished, it will invoke the CaptureCB callback with an array of MediaFile objects describing each captured audio clip file. If the operation is terminated by the user before an audio clip is captured, the CaptureErrorCB callback will be invoked with a CaptureError object with the CaptureError.CAPTURE_NO_MEDIA_FILES error code.

Supported Platforms

Quick Example 

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start audio capture
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Capture Audio</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Called when capture operation is finished
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }       
    }

    // Called if something bad happens.
    // 
    function captureError(error) {
        var msg = 'An error occurred during capture: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // A button will call this function
    //
    function captureAudio() {
        // Launch device audio recording application, 
        // allowing user to capture up to 2 audio clips
        navigator.device.capture.captureAudio(captureSuccess, captureError, {limit: 2});
    }

    // Upload files to server
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Upload success: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes sent');
            },
            function(error) {
                console.log('Error uploading file ' + path + ': ' + error.code);
            },
            { fileName: name });   
    }

    </script>
    </head>
    <body>
        <button onclick="captureAudio();">Capture Audio</button> <br>
    </body>
</html>

BlackBerry WebWorks Quirks

iOS Quirks

Windows Phone 7 Quirks

CaptureAudioOptions

Encapsulates audio capture configuration options.

Properties

Quick Example 

// limit capture operation to 3 media files, no longer than 10 seconds each
var options = { limit: 3, duration: 10 };

navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android Quirks

BlackBerry WebWorks Quirks

iOS Quirks

capture.captureImage

Start the camera application and return information about captured image file(s).

navigator.device.capture.captureImage( 
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);

Description

This method starts an asynchronous operation to capture images using the device camera application. The operation allows the device user to capture multiple images in a single session.

The capture operation ends when either the user exits the camera application, or the maximum number of images, specified by the limit parameter in CaptureImageOptions, has been reached. If no value is provided for the limit parameter, a default value of one (1) is used, and the capture operation will terminate after the user captures a single image.

When the capture operation is finished, it will invoke the CaptureCB callback with an array of MediaFile objects describing each captured image file. If the operation is terminated by the user before an image is captured, the CaptureErrorCB callback will be invoked with a CaptureError object with the CaptureError.CAPTURE_NO_MEDIA_FILES error code.

Supported Platforms

Windows Phone 7 Quirks

Invoking the native camera application while your device is connected via Zune will not work, and the error callback will be triggered.

Quick Example 

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start image capture
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Capture Image</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Called when capture operation is finished
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }       
    }

    // Called if something bad happens.
    // 
    function captureError(error) {
        var msg = 'An error occurred during capture: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // A button will call this function
    //
    function captureImage() {
        // Launch device camera application, 
        // allowing user to capture up to 2 images
        navigator.device.capture.captureImage(captureSuccess, captureError, {limit: 2});
    }

    // Upload files to server
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Upload success: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes sent');
            },
            function(error) {
                console.log('Error uploading file ' + path + ': ' + error.code);
            },
            { fileName: name });   
    }

    </script>
    </head>
    <body>
        <button onclick="captureImage();">Capture Image</button> <br>
    </body>
</html>

CaptureImageOptions

Encapsulates image capture configuration options.

Properties

Quick Example 

// limit capture operation to 3 images
var options = { limit: 3 };

navigator.device.capture.captureImage(captureSuccess, captureError, options);

Android Quirks

BlackBerry WebWorks Quirks

iOS Quirks

capture.captureVideo

Start the video recorder application and return information about captured video clip file(s).

navigator.device.capture.captureVideo( 
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);

Description

This method starts an asynchronous operation to capture video recordings using the device video recording application. The operation allows the device user to capture multiple recordings in a single session.

The capture operation ends when either the user exits the video recording application, or the maximum number of recordings, specified by the limit parameter in CaptureVideoOptions, has been reached. If no value is provided for the limit parameter, a default value of one (1) is used, and the capture operation will terminate after the user records a single video clip.

When the capture operation is finished, it will invoke the CaptureCB callback with an array of MediaFile objects describing each captured video clip file. If the operation is terminated by the user before an video clip is captured, the CaptureErrorCB callback will be invoked with a CaptureError object with the CaptureError.CAPTURE_NO_MEDIA_FILES error code.

Supported Platforms

Quick Example 

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start video capture
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Capture Video</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Called when capture operation is finished
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }       
    }

    // Called if something bad happens.
    // 
    function captureError(error) {
        var msg = 'An error occurred during capture: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // A button will call this function
    //
    function captureVideo() {
        // Launch device video recording application, 
        // allowing user to capture up to 2 video clips
        navigator.device.capture.captureVideo(captureSuccess, captureError, {limit: 2});
    }

    // Upload files to server
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Upload success: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes sent');
            },
            function(error) {
                console.log('Error uploading file ' + path + ': ' + error.code);
            },
            { fileName: name });   
    }

    </script>
    </head>
    <body>
        <button onclick="captureVideo();">Capture Video</button> <br>
    </body>
</html>

BlackBerry WebWorks Quirks

CaptureVideoOptions

Encapsulates video capture configuration options.

Properties

Quick Example 

// limit capture operation to 3 video clips
var options = { limit: 3 };

navigator.device.capture.captureVideo(captureSuccess, captureError, options);

Android Quirks

BlackBerry WebWorks Quirks

iOS Quirks

CaptureError

Encapsulates the error code resulting from a failed media capture operation.

Properties

Constants

CaptureCB

Invoked upon a successful media capture operation.

function captureSuccess( MediaFile[] mediaFiles ) { ... };

Description

This function is invoked after a successful capture operation has completed. This means a media file has been captured, and either the user has exited the media capture application, or the capture limit has been reached.

Each MediaFile object describes a captured media file.

Quick Example 

// capture callback
function captureSuccess(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

CaptureErrorCB

Invoked if an error occurs during a media capture operation.

function captureError( CaptureError error ) { ... };

Description

This function is invoked if an error occurs when trying to launch a media capture operation and the capture application is busy, if an error occurs while the capture operation is taking place, or if the capture operation has been canceled by the user before any media files have been captured.

This function is invoked with a CaptureError object containing an appropriate error code.

Quick Example 

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

ConfigurationData

Encapsulates a set of media capture parameters that a device supports.

Description

This object is used to describe media capture modes supported by the device. The configuration data includes the MIME type, and capture dimensions (for video or image capture).

The MIME types should adhere to RFC2046. Examples:

Properties

Quick Example 

// retrieve supported image modes
var imageModes = navigator.device.capture.supportedImageModes;

// Select mode that has the highest horizontal resolution
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
    if (mode.width > width) {
        width = mode.width;
        selectedmode = mode;
    }
}

Not supported by any platform. All configuration data arrays are empty.

MediaFile

Encapsulates properties of a media capture file.

Properties

Methods

MediaFile.getFormatData

Retrieves format information about the media capture file.

mediaFile.getFormatData( 
    MediaFileDataSuccessCB successCallback, 
    [MediaFileDataErrorCB errorCallback]
);

Description

This function asynchronously attempts to retrieve the format information for the media file. If successful, it invokes the MediaFileDataSuccessCB callback with a MediaFileData object. If the attempt fails, this function will invoke the MediaFileDataErrorCB callback.

Supported Platforms

BlackBerry WebWorks Quirks

There is no API that provides format information of media files. Therefore, all MediaFileData objects will be returned with default values. See MediaFileData documentation.

Android Quirks

The API for retrieving media file format information is limited. Therefore, not all MediaFileData properties are supported. See MediaFileData documentation.

iOS Quirks

The API for retrieving media file format information is limited. Therefore, not all MediaFileData properties are supported. See MediaFileData documentation.

MediaFileData

Encapsulates format information about a media file.

Properties

BlackBerry WebWorks Quirks

There is no API that provides format information of media files. So the MediaFileData object returned by the MediaFile.getFormatData function will have the following default values:

Android Quirks

Support for the MediaFileData properties is as follows:

iOS Quirks

Support for the MediaFileData properties is as follows: