Spec-Zone.ru › Cordova 6

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

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

  • 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 поддерживает дополнительное свойство качество, чтобы разрешить захват видео с разным качеством. Значение 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 будет выведен в фоновый режим приложением захвата. Подробнее об этой проблеме см. в Руководстве по жизненному циклу 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/6.x/reference/cordova-plugin-media-capture/index.html

Spec-Zone.ru

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