Spec-Zone.ru › Cordova 8

cordova-plugin-media-capture

Этот плагин предоставляет доступ к функциям записи аудио, изображений и видео на устройстве.

ПРЕДУПРЕЖДЕНИЕ: Сбор и использование изображений, видео или аудио с камеры или микрофона устройства поднимает важные вопросы конфиденциальности. Политика конфиденциальности вашего приложения должна обсуждать, как приложение использует такие датчики и делится ли записанные данные с другими сторонами. Кроме того, если использование камеры или микрофона не очевидно в пользовательском интерфейсе, вы должны предоставить уведомление в режиме реального времени перед доступом приложения к камере или микрофону (если операционная система устройства этого ещё не делает). Это уведомление должно содержать ту же информацию, что и выше, а также запрашивать разрешение пользователя (например, предлагая варианты OK и Нет, спасибо). Обратите внимание, что некоторые маркетплейсы приложений могут потребовать, чтобы ваше приложение предоставило уведомление в режиме реального времени и получило разрешение пользователя перед доступом к камере или микрофону. Для получения дополнительной информации см. Руководство по конфиденциальности.

Этот плагин определяет глобальный 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

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

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

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

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

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

  • Android
  • Браузер
  • iOS
  • Windows

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

С iOS 10 обязательно предоставлять описание использования в info.plist при попытке доступа к данным, чувствительным к конфиденциальности. Когда система запросит у пользователя разрешение на доступ, это описание использования будет отображено в диалоговом окне разрешения, но если вы не предоставите описание использования, приложение аварийно завершит работу до отображения диалога. Кроме того, Apple отклонит приложения, которые обращаются к конфиденциальным данным, но не предоставляют описание использования.

Этот плагин требует следующих описаний использования:

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

Чтобы добавить эти записи в info.plist, можно использовать тег edit-config в config.xml следующим образом:

<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 не поддерживают 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 код ошибки.

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

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

Пример

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

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

Особенности 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.

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

  • 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: Поддерживается на устройствах iOS 4 только для аудио. Возвращает ноль для изображений и видео.

  • 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 был уничтожен во время операции захвата.

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

Spec-Zone.ru

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