camera tutorial (phonegap)

Capture

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

Objects

Capture
CaptureAudioOptions
CaptureImageOptions
CaptureVideoOptions
CaptureCB
CaptureErrorCB
ConfigurationData
MediaFile
MediaFileData

Methods

capture.captureAudio
capture.captureImage
capture.captureVideo
MediaFile.getFormatData

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

supportedAudioModes: The audio recording formats supported by the device. (ConfigurationData[])
supportedImageModes: The recording image sizes and formats supported by the device. (ConfigurationData[])
supportedVideoModes: The recording video resolutions and formats supported by the device. (ConfigurationData[])

Methods

capture.captureAudio: Launch the device audio recording application for recording audio clip(s).
capture.captureImage: Launch the device camera application for taking image(s).
capture.captureVideo: Launch the device video recorder application for recording video(s).

Supported Platforms

Android
BlackBerry WebWorks (OS 5.0 and higher)

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

Android
BlackBerry WebWorks (OS 5.0 and higher)

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







BlackBerry WebWorks Quirks PhoneGap for BlackBerry WebWorks attempts to launch the Voice Notes Recorder application, provided by RIM, to capture the audio recordings. The developer will receive a CaptureError.CAPTURE_NOT_SUPPORTED error code if the application is not installed on the device. CaptureAudioOptions Encapsulates audio capture configuration options. Properties limit: The maximum number of audio clips the device user can record in a single capture operation. The value must be greater than or equal to 1 (defaults to 1). duration: The maximum duration of an audio sound clip, in seconds. mode: The selected audio mode. The value must match one of the elements in capture.supportedAudioModes. 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 The duration parameter is not supported. Recording lengths cannot be limited programmatically. The mode parameter is not supported. The audio recording format cannot be altered programmatically. Recordings are encoded using Adaptive Multi-Rate (AMR) format (audio/amr). BlackBerry WebWorks Quirks The duration parameter is not supported. Recording lengths cannot be limited programmatically. The mode parameter is not supported. The audio recording format cannot be altered programmatically. Recordings are encoded using Adaptive Multi-Rate (AMR) format (audio/amr). 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 Android BlackBerry WebWorks (OS 5.0 and higher) 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


CaptureImageOptions Encapsulates image capture configuration options. Properties limit: The maximum number of images the device user can capture in a single capture operation. The value must be greater than or equal to 1 (defaults to 1). mode: The selected image mode. The value must match one of the elements in capture.supportedImageModes. Quick Example // limit capture operation to 3 images var options = { limit: 3 }; navigator.device.capture.captureImage(captureSuccess, captureError, options); Android Quirks The mode parameter is not supported. The image size and format cannot be altered programmatically; however, the image size can be altered by the device user. Images are saved in JPEG format (image/jpeg). BlackBerry WebWorks Quirks The mode parameter is not supported. The image size and format cannot be altered programmatically; however, the image size can be altered by the device user. Images are saved in JPEG format (image/jpeg). 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 Android BlackBerry WebWorks (OS 5.0 and higher) 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


BlackBerry WebWorks Quirks PhoneGap for BlackBerry WebWorks attempts to launch the Video Recorder application, provided by RIM, to capture the video recordings. The developer will receive a CaptureError.CAPTURE_NOT_SUPPORTED error code if the application is not installed on the device. CaptureVideoOptions Encapsulates video capture configuration options. Properties limit: The maximum number of video clips the device user can capture in a single capture operation. The value must be greater than or equal to 1 (defaults to 1). duration: The maximum duration of a video clip, in seconds. mode: The selected video capture mode. The value must match one of the elements in capture.supportedVideoModes. Quick Example // limit capture operation to 3 video clips var options = { limit: 3 }; navigator.device.capture.captureVideo(captureSuccess, captureError, options); Android Quirks The duration parameter is not supported. Recording lengths cannot be limited programmatically. The mode parameter is not supported. The video size and format cannot be altered programmatically; however, these parameters can be changed by the device user. By default, videos are recorded in 3GPP (video/3gpp) format. BlackBerry WebWorks Quirks The duration parameter is not supported. Recording lengths cannot be limited programmatically. The mode parameter is not supported. The video size and format cannot be altered programmatically; however, these parameters can be changed by the device user. By default, videos are recorded in 3GPP (video/3gpp) format. 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: video/3gpp image/jpeg audio/amr Properties type: The ASCII-encoded string in lower case representing the media type. (DOMString) height: The height of the image or video in pixels. In the case of a sound clip, this attribute has value 0. (Number) width: The width of the image or video in pixels. In the case of a sound clip, this attribute has value 0. (Number) 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;
}
}

MediaFile

Encapsulates properties of a media capture file.

Properties

name: The name of the file, without path information. (DOMString)
fullPath: The full path of the file, including the name. (DOMString)
type: The mime type (DOMString)
lastModifiedDate: The date and time that the file was last modified. (Date)
size: The size of the file, in bytes. (Number)

Methods

MediaFile.getFormatData: Retrieves the format information of the media file.

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

Android
BlackBerry WebWorks (OS 5.0 and higher)

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.
MediaFileData

Encapsulates format information about a media file.

Properties

codecs: The actual format of the audio and video content. (DOMString)
bitrate: The average bitrate of the content. In case of an image, this attribute has value 0. (Number)
height: The height of the image or video in pixels. In the case of a sound clip, this attribute has value 0. (Number)
width: The width of the image or video in pixels. In the case of a sound clip, this attribute has value 0. (Number)
duration: The length of the video or sound clip in seconds. In the case of an image, this attribute has value 0. (Number)

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:

codecs: Not supported. The attribute will always be null.
bitrate: Not supported. The attribute will always be 0.
height: Not supported. The attribute will always be 0.
width: Not supported. The attribute will always be 0.
duration: Not supported. The attribute will always be 0.

Android Quirks

Support for the MediaFileData properties is as follows:

codecs: Not supported. The attribute will always be null.
bitrate: Not supported. The attribute will always be 0.
height: Supported. (Image and video files only).
width: Supported. (Image and video files only).
duration: Supported. (Audio and video files only).