cordova-plugin-media-capture 1.4.0

您想将以下代码添加到 Podfile 中：pod 'cordova-plugin-media-capture', '~> 1.4'

target 'MyApp' do
  pod 'cordova-plugin-media-capture', '~> 1.4'
end

然后在您的终端或从 CocoaPods.app 中运行 pod install。

或者，为了进行测试运行，运行以下命令：

pod try cordova-plugin-media-capture


依赖
Cordova	>= 4.3.0
cordova-plugin-file	>= 0

cordova-plugin-media-capture 1.4.0

由
Adobe PhoneGap 团队

标题：媒体捕捉

描述：捕捉音频、视频和图像。

Android	iOS	Windows 8.1 商店	Windows 8.1 手机	Windows 10 商店	Travis CI

cordova-plugin-media-capture

此插件提供对设备音频、图像和视频捕捉功能的使用。

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

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

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

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

在 Apache Cordova 问题跟踪器上报告此插件的问题。

安装

cordova plugin add cordova-plugin-media-capture

支持的平台

Amazon Fire OS
Android
BlackBerry 10
浏览器
iOS
Windows Phone 7 和 8
Windows 8
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，且在用户录制一个音频剪辑后捕获操作将终止。

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

支持的平台

Amazon Fire OS
Android
BlackBerry 10
iOS
Windows Phone 7 和 8
Windows 8
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回调。如果用户在捕获图像之前终止操作，则执行带有具有CaptureError.CAPTURE_NO_MEDIA_FILES错误代码的CaptureErrorCB回调。

支持的平台

Amazon Fire OS
Android
BlackBerry 10
浏览器
iOS
Windows Phone 7 和 8
Windows 8
Windows

iOS 特殊情况

从iOS 10开始，在info.plist中添加NSCameraUsageDescription、NSMicrophoneUsageDescription和NSPhotoLibraryUsageDescription是强制性的。

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

当系统提示用户允许访问时，此字符串将作为对话框的一部分显示。

要添加此条目，您可以在安装插件时传递以下变量。

CAMERA_USAGE_DESCRIPTION用于NSCameraUsageDescription
MICROPHONE_USAGE_DESCRIPTION用于NSMicrophoneUsageDescription
PHOTOLIBRARY_USAGE_DESCRIPTION用于NSPhotoLibraryUsageDescription

示例

cordova plugin add cordova-plugin-media-capture --variable CAMERA_USAGE_DESCRIPTION="您的使用说明消息"

如果不传递变量，插件将添加一个空字符串作为值。

Windows Phone 7 小问题

在设备通过Zune连接时调用本机相机应用程序不起作用，并且错误回调执行。

浏览器小问题

仅在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错误代码。

支持的平台

Amazon Fire OS
Android
BlackBerry 10
iOS
Windows Phone 7 和 8
Windows 8
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});

BlackBerry 10 小问题

Cordova for BlackBerry 10尝试启动RIM提供的视频录制器应用程序来捕获视频记录。如果该应用程序未安装在设备上，则应用程序将接收一个CaptureError.CAPTURE_NOT_SUPPORTED错误代码。

CaptureAudioOptions

封装音频捕获配置选项。

属性

限制：设备用户在单个捕获操作中可以记录的最大音频片段数。该值必须大于或等于1（默认为1）。
持续时间：音频声音片段的最大持续时间，以秒为单位。

示例

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

Amazon Fire OS 问题

duration参数不受支持。无法通过程序限制录制长度。

Android 问题

duration参数不受支持。无法通过程序限制录制长度。

BlackBerry 10 问题

duration参数不受支持。无法通过程序限制录制长度。
limit参数不受支持，因此每次调用只能创建一个录制。

iOS 问题

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

CaptureImageOptions

封装图像捕获配置选项。

属性

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

示例

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

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

iOS 问题

限制参数不受支持，每次调用只拍摄一张图片。

CaptureVideoOptions

封装视频捕获配置选项。

属性

限制：设备用户在单个捕获操作中可以捕获的最大视频片段数。该值必须大于或等于1（默认为1）。
持续时间：视频片段的最大持续时间，以秒为单位。

示例

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

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

BlackBerry 10 问题

持续时间属性将被忽略，因此无法通过程序限制录制长度。

iOS 问题

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

Android 问题

Android 支持一个额外的 quality 属性，允许以不同的质量捕获视频。值 1（默认值）表示高质量，值 0 表示低质量，适合短信。有关详细信息，请参阅此处。

示例（Android带质量参数）

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

捕获错误

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

属性

code：下列预定义错误代码之一。

常量

CaptureError.CAPTURE_INTERNAL_ERR：相机或麦克风无法捕获图像或声音。
CaptureError.CAPTURE_APPLICATION_BUSY：相机或音频捕获应用程序当前正在处理另一个捕获请求。
CaptureError.CAPTURE_INVALID_ARGUMENT：API使用无效（例如，limit的值小于一）。
CaptureError.CAPTURE_NO_MEDIA_FILES：用户在捕获任何内容之前退出相机或音频捕获应用程序。
CaptureError.CAPTURE_PERMISSION_DENIED：用户拒绝了执行给定捕获请求所需的权限。
CaptureError.CAPTURE_NOT_SUPPORTED：请求的捕获操作不受支持。

捕获错误回调

在媒体捕获操作期间发生错误时调用。

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

描述

如果尝试启动媒体捕获操作时发生错误，则执行此函数。失败的场景包括捕获应用程序正在忙碌、正在执行捕获操作或用户在捕获任何媒体文件之前取消操作。

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

示例

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

配置数据

封装了一组设备支持的媒体捕获参数。

描述

描述设备支持的媒体捕获模式。配置数据包括视频或图像捕获的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回调。

支持的平台

Amazon Fire OS
Android
BlackBerry 10
iOS
Windows Phone 7 和 8
Windows 8
Windows

Amazon Fire OS 的一些特性

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

BlackBerry 10的一些特性

不提供获取媒体文件信息的API，因此所有MediaFileData对象都返回默认值。

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）

BlackBerry 10的一些特性

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

codecs: 不受支持，并返回null。
bitrate: 不受支持，并返回零。
height: 不受支持，并返回零。
width: 不受支持，并返回零。
duration: 不受支持，并返回零。

Amazon Fire OS 的一些特性

支持以下MediaFileData属性

codecs: 不受支持，并返回null。
bitrate: 不受支持，并返回零。
height: 支持：仅图像和视频文件。
width: 支持：仅图像和视频文件。
duration: 支持：仅音频和视频文件。

Android 的一些特性

支持以下MediaFileData属性

codecs: 不受支持，并返回null。
bitrate: 不受支持，并返回零。
height: 支持：仅图像和视频文件。
width: 支持：仅图像和视频文件。
duration: 支持：仅音频和视频文件。

苹果iOS的特有行为

支持以下MediaFileData属性

codecs: 不受支持，并返回null。
比特率：仅在iOS4设备上支持音频，图像和视频返回零。
height: 支持：仅图像和视频文件。
width: 支持：仅图像和视频文件。
duration: 支持：仅音频和视频文件。

安卓生命周期特有行为

在安卓平台上捕获音频、视频或图像时，有可能应用程序在原生日志捕获应用将Cordova WebView推送到后台后会被销毁。有关此问题的详细描述，请参阅安卓生命周期指南。在这种情况下，传递给捕获方法的成功和失败回调不会触发，而是通过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);

由您跟踪这些结果来自代码的哪个部分。确信在适当的暂停和恢复事件中保存和恢复应用程序的状态。请注意，这些事件仅在安卓平台上触发，并且仅在WebView在捕获操作过程中被销毁时触发。