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 capturing 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, and so on.

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. Returns IDs for each of the cameras connected to the device.

Parameters

None

Call Returns

Name

Required

Type

Description

deviceListOptionalObject array: deviceList

Indicates the list of cameras connected to the device. 

Note: The method 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. Returns the device handle for this connection instance. 

Parameters

Name

Required

Type

Description

idRequiredString

Indicates the 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 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.
handleOptionalNumber

Indicates the 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

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

Response:

{
   "returnValue":true,
   "handle":9383
}

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

Response:

{
   "returnValue":true,
   "handle":886
}

# 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. 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

Indicates the handle for the device obtained using the open() API. 

paramsRequiredObject: camera_memory_source

Defines the type and source of the memory.

Note: Currently, this parameter supports only shared memory.

Call Returns

Name

Required

Type

Description

keyOptionalNumber

Indicates the key for memory access.

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/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

Indicates the handle for the device obtained using the open() API. 

paramsRequiredObject: camera_capture_format

Indicates the size and format of the images to be captured. 

pathOptionalString

Indicates the 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 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/startCapture '{
     "handle": 9383,
     "params":
          {
             "width": 640,
             "height": 480,
             "format": "JPEG",
             "mode":"MODE_BURST",
             "nimage":2
          }
}'

Response:

{
   "returnValue":true
}

# 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
}

# 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. Continuous mode captures frames in succession till the stopCapture() method is called. 

    Parameters

    Name

    Required

    Type

    Description

    handleRequiredNumber

    Indicates the handle for the device obtained using the open() API.

    Call Returns

    Name

    Required

    Type

    Description

    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/stopCapture '{
       "handle":9383
    }'

    Response:

    {
       "returnValue":true
    }

    stopPreview

    Description

    Stops the preview stream.

      Parameters

      Name

      Required

      Type

      Description

      handleRequiredNumber

      Indicates the handle for the device obtained using the open() API.

      Call Returns

      Name

      Required

      Type

      Description

      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/stopPreview '{
         "handle":9383
      }'

      Response:

      {
         "returnValue":true
      }

      close

      Description

      Closes the connection between the camera and the webOS device.

      Parameters

      Name

      Required

      Type

      Description

      handleRequiredNumber

      Indicates the handle for the device obtained using the open() API. 

      Call Returns

      Name

      Required

      Type

      Description

      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/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

        Indicates id of the camera obtained using the getCameraList() API.

        Call Returns

        Name

        Required

        Type

        Description

        infoOptionalObject array: capture_info

        Returns information about the camera.

        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/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

        Indicates the handle for the device obtained using the open() API.

        paramsOptionalString array

        Indicates the list of specific properties for which settings are returned.

        Call Returns

        Name

        Required

        Type

        Description

        paramsOptionalObject: camera_properties

        Indicates the current properties of the camera.

        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/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"
                 ]
              }
           }
        }

        # 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

        Indicates the handle for the device obtained using the open() API. 

        paramsRequiredObject: camera_properties

        Indicates an object containing properties of the camera.

        Note: At least one value must be included.

        Call Returns

        Name

        Required

        Type

        Description

        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/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

        Indicates the camera handle obtained using the open() API.

        paramsRequiredObject: camera_format

        Indicates the size and format of the preview stream.

        Call Returns

        Name

        Required

        Type

        Description

        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/setFormat '{
           "handle":9383,
           "params":{
              "width":640,
              "height":480,
              "format":"JPEG",
              "fps":30
           }
        }'

        Response:

        {
           "returnValue":true
        }

        getEventNotification

        Description

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

        Parameters

        Name

        Required

        Type

        Description

        subscribeRequiredBoolean

        Indicates if subscribed to get notifications.

        Possible values are:

        • true: Subscribed for notifications
        • false: Not subscribed

        Call Returns

        Name

        Required

        Type

        Description

        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.
        idOptionalString

        Indicates the 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

        Indicates the details of camera properties when eventType is properties.

        formatInfoOptionalObject: camera_format

        Returns the details of the 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

        Contains properties of the camera.

        Name

        Required

        Type

        Description

        frequencyOptionalNumber

        Indicates the camera power line frequency (0-2)

        saturationOptionalNumber

        Indicates the camera saturation (0-255)

        brightnessOptionalNumber

        Indicates the camera brightness (0-255)

        autoWhiteBalanceOptionalNumber

        Indicates the camera auto white balance on/off (true/false)

        tiltOptionalNumber

        Indicates the tilt value

        contrastOptionalNumber

        Indicates the camera contrast (0-255)

        backlightCompensationOptionalBoolean

        Indicates the camera backlight compensation value

        Possible values:

        • true
        • false
        gainOptionalNumber

        Indicates the camera gain (0-255)

        gammaOptionalNumber

        Camera gamma (1-255)

        hueOptionalNumber

        Indicates the camera hue (-180 ~ 180)

        panOptionalNumber

        Indicates the pan value(0-255)

        sharpnessOptionalNumber

        Indicates the camera sharpness (0-255)

        resolutionOptionalObject

        Indicates the supported format resolutions in string array format.

        whiteBalanceTemperatureOptionalNumber

        Indicates the white balance temperature (0-10000)

        deviceList

        Contains the list of cameras connected to the webOS device. 

        Name

        Required

        Type

        Description

        idOptionalString

        Indicates the unique camera identifier.

        camera_format

        Indicates size and format for the preview stream and images. 

        Name

        Required

        Type

        Description

        widthRequiredNumber

        Indicates the width of the image to be captured.

        Default: 640 pixels

        heightRequiredNumber

        Indicates the height of the image to be captured.

        Default: 480 pixels

        formatRequiredString

        Indicates the format of the image.

        Possible values are:

        • JPEG
        • YUV

        Default: YUV

        fpsRequiredNumber

        Indicates the frames per second.

        capture_info

        Indicates the information about the camera.

        Name

        Required

        Type

        Description

        detailsOptionalObject: details

        Indicates the video and the picture details.

        nameOptionalString

        Indicates the name of the camera.

        typeOptionalString

        Indicates the type of the device.

        Possible values are:

        • camera
        builtinOptionalBoolean

        Indicates 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

        Indicates the type of the memory for the preview data to be written.

        Name

        Required

        Type

        Description

        typeRequiredString

        Indicates the type of the memory.

        Note: Currently supports only shared memory.

        sourceRequiredString

        Indicates the 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

        Indicates the width of the image to be captured.

        Default width: 640 pixels

        heightRequiredNumber

        Indicates the height of the image to be captured.

        Default value: 480 pixels

        formatRequiredString

        Indicates the format of the image.

        Possible values are:

        • JPEG
        • YUV

        Default: YUV

        nimageOptionalNumber

        Indicates the number of images to be captured.

        Note: The field is required for capturing images in burst mode.

        modeRequiredString

        Indicates the 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