cordova-plugin-media-capture

Android Testsuite Chrome Testsuite iOS Testsuite Lint Test

此插件提供对设备音频、图像和视频捕获功能的访问。

警告：从设备的相机或麦克风收集和使用图像、视频或音频会引发重要的隐私问题。您的应用程序的隐私政策应讨论应用程序如何使用此类传感器，以及记录的数据是否与任何其他方共享。此外，如果应用程序对相机或麦克风的使用在用户界面中不明显，您应该在应用程序访问相机或麦克风之前提供及时的通知（如果设备操作系统尚未这样做）。该通知应提供上述相同的信息，并获得用户的许可（例如，通过提供确定和不了，谢谢的选择）。请注意，某些应用市场可能要求您的应用在访问相机或麦克风之前提供及时的通知并获得用户的许可。有关更多信息，请参阅隐私指南。

此插件定义全局 navigator.device.capture 对象。

尽管在全局范围内，但它在 deviceready 事件之后才可用。

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.device.capture);
}

安装

cordova plugin add cordova-plugin-media-capture

支持的平台

  • Android
  • 浏览器
  • iOS
  • Windows

对象

  • Capture
  • CaptureAudioOptions
  • CaptureImageOptions
  • CaptureVideoOptions
  • CaptureCallback
  • CaptureErrorCB
  • ConfigurationData
  • MediaFile
  • MediaFileData

方法

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

属性

  • supportedAudioModes：设备支持的音频录制格式。(ConfigurationData[])

  • supportedImageModes：设备支持的录制图像大小和格式。(ConfigurationData[])

  • supportedVideoModes：设备支持的录制视频分辨率和格式。(ConfigurationData[])

capture.captureAudio

启动音频录制器应用程序并返回有关捕获的音频剪辑文件的信息。

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

描述

启动一个异步操作，使用设备的默认音频录制应用程序捕获音频录音。该操作允许设备用户在单个会话中捕获多个录音。

当用户退出音频录制应用程序，或者达到 CaptureAudioOptions.limit 指定的最大录音数时，捕获操作结束。如果没有指定 limit 参数值，则默认为 1 (1)，并且捕获操作在用户录制单个音频剪辑后终止。

当捕获操作完成时，CaptureCallback 将执行，其中包含描述每个捕获的音频剪辑文件的 MediaFile 对象数组。如果用户在捕获音频剪辑之前终止该操作，则 CaptureErrorCallback 将执行，并返回一个具有 CaptureError.CAPTURE_NO_MEDIA_FILES 错误代码的 CaptureError 对象。

支持的平台

  • Android
  • iOS
  • Windows

示例

// 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});

iOS 怪癖

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

Windows Phone 7 和 8 怪癖

  • Windows Phone 7 没有默认的音频录制应用程序，因此提供了一个简单的用户界面。

capture.captureImage

启动相机应用程序并返回有关捕获的图像文件的信息。

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

描述

启动一个异步操作，使用设备的相机应用程序捕获图像。该操作允许用户在单个会话中捕获多个图像。

当用户关闭相机应用程序，或者达到 CaptureImageOptions.limit 指定的最大录制数时，捕获操作结束。如果没有指定 limit 值，则默认为 1 (1)，并且捕获操作在用户捕获单个图像后终止。

当捕获操作完成时，它会使用描述每个捕获的图像文件的 MediaFile 对象数组调用 CaptureCB 回调。如果用户在捕获图像之前终止该操作，则 CaptureErrorCB 回调将执行，并返回一个具有 CaptureError.CAPTURE_NO_MEDIA_FILES 错误代码的 CaptureError 对象。

支持的平台

  • Android
  • 浏览器
  • iOS
  • Windows

iOS 怪癖

自 iOS 10 起，如果尝试访问隐私敏感数据，则必须在 info.plist 中提供使用描述。当系统提示用户允许访问时，此使用描述字符串将显示为权限对话框的一部分，但是如果您没有提供使用描述，则应用程序将在显示对话框之前崩溃。此外，Apple 将拒绝访问私人数据但不提供使用描述的应用程序。

此插件需要以下使用描述

  • NSCameraUsageDescription 描述了应用程序访问用户相机的原因。
  • NSMicrophoneUsageDescription 描述了应用程序访问用户麦克风的原因。
  • NSPhotoLibraryUsageDescriptionentry 描述了应用程序访问用户照片库的原因。

要将这些条目添加到 info.plist 中，您可以使用 config.xml 中的 edit-config 标签，如下所示

<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
    <string>need camera access to take pictures</string>
</edit-config>

<edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
    <string>need microphone access to record sounds</string>
</edit-config>

<edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need to photo library access to get pictures from there</string>
</edit-config>

浏览器怪癖

仅在 Chrome、Firefox 和 Opera 中有效（因为 IE 和 Safari 不支持 navigator.getUserMedia API）

仅在 Chrome/Opera 中可以显示使用捕获文件的 URL 的图像。Firefox 将捕获的图像存储在 IndexedDB 存储中（请参阅 File 插件文档），因此显示捕获图像的唯一方法是读取它并使用其 DataURL 显示。

示例

// 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});

capture.captureVideo

启动视频录制器应用程序并返回有关捕获的视频剪辑文件的信息。

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

描述

启动一个异步操作，使用设备的视频录制应用程序捕获视频录像。该操作允许用户在单个会话中捕获多个录像。

当用户退出视频录制应用程序，或者达到 CaptureVideoOptions.limit 指定的最大录制数时，捕获操作结束。如果没有指定 limit 参数值，则默认为 1 (1)，并且捕获操作在用户录制单个视频剪辑后终止。

当捕获操作完成时，它会使用描述每个捕获的视频剪辑文件的 MediaFile 对象数组执行 CaptureCB 回调。如果用户在捕获视频剪辑之前终止该操作，则 CaptureErrorCB 回调将执行，并返回一个具有 CaptureError.CAPTURE_NO_MEDIA_FILES 错误代码的 CaptureError 对象。

支持的平台

  • Android
  • iOS
  • Windows

示例

// 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});

CaptureAudioOptions

封装音频捕获配置选项。

属性

  • limit：设备用户在单个捕获操作中可以录制的最大音频剪辑数。该值必须大于或等于 1（默认为 1）。

  • duration：音频片段的最大持续时间，以秒为单位。

示例

// 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 怪癖

  • 不支持 duration 参数。录制长度无法以编程方式限制。

iOS 怪癖

  • 不支持 limit 参数，因此每次调用只能创建一个录制。

CaptureImageOptions

封装图像捕获配置选项。

属性

  • limit：用户在单个捕获操作中可以捕获的最大图像数。该值必须大于或等于 1（默认为 1）。

示例

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

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

iOS 怪癖

  • 不支持 limit 参数，每次调用只拍摄一张图像。

CaptureVideoOptions

封装视频捕获配置选项。

属性

  • limit：设备的在单个捕获操作中可以捕获的最大视频剪辑数。该值必须大于或等于 1（默认为 1）。

  • duration：视频剪辑的最大持续时间，以秒为单位。

  • quality：允许以不同质量捕获视频。值为 1（默认值）表示高质量，值为 0 表示低质量，适合 MMS 消息。

示例

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

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

iOS 怪癖

  • limit 属性被忽略。每次调用只录制一个视频。

  • quality 属性的值可以为 0.5 表示中等质量。

  • 有关 iOS 上 quality 属性的更多详细信息，请参阅此处。

Android 怪癖

  • 有关 Android 上 quality 属性的更多详细信息，请参阅此处。

示例（带 quality）

// limit capture operation to 1 video clip of low quality
var options = { limit: 1, quality: 0 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

CaptureCB

在成功完成媒体捕获操作后调用。

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

描述

此函数在成功完成捕获操作后执行。此时，已捕获媒体文件，并且用户已退出媒体捕获应用程序，或者已达到捕获限制。

每个 MediaFile 对象都描述一个捕获的媒体文件。

示例

// 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
    }
};

CaptureError

封装因媒体捕获操作失败而产生的错误代码。

属性

  • code：下面列出的预定义错误代码之一。

常量

  • CaptureError.CAPTURE_INTERNAL_ERR：摄像头或麦克风未能捕获图像或声音。

  • CaptureError.CAPTURE_APPLICATION_BUSY：摄像头或音频捕获应用程序当前正在处理另一个捕获请求。

  • CaptureError.CAPTURE_INVALID_ARGUMENT：API 使用无效（例如，limit 的值小于 1）。

  • CaptureError.CAPTURE_NO_MEDIA_FILES：用户在未捕获任何内容的情况下退出摄像头或音频捕获应用程序。

  • CaptureError.CAPTURE_PERMISSION_DENIED：用户拒绝了执行给定捕获请求所需的权限。

  • CaptureError.CAPTURE_NOT_SUPPORTED：不支持请求的捕获操作。

CaptureErrorCB

如果在媒体捕获操作期间发生错误，则会调用此函数。

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

描述

当尝试启动媒体捕获操作时发生错误时，会执行此函数。失败的情况包括捕获应用程序繁忙、已在进行捕获操作，或用户在未捕获任何媒体文件之前取消操作。

此函数会使用包含适当错误 code 的 CaptureError 对象执行。

示例

// capture error callback
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：图像或视频的高度，以像素为单位。对于声音剪辑，该值为零。(Number)

  • width：图像或视频的宽度，以像素为单位。对于声音剪辑，该值为零。(Number)

示例

// 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.getFormatData

检索有关媒体捕获文件的格式信息。

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

描述

此函数异步尝试检索媒体文件的格式信息。如果成功，它会使用 MediaFileData 对象调用 MediaFileDataSuccessCB 回调。如果尝试失败，此函数会调用 MediaFileDataErrorCB 回调。

支持的平台

  • Android
  • iOS
  • Windows

Android 怪癖

用于访问媒体文件格式信息的 API 是有限的，因此并非所有 MediaFileData 属性都受支持。

iOS 怪癖

用于访问媒体文件格式信息的 API 是有限的，因此并非所有 MediaFileData 属性都受支持。

MediaFile

封装媒体捕获文件的属性。

属性

  • name：文件的名称，不包含路径信息。(DOMString)

  • fullPath：文件的完整路径，包括名称。(DOMString)

  • type：文件的 MIME 类型 (DOMString)

  • lastModifiedDate：文件上次修改的日期和时间。(Date)

  • size：文件的大小，以字节为单位。(Number)

方法

  • MediaFile.getFormatData：检索媒体文件的格式信息。

MediaFileData

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

属性

  • codecs：音频和视频内容的实际格式。(DOMString)

  • bitrate：内容的平均比特率。对于图像，该值为零。(Number)

  • height：图像或视频的高度，以像素为单位。对于音频剪辑，该值为零。(Number)

  • width：图像或视频的宽度，以像素为单位。对于音频剪辑，该值为零。(Number)

  • duration：视频或声音剪辑的长度，以秒为单位。对于图像，该值为零。(Number)

Android 怪癖

支持以下 MediaFileData 属性：

  • codecs：不支持，并返回 null。

  • bitrate：不支持，并返回零。

  • height：支持：仅限图像和视频文件。

  • width：支持：仅限图像和视频文件。

  • duration：支持：仅限音频和视频文件。

iOS 怪癖

支持以下 MediaFileData 属性：

  • codecs：不支持，并返回 null。

  • bitrate：在 iOS4 设备上仅支持音频。对于图像和视频，返回零。

  • height：支持：仅限图像和视频文件。

  • width：支持：仅限图像和视频文件。

  • duration：支持：仅限音频和视频文件。

Android 生命周期怪癖

在 Android 平台上捕获音频、视频或图像时，Cordova Webview 被原生捕获应用程序推到后台后，应用程序可能会被销毁。有关此问题的完整描述，请参阅Android 生命周期指南。在这种情况下，传递给捕获方法的成功和失败回调将不会被触发，相反，调用的结果将通过在 Cordova 恢复事件之后触发的文档事件传递。

在您的应用中，您应该像这样订阅这两个可能的事件：

function onDeviceReady() {
    // pendingcaptureresult is fired if the capture call is successful
    document.addEventListener('pendingcaptureresult', function(mediaFiles) {
        // Do something with result
    });

    // pendingcaptureerror is fired if the capture call is unsuccessful
    document.addEventListener('pendingcaptureerror', function(error) {
        // Handle error case
    });
}

// Only subscribe to events after deviceready fires
document.addEventListener('deviceready', onDeviceReady);

您需要自行跟踪这些结果来自您代码的哪个部分。请务必在 暂停 和 恢复 事件中适当保存和恢复您的应用程序状态。请注意，这些事件仅在 Android 平台上触发，并且仅当 Webview 在捕获操作期间被销毁时触发。