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

对象

  • 捕获
  • 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，并且在用户录制单个音频剪辑后捕获操作终止。

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

支持的平台

  • 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，并且在用户捕获单个图像后捕获操作终止。

捕获操作完成后，它使用描述每个捕获的图像文件的 MediaFile 对象数组调用 CaptureCB 回调。如果用户在捕获图像之前终止操作，则 CaptureErrorCB 回调使用 CaptureError 对象执行，其中包含 CaptureError.CAPTURE_NO_MEDIA_FILES 错误代码。

支持的平台

  • 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 存储中（请参阅文件插件文档），因此显示捕获图像的唯一方法是读取它并使用其 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，并且在用户录制单个视频剪辑后，捕获操作终止。

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

支持的平台

  • 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 表示低质量，适用于彩信。

示例

// 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 属性的更多详细信息，请参见 此处。

示例（带质量）

// 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：图像或视频的高度（以像素为单位）。对于声音剪辑，该值为零。（数字）

  • width：图像或视频的宽度（以像素为单位）。对于声音剪辑，该值为零。（数字）

示例

// 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：文件上次修改的日期和时间。（日期）

  • size：文件的大小（以字节为单位）。（数字）

方法

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

MediaFileData

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

属性

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

  • bitrate：内容的平均比特率。对于图像，该值为零。（数字）

  • height：图像或视频的高度（以像素为单位）。对于音频剪辑，该值为零。（数字）

  • width：图像或视频的宽度（以像素为单位）。对于音频剪辑，该值为零。（数字）

  • duration：视频或声音剪辑的长度（以秒为单位）。对于图像，该值为零。（数字）

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 被销毁时触发。