采集

Capture

“

提供对设备音频、图像和视频采集功能的访问。

对象：

方法：

范围：

capture对象被分配给navigator.device对象，因此作用域为全局范围。

简单的范例：

复制

// 全局范围的capture对象	
var capture = navigator.device.capture;

属性：

supportedAudioModes：当前设备所支持的音频录制格式。（ConfigurationData[] 类型）
supportedImageModes：当前设备所支持的拍摄图像尺寸及格式。（ConfigurationData[] 类型）
supportedVideoModes：当前设备所支持的拍摄视频分辨率及格式。（ConfigurationData[] 类型）

方法：

capture.captureAudio：启动设备录制音频剪辑的音频录制应用程序。
capture.captureImage：启动设备拍摄照片的摄像头应用程序。
capture.captureVideo：启动设备拍摄视频的视频录制应用程序。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS
Windows Phone 7 ( Mango )

capture.captureAudio

“

启动录音机应用程序并返回采集的音频剪辑文件。

复制

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

说明：

该方法通过设备默认的音频录制应用程序开始一个异步操作以采集音频录制。该操作允许设备用户在一个会话中同时采集多个录音。

当用户退出音频录制应用程序，或系统到达CaptureAudioOptions的limit参数所定义的最大录制数时都会停止采集操作。如果没有设置limit参数的值，则使用其默认值1，也就是说当用户录制好一个音频剪辑后采集操作就会终止。

当采集操作结束后，系统会调用CaptureCB回调函数，传递一个包含所有采集到的音频剪辑文件的MediaFile对象数组。如果用户在完成一个音频剪辑采集之前终止采集操作，系统会调用CaptureErrorCB回调函数，并传递一个包含CaptureError.CAPTURE_NO_MEDIA_FILES错误代码的CaptureError对象。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS
Windows Phone 7 ( Mango )

简单的范例：

复制

// 采集操作成功完成后的回调函数
var captureSuccess = function(mediaFiles) { 
	var i, path, len;
	for (i = 0, len = mediaFiles.length; i < len; i += 1) {
		path = mediaFiles[i].fullPath; 	
		// 对文件进行感兴趣的操作
	} 
};  
	
// 采集操作出错后的回调函数
var captureError = function(error) { 
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
};  
	
// 开始采集音频
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

完整的范例：

复制


Capture Audio

BlackBerry WebWorks的特异情况：

在BlackBerry WebWorks上，PhoneGap会尝试启动RIM提供的Voice Notes Recorder应用程序来采集音频录制。如果设备没有安装该应用程序，开发者会收到一个CaptureError.CATURE_NOT_SUPPORTED错误代码。

iOS的特异情况：

iOS没有默认的音频录制应用程序，因此仅提供一个简单的用户界面。

CaptureAudioOptions

“

封装音频采集的配置选项。

属性：

limit：在单个采集操作期间能够记录的音频剪辑数量最大值，必须设定为大于等于1（默认值为1）。
drration：一个音频剪辑的最长时间，单位为秒。
mode：选定的音频模式，必须设定为capture.supportedAudioModes枚举中的值。

简单的范例：

复制

// 限制采集上限为3个媒体文件，每个文件不超过10秒
var options = { limit: 3, duration: 10 };
	
navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android的特异情况：

不支持duration参数，无法通过程序限制录制长度。
不支持mode参数，无法通过程序修改音频录制格式。使用自适应多速率（AMR）格式（audio/amr）进行音频录制编码。

BlackBerry WebWorks的特异情况：

不支持duration参数，无法通过程序限制录制长度。
不支持mode参数，无法通过程序修改音频录制格式。使用自适应多速率（AMR）格式（audio/amr）进行音频录制编码。

iOS的特异情况：

不支持limit参数，每次调用只能创建一个录制。
不支持mode参数，无法通过程序修改音频录制格式。使用波形音频（WAV）格式（audio/wav）进行音频录制编码。

capture.captureImage

“

开启摄像头应用程序，返回采集到的图像文件信息。

复制

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

说明：

该方法通过设备的摄像头应用程序开始一个异步操作以采集图像。该操作允许设备用户在一个会话中同时采集多个图像。

当用户退出摄像头应用程序，或系统到达CaptureImageOptions的limit参数所定义的最大图像数时都会停止采集操作。如果没有设置limit参数的值，则使用其默认值1，也就是说当用户采集到一个图像后采集操作就会终止。

当采集操作结束后，系统会调用CaptureCB回调函数，传递一个包含每个采集到的图像文件的MediaFile对象数组。如果用户在完成一个图像采集之前终止采集操作，系统会调用CaptureErrorCB回调函数，并传递一个包含CaptureError.CAPTURE_NO_MEDIA_FILES错误代码的CaptureError对象。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS
Windows Phone 7 ( Mango )

简单的范例：

复制

// 采集操作成功完成后的回调函数
var captureSuccess = function(mediaFiles) { 
	var i, path, len; 
	for (i = 0, len = mediaFiles.length; i < len; i += 1) { 
		path = mediaFiles[i].fullPath;
		// 对文件进行感兴趣的操作
	} 
}; 

// 采集操作出错后的回调函数
var captureError = function(error) { 
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}; 

// 开始采集图像
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

完整的范例：

复制

	
Capture Image

CaptureImageOptions

“

封装图像采集的配置选项。

属性：

limit：在单个采集操作期间能够采集的图像数量最大值，必须设定为大于等于1（默认值为1）。
mode：选定的图像模式，必须设定为capture.supportedImageModes枚举中的值。

简单的范例：

复制

// 最多采集3幅图像
var options = { limit: 3 };

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

Android的特异情况：

不支持mode参数，无法通过程序修改图像的大小和格式。不过设备用户可以修改图像的大小，图像会以JPEG格式(image/jpeg)存储。

BlackBerry WebWorks的特异情况：

不支持mode参数，无法通过程序修改图像的大小和格式。不过设备用户可以修改图像的大小，图像会以JPEG格式(image/jpeg)存储。

iOS的特异情况：

不支持limit参数，每调用一次采集一幅图像。
不支持mode参数，无法通过程序修改图像的大小和格式。图像会以JPEG格式(image/jpeg)存储。

capture.captureVideo

“

开启视频录制应用程序，返回采集到的视频剪辑文件信息。

复制

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

说明：

该方法通过设备的视频录制应用程序开始一个异步操作以采集视频录制。该操作允许设备用户在一个会话中同时采集多个视频录制。

当用户退出视频录制应用程序，或系统到达CaptureVideoOptions的limit参数所定义的最大录制数时都会停止采集操作。如果没有设置limit参数的值，则使用其默认值1，也就是说当用户录制到一个视频剪辑后采集操作就会终止。

当采集操作结束后，系统会调用CaptureCB回调函数，传递一个包含每个采集到的视频剪辑文件的MediaFile对象数组。如果用户在完成一个视频剪辑采集之前终止采集操作，系统会调用CaptureErrorCB回调函数，并传递一个包含CaptureError.CAPTURE_NO_MEDIA_FILES错误代码的CaptureError对象。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS
Windows Phone 7 ( Mango )

简单的范例：

复制

// 采集操作成功完成后的回调函数
var captureSuccess = function(mediaFiles) { 
	var i, path, len; 
	for (i = 0, len = mediaFiles.length; i < len; i += 1) { 	
		path = mediaFiles[i].fullPath; 
		// 对文件进行感兴趣的操作
	} 
}; 

// 采集操作出错后的回调函数 
var captureError = function(error) { 
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error'); 
}; 

// 开始采集视频
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

完整的范例：

复制


Capture Video

BlackBerry WebWorks 的特异情况：

在BlackBerry WebWorks上，PhoneGap会尝试启动RIM提供的Video Recorder应用程序来采集视频录制。如果设备没有安装该应用程序，开发者会收到一个CaptureError.CATURE_NOT_SUPPORTED错误代码。

CaptureVideoOptions

“

封装视频采集的配置选项。

属性：

limit：在单个采集操作期间能够采集的视频剪辑数量最大值，必须设定为大于等于1（默认值为1）。
drration：一个视频剪辑的最长时间，单位为秒。
mode：选定的视频采集模式，必须设定为capture.supportedVideoModes枚举中的值。

简单的范例：

复制

// 最多采集3个视频剪辑
var options = { limit: 3 };

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

Android的特异情况：

不支持duration参数，无法通过程序限制录制长度。
不支持mode参数，无法通过程序修改视频的大小和格式。不过，设备用户可以修改这些参数，默认情况下视频会以3GPP格式(video/3gpp)存储。

BlackBerry WebWorks的特异情况：

不支持duration参数，无法通过程序限制录制长度。
不支持mode参数，无法通过程序修改视频的大小和格式。不过，设备用户可以修改这些参数，默认情况下视频会以3GPP(video/3gpp)格式存储。

iOS的特异情况：

不支持limit参数，每调用一次采集一个视频。
不支持duration参数，无法通过程序限制录制长度。
不支持mode参数，无法通过程序修改视频的大小和格式。默认情况下视频会以MOV(video/3gpp)格式存储。

CaptureError

“

封装了多媒体采集失败的返回信息。

属性：

code：下面预定义的error codes之一。

常量：

CaptureError.CAPTURE_INTERNAL_ERR：摄像头或者耳机采集图片或声音失败。
CaptureError.CAPTURE_APPLICATION_BUSY：摄像头或者音频采集程序正在处理别的采集请求。
CaptureError.CAPTURE_INVALID_ARGUMENT：非法的API调用(Limit 参数的值小于1)。
CaptureError.CAPTURE_NO_MEDIA_FILES：在采集到任何信息之前用户退出了摄像头或者音频采集程序。
CaptureError.CAPTURE_NOT_SUPPORTED：采集信息的请求是不支持的请求。

CaptureCB

“

媒体采集成功后调用的回调函数。

复制

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

说明：

当完成一个成功的采集操作后会调用该函数。这意味着已经采集到一个媒体文件，同时要么用户已经退出媒体采集应用程序，要么已经到达采集数量上限。

每个MediaFile对象都指向一个采集到的媒体文件。

简单的范例：

复制

// 采集操作成功完成后的回调函数
function captureSuccess(mediaFiles) {
   	var i, path, len;
   	for (i = 0, len = mediaFiles.length; i < len; i += 1) {
	   	path = mediaFiles[i].fullPath;
	   	//对文件进行感兴趣的操作
	}
}

CaptureErrorCB

“

媒体采集操作发生错误后调用的回调函数。

复制

function captureError( CaptureError error ) { ... }

说明：

出现以下情况会调用该函数：试图在采集应用程序繁忙时启动媒体采集操作而引起错误、采集操作正在工作时出现错误、用户在没有任何媒体文件采集完成前取消采集操作。

该函数调用时会传递一个包含相应错误代码的CaptureError对象。

简单的范例：

复制

// 采集操作出错后的回调函数
var captureError = function(error) {
	navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
}

ConfigurationData

“

封装设备支持的媒体采集参数集。

说明：

该对象用于描述设备所支持的媒体采集模式，配置数据包括MIME类型和采集尺寸（适用于视频和图像采集）。

MIME类型应该符合RFC2046规范，例如：

video/3gpp
video/quicktime
image/jpeg
audio/amr
audio/wav

属性：

type：用小写ASCII编码字符串表示的媒体类型。（DOMString格式）
height：用像素表示的图像或视频高度，音频剪辑为0。（数字类型）
width：用像素表示的图像或视频宽度，音频剪辑为0。（数字类型）

简单的范例：

复制

// 获得支持的图像模式
var imageModes = navigator.device.capture.supportedImageModes;

// 选择最高水平分辨率的模式
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
	if (mode.width > width) {
	   	width = mode.width;
	   	selectedmode = mode;
   	}
}

没有任何一个平台支持，所有配置数据数组都为空。

MediaFile

“

封装采集到的媒体文件的属性。

属性：

name：不含路径信息的文件名。（DOMString类型）
fullPath：包含文件名的文件全路径。（DOMString类型）
type： MIME类型。（DOMString类型）
lastModifiedDate：文件最后修改的日期和时间。（日期类型）
size：以字节数表示的文件大小。（数字类型）

方法：

MediaFile.getFormatData：获取媒体文件的格式信息

MediaFile.getFormatData

“

获取采集到的媒体文件的格式信息。

复制

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

说明：

该方法通过异步方式尝试获取媒体文件的格式信息。获取成功的情况下该方法会调用MediaFileDataSuccessCB回调并传递一个MediaFileData对象，尝试失败的情况下该方法会调用MediaFileDataErrorCB回调。

支持的平台：

Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS
Windows Phone 7 ( Mango )

BlackBerry WebWorks的特异情况：

没有提供媒体文件格式信息的API，因此，所有MediaFileData对象都会返回默认值。参考MediaFileData文档。

Android的特异情况：

获取媒体文件格式信息的API受到限制，因此，不是所有的MediaFileData属性都支持。参考MediaFileData文档。

iOS的特异情况：

获取媒体文件格式信息的API受到限制，因此，不是所有的MediaFileData属性都支持。参考MediaFileData文档。

MediaFileData

“

封装媒体文件的格式信息。

属性：

codecs：音频及视频内容的实际格式。（DOMString类型）
bitrate：文件内容的平均比特率。对于图像文件，属性值为0。（数字类型）
height：用像素表示的图像或视频高度，音频剪辑的该属性值为0。（数字类型）
width：用像素表示的图像或视频的宽度，音频剪辑的该属性值为0。（数字类型）
duration：以秒为单位的视频或音频剪辑时长，图像文件的该属性值为0。（数字类型）

BlackBerry WebWorks的特异情况：

没有提供媒体文件格式信息的API，因此MediaFile.getFormatData方法返回的MediaFileData对象包含以下默认值：

codecs：不支持，该属性始终为空。
bitrate：不支持，该属性始终为0。
heigh：不支持，该属性始终为0。
width：不支持，该属性始终为0。
duration：不支持，该属性始终为0。

Android的特异情况：

MediaFileData属性的支持情况如下：

codecs：不支持，该属性始终为空。
bitrate：不支持，该属性始终为0。
height：支持（仅限图像或视频文件）。
width：支持（仅限图像或视频文件）。
duration：支持（仅限音频或视频文件）。

iOS的特异情况：

MediaFileData属性的支持情况如下：

codecs：不支持，该属性始终为空。
bitrate：iOS4设备上仅支持音频，对于图像和视频此属性值为0。
height：支持（仅限图像或视频文件）。
width：支持（仅限图像或视频文件）。
duration：支持（仅限音频或视频文件）。