Capture
Proporciona acceso a las capacidades de captura de audio, imagen, y vídeo del dispositivo.
Objetos
- Capture
- CaptureAudioOptions
- CaptureImageOptions
- CaptureVideoOptions
- CaptureCB
- CaptureErrorCB
- ConfigurationData
- MediaFile
- MediaFileData
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
- supportedAudioModes: Lo formatos de grabación de audio soportados en el dispositivo. (ConfigurationData[])
- supportedImageModes: Las resoluciones de imágenes y formatos soportados en el dispositivo. (ConfigurationData[])
- supportedVideoModes: Las resoluciones de vídeo y formatos soportados por el dispositivo. (ConfigurationData[])
Métodos
- capture.captureAudio: Inicia la aplicación del dispositivo para grabar clips de audio.
- capture.captureImage: Inicia la aplicación del dispositivo para tomar imágenes.
- capture.captureVideo: Inicia la aplicación del dispositivo para grabar vídeos.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
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
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
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
- PhoneGap para BlackBerry WebWorks intenta lanzar la aplicación Grabadora de notas de voz proporcionada por RIM para grabar audio. Si la aplicación no esta instalada se pasara un CaptureError. con el código
CAPTURE_NOT_SUPPORTED
.
Peculiaridades iOS
- iOS no tiene una aplicación por defecto para grabar audio, entonces se proporcionara una interfaz simple de grabación.
CaptureAudioOptions
Encapsula opciones personalizables para la captura de audio.
Atributos
- limit: El numero máximo de clips de audio que el dispositivo puede grabar en la misma operación. Debe ser mayor o igual a 1 (Por defecto: 1).
- duration: La duración máxima de un clip de audio, en segundos.
-
mode: El modo de audio seleccionado. Este valor debe coincidir con uno de los elementos en
capture.supportedAudioModes
.
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
- El argumento duration no esta soportado. La duración de la grabación no puede limitarse programaticamente.
- El argumento mode no esta soportado. El formato de grabación de audio no puede ser controlado programaticamente. Las grabaciones son codificadas usando el formato 'Adaptive Multi-Rate' (AMR) (audio/amr).
Peculiaridades BlackBerry WebWorks
- El argumento duration no esta soportado. La duración de la grabación no puede limitarse programaticamente.
- El argumento mode no esta soportado. El formato de grabación de audio no puede ser controlado programaticamente. Las grabaciones son codificadas usando el formato 'Adaptive Multi-Rate' (AMR) (audio/amr).
Peculiaridades iOS
- El argumento limit no esta soportado. Solo se puede grabar un clip de audio por cada operación.
- El argumento mode no esta soportado. El formato de grabación de audio no puede ser controlado programaticamente. El formato de grabación de audio no puede ser alterado programaticamente. Las grabaciones son codificadas usando el formato 'Waveform Audio' (WAV) (audio/wav).
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
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
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
- limit: El numero máximo de imágenes que el usuario podrá tomar en la misma operación. Debe ser mayor o igual a 1 (Por defecto: 1).
-
mode: El modo de imagen seleccionado. Este valor debe coincidir con uno de los definidos en
capture.supportedImageModes
.
Ejemplo Rápido
// limita la captura a 3 imágenes
var options = { limit: 3 };
navigator.device.capture.captureImage(captureSuccess, captureError, options);
Peculiaridades Android
- El argumento mode no esta soportado. La resolución de imagen y el formato no puede ser controlado programaticamente; en cambio, la resolución si puede ser cambiada por el usuario. Las imágenes son guardadas en formato JPEG (image/jpeg).
Peculiaridades BlackBerry WebWorks
- El argumento mode no esta soportado. La resolución de imagen y el formato no puede ser controlado programaticamente; en cambio, la resolución puede ser cambiada por el usuario. Las imágenes son guardadas en formato JPEG (image/jpeg).
Peculiaridades iOS
- El argumento limit no esta soportado. Solo se tomara una imagen por llamada.
- El argumento mode no esta soportado. La resolución de imagen y el formato no puede ser alterado programaticamente. Las imágenes son guardadas en formato JPEG (image/jpeg).
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
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
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
- Phonegap para BlackBerry WebWorks intentara iniciar la aplicación Grabadora de videos, que se distribuye en RIM. Si la aplicación no esta instalada se recibirá un objeto
CaptureError
con el códigoCAPTURE_NOT_SUPPORTED
.
CaptureVideoOptions
Encapsula opciones personalizables para la captura de vídeo.
Atributos
- limit: El numero máximo de clips de vídeos que el usuario podrá grabar en la misma operación. El valor debe ser mayor o igual a 1 (1 por defecto).
- duration: La duración máxima permitida de cada clip (en segundos).
-
mode: El modo de vídeo seleccionado. Este valor debe coincidir con uno de los definidos en
capture.supportedVideoModes
.
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
- El atributo duration no esta soportado. La duración de la grabación no puede limitarse programaticamente.
- El atributo mode no esta soportado. La resolución del vídeo y el formato no pueden ser controlados programaticamente; en cambio, esta opción puede ser cambiada por el usuario. Por defecto, los vídeos son grabados en formato 3GPP (vídeo/3gpp).
Peculiaridades BlackBerry WebWorks
- El atributo duration no esta soportado. La duración de la grabación no puede limitarse programaticamente.
- El atributo mode no esta soportado. La resolución del vídeo y el formato no pueden ser controlados programaticamente; en cambio, esta opción puede ser cambiada por el usuario. Por defecto, los vídeos son grabados en formato 3GPP (vídeo/3gpp).
Peculiaridades iOS
- El argumento limit no esta soportado. Solo se permite un vídeo por sesión.
- El argumento duration no esta soportado. La duración de la grabación no puede limitarse programaticamente.
- El argumento mode no esta soportado. La resolución del vídeo y el formato no pueden ser controlados programaticamente. Por defecto, los vídeos son grabados en formato MOV (vídeo/quicktime).
CaptureError
Encapsula el código de error resultante de una operación fallida.
Atributos
- code: Uno de los errores predefinidos en la lista inferior.
Constantes
-
CaptureError.
CAPTURE_INTERNAL_ERR
: La cámara o el micrófono fallo al capturar la imagen o el sonido. -
CaptureError.
CAPTURE_APPLICATION_BUSY
: La aplicación de cámara o de captura de audio esta siendo usada. -
CaptureError.
CAPTURE_INVALID_ARGUMENT
: Uso invalido de la API (ejem. el parámetro limit es menor que 1). -
CaptureError.
CAPTURE_NO_MEDIA_FILES
: El usuario cerro la aplicación de cámara o la de captura de audio antes de haber capturado nada. -
CaptureError.
CAPTURE_NOT_SUPPORTED
: La operación de captura solicitada no esta soportada.
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:
- vídeo/3gpp
- vídeo/quicktime
- image/jpeg
- audio/amr
- audio/wav
Atributos
- type: El tipo de archivo multimedia, codificado en ASCII y minúsculas. (DOMString)
- height: La altura de la imagen o vídeo en píxeles. En el caso de los clips de sonido, este atributo tiene un valor 0. (Number)
- width: La altura de la imagen o vídeo en píxeles. En el caso de los clips de sonidos, este atributo tiene un valor 0. (Number)
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
- name: El nombre del fichero, sin la ruta. (DOMString)
- fullPath: La ruta completa al fichero, incluido el nombre. (DOMString)
- type: El tipo MIME del fichero (DOMString)
- lastModifiedDate: La fecha y hora de la ultima modificación. (Date)
- size: El tamaño del fichero, en bytes. (Number)
Métodos
- MediaFile.getFormatData: Retorna información sobre el formato del archivo multimedia.
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
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
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
- codecs: El formato del fichero de audio o vídeo. (DOMString)
- bitrate: El bitrate medio del contenido. En el caso de una imagen, este atributo valdrá 0. (Number)
- height: La altura de una imagen o vídeo en píxeles. En el caso de un clip se sonido, este atributo valdrá 0. (Number)
- width: El ancho de una imagen o vídeo en píxeles. En el caso de un clip de sonido, este atributo valdrá 0. (Number)
- duration: La duración del clip de vídeo o sonido en segundos. En el caso de una imagen, este atributo valdrá 0. (Number)
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.
- codecs: No soportado. siempre retornara null.
- bitrate: No soportado. siempre retornara 0.
- height: No soportado. siempre retornara 0.
- width: No soportado. siempre retornara 0.
- duration: No soportado. siempre retornara 0.
Peculiaridades Android
El soporte de atributos de MediaFileData
es el siguiente:
- codecs: No soportado. siempre retornara null.
- bitrate: No soportado. siempre retornara 0.
- height: Soportado. (Solo ficheros de imagen y vídeo).
- width: Soportado. (Solo ficheros de imagen y vídeo).
- duration: Soportado. (Solo ficheros de imagen y vídeo).
Peculiaridades iOS
El soporte de atributos de MediaFileData
es el siguiente:
- codecs: No soportado. siempre retornara null.
- bitrate: Soportado en iOS4 y solo para audio. siempre retornara 0 en imágenes y vídeos.
- height: Soportado. (Solo en imágenes y vídeos).
- width: Soportado. (Solo en imágenes y vídeos).
- duration: Soportado. (Solo en audio y vídeos).