Spec-Zone.ru › Cordova 9

cordova-plugin-media-capture

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

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

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

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

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

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

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

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

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

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

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/9.x/reference/cordova-plugin-media-capture/index.html

Spec-Zone.ru

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