com.webos.service.camera2

API Summary

Provides an interface to capture and stream images from a camera that is connected to a webOS device.

Note: Currently, only V4L2 USB cameras are supported.

It provides the following features:

  • Live Camera Preview – Continuously streams live data from the camera to the shared memory. The data on the shared memory can be used by applications either using the native shared memory API for Linux or through multimedia middleware framework like GStreamer.
  • Capture Images – Allows you to capture images in various modes. You can take single or multiple images based on the selected mode. 
  • Control Camera Settings – Allows you to adjust the camera frame size, output format, and properties such as brightness, exposure, etc.

API Usage:

com.webos.service.camera2 API usage

 

Overview of the API

N/A

Methods

getCameraList

Description

Gets the list of cameras connected to the webOS device.

This method returns IDs for each of the cameras connected to the device.

Parameters

None

Call Returns

Name

Required

Type

Description

deviceListOptionalObject array: deviceList

List of cameras connected to the device.

Returns an empty list if no camera is connected.

returnValueRequiredBoolean

Indicates the status of the operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

# luna-send -n 1 -f luna://com.webos.service.camera2/getCameraList '{}'

 

Response:

{  
   "deviceList":[  
      {  
         "id":"camera1"
      }
   ],
   "returnValue":true
}

open

Description

Establishes a connection between a camera and the webOS device, and returns the device handle for this connection instance. 

Parameters

Name

Required

Type

Description

idRequiredString

Unique identifier of the camera. Obtained using the getCameraList() API.

modeOptionalString

Indicates whether the calling app can update the camera settings. Possible values are:

  • primary - Calling app can update the camera settings.
  • secondary - Calling app cannot update the camera settings.

Note:

  • If no mode is selected, then the first call to open the camera gets primary access, and others are given secondary access.
  • If there are multiple calls with the mode set as primary, then only the first call gets primary access.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
handleOptionalNumber

Unique identifier for each connection instance.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example 1: Open command with no mode

# luna-send -n 1 -f luna://com.webos.service.camera2/open '{"id": "camera1"}'

 

Response:
{

    "returnValue": true,

    "handle": 9383

}

 

Example 2: Open command with the mode set to primary

#luna-send -n 1 -f luna://com.webos.service.camera2/open '{"id": "camera1","mode":"primary"}'

 

Response:
{

    "returnValue": true,

    "handle": 886

}

 

Example 3: [Error case] Open command with mode as primary (when an application has already opened with mode as primary)

#luna-send -n 1 -f luna://com.webos.service.camera2/open '{"id": "camera1","mode":"primary"}'

 

Response:

{

    "errorCode": 44,

    "returnValue": false,

    "errorText": "Already another device opened as primary"

}

startPreview

Description

Starts the preview stream on the camera and writes live data to the shared memory.

The method returns a key for accessing the shared memory. This key is required for applications to access data from the shared memory.

Note: Use the setFormat() method to set the size and format of the preview stream. 

Parameters

Name

Required

Type

Description

handleRequiredNumber

Handle for the device. Obtained using the open() API. 

paramsRequiredObject: camera_memory_source

Defines the type and source of the memory.
Currently, supports only shared memory.

Call Returns

Name

Required

Type

Description

keyOptionalNumber

Key for memory access.

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

# luna-send -n 1 -f luna://com.webos.service.camera2/startPreview '{
    "handle": 9383,
    "params":
           {
               "type":"sharedmemory",
               "source":"0"
            }
}'

 

Response:
{
    "returnValue": true,
    "key": 7011
}

startCapture

Description

Starts capturing images using the camera. 

The captured images are stored as separate files at the location given by the "path" parameter.

The default file name is of the format PictureDDMMYYYY-HHMMSS, where DDMMYYYY-HHMMSS is current date and time. Example: /tmp/Picture11022019-204128.jpeg

By default, captured images are saved in the /tmp/ folder.

Parameters

Name

Required

Type

Description

handleRequiredNumber

Handle for the device. Obtained using the open() API. 

paramsRequiredObject: camera_capture_format

Size and format in which images are to be captured. 

pathOptionalString

Location where the captured images are to be saved.

Note: The API returns an error (error code 45) if the path specified is read-only.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example 1: Without specifying the location

# luna-send -n 1 -f luna://com.webos.service.camera2/startCapture '{
     "handle": 9383,
     "params":
          {
             "width": 640,
             "height": 480,
             "format": "JPEG",
             "mode":"MODE_BURST",
             "nimage":2
          }
}'

 

Response:

{
   "returnValue":true
}

 

Example 2 : With location specified

# luna-send -n 1 -f luna://com.webos.service.camera2/startCapture '{
     "handle": 9383,
     "params":
          {
             "width": 640,
             "height": 480,
             "format": "JPEG",
             "mode":"MODE_BURST",
             "nimage":2
          },
     "path":"/tmp/"
}'

 

Response:

{
   "returnValue":true
}

 

Example 3: [Error case] With read-only location specified

# luna-send -n 1 -f luna://com.webos.service.camera2/startCapture '{
     "handle": 9383,
     "params":
          {
             "width": 640,
             "height": 480,
             "format": "JPEG",
             "mode":"MODE_BURST",
             "nimage":2
          },
     "path":"/sys/"
}'

Response:

{
    "errorCode": 45,
    "returnValue": false,
    "errorText": "Cannot write at specified location"
}

stopCapture

Description

Stops camera from capturing images in the continuous mode.

That is, continuous mode captures frames in succession till the stopCapture() method is called. 

    Parameters

    Name

    Required

    Type

    Description

    handleRequiredNumber

    Handle for the device. Obtained using the open() API. 

    Call Returns

    Name

    Required

    Type

    Description

    returnValueRequiredBoolean

    Indicates the status of operation. Possible values are:

    • true - Indicates that the operation was successful.
    • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
    errorCodeOptionalNumber

    The error code for the failed operation.

    errorTextOptionalString

    Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

    Example

    # luna-send -n 1 -f luna://com.webos.service.camera2/stopCapture '{"handle": 9383}'

     

    Response:

    {
       "returnValue":true
    }

    stopPreview

    Description

    Stops the preview stream.

      Parameters

      Name

      Required

      Type

      Description

      handleRequiredNumber

      Handle for the device. Obtained using the open() API. 

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of operation. Possible values are:

      • true - Indicates that the operation was successful.
      • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
      errorCodeOptionalNumber

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

      Example

      # luna-send -n 1 -f luna://com.webos.service.camera2/stopPreview '{"handle": 9383}'

       

      Response:

      {
         "returnValue":true
      }

      close

      Description

      Closes the connection between the camera and the webOS device.

      Parameters

      Name

      Required

      Type

      Description

      handleRequiredNumber

      Handle for the device. Obtained using the open() API. 

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of operation. Possible values are:

      • true - Indicates that the operation was successful.
      • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
      errorCodeOptionalNumber

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

      Example

      # luna-send -n 1 -f luna://com.webos.service.camera2/close '{"handle": 886}'

       

      Response:

      {
         "returnValue":true
      }

      getInfo

      Description

      Gets information about a camera that is connected to the webOS device. 

        Parameters

        Name

        Required

        Type

        Description

        idRequiredString

        ID of the camera. Obtained using the getCameraList() API.

        Call Returns

        Name

        Required

        Type

        Description

        infoOptionalObject array: capture_info

        Information about the camera. 

        returnValueRequiredBoolean

        Indicates the status of operation. Possible values are:

        • true - Indicates that the operation was successful.
        • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
        errorCodeOptionalNumber

        The error code for the failed operation.

        errorTextOptionalString

        Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

        Example

        # luna-send -n 1 -f luna://com.webos.service.camera2/getInfo '{"id": "camera1"}'

         

        Response:

        {  
           "info":{  
              "type":"camera",
              "builtin":false,
              "details":{  
                 "video":{  
                    "maxWidth":800,
                    "maxHeight":600,
                    "frameRate":30,
                    "format":"YUV|JPEG|"
                 },
                 "picture":{  
                    "maxWidth":800,
                    "maxHeight":600,
                    "format":"YUV|JPEG|"
                 }
              },
              "name":"Logitech, Inc."
           },
           "returnValue":true
        }

        getProperties

        Description

        Gets the current settings of the connected camera device.

        Parameters

        Name

        Required

        Type

        Description

        handleRequiredNumber

        Handle for the device. Obtained using the open() API. 

        paramsOptionalString array

        List of specific properties for which settings are returned.

        Call Returns

        Name

        Required

        Type

        Description

        paramsOptionalObject: camera_properties

        Current properties of the camera.

        returnValueRequiredBoolean

        Indicates the status of operation. Possible values are:

        • true - Indicates that the operation was successful.
        • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
        errorCodeOptionalNumber

        The error code for the failed operation.

        errorTextOptionalString

        Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

        Example

        Example 1:

        #  luna-send -n 1 -f luna://com.webos.service.camera2/getProperties '{"handle": 9383}'

         

        Response:

        {  
           "returnValue":true,
           "params":{  
              "frequency":2,
              "saturation":128,
              "brightness":128,
              "autoWhiteBalance":true,
              "tilt":0,
              "contrast":128,
              "backlightCompensation":false,
              "gain":0,
              "gamma":128,
              "hue":0,
              "pan":0,
              "sharpness":128,
              "resolution":{  
                 "YUV":[  
                    "640,480,30",
                    "160,120,30",
                    "176,144,30",
                    "320,176,30",
                    "320,240,30",
                    "352,288,30",
                    "432,240,30",
                    "544,288,30",
                    "640,360,30",
                    "752,416,30",
                    "800,448,30",
                    "800,600,30",
                    "864,480,30",
                    "960,544,30",
                    "960,720,30",
                    "1024,576,30",
                    "1184,656,30",
                    "1280,720,30",
                    "1280,960,30"
                 ],
                 "JPEG":[  
                    "640,480,30",
                    "160,120,30",
                    "176,144,30",
                    "320,176,30",
                    "320,240,30",
                    "352,288,30",
                    "432,240,30",
                    "544,288,30"
                 ]
              }
           }
        }

         

        Example 2: 

        # luna-send -n 1 -f luna://com.webos.service.camera2/getProperties '{"handle": 9383,"params":["frequency","saturation"]}'

         

        Response:
        {
            "returnValue": true,
            "params": {
                "frequency": 2,
                "saturation": 128
            }
        }

        setProperties

        Description

        Sets the properties of the connected camera device.

        Parameters

        Name

        Required

        Type

        Description

        handleRequiredNumber

        Handle for the device. Obtained using the open() API. 

        paramsRequiredObject: camera_properties

        Properties of the camera. At least one value must be included.

        Call Returns

        Name

        Required

        Type

        Description

        returnValueRequiredBoolean

        Indicates the status of operation. Possible values are:

        • true - Indicates that the operation was successful.
        • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
        errorCodeOptionalNumber

        The error code for the failed operation.

        errorTextOptionalString

        Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

        Example

        # luna-send -n 1 -f luna://com.webos.service.camera2/setProperties '{
             "handle": 9383,
             "params":
                  {
                     "contrast": 100
                  }
        }'

         

        Response:

        {
           "returnValue":true
        }

        setFormat

        Description

        Sets the size and format of the preview stream. This includes the height and width of the frame and the format in which data is to be written to the shared buffer.

        Parameters

        Name

        Required

        Type

        Description

        handleRequiredNumber

        Camera handle obtained using the open() API.

        paramsRequiredObject: camera_format

        Size and format of the preview stream.

        Call Returns

        Name

        Required

        Type

        Description

        returnValueRequiredBoolean

        Indicates the status of operation. Possible values are:

        • true - Indicates that the operation was successful.
        • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
        errorCodeOptionalNumber

        The error code for the failed operation.

        errorTextOptionalString

        Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

        Example

        #luna-send -n 1 -f luna://com.webos.service.camera2/setFormat '{
             "handle": 9383,
             "params":
                  {
                    "width": 640,
                    "height": 480,
                    "format": "JPEG",
                    "fps": 30
                  }
        }'

         

        Response:

        {
           "returnValue":true
        }

        getEventNotification

        Description

        Get a notification when there is a change in any of the camera properties and formats.

        Parameters

        Name

        Required

        Type

        Description

        subscribeRequiredBoolean

        Subscribe for notifications. Possible values are:

        • true - Get notifications.
        • false - Notifications are not required.

        Call Returns

        Name

        Required

        Type

        Description

        returnValueRequiredBoolean

        Indicates the status of operation. Possible values are:

        • true - Indicates that the operation was successful.
        • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
        idOptionalString

        ID of the camera.

        eventTypeOptionalString

        Indicates whether there is a change in camera format or properties.

        Possible values are:

        • format - If there is a change in camera format. 
        • properties - If there is a change in camera properties.
        propertiesInfoOptionalObject: camera_properties

        Details of camera properties when eventType is properties.

        formatInfoOptionalObject: camera_format

        Details of camera format when eventType is format.

        Note: It may not return all the values mentioned in the formatInfo object.  

        errorCodeOptionalNumber

        The error code for the failed operation.

        errorTextOptionalString

        Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

        Example

        #luna-send -n 1 -f luna://com.webos.service.camera2/getEventNotification '{"subscribe":true}'

         

        Response (If no event received): 
        {
            "returnValue": true
        }

         

        Response (If properties are changed) :

        {
            "id": "camera1",
            "eventType":"properties",
            "returnValue":true,
            "propertiesInfo": 
            {
                "frequency":0,
                "saturation":255,
                "brightness":255,
                "autoWhiteBalance":false,
                "contrast":100,
                "whiteBalanceTemperature":0,
                "gain":255,
                "backlightCompensation":true,
                "sharpness":255
            }
        }

         

        Response (If format changed to JPEG) :
        {
            "id": "camera1",
            "eventType":"format",
            "returnValue":true,
            "formatInfo":
            {       
                "format":"JPEG",
            }
        }

        Objects

        camera_properties

        Properties of the camera.

        Name

        Required

        Type

        Description

        frequencyOptionalNumber

        Camera power line frequency (0-2)

        saturationOptionalNumber

        Camera saturation (0-255)

        brightnessOptionalNumber

        Camera brightness (0-255)

        autoWhiteBalanceOptionalNumber

        Camera auto white balance on/off (true/false)

        tiltOptionalNumber

        Tilt value

        contrastOptionalNumber

        Camera contrast (0-255)

        backlightCompensationOptionalBoolean

        Backlight compensation value(true/false)

        gainOptionalNumber

        Camera gain (0-255)

        gammaOptionalNumber

        Camera gamma (1-255)

        hueOptionalNumber

        Camera hue (-180 ~ 180)

        panOptionalNumber

        Pan value(0-255)

        sharpnessOptionalNumber

        Camera sharpness (0-255)

        resolutionOptionalObject

        Supported format resolutions in string array format.

        whiteBalanceTemperatureOptionalNumber

        White balance temperature (0-10000)

        deviceList

        List of cameras connected to the webOS device. 

        Name

        Required

        Type

        Description

        idOptionalString

        Unique camera identifier

        camera_format

        Size and format for the preview stream and images. 

        Name

        Required

        Type

        Description

        widthRequiredNumber

        Width of the image to be captured. Default width is 640 pixels.

        heightRequiredNumber

        Height of the image to be captured. Default value is 480 pixels. 

        formatRequiredString

        Format of the image. Possible values are:

        • JPEG
        • YUV

        The default value is YUV.

        fpsRequiredNumber

        Frames per second.

        capture_info

        Information about the camera. 

        Name

        Required

        Type

        Description

        detailsOptionalObject: details

        Video and picture details

        nameOptionalString

        Name of the camera

        typeOptionalString

        Type of device. Possible values are:

        • camera
        builtinOptionalBoolean

        Denotes if the camera is built-in or not

        picture

        Image size and format. 

        Name

        Required

        Type

        Description

        maxWidthOptionalNumber

        Width value

        maxHeightOptionalNumber

        Height value

        formatOptionalString

        Supported formats

        video

        Video size and format. 

        Name

        Required

        Type

        Description

        maxWidthOptionalNumber

        Width value

        maxHeightOptionalNumber

        Height value

        formatOptionalString

        Gives the supported format for video

        frameRateOptionalNumber

        Frame rate for video

        camera_memory_source

        Type of memory for preview data to be written.

        Name

        Required

        Type

        Description

        typeRequiredString

        Type of memory. Currently supports only shared memory.

        sourceRequiredString

        ID of memory source, if the client has created the memory and wants data to be written at that specific address.

        details

        Picture and video details of the camera device.

        Name

        Required

        Type

        Description

        videoOptionalObject: video

        Video info

        pictureOptionalObject: picture

        Image info

        camera_capture_format

        Size and format in which images are to be captured. 

        Name

        Required

        Type

        Description

        widthRequiredNumber

        Width of the image to be captured. Default width is 640 pixels.

        heightRequiredNumber

        Height of the image to be captured. Default value is 480 pixels. 

        formatRequiredString

        Format of the image. Possible values are:

        • JPEG
        • YUV

        The default value is YUV.

        nimageOptionalNumber

        Number of images to be captured. This field is required for capturing images in burst mode.

        modeRequiredString

        Mode in which the image is to be captured. Possible values are:

        • MODE_ONESHOT - For one-shot mode. 
        • MODE_BURST - For burst mode. 
        • MODE_CONTINUOUS - For continuous mode. 

        API Error Codes Reference

        Error Code

        Error Text

        Error Description

        2Cannot close device

        Device cannot be closed.

        3Cannot open device

        Device cannot be opened.

        5Cannot start device

        Preview stream cannot be started.

        6Cannot stop device

        Preview stream cannot be stopped.

        7Device already closed

        Device is already closed.

        8Device is already open

        Device is already opened.

        9Device is already started

        Preview stream is already started.

        10Device is already stopped

        Preview stream is already stopped.

        11Device not opened

        Device is not opened.

        12Device not started

        Preview stream is not yet started.

        13No Device

        There is no device connected corresponding to input ID.

        19Parsing error

        Luna command parsing error.

        22Param missing

        One or more parameters are missing in luna command.

        23Request Timeout

        Requested operation is timed out.

        29Device unsupported

        Device is not supported.

        30Format unsupported

        Format is not supported.

        32Wrong param

        Input parameter is incorrect.

        38Unknown error

        Unknown error.

        44Already another device opened as primary

        Only one application can open a camera device as primary. Other application will not be allowed to open camera if an application has already opened with primary priority.

        45Cannot write at specified location

        Cannot write at the specified location.

        Contents