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:

OSE_com_webos_service_camera2_API Usage.png

 

Overview of the API

(click to expand)

N/A


Open All


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.


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.