© 2009 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.
The camera API provides access to local camera devices to allow capturing video and photo.
CameraArray
CameraFeatureArray
FeatureValueArray
CameraSuccessCallback
CamerasRetrievedSuccessCallback
CameraLiveVideoSuccessCallback
CameraError
CameraManager
CaptureOptions
FeatureValue
CameraFeature
Camera
CameraManagerObject
| Interface | Method |
|---|---|
| CameraSuccessCallback | void onSuccess(DOMString file) |
| CamerasRetrievedSuccessCallback | void onSuccess(CameraArray cameras) |
| CameraLiveVideoSuccessCallback | void onSuccess(DOMString identifier) |
| CameraError | |
| CameraManager | PendingOperation getCameras(CamerasRetrievedSuccessCallback successCallback, ErrorCallback errorCallback) |
| CaptureOptions | |
| FeatureValue | |
| CameraFeature | |
| Camera | CameraFeatureArray getSupportedFeatures() void setFeature(unsigned short featureID, float value) PendingOperation requestLiveVideo(CameraLiveVideoSuccessCallback successCallback, ErrorCallback errorCallback) PendingOperation takePicture(CameraSuccessCallback successCallback, ErrorCallback errorCallback, CaptureOptions options) PendingOperation startVideo(SuccessCallback successCallback, ErrorCallback errorCallback, CaptureOptions options) PendingOperation stopVideo(CameraSuccessCallback successCallback, ErrorCallback errorCallback) |
| CameraManagerObject |
The camera API allows for capturing pictures and videos with the available device cameras. A list of cameras is provided and a preferred one can be selected based on the camera properties. To influence the camera's behavior, the API provides various configurable camera or media properties, e.g., camera resolution, flash light, and zoom. Additional, unspecified, parameters, e.g., special device dependent parameters, can be added to the standard set of configuration properties.
This is the URI used to declare this API's feature set, for use in bondi.requestFeature. For the URL, the list of features included by the feature set is provided.
All the Camera features
Includes API features:
http://bondi.omtp.org/api/camera.access
http://bondi.omtp.org/api/camera.capture
http://bondi.omtp.org/api/camera.record
This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.
When any of the features
http://bondi.omtp.org/api/camera.capture
http://bondi.omtp.org/api/camera.record
http://bondi.omtp.org/api/camera.access
is successfully requested, the interface
CameraManager
is instantiated, and the resulting object appears in the global
namespace as
Bondi.cameraManager.
Feature that allows for the detection of available cameras.
Device capabilities:
camera.access
Feature that allows for capturing a picture from a selected camera.
Device capabilities:
camera.capture
Feature that allows for capturing a video from a selected camera.
Device capabilities:
camera.record
camera.access
Retrieving camera hardware devices available on the device
camera.capture
Capturing an image by using a camera hardware device
camera.record
Recording a video by using a camera hardware device
CameraArray
Array that contains representations of available camera devices.
typedef sequence<Camera> CameraArray;
CameraFeatureArray
Array that contains the available camera features of a camera device.
typedef sequence<CameraFeature> CameraFeatureArray;
FeatureValueArray
Array that contains available values of a specific camera property.
typedef sequence<FeatureValue> FeatureValueArray;
CameraSuccessCallback
The camera API specific success callback.
[Callback=FunctionOnly, NoInterfaceObject] interface CameraSuccessCallback {
void onSuccess(in DOMString file);
};
The callback is used and called with a file identifier (e.g. full file reference) as input parameter if a picture of video was successfully captured.
onSuccess
The callback for successful video capturing and picture shots. The callback is called with a file reference in case of finished video capturing or picture shoots.
void onSuccess(in DOMString file);
CamerasRetrievedSuccessCallback
The camera API specific success callback for retrieving the available cameras.
[Callback=FunctionOnly, NoInterfaceObject] interface CamerasRetrievedSuccessCallback {
void onSuccess(in CameraArray cameras);
};
This callback is called after available local camera devices were detected and a list of cameras was created accordingly.
onSuccess
The success callback for retrieved cameras that are ready to use.
void onSuccess(in CameraArray cameras);
CameraLiveVideoSuccessCallback
The camera API specific success callback for retrieving a live video identifier.
[Callback=FunctionOnly, NoInterfaceObject] interface CameraLiveVideoSuccessCallback {
void onSuccess(in DOMString identifier);
};
This callback is called after a live video identifier is requestend and can be provided. The live video identifier can be a URL for streaming video that represents the live video or a device dependent identifier that allows for direct integration of the camera preview video into the Web content. See requestLiveVideo() for more information.
onSuccess
The success callback for provided live video identifiers.
void onSuccess(in DOMString identifier);
CameraError
The camera error interface
interface CameraError : GenericError {
const unsigned short CAMERA_ALREADY_IN_USE_ERROR = 0;
const unsigned short CAMERA_CAPTURE_ERROR = 1;
const unsigned short CAMERA_LIVEVIDEO_ERROR = 2;
};
The camera error interface defines error codes that are unique to the camera API.
unsigned short CAMERA_ALREADY_IN_USE_ERROR
Error thrown if the used camera is already in use.
unsigned short CAMERA_CAPTURE_ERROR
Error thrown if an unpredicted error occurs while a picture or video is being captured or if endRecording is called while no video is currently captured.
unsigned short CAMERA_LIVEVIDEO_ERROR
Error thrown if a camera live video cannot be provided.
CameraManager
Camera Manager that provides access to the device's available cameras.
interface CameraManager {
PendingOperation getCameras(in CamerasRetrievedSuccessCallback successCallback, in ErrorCallback errorCallback )
raises(SecurityError,DeviceAPIError);
};
The camera manager provides access to a list of available local camera devices. The number and type of available cameras depends on the device.
var camera;
bondi.camera.getCameras(onCameras, onError);
function onCameras(CameraArray cameras){
for (var i = 0; i < cameras.length; i++){
//select a camera by checking the camera description or the supported features
camera = cameras[i];
}
}
function onError(error) {
alert(error.code);
}
getCameras
Returns representations of available cameras.
PendingOperation getCameras(in CamerasRetrievedSuccessCallback successCallback, in ErrorCallback errorCallback);
The number of cameras that are accessible by the camera API depends on the number of available hardware devices as well as on the number of cameras that are supported by the implementation. To distinguish between multiple cameras the camera description and properties can be used to select a camera device. Also showing camera preview videos to let let the user choose a camera may an appropriate option.
PERMISSION_DENIED_ERROR when accessing the device cameras is denied by the security policy.
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
var camera;
bondi.camera.getCameras(onCameras, onError);
function onCameras(CameraArray cameras){
for (var i = 0; i < cameras.length; i++){
//select a camera by checking the camera description or the supported features
camera = cameras[i];
}
}
function onError(error) {
alert(error.code);
}
CaptureOptions
This interface specifies optional capture options for video and picture recordings.
interface CaptureOptions {
attribute unsigned short width;
attribute unsigned short height;
attribute float frameRate;
attribute DOMString mimeType;
attribute boolean audio;
attribute unsigned long maximumBitrate;
};
The optional capture options, used for taking a picture or starting a video record, allowing to specify the output format of the recorded picture or video, i.e., the capture options containing properties that have only effect to the recorded media. The values are used as hints about the desired file format and media properties. If any option cannot be satisfied by the device or implementation, e.g., due to any device or platform limitations, a close or similar value is automatically selected and used instead the given one.
As well as the whole capture options, each field is also optional. If a field is not set the implementation will automatically select an optimal value.
unsigned short width
The desired width of the video or picture.
The desired width of the video or picture. If a given value cannot be used by the implementation, e.g., due to hardware limitations, the best possible nearby value is automatically selected and used by the implementation.
unsigned short height
The desired height of the video or picture.
The desired height of the video or picture. If a given value cannot be used by the implementation, e.g., due to hardware limitations, the best possible nearby value is automatically selected and used by the implementation.
float frameRate
The desired frame rate for video records.
The desired frame rate for video records. If a given value cannot be used by the implementation, e.g., due to hardware limitations, the best possible nearby value is automatically selected and used by the implementation.
DOMString mimeType
The desired MIME type of the recorded video or picture.
The desired mimeType of the recorded video or picture. If a given value cannot be used by the implementation, e.g., due to hardware limitations, a most similar mime type is automatically selected and used by the implementation.
boolean audio
The desired state of audio for video recordings.
Forcing video records to include audio or not. The default value is true (on). The selected audio codec depends on the used video codec.
unsigned long maximumBitrate
The desired maxium bit rate of the recorded video media.
The desired maximum total bit rate in bits per second of the recorded media, which includes audio plus video bitrate. Usually the recorded media will have less visual quality if the bit rate drops. The default value used depends on the implementation, e.g., the used video and audio codecs, or if audio recording is enabled / disabled. By default, an implementation should provide the best possible qualitiy depending on the device's capabilities. If the desired bitrate cannot be applied, a close possible one is selected and used for audio and video encodings.
FeatureValue
Represents the value of a camera feature.
interface FeatureValue{
attribute float value;
attribute DOMString description;
};
A camera feature value, used within the CameraFeature interface, consisting of a value and a value description.
float value
The feature value identifier.
Feature configurations must be represented by an float identifier. This identifier must be unique according to a specific feature identifier. How the feature value identifier is interpreted to map to a specific feature value depends on the feature type, the specifications within this API, or on the implementation if additional camera features, which are not specified in this API version, are supported. For example, using FLASH_AUTOFLASH as feature value while configurating the FLASH feature must be interpreted as automatic flash mode.
DOMString description
A optional description of the feature value.
The optional description of a feature value that can be presented to the user. Its recommended to use this attribute if camera features which are not specified in this API are used.
CameraFeature
The CameraFeature interface represents a configurable feature provided by the camera.
interface CameraFeature{
const short FEATURETYPE_INTERVALL = 0;
const short FEATURETYPE_BINARY = 1;
const short FEATURETYPE_ENUMERATION = 2;
attribute DOMString description;
attribute long id;
attribute short type;
attribute FeatureValue value;
attribute FeatureValue default;
attribute FeatureValueArray possibleValues;
};
The CameraFeature covers the feature type, its value and default value, a feature descriptions that may be presented to the user, a feature id to use for the feature configuration, and a description of possible values for the feature. A feature's type can be an intervall, an enumeration, or binary.
short FEATURETYPE_INTERVALL
The feature type if the camera feature is represented by an intervall.
short FEATURETYPE_BINARY
The feature type if the camera feature is represented binary.
short FEATURETYPE_ENUMERATION
The feature type if the camera feature is represented by an enumeration.
DOMString description
A optional description of the feature.
The optional description of a feature that can be presented to the user. Its recommended to use this attribute if camera features which are not specified in this API are used.
long id
The unique feature identifier.
The unique identifier of a feature used to set a features value. For pre-defined features, e.g., camera features that are defined within this API, this id is globally unique. For additional features the id is locally unique whereas it is recommendet to use GUIDs.
short type
The type of the camera feature.
A camera feature configuration can be represented as an intervall, a binary value, or as an enumeration with an unrestricted set of possible values.
Intervall types having a minimum and a maximum float value whereas any value between both, including decimal numbers and intervall borders, is allowed. Intervall types may be configurable using sliders for getting the feature configuration. Exemplary intervall types are brightness and zoom.
The binary type should be used if only two values are possible. Examples are "ON" or "OFF", "ACTIVE" or "INACTIVE", or "ENABLED" or "DISABLED". A check box may be used to configure binary types. Exemplary binary types are night mode and the manual focus switch.
Enumeration types should be used if more than two options are possibled and the configuration is not represented by an intervall. Examples for that may be "FLASH OFF", "FLASH ON", and "AUTOMATIC flash". To configure enumeration types radio buttons may be presented to the user. As example, flash light is an enumeration type.
FeatureValue value
The current value of the camera feature.
FeatureValue default
The default value of the camera feature.
The default value of the camera feature that may be used to set the camera feature to its default value.
FeatureValueArray possibleValues
A set of feature values that represents the allowed feature configurations.
The meaning of the values depends on the feature type.
Two values are mandatory for feature type intervall. The first one must be the minimal allowed value and second one must be the maximum allowed value. For example, if possibleValues[0].value = 5 and possibleValues[1].value = 10 means that all values between 5 and 10 are allowed (including 5 and 10).
Also two values are mandatory for feature type binary. The first one must be a value that represents a negative choice (e.g., "off" or "disabled") whereas the feature value must be 0 (possibleValues[1].value = 0). The second one must be a value that represents a positive choice (e.g., "on" or "enabled") whereas the feature value must be 1 (possibleValues[1].value = 1).
An unrestricted set of possible feature values is allowed for the feature type enumeration whereas each entry represents one possible feature configuration. For example, possibleValues looks as follows for the FLASH feature: possibleValues[0].value = 0 possibleValues[0].description = "NO_OFF" //arbitrary text describing the feature value possibleValues[1].value = 1 possibleValues[1].description = "AUTO_FLASH" //arbitrary text describing the feature value possibleValues[2].value = 2 possibleValues[2].description = "FORCED_FLASH" //arbitrary text describing the feature value
Camera
The camera interface allows to use features provided by a camera device.
interface Camera {
readonly attribute DOMString description;
const unsigned short ZOOM = 0;
const unsigned short ZOOM_NOZOOM = 1;
const unsigned short CONTRAST = 2;
const unsigned short BRIGHTNESS = 3;
const unsigned short COLORTEMPERATURE = 4;
const unsigned short NIGHTMODE = 5;
const unsigned short NIGHTMODE_OFF = 0;
const unsigned short NIGHTMODE_ON = 1;
const unsigned short MANUALFOCUS = 6;
const unsigned short MANUALFOCUS_ON = 1;
const unsigned short MANUALFOCUS_OFF = 0;
const unsigned short FOCUS = 7;
const unsigned short LIGHT = 8;
const unsigned short FLASH = 9;
const unsigned short FLASH_NO_FLASH = 0;
const unsigned short FLASH_AUTOFLASH = 1;
const unsigned short FLASH_FORCEDFLASH = 2;
CameraFeatureArray getSupportedFeatures();
void setFeature(in unsigned short featureID, in float value)
raises(DeviceAPIError);
PendingOperation requestLiveVideo(in CameraLiveVideoSuccessCallback successCallback, in ErrorCallback errorCallback)
raises(SecurityError,DeviceAPIError);
PendingOperation takePicture(in CameraSuccessCallback successCallback,in ErrorCallback errorCallback,
[Optional] in CaptureOptions options)
raises(SecurityError,DeviceAPIError,CameraError);
PendingOperation startVideo(in SuccessCallback successCallback, in ErrorCallback errorCallback,
[Optional] in CaptureOptions options)
raises(SecurityError,DeviceAPIError,CameraError);
PendingOperation stopVideo(in CameraSuccessCallback successCallback, in ErrorCallback errorCallback)
raises(DeviceAPIError,CameraError);
};
The camera interface abstracts a hardware camera device that is accessible by the camera manager. Beside of taking pictures or recording videos different camera properties that effecting directly the visible picture can be set.
Namely the available camera properties are: zoom, flash, light, contrast, brightness, white balance, and focus.
unsigned short ZOOM
The zoom multiplier to use.
The applied zoom factor with the feature type INTERVALL whereas the minimum value is 1 which represents no applied zoom. If the set zoom factor cannot be applied, the next possible nearby value is selected automatically. For example, if the set value exceeds the device's maximum zoom factor the value is automatically set to the device's maximum zoom factor. The default value is 1 for no applied zoom, resp., for the wides angle supported by the camera. If the device does not support zooming getSupportedFeatures() will not return a feature that represents the zoom feature.
unsigned short ZOOM_NOZOOM
Constant zoom feature value representing a disabled zoom.
unsigned short CONTRAST
The contrast level configuration to use.
The contrast value influences the visible picture by adjusting how distinguishable objects to each other appear.
The feature type is intervall where valid values are between 0 and 100 (as percentage values) which represents the minimum possible contrast and the maximum possible contrast configuration that can be applied. The default value depends on the device and should reflect a natural looking picture. If the device does not support contrast configurations getSupportedFeatures() will not return a feature that represents the contrast feature.
unsigned short BRIGHTNESS
The brightness level configuration to use.
The brightness value influences the visible picture by adjusting how bright or dark the visible picture should appear.
The feature type is intervall where valid values are between 0 and 100 (as percentage values) and representing the minimum possible brightness and the maximum possible brightness value that can be applied. The default value depends on the device and should reflect a natural looking picture. If the device does not support brightness configurations getSupportedFeatures() will not return a feature that represents the brightness feature.
unsigned short COLORTEMPERATURE
The color temperature level configuration to use.
The colorTemperature value influences the visible picture by adjusting the color temperature.
The feature type is intervall where the minimum value indicates the the minimum possible color temperature and the maximum value indicates the maximum possible color temperature value that can be applied. The default value depends on the device and should reflect a natural looking picture. If the device does not support color temperature configurations getSupportedFeatures() will not return a feature that represents the color temperature feature.
unsigned short NIGHTMODE
The night mode configuration to use.
The night mode feature influences the visible picture by enabling a high light sensitivity to allow recording in dark environments.
The feature type is binary whereas valid values are only 0 and 1 which represents a disabled night mode respectively a enabled night mode. The default value is 0 (no night mode). If the device does not support night mode getSupportedFeatures() will not return a feature that represents the night mode feature.
unsigned short NIGHTMODE_OFF
Constant night mode feature value representing a disabled night mode.
unsigned short NIGHTMODE_ON
Constant night mode feature value representing an enabled night mode.
unsigned short MANUALFOCUS
Enables or disables the manual focus mode.
The feature type is binary where valid values are only 0 and 1 which represents automatic focus mode or using a manual focus configuration The default value is 0, i.e., using automatic focus. If the value is set to 1, the focus attribute configuration can be used to influence the focus distance. If the device does not support manual focus configurations getSupportedFeatures() will not return a feature that represents the focus mode.
unsigned short MANUALFOCUS_ON
Constant focus mode feature value representing an enabled manual focus.
unsigned short MANUALFOCUS_OFF
Constant focus mode feature value representing a disabled manual focus.
unsigned short FOCUS
The focus configuration to use.
The focus value influences the visible picture by adjusting the distance between the device and the focused object.
The feature type is intervall where the minimum value indicates the minumum needed distance between the camera and a focused object and the maximum value indicates the maximum distance between the camera and a focused object. The default value is 0 for the minimal distance. If the device does not support setting a manual focus configuration getSupportedFeatures() will not return a feature that represents the focus configuration feature.
unsigned short LIGHT
The light configuration to use.
The light feature influences the visible picture by configuring a built in light to allow records in dark environments.
The feature type is intervall whereas valid values are between 0 and 100 (including 0 and 100) and representing a disabled light (0) and the maximum luminance (100) that is possible on the device. Values between the minimum and maximum values can be used for dimmable lights. If a value configuration is not supported it is automatically set to the next possible value. The default value is 0 (disabled light). If the device does not support configuring a light getSupportedFeatures() will not return a feature that represents the light configuration feature.
unsigned short FLASH
Set the flash mode to apply on picture shoots.
The value type is enumeration where valid values are 0 for a disabled flash light, 1 for automatic flash light mode, and 2 for a forced flash light. The default value is 1 for automatic flash mode. Since flash is an enumeration type additional device dependent flash mode are possible. If the device does not support configuring the flash light getSupportedFeatures() will not return a feature that represents the flash light configuration feature.
unsigned short FLASH_NO_FLASH
Constant flash light mode feature value representing a disabled light.
unsigned short FLASH_AUTOFLASH
Constant flash light mode feature value representing autdisabled light.
unsigned short FLASH_FORCEDFLASH
Constant flash light mode feature value representing a forced flash light.
readonly
DOMString description
The camera description
The description of the camera, e.g., the camera name, camera type or any other description that should allow the identification of the camera, e.g., front or rear camera.
getSupportedFeatures
Gets a list of supported camera features.
CameraFeatureArray getSupportedFeatures();
Provides a list of supported camera features which can be configured with setFeature(). If a camera supports the pre-defined feature set, then they should be configurable with the use of the defined feature names and values. Additional features which are not covered by the pre-defined camera features can be added by implementations with a lack of pre-defined meanings for these features. Therefore, the feature name should be a human understandable description of the feature. Using pre-defined features names and values for other camera features is not allowed because this may change the meaning of a feature which may be important for applications.
The length of the list is 0 if no camera features are configurable.
setFeature
Sets the value of a camera feature.
void setFeature(in unsigned short featureID, in float value);
Sets the value of a given camera feature to the provided camera feature value. The allowed input parameters are either specified in this API for a base set of camera features or are device specific feature set extensions.
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
requestLiveVideo
Requests an identifier that represents the cameras live video preview.
PendingOperation requestLiveVideo(in CameraLiveVideoSuccessCallback successCallback, in ErrorCallback errorCallback);
Requsting a camera live video identifier that represents the location of the camera video preview. By providing a live video preview the actual video content can be embeded into the web context. Thus, a preview can be shown to the user and the camera API can be used to take pictures or record videos in parallel.
Two alternatives for the camera live video identifier can be considered:
The identifier can be a HTTP URL that points to a local video streaming server that streams the camera preview video to a video player client. In this case, each HTTP video streaming client (e.g. HTML5 video tag) can consume the provided live video. Implementations should provide the video in a fromat that is commonly provided by the platform to ensure proper video playback on the device. If the video playback client disconnects from the stream the streaming server can stop providing the camera preview.
The second identifier option is to provide a platform specific identifier (e.g. cam:\). This allows Web rendering engines to directly integrate the camera preview wherefore the HTML5 video tag must be used. Thus, the Web rendering engine must provide the HTML5 video tag and it must understand the platform specific camera identifier.
If the provided identifier is not an HTTP URL the application has to use the HTML5 video tag for a proper camera live view playback. Furthermore, the platform must understand the platform specif camera identifier to start the camera preview playback.
The successCallback is called if a live video identifier can be provided which is either a provided video stream or a platform dependent camera identifier that can be used within the HTML5 video tag.
If a live video feed integration cannot be provided...
PERMISSION_DENIED_ERROR when access is denied by the security policy.
CAMERA_LIVEVIDEO_ERROR if a live preview cannot be provided or on other live preview related errors.
INVALID_ARGUMENT_ERROR if input parameters or input values are invalid.
//use the first available camera device, in the sample code it is asumed that
//at least one camera is available
var camera;
// this function handles the error case
function onError(error) {
alert(error.code);
}
function onCameras(cameras){
camera = cameras[0];
}
bondi.camera.getCameras(onCameras,onError);
// this function handles the end record notification
function onPreview(DOMString identifier) {
//manipulating DOM, e.g., insert the identifier into an existing HTML5 video tag
}
camera.requestLiveVideo(onPreview, onError);
takePicture
PendingOperation takePicture(in CameraSuccessCallback successCallback, in ErrorCallback errorCallback, in CaptureOptions options);
startVideo
PendingOperation startVideo(in SuccessCallback successCallback, in ErrorCallback errorCallback, in CaptureOptions options);
stopVideo
PendingOperation stopVideo(in CameraSuccessCallback successCallback, in ErrorCallback errorCallback);
CameraManagerObject
Specifies what is instantiated at feature request
interface CameraManagerObject {
readonly attribute CameraManager cameraManager;
};
Bondi implements CameraManagerObject;