Este complemento brinda acceso a las capacidades de captura de audio, imagen y video del dispositivo.

ADVERTENCIA:   La recopilación y el uso de imágenes, videos o audio de la cámara o el micrófono del dispositivo plantea importantes problemas de privacidad. La política de privacidad de su aplicación debe analizar cómo la aplicación utiliza dichos sensores y si los datos registrados se comparten con otras partes. Además, si el uso de la cámara o el micrófono por parte de la aplicación no es evidente en la interfaz de usuario, debe proporcionar un aviso justo a tiempo antes de que la aplicación acceda a la cámara o al micrófono (si el sistema operativo del dispositivo aún no lo hace). ). Ese aviso debe proporcionar la misma información mencionada anteriormente, además de obtener el permiso del usuario (por ejemplo, presentando opciones para Aceptar y No, gracias). Tenga en cuenta que algunos mercados de aplicaciones pueden exigir que su aplicación proporcione un aviso justo a tiempo y obtenga permiso del usuario antes de acceder a la cámara o al micrófono.

Este complemento define   navigator.device.capture  el objeto global.

Aunque esta en el ámbito global, no estará disponible hasta después del evento deviceready.

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

Objects

• Capture
• CaptureAudioOptions
• CaptureImageOptions
• CaptureVideoOptions
• CaptureCallback
• CaptureErrorCB
• ConfigurationData
• MediaFile
• MediaFileData

Methods

• capture.captureAudio
• capture.captureImage
• capture.captureVideo
• MediaFile.getFormatData

Properties

• SupportedAudioModes:  los formatos de grabación de audio admitidos por el dispositivo. (Datos de configuración[])
• SupportImageModes:  los tamaños y formatos de imágenes de grabación admitidos por el dispositivo. (Datos de configuración[])
• SupportVideoModes:  las resoluciones y formatos de grabación de video admitidos por el dispositivo. (Datos de configuración[])

capture.captureAudio

Inicie la aplicación de grabación de audio y devuelva información sobre los archivos de clips de audio capturados.

navigator.device.capture.captureAudio(
    CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);

Description

Inicia una operación asincrónica para capturar grabaciones de audio utilizando la aplicación de grabación de audio predeterminada del dispositivo. La operación permite al usuario del dispositivo capturar múltiples grabaciones en una sola sesión.

La operación de captura finaliza cuando el usuario sale de la aplicación de grabación de audio o cuando se alcanza el número máximo de grabaciones especificado por CaptureAudioOptions.limit. Si no se especifica ningún valor de parámetro límite, el valor predeterminado es uno (1) y la operación de captura finaliza después de que el usuario graba un único clip de audio.

Cuando finaliza la operación de captura, CaptureCallback se ejecuta con una matriz de objetos MediaFile que describen cada archivo de clip de audio capturado. Si el usuario finaliza la operación antes de capturar un clip de audio, CaptureErrorCallback se ejecuta con un objeto CaptureError, que presenta el código de error CaptureError.CAPTURE_NO_MEDIA_FILES.

Ejemplo

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

capture.captureImage

Inicie la aplicación de la cámara y devuelva información sobre los archivos de imágenes capturadas.

navigator.device.capture.captureImage(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);

Description

Inicia una operación asincrónica para capturar imágenes usando la aplicación de cámara del dispositivo. La operación permite a los usuarios capturar más de una imagen en una sola sesión.

La operación de captura finaliza cuando el usuario cierra la aplicación de la cámara o cuando se alcanza el número máximo de grabaciones especificado por CaptureImageOptions.limit. Si no se especifica ningún valor límite, el valor predeterminado es uno (1) y la operación de captura finaliza después de que el usuario captura una sola imagen.

Cuando finaliza la operación de captura, invoca la devolución de llamada CaptureCB con una matriz de objetos MediaFile que describen cada archivo de imagen capturado. Si el usuario finaliza la operación antes de capturar una imagen, la devolución de llamada CaptureErrorCB se ejecuta con un objeto CaptureError que presenta un código de error CaptureError.CAPTURE_NO_MEDIA_FILES.

Ejemplo

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

Inicie la aplicación de grabación de video y devuelva información sobre los archivos de videoclips capturados.

navigator.device.capture.captureVideo(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);

Description

Inicia una operación asincrónica para capturar grabaciones de video utilizando la aplicación de grabación de video del dispositivo. La operación permite al usuario capturar más de una grabación en una sola sesión.

La operación de captura finaliza cuando el usuario sale de la aplicación de grabación de video o cuando se alcanza la cantidad máxima de grabaciones especificada por CaptureVideoOptions.limit. Si no se especifica ningún valor de parámetro límite, el valor predeterminado es uno (1) y la operación de captura finaliza después de que el usuario graba un único clip de vídeo.

Cuando finaliza la operación de captura, la devolución de llamada de CaptureCB se ejecuta con una serie de objetos MediaFile que describen cada archivo de videoclip capturado. Si el usuario finaliza la operación antes de capturar un clip de vídeo, la devolución de llamada CaptureErrorCB se ejecuta con un objeto CaptureError que presenta un código de error CaptureError.CAPTURE_NO_MEDIA_FILES.

Ejemplo

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

CaptureImageOptions

Encapsula las opciones de configuración de captura de imágenes.

Properties

• limit:  la cantidad máxima de imágenes que el usuario puede capturar en una sola operación de captura. El valor debe ser mayor o igual a 1 (el valor predeterminado es 1).

Ejemplo

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

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

CaptureVideoOptions

Encapsula las opciones de configuración de captura de video.

Properties

• limit:  la cantidad máxima de videoclips que el usuario del dispositivo puede capturar en una sola operación de captura. El valor debe ser mayor o igual a 1 (el valor predeterminado es 1).
• duration:  La duración máxima de un videoclip, en segundos.
• quality:  Para permitir capturar vídeo en diferentes calidades. Un valor de 1 (valor predeterminado) significa alta calidad y un valor de 0 significa baja calidad, adecuado para mensajes MMS.

Ejemplo

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

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

Consulte aquí para obtener más detalles sobre la propiedad de calidad en Android.

Ejemplo (con calidad)

// limit capture operation to 1 video clip of low quality
var options = { limit: 1, quality: 0 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

CaptureCB

Invocado tras una operación exitosa de captura de medios.

function captureSuccess( MediaFile[] mediaFiles ) { ... };

Description

Esta función se ejecuta después de que se completa una operación de captura exitosa. En este punto, se capturó un archivo multimedia y el usuario salió de la aplicación de captura multimedia o se alcanzó el límite de captura.

Cada objeto MediaFile describe un archivo multimedia capturado.

Ejemplo

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

Encapsula el código de error resultante de una operación fallida de captura de medios.

Properties

• code:  Uno de los códigos de error predefinidos que se enumeran a continuación.

Constants

• CaptureError.CAPTURE_INTERNAL_ERR : La cámara o el micrófono no pudieron capturar la imagen o el sonido.
• CaptureError.CAPTURE_APPLICATION_BUSY : La cámara o la aplicación de captura de audio actualmente está atendiendo otra solicitud de captura.
• CaptureError.CAPTURE_INVALID_ARGUMENT : Uso no válido de la API (p. ej., el valor del límite es inferior a uno).
• CaptureError.CAPTURE_NO_MEDIA_FILES : El usuario sale de la cámara o de la aplicación de captura de audio antes de capturar algo.
• CaptureError.CAPTURE_PERMISSION_DENIED : El usuario denegó el permiso necesario para realizar la solicitud de captura dada.
• CaptureError.CAPTURE_NOT_SUPPORTED : La operación de captura solicitada no es compatible.

CaptureErrorCB

Se invoca si se produce un error durante una operación de captura de medios.

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

Description

Esta función se ejecuta si se produce un error al intentar iniciar una operación de captura de medios. Los escenarios de falla incluyen cuando la aplicación de captura está ocupada, ya se está realizando una operación de captura o el usuario cancela la operación antes de que se capturen los archivos multimedia.

Esta función se ejecuta con un objeto CaptureError que contiene un código de error apropiado.

Ejemplo

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

ConfigurationData

Encapsula un conjunto de parámetros de captura de medios que admite un dispositivo.

Description

Describe los modos de captura de medios admitidos por el dispositivo. Los datos de configuración incluyen el tipo MIME y las dimensiones de captura para captura de vídeo o imagen.

• video/3gpp
• video/quicktime
• image/jpeg
• audio/amr
• audio/wav

Properties

• type:  uno de los códigos de error predefinidos que se enumeran a continuación. (DOMString)
• height:  La altura de la imagen o video en píxeles. El valor es cero para los clips de sonido. (Number)
• width:  El ancho de la imagen o video en píxeles. El valor es cero para los clips de sonido. (Number)

MediaFile.getFormatData

Recupera información de formato sobre el archivo de captura multimedia.

mediaFile.getFormatData(
    MediaFileDataSuccessCB successCallback,
    [MediaFileDataErrorCB errorCallback]
);

Description

Esta función intenta recuperar de forma asincrónica la información de formato del archivo multimedia. Si tiene éxito, invoca la devolución de llamada MediaFileDataSuccessCB con un objeto MediaFileData. Si el intento falla, esta función invoca la devolución de llamada MediaFileDataErrorCB.

La API para acceder a la información del formato de archivos multimedia es limitada, por lo que no se admiten todas las propiedades de MediaFileData.

MediaFile

Encapsula las propiedades de un archivo de captura multimedia.

Properties

• name:  el nombre del archivo, sin información de ruta. (DOMString)
• fullPath:  la ruta completa del archivo, incluido el nombre. (Number)
• type:  el tipo mime del archivo (Number)
• lastModifiedDate:  la fecha y hora en que se modificó el archivo por última vez. (Number)
• size:  el tamaño del archivo, en bytes. (Number)

Methods

• MediaFile.getFormatData:  recupera la información de formato del archivo multimedia.

MediaFileData

Encapsula información de formato sobre un archivo multimedia.

Properties

• height:  La altura de la imagen o video en píxeles. El valor es cero para los clips de audio. Compatible: solo archivos de imagen y vídeo. (Number)
• width:  El ancho de la imagen o video en píxeles. El valor es cero para los clips de audio. Compatible: solo archivos de imagen y vídeo. (Number)
• duration:  La duración del vídeo o clip de sonido en segundos. El valor es cero para las imágenes. Compatible: solo archivos de audio y vídeo. (Number)

Methods

• MediaFile.getFormatData:  recupera la información de formato del archivo multimedia.

Android Lifecycle Quirks

Al capturar audio, vídeo o imágenes en la plataforma Android, existe la posibilidad de que la aplicación se destruya después de que la aplicación de captura nativa pase la vista web a un segundo plano. En este caso, las devoluciones de llamadas de éxito y fracaso pasadas al método de captura no se activarán y, en cambio, los resultados de la llamada se entregarán a través de un evento de documento que se activa después del evento de reanudación.

En tu aplicación, debes suscribirte a los dos eventos posibles así:

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

Depende de usted rastrear de qué parte de su código provienen estos resultados. Asegúrese de guardar y restaurar el estado de su aplicación como parte de los eventos de pausa y reanudación según corresponda. Tenga en cuenta que estos eventos solo se activarán en la plataforma Android y solo cuando la vista web se destruyó durante una operación de captura.