Camera API (Tizen Extension)

This API module provides interfaces for configuring camera options, recording video/audio, and capturing images. The API is designed to work together with navigator.getUserMedia() API to access media stream object and with video element to provide camera preview.

Since: 2.2

Table of Contents

Summary of Interfaces and Methods

Interface Method
NavigatorTizenCamera
TizenCamera void createCameraControl (MediaStream stream, CreateCameraSuccessCallback successCallback, CameraErrorCallback errorCallback)
CreateCameraSuccessCallback void handleEvent (CameraControl cameraControl)
CameraErrorCallback void handleEvent (CameraError error)
CameraControl void applySettings (CameraControlSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror)
boolean autoFocus ()
void release ()
CameraControlSettings
CameraSuccessCallback void handleEvent ()
CameraSettingErrorCallback void handleEvent (CameraSettingErrors errors)
CameraMediaRecorder void applySettings (CameraRecorderSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror)
void start (CameraSuccessCallback onsuccess, CameraErrorCallback onerror)
void stop (CameraSuccessCallback onsuccess, CameraErrorCallback onerror)
CameraImageCapture void applySettings (CameraPictureSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror)
void takePicture (CameraSuccessCallback onsuccess, CameraErrorCallback onerror)
CameraCapabilities
CameraSize
CameraArea
CameraPictureSettings
CameraRecorderSettings
CameraError
CameraSettingErrors

1. Interfaces

1.1. NavigatorTizenCamera

This interface defines a global object (under navigator) that exposes a single interface for creating a CameraControl object. 
    [NoInterfaceObject] interface NavigatorTizenCamera {

        readonly attribute TizenCamera tizCamera;
    };
    Navigator implements NavigatorTizenCamera;

Since: 2.2

Attributes

  • readonly TizenCamera tizCamera
    An attribute to store tizen camera object.

    Since: 2.2

1.2. TizenCamera

This interface defines a factory method to create CameraControl object given the MediaStream object as input. 
    [NoInterfaceObject] interface TizenCamera {

        void createCameraControl(MediaStream stream, CreateCameraSuccessCallback successCallback, CameraErrorCallback errorCallback);
    };

Since: 2.2

Methods

createCameraControl
Asynchronously create CameraControl object using input stream. 
void createCameraControl(MediaStream stream, CreateCameraSuccessCallback successCallback, CameraErrorCallback errorCallback);

Since: 2.2

Privilege level: public

Privilege: http://tizen.org/privilege/camera

Privilege: http://tizen.org/privilege/audiorecorder

Remark : For video recording and image capture, use http://tizen.org/privilege/camera privilege. For audio recording, use http://tizen.org/privilege/audiorecorder privilege.

Parameters:

  • stream: Stream object obtained from getUserMedia. "audio" of MediaStreamOptions dictionary is supported
  • successCallback: The method to invoke when CameraControl object is created successfully.
  • errorCallback: The method to invoke when an error occurs.

Code example:

 navigator.webkitGetUserMedia({video:true,audio:true}, gotStream, noStream);

 // For audio recording, use the API as following:
 // navigator.webkitGetUserMedia({video:false,audio:true}, gotStream, noStream);

 // WARNING :
 // Audio recording is not supported in initial target platform verison 2.2.1.
 // Please include following checking and guideline for end user.
 // if (tizen.systeminfo.getCapabilities().platformVersion === "2.2.1") {
 //     // Inform the user to upgrade his/her system OS to properly use this application.
 // }

 function gotStream(stream) {
   navigator.tizCamera.createCameraControl(stream, gotCamera, noCamera);
 }

 function noStream() {
 }

 function gotCamera(cam) {//CameraControl
   camera = cam;
 }

 function noCamera() {
 }

1.3. CreateCameraSuccessCallback

The success callback for TizenCamera.createCameraControl(). 
    callback interface CreateCameraSuccessCallback {

        void handleEvent(CameraControl cameraControl);
    };

Since: 2.2

Methods

handleEvent
Called on successful creation of Camera Control object. 
void handleEvent(CameraControl cameraControl);

Since: 2.2

Parameters:

  • cameraControl: Created camera control.

1.4. CameraErrorCallback

The error callback for any camera error. 
    callback interface CameraErrorCallback {

        void handleEvent(CameraError error);
    };

Since: 2.2

Methods

handleEvent
Called upon Camera API call errors. 
void handleEvent(CameraError error);

Since: 2.2

Parameters:

  • error: Error that occurred.

1.5. CameraControl

This interface defines attributes and methods to configure camera options, record audio/video, and capture image. 
    [NoInterfaceObject] interface CameraControl {

        readonly attribute CameraCapabilities   capabilities;

        readonly attribute CameraMediaRecorder  recorder;

        readonly attribute CameraImageCapture   image;


        void applySettings(CameraControlSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);

        boolean autoFocus();

        void release();
    };

Since: 2.2

Attributes

  • readonly CameraCapabilities capabilities
    Represents a collection of camera capabilities that camera device provides.

    Since: 2.2

  • readonly CameraMediaRecorder recorder
    Represents an object defines media recording related methods.

    Since: 2.2

  • readonly CameraImageCapture image
    Represents an object defines image capture related methods.

    Since: 2.2

Methods

applySettings
Method to apply new settings to CameraControl object. 
void applySettings(CameraControlSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);

Since: 2.2

Parameters:

  • settings: Settings for camera.
  • onsuccess: The method to invoke when a new setting is applied successfully.
  • onerror: The method to invoke when setting related error occurs.
autoFocus
Method responsible for autofocus. 
boolean autoFocus();

Since: 2.2

release
Method to release the camera resource when an application exits the use of camera. 
void release();

Since: 2.2

1.6. CameraControlSettings

The CameraControlSettings object is used as setting parameter in applySettings method. 
    dictionary CameraControlSettings {

        CameraArea focusArea;
    };

Since: 2.2

Dictionary members

CameraArea focusArea
Specifies focus area bounds.

Since: 2.2

1.7. CameraSuccessCallback

Success callback interface for camera methods. 
    callback interface CameraSuccessCallback {

        void handleEvent();
    };

Since: 2.2

Methods

handleEvent
Called on success. 
void handleEvent();

Since: 2.2

1.8. CameraSettingErrorCallback

Error callback interface for applySettings method. 
        callback interface CameraSettingErrorCallback {

            void handleEvent(CameraSettingErrors errors);
        };

Since: 2.2

Methods

handleEvent
Called on error. 
void handleEvent(CameraSettingErrors errors);

Since: 2.2

Parameters:

  • errors: Containing error codes.

1.9. CameraMediaRecorder

This interface defines media recording related methods. 
    [NoInterfaceObject] interface CameraMediaRecorder {

        attribute   onrecordingstatechange;


        void applySettings(CameraRecorderSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);


        void start(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);


        void stop(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);
    };

Since: 2.2

Attributes

  • EventHandler onrecordingstatechange
    Recording state change event handler.

    Since: 2.2

Methods

applySettings
Set new settings for camera recording. 
void applySettings(CameraRecorderSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);

Since: 2.2

Parameters:

  • settings: New settings for camera recording.
  • onsuccess: The method to invoke when new settings is applied successfully.
  • onerror: The method to invoke when some error occurs.
start
Start recording video using camera device. 
void start(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);

Since: 2.2

Parameters:

  • onsuccess: The method to invoke when recording is started successfully.
  • onerror: The method to invoke when some error occurs.
stop
Stop recording video using camera device. 
void stop(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);

Since: 2.2

Parameters:

  • onsuccess: The method to invoke when recording is started successfully.
  • onerror: The method to invoke when en error occurs.

1.10. CameraImageCapture

This interface defines image capture related methods. 
    [NoInterfaceObject] interface CameraImageCapture {

        attribute  onshutter;

        void applySettings(CameraPictureSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);

        void takePicture(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);
    };

Since: 2.2

Attributes

  • EventHandler onshutter
    Shutter event handler.

    Since: 2.2

Methods

applySettings
Set new settings for camera image capture. 
void applySettings(CameraPictureSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);

Since: 2.2

Parameters:

  • settings: New settings for photo.
  • onsuccess: The method to invoke when new settings is applied successfully.
  • onerror: The method to invoke when en error occurs.
takePicture
Take picture using camera. 
void takePicture(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);

Since: 2.2

Parameters:

  • onsuccess
  • onerror

1.11. CameraCapabilities

This interface defines a collection of camera capabilities that the camera device provides. 
    [NoInterfaceObject] interface CameraCapabilities {

        readonly attribute CameraSize[] pictureSizes;

        readonly attribute DOMString[]  pictureFormats;

        readonly attribute DOMString[]  recordingFormats;
    };

Since: 2.2

Attributes

  • readonly CameraSize[] pictureSizes
    Array containing available picture sizes.

    The following values must be supported:

    Device

    • [320, 240]
    • [320, 320]
    • [640, 480]
    • [640, 640]
    • [1280, 720]
    • [1280, 960]

    Emulator

    • [320, 240]
    • [640, 480]

    Since: 2.2

  • readonly DOMString[] pictureFormats
    Array containing available picture formats.

    The following formats must be supported:

    • "jpeg"
    • "png"

    Since: 2.2

  • readonly DOMString[] recordingFormats
    Array containing available picture formats.

    The following formats must be supported:

    • "3gp"
    • "amr"

    Since: 2.2

1.12. CameraSize

Camera size dictionary. 
    dictionary CameraSize {

        long width;

        long height;
    };

Since: 2.2

Dictionary members

long width
Width of photo/video.

Since: 2.2

long height
Height of photo/video.

Since: 2.2

1.13. CameraArea

Camera area is used to choose specific metric and focus area for the camera, and it contains position of bounds of the area. 
    dictionary CameraArea {

        long top;

        long left;

        long bottom;

        long right;
    };

Since: 2.2

Dictionary members

long top
Top position of selected area.

Since: 2.2

long left
Left position of selected area.

Since: 2.2

long bottom
Bottom position of selected area.

Since: 2.2

Right position of selected area.

Since: 2.2

1.14. CameraPictureSettings

Camera picture settings is used to set the size, the format, and the file name of pictures. 
    dictionary CameraPictureSettings {

        CameraSize pictureSize;

        DOMString pictureFormat;

        DOMString fileName;
    };

Since: 2.2

Dictionary members

CameraSize pictureSize
Contains size of picture. Only sizes in CameraCapabilities are allowed.

Since: 2.2

DOMString pictureFormat
Picture format. Available formats described in CameraCapabilities.pictureFormats.

Since: 2.2

DOMString fileName
File name (without directory) of the picture taken. Files are stored in "/opt/usr/media/Images".

Since: 2.2

1.15. CameraRecorderSettings

Camera recorder settings is used to set the maximum file size, the recording format, and the file name of recording video. 
    dictionary CameraRecorderSettings {


        long maxFileSizeBytes;

        DOMString recordingFormat;

        DOMString fileName;
    };

Since: 2.2

Dictionary members

long maxFileSizeBytes
Max size of file in bytes. Maximum file size is 10MB (10485760 bytes).

Since: 2.2

DOMString recordingFormat
Format of recording video. Available formats are listed in CameraCapabilities.recordingFormats.

Since: 2.2

DOMString fileName
File name (without directory) of the recorded video. Files are stored in "/opt/usr/media/Videos".

Since: 2.2

1.16. CameraError

This interface defines attributes of object passed as error to CameraErrorCallback. 
    [NoInterfaceObject] interface CameraError {

        readonly attribute unsigned short code;

        const unsigned short CREATION_FAILED = 0;

        const unsigned short PERMISSION_DENIED = 1;

        const unsigned short NO_CAMERA = 2;

        const unsigned short PIPELINE_ERR = 3;

    const unsigned short FILE_WRITE_ERR = 4;
    };

Since: 2.2

Constants

  • CREATION_FAILED
    Code for error occurred during object creation.

    Since: 2.2



  • PERMISSION_DENIED
    Code for error occurred on permission denied exception.

    Since: 2.2



  • NO_CAMERA
    Code for error occurred when device has no available camera.

    Since: 2.2



  • PIPELINE_ERR
    Code for error occurred on pipeline error.

    Since: 2.2



  • FILE_WRITE_ERR
    Code for error occurred during write to file.

    Since: 2.2



    • Attributes

    • readonly unsigned short code
      Error code.

      Since: 2.2

    1.17. CameraSettingErrors

    Error This interface defines attributes of object passed as error to CameraSettingErrorCallback. 
        [NoInterfaceObject] interface CameraSettingErrors {

        readonly attribute unsigned short[] codes;

        const unsigned short FOCUS_AREA_ERR = 0;

        const unsigned short PICTURE_SIZE_ERR = 1;

        const unsigned short PICTURE_FORMAT_ERR = 2;

        const unsigned short RECORDING_FORMAT_ERR = 3;

        const unsigned short FILENAME_ERR = 4;

        const unsigned short MAX_FILE_SIZE_BYTES_ERR = 5;
    };

    Since: 2.2

    Constants

  • FOCUS_AREA_ERR
    Code for invalid focus area.

    Since: 2.2



  • PICTURE_SIZE_ERR
    Code for invalid picture size.

    Since: 2.2



  • PICTURE_FORMAT_ERR
    Code for invalid picture format.

    Since: 2.2



  • RECORDING_FORMAT_ERR
    Code for invalid recording format.

    Since: 2.2



  • FILENAME_ERR
    Code for invalid file name.

    Since: 2.2



  • MAX_FILE_SIZE_BYTES_ERR
    Code for invalid max file size.

    Since: 2.2



    • Attributes

    • readonly unsigned short[] codes
      Error code.

      Since: 2.2

    2. Related Feature

    It is recommended to design feature related code in a modular way. You can check if this API is supported with tizen.systeminfo.getCapabilities() and decide enable/disable codes that need this API.

    To guarantee the running of this application on a device with audio recording, define the following requirements in the config file:

  • http://tizen.org/feature/media.audio_recording

    • To guarantee the running of this application on a device with image capture, define the following requirements in the config file:

  • http://tizen.org/feature/media.image_capture

    • To guarantee the running of this application on a device with video recording, define the following requirements in the config file:

  • http://tizen.org/feature/media.video_recording

    • 3. Full WebIDL

    module Camera {

    [NoInterfaceObject] interface NavigatorTizenCamera {

        readonly attribute TizenCamera tizCamera;
    };
    Navigator implements NavigatorTizenCamera;


    [NoInterfaceObject] interface TizenCamera {

        void createCameraControl(MediaStream stream, CreateCameraSuccessCallback successCallback, CameraErrorCallback errorCallback);
    };


    callback interface CreateCameraSuccessCallback {

        void handleEvent(CameraControl cameraControl);
    };


    callback interface CameraErrorCallback {

        void handleEvent(CameraError error);
    };


    [NoInterfaceObject] interface CameraControl {

        readonly attribute CameraCapabilities   capabilities;

        readonly attribute CameraMediaRecorder  recorder;

        readonly attribute CameraImageCapture   image;


        void applySettings(CameraControlSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);

        boolean autoFocus();

        void release();
    };


    dictionary CameraControlSettings {

        CameraArea focusArea;
    };


    callback interface CameraSuccessCallback {

        void handleEvent();
    };


        callback interface CameraSettingErrorCallback {

            void handleEvent(CameraSettingErrors errors);
        };


    [NoInterfaceObject] interface CameraMediaRecorder {

        attribute   onrecordingstatechange;


        void applySettings(CameraRecorderSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);


        void start(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);


        void stop(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);
    };


    [NoInterfaceObject] interface CameraImageCapture {

        attribute  onshutter;

        void applySettings(CameraPictureSettings settings, CameraSuccessCallback onsuccess, CameraSettingErrorCallback onerror);

        void takePicture(CameraSuccessCallback onsuccess, CameraErrorCallback onerror);
    };


    [NoInterfaceObject] interface CameraCapabilities {

        readonly attribute CameraSize[] pictureSizes;

        readonly attribute DOMString[]  pictureFormats;

        readonly attribute DOMString[]  recordingFormats;
    };


    dictionary CameraSize {

        long width;

        long height;
    };


    dictionary CameraArea {

        long top;

        long left;

        long bottom;

        long right;
    };


    dictionary CameraPictureSettings {

        CameraSize pictureSize;

        DOMString pictureFormat;

        DOMString fileName;
    };


    dictionary CameraRecorderSettings {


        long maxFileSizeBytes;

        DOMString recordingFormat;

        DOMString fileName;
    };


    [NoInterfaceObject] interface CameraError {

        readonly attribute unsigned short code;

        const unsigned short CREATION_FAILED = 0;

        const unsigned short PERMISSION_DENIED = 1;

        const unsigned short NO_CAMERA = 2;

        const unsigned short PIPELINE_ERR = 3;

    const unsigned short FILE_WRITE_ERR = 4;
    };


    [NoInterfaceObject] interface CameraSettingErrors {

        readonly attribute unsigned short[] codes;

        const unsigned short FOCUS_AREA_ERR = 0;

        const unsigned short PICTURE_SIZE_ERR = 1;

        const unsigned short PICTURE_FORMAT_ERR = 2;

        const unsigned short RECORDING_FORMAT_ERR = 3;

        const unsigned short FILENAME_ERR = 4;

        const unsigned short MAX_FILE_SIZE_BYTES_ERR = 5;
    };
};