Capture

Capture

Proporciona acceso a las capacidades de captura de audio, imagen, y vídeo del dispositivo.

Objetos

Métodos

Ámbito de la variable

El objeto capture es asignado al objeto navigator.device, y por lo tanto, tiene una visibilidad global.

// El objeto global `capture`
var capture = navigator.device.capture;

Atributos

Métodos

Plataformas Soportadas


capture.captureAudio

Inicia la aplicación del dispositivo de grabación de audio y retorna información sobre el fichero capturado.

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

Descripción

Este método inicia una operación asíncrona de captura de audio usando la aplicación por defecto para la grabación de audio. Esta operación permite al usuario realizar varias grabaciones de una misma vez.

La operación termina cuando el usuario sale de la aplicación de grabación, o cuando se alcanza el numero máximo de grabaciones especificadas por la opción limit del argumento CaptureAudioOptions. Si no se especifica un valor para limit, por defecto sera 1, y la aplicación se cerrara tras grabar un solo clip.

Cuando termina la captura, se llamara a la función 'callback' CaptureCB con el array de objetos MediaFile. Si la aplicación de grabación es cerrada por el usuario sin grabar nada, se llamara a la función CaptureErrorCB pasándole un objeto CaptureError con el código CAPTURE_NO_MEDIA_FILES.

Plataformas Soportadas

Ejemplo Sencillo

// función 'callback' satisfactoria
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // hacer algo interesante con el fichero...
    }
};

// función 'callback' de error
var captureError = function(error) {
    navigator.notification.alert('Código de error: ' + error.code, null, 'Error de captura');
};

// inicia la captura de audio
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Capture</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Llamado cuando termine la operación de captura
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }       
    }

    // Llamado cuando ocurra algo mal.
    // 
    function captureError(error) {
        var msg = 'Ocurrió un error durante la captura: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // Un botón llamara a esta función
    //
    function captureAudio() {
        // Inicia la aplicación del dispositivo de captura de audio
        // permitiendo al usuario capturar hasta 2 clips de audio.
        navigator.device.capture.captureAudio(captureSuccess, captureError, {limit: 2});
    }

    // Subir ficheros al servidor
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Subida correcta: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes enviados');
            },
            function(error) {
                console.log('Error subiendo el fichero ' + path + ': ' + error.code);
            },
            { fileName: name });   
    }

    </script>
    </head>
    <body>
        <button onclick="captureAudio();">Capturar audio</button> <br>
    </body>
</html>

Peculiaridades BlackBerry WebWorks

Peculiaridades iOS


CaptureAudioOptions

Encapsula opciones personalizables para la captura de audio.

Atributos

Ejemplo Rápido

// Limita la operación de captura a 3 ficheros de audio, de no mas de 10 segundos cada uno
var options = { limit: 3, duration: 10 };

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

Peculiaridades Android

Peculiaridades BlackBerry WebWorks

Peculiaridades iOS


capture.captureImage

Inicia la aplicación de cámara y retorna información sobre los ficheros de imágenes capturados.

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

Descripción

Este método inicia una operación asíncrona para capturar imágenes usando la aplicación de cámara del dispositivo. Se pueden tomar varias imágenes en una sola sesión. La operación de captura termina cuando el usuario sale de la aplicación de cámara, o cuando se alcanza el numero máximo de imágenes especificado en la opción limit de CaptureImageOptions. Si no se especifica ningún valor, se usara 1 por defecto. Cuando la operación de captura termine, llamara a la función 'callback' CaptureCB con un array de objetos MediaFile con información sobre las imágenes capturadas. Si el usuario cierra la aplicación antes de capturar ninguna imagen, se lanzara la función 'callback' CaptureErrorCB pasándole de argumento un CaptureError con código CAPTURE_NO_MEDIA_FILES.

Plataformas Soportadas

Ejemplo Rápido

// Función 'callback' de captura
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // hacer algo interesante con el fichero
    }
};

// función 'callback' de error
var captureError = function(error) {
    navigator.notification.alert('Código de error: ' + error.code, null, 'Capture Error');
};

// Inicia la captura de imágenes
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Capture</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Función 'callback' satisfactoria
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }       
    }

    // Llamada si algún error ocurre.
    // 
    function captureError(error) {
        var msg = 'Ocurrió un error mientras se capturaba: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // Un botón llamara esta función
    //
    function captureImage() {
        // Lanza la aplicación de cámara, 
        // y permite capturar hasta 2 imágenes
        navigator.device.capture.captureImage(captureSuccess, captureError, {limit: 2});
    }

    // Sube los ficheros al servidor
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Subida correcta: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes enviados');
            },
            function(error) {
                console.log('Error en la subida del fichero ' + path + ': ' + error.code);
            },
            { fileName: name });   
    }

    </script>
    </head>
    <body>
        <button onclick="captureImage();">Capturar imagen</button> <br>
    </body>
</html>

CaptureImageOptions

Encapsula opciones personalizables para la captura de imágenes.

Atributos

Ejemplo Rápido

// limita la captura a 3 imágenes
var options = { limit: 3 };

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

Peculiaridades Android

Peculiaridades BlackBerry WebWorks

Peculiaridades iOS


capture.captureVideo

Inicia la aplicación de cámara de vídeo y retorna información sobre los clips de vídeo capturados.

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

Descripción

Este método inicia una operación asíncrona para capturar clips de vídeo usando la aplicación de cámara del dispositivo. Se pueden grabar varios clips en una sola sesión. El proceso de captura finaliza cuando el usuario sale de la aplicación de grabación, o cuando se alcanza el numero máximo de grabaciones especificado en la opción limit de CaptureVideoOptions. Si no se especifica un valor se tomara 1 por defecto, y la aplicación se cerrara tras grabar un clip de vídeo.

Cuando la aplicación termine, se llamara a la función 'callback' pasándole un array de objetos MediaFile describiendo cada fichero de vídeo. Si el proceso es cancelado por el usuario sin capturar ningún vídeo, se lanzara la función 'callback' CaptureErrorCB pasándole un objeto CaptureError con el código de error CAPTURE_NO_MEDIA_FILES.

Plataformas Soportadas

Ejemplo Rápido

// Función 'callback' de captura
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // hacer algo interesante con los ficheros
    }
};

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

// Inicia la captura de vídeo
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de Capture</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Llamado cuando el proceso de captura finalice
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }       
    }

    // Llamado si ocurre algún error
    // 
    function captureError(error) {
        var msg = 'Ocurrió un error mientras se capturaba: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // Un botón llamara esta función
    //
    function captureVideo() {
        // Inicia la aplicación de grabación
        // y permite capturar hasta 2 clips de vídeo
        navigator.device.capture.captureVideo(captureSuccess, captureError, {limit: 2});
    }

    // Sube los ficheros al servidor
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Subida correcta: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes enviados');
            },
            function(error) {
                console.log('Error en la subida del fichero ' + path + ': ' + error.code);
            },
            { fileName: name });   
    }

    </script>
    </head>
    <body>
        <button onclick="captureVideo();">Capturar vídeo</button> <br>
    </body>
</html>

Peculiaridades BlackBerry WebWorks


CaptureVideoOptions

Encapsula opciones personalizables para la captura de vídeo.

Atributos

Ejemplo Rápido

// limita la captura a 3 clips de vídeo
var options = { limit: 3 };

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

Peculiaridades Android

Peculiaridades BlackBerry WebWorks

Peculiaridades iOS


CaptureError

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

Atributos

Constantes


CaptureCB

Llamado tras una captura correcta.

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

Descripción

Esta función se llama después de que se complete una operación de captura. Esto quiere decir cuando se capture un fichero y el usuario salga de la aplicación, o cuando se alcance el limite máximo.

Cada objeto MediaFile describe un fichero multimedia capturado.

Ejemplo Rápido

// función 'callback' satisfactoria
function captureSuccess(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // hacer algo interesante con el fichero
    }
};

CaptureErrorCB

Llamada si ocurre un error durante la captura.

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

Descripción

Esta función sera llamada si ocurre un error mientras se intenta lanzar la aplicación de captura y esta estuviera ocupada, si no pudiera capturar por algún problema, o si la operación fuera cancelada por el usuario sin capturar nada.

Se le pasara un objeto CaptureError que contiene el código de error especifico.

Ejemplo Rápido

// Función 'callback' de error
var captureError = function(error) {
    navigator.notification.alert('Código de error: ' + error.code, null, 'Error de captura');
};

ConfigurationData

Encapsula un conjunto de parámetros de captura que el dispositivo soporta.

Descripción

Este objeto se usa para enumerar los modos de captura soportados en el dispositivo. Los datos incluyen el tipo MIME, y la resolución de la captura (en el caso de vídeo y imágenes).

Los tipos MIME de archivos deberían adherirse al RFC2046.

Ejemplos:

Atributos

Ejemplo Rápido

// retornar los modos de imágenes soportados
var imageModes = navigator.device.capture.supportedImageModes;

// selecciona el modo que tenga la mayor resolución horizontal
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
    if (mode.width > width) {
        width = mode.width;
        selectedmode = mode;
    }
}

No soportado por ninguna plataforma. Todos los array de configuración están vacíos.


MediaFile

Encapsula atributos de un fichero multimedia capturado.

Atributos

Métodos


MediaFile.getFormatData

Retorna información sobre el formato de los archivos multimedia capturados.

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

Descripción

Esta función funciona de forma asíncrona e intentara retornar información sobre el formato de los archivos multimedia. Si la función termina correctamente, se llamara a la función 'callback' MediaFileDataSucessCB con el objeto MediaFileData. Si en cambio ocurre algún error, se llamara a MediaFileDataErrorCB.

Plataformas Soportadas

Peculiaridades BlackBerry WebWorks

No se dispone de ninguna API que proporcione información sobre el formato de los archivos multimedia. Por tanto, todos los objetos MediaFileData serán devueltos con los valores por defecto. Consulta la documentación de MediaFileData.

Peculiaridades Android

La API para obtener los formatos de archivos multimedia esta limitada. Por tanto, no están soportados todos los atributos de MediaFileData. Consulta la documentación de MediaFileData.

Peculiaridades iOS

La API para obtener los formatos de archivos multimedia esta limitada. Por tanto, no están soportados todos los atributos de MediaFileData. Consulta la documentación MediaFileData.


MediaFileData

Encapsula información sobre el formato del archivo multimedia.

Atributos

Peculiaridades BlackBerry WebWorks

No se dispone de ninguna API que proporcione información sobre el formato de los archivos multimedia. Entonces el objeto MediaFileData retornado por MediaFile.getFormatData tendrán los siguientes valores por defecto.

Peculiaridades Android

El soporte de atributos de MediaFileData es el siguiente:

Peculiaridades iOS

El soporte de atributos de MediaFileData es el siguiente: