Spec-Zone.ru › Cordova 7

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

Объекты

  • 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), и операция захвата завершается после записи пользователем одного аудиоклипа.

По завершении операции захвата CaptureCallback выполняется с массивом объектов MediaFile, описывающих каждый файл аудиоклипа. Если пользователь прерывает операцию до захвата аудиоклипа, CaptureErrorCallback выполняется с объектом 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 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), и операция захвата завершается после захвата пользователем одного изображения.

При завершении операции захвата вызывается обратный вызов CaptureCB с массивом объектов MediaFile, описывающих каждый файл захваченного изображения. Если пользователь прерывает операцию до захвата изображения, обратный вызов CaptureErrorCB выполняется с объектом CaptureError, содержащим код ошибки CaptureError.CAPTURE_NO_MEDIA_FILES.

Поддерживаемые платформы

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Браузер
  • iOS
  • Windows Phone 7 и 8
  • Windows 8
  • Windows

Особенности iOS

Начиная с iOS 10, обязательно добавить NSCameraUsageDescription, NSMicrophoneUsageDescription и NSPhotoLibraryUsageDescriptionentry в info.plist.

  • NSCameraUsageDescription описывает причину доступа приложения к камере пользователя.
  • NSMicrophoneUsageDescription описывает причину доступа приложения к микрофону пользователя.
  • NSPhotoLibraryUsageDescriptionentry описывает причину доступа приложения к фотобиблиотеке пользователя.

Когда система предлагает пользователю разрешить доступ, эта строка отображается в диалоговом окне.

Для добавления этой записи можно передать следующие переменные при установке плагина.

  • CAMERA_USAGE_DESCRIPTION для NSCameraUsageDescription
  • MICROPHONE_USAGE_DESCRIPTION для NSMicrophoneUsageDescription
  • PHOTOLIBRARY_USAGE_DESCRIPTION для NSPhotoLibraryUsageDescriptionentry

- Пример:

cordova plugin add cordova-plugin-media-capture --variable CAMERA_USAGE_DESCRIPTION="your usage message"

Если вы не передадите переменную, плагин добавит пустую строку в качестве значения.

Особенности Windows Phone 7

Вызов приложения камеры, когда устройство подключено через Zune, не работает, и выполняется обратный вызов с ошибкой.

Особенности браузера

Работает только в Chrome, Firefox и Opera (так как IE и Safari не поддерживают API navigator.getUserMedia).

Отображение изображений с помощью URL файла, захваченного в Chrome/Opera. 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), и операция захвата завершается после записи пользователем одного видеоклипа.

По завершении операции захвата 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 для BlackBerry 10 пытается запустить приложение Video Recorder, предоставленное RIM, для захвата видеозаписей. Приложение получает код ошибки CaptureError.CAPTURE_NOT_SUPPORTED если приложение не установлено на устройстве.

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

Особенности Amazon Fire OS

  • Параметр duration не поддерживается. Продолжительность записи не может быть ограничена программно.

Особенности Android

  • Параметр duration не поддерживается. Продолжительность записи не может быть ограничена программно.

Особенности BlackBerry 10

  • Параметр duration не поддерживается. Продолжительность записи не может быть ограничена программно.
  • Параметр limit не поддерживается, поэтому для каждого вызова может быть создана только одна запись.

Особенности 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: Максимальная продолжительность видеоклипа в секундах.

Пример

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

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

Особенности BlackBerry 10

  • Свойство duration игнорируется, поэтому длительность записей не может быть ограничена программно.

Особенности iOS

  • Свойство limit игнорируется. Запись одного видео выполняется за один вызов.

Особенности Android

  • Android поддерживает дополнительное свойство quality, позволяющее захватывать видео с разным качеством. Значение 1 (по умолчанию) означает высокое качество, а значение 0 означает низкое качество, подходящее для сообщений MMS. Подробнее см. здесь.

Пример (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
    }
};

CaptureError

Содержит код ошибки, возникшей при неудачной операции захвата медиа.

Свойства

  • 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: Запрошенная операция захвата не поддерживается.

CaptureErrorCB

Вызывается, если во время операции захвата медиа произошла ошибка.

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

Описание

Эта функция выполняется, если при попытке запуска операции захвата медиа произошла ошибка. Сценарии ошибок включают ситуации, когда приложение захвата занято, уже выполняется операция захвата или пользователь отменяет операцию, прежде чем какие-либо файлы медиа были захвачены.

Эта функция выполняется с объектом CaptureError, содержащим соответствующую ошибку code.

Пример

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

Описание

Эта функция асинхронно пытается получить информацию о формате файла медиа. При успехе она вызывает обратный вызов MediaFileDataSuccessCB с объектом MediaFileData. В случае неудачи функция вызывает обратный вызов 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: Дата и время последнего изменения файла. (Дата)

  • size: Размер файла в байтах. (Число)

Методы

  • MediaFile.getFormatData: Получает информацию о формате файла медиа.

MediaFileData

Содержит информацию о формате файла медиа.

Свойства

  • codecs: Фактический формат аудио и видео контента. (DOMString)

  • bitrate: Средняя битрейт контента. Значение равно нулю для изображений. (Число)

  • height: Высота изображения или видео в пикселях. Значение равно нулю для аудиоклипов. (Число)

  • width: Ширина изображения или видео в пикселях. Значение равно нулю для аудиоклипов. (Число)

  • duration: Длительность видео или аудиоклипа в секундах. Значение равно нулю для изображений. (Число)

Особенности BlackBerry 10

API не предоставляет информацию о формате файлов медиа, поэтому объект MediaFileData, возвращаемый MediaFile.getFormatData, имеет следующие значения по умолчанию:

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

  • bitrate: Поддерживается на устройствах iOS4 только для аудио. Возвращает ноль для изображений и видео.

  • height: Поддерживается: только для файлов изображений и видео.

  • width: Поддерживается: только для файлов изображений и видео.

  • duration: Поддерживается: только для аудио и видео файлов.

Особенности жизненного цикла Android

При захвате аудио, видео или изображений на платформе Android существует вероятность того, что приложение будет уничтожено после того, как Cordova Webview будет переведен в фоновый режим приложением native capture. Подробное описание проблемы см. в Руководстве по жизненному циклу Android. В этом случае события успеха и ошибки, переданные методу захвата, не будут вызваны, и вместо этого результаты вызова будут переданы через событие документа, которое срабатывает после события Cordova resume.

В вашем приложении вы должны подписаться на два возможных события следующим образом:

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

Вам нужно отслеживать, от какой части вашего кода эти результаты поступают. Убедитесь, что вы сохраняете и восстанавливаете состояние вашего приложения в рамках событий pause и resume, как это необходимо. Обратите внимание, что эти события будут срабатывать только на платформе Android и только когда Webview был уничтожен во время операции захвата.

© 2012, 2013, 2015 The Apache Software Foundation
Licensed under the Apache License 2.0.
https://cordova.apache.org/docs/en/7.x/reference/cordova-plugin-media-capture/index.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API