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:

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
deviceList	Optional	Object array: deviceList	List of cameras connected to the device. Returns an empty list if no camera is connected.
returnValue	Required	Boolean	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.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	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
id	Required	String	Unique identifier of the camera. Obtained using the getCameraList() API.
mode	Optional	String	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.

Name

Required

Type

Description

Required

String

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

mode

Optional

String

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
returnValue	Required	Boolean	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.
handle	Optional	Number	Unique identifier for each connection instance.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	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
handle	Required	Number	Handle for the device. Obtained using the open() API.
params	Required	Object: camera_memory_source	Defines the type and source of the memory. Currently, supports only shared memory.

Call Returns

Name	Required	Type	Description
key	Optional	Number	Key for memory access.
returnValue	Required	Boolean	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.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	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

handle

Required

Number

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

params

Required

Object: camera_capture_format

Size and format in which images are to be captured.

path

Optional

String

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

returnValue

Required

Boolean

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.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

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

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
handle	Required	Number	Handle for the device. Obtained using the open() API.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

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.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

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
handle	Required	Number	Handle for the device. Obtained using the open() API.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

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.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

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
handle	Required	Number	Handle for the device. Obtained using the open() API.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

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.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

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
id	Required	String	ID of the camera. Obtained using the getCameraList() API.

Call Returns

Name	Required	Type	Description
info	Optional	Object array: capture_info	Information about the camera.
returnValue	Required	Boolean	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.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	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
handle	Required	Number	Handle for the device. Obtained using the open() API.
params	Optional	String array	List of specific properties for which settings are returned.

Call Returns

Name	Required	Type	Description
params	Optional	Object: camera_properties	Current properties of the camera.
returnValue	Required	Boolean	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.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	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
handle	Required	Number	Handle for the device. Obtained using the open() API.
params	Required	Object: camera_properties	Properties of the camera. At least one value must be included.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

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.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

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
handle	Required	Number	Camera handle obtained using the open() API.
params	Required	Object: camera_format	Size and format of the preview stream.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

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.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

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
subscribe	Required	Boolean	Subscribe for notifications. Possible values are: true - Get notifications. false - Notifications are not required.

Name

Required

Type

Description

Required

Boolean

Subscribe for notifications. Possible values are:

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

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	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.
id	Optional	String	ID of the camera.
eventType	Optional	String	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.
propertiesInfo	Optional	Object: camera_properties	Details of camera properties when eventType is properties.
formatInfo	Optional	Object: camera_format	Details of camera format when eventType is format. Note: It may not return all the values mentioned in the formatInfo object.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	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
frequency	Optional	Number	Camera power line frequency (0-2)
saturation	Optional	Number	Camera saturation (0-255)
brightness	Optional	Number	Camera brightness (0-255)
autoWhiteBalance	Optional	Number	Camera auto white balance on/off (true/false)
tilt	Optional	Number	Tilt value
contrast	Optional	Number	Camera contrast (0-255)
backlightCompensation	Optional	Boolean	Backlight compensation value(true/false)
gain	Optional	Number	Camera gain (0-255)
gamma	Optional	Number	Camera gamma (1-255)
hue	Optional	Number	Camera hue (-180 ~ 180)
pan	Optional	Number	Pan value(0-255)
sharpness	Optional	Number	Camera sharpness (0-255)
resolution	Optional	Object	Supported format resolutions in string array format.
whiteBalanceTemperature	Optional	Number	White balance temperature (0-10000)

deviceList

List of cameras connected to the webOS device.

Name	Required	Type	Description
id	Optional	String	Unique camera identifier

camera_format

Size and format for the preview stream and images.

Name	Required	Type	Description
width	Required	Number	Width of the image to be captured. Default width is 640 pixels.
height	Required	Number	Height of the image to be captured. Default value is 480 pixels.
format	Required	String	Format of the image. Possible values are: JPEG YUV The default value is YUV.
fps	Required	Number	Frames per second.

capture_info

Information about the camera.

Name	Required	Type	Description
details	Optional	Object: details	Video and picture details
name	Optional	String	Name of the camera
type	Optional	String	Type of device. Possible values are: camera
builtin	Optional	Boolean	Denotes if the camera is built-in or not

picture

Image size and format.

Name	Required	Type	Description
maxWidth	Optional	Number	Width value
maxHeight	Optional	Number	Height value
format	Optional	String	Supported formats

video

Video size and format.

Name	Required	Type	Description
maxWidth	Optional	Number	Width value
maxHeight	Optional	Number	Height value
format	Optional	String	Gives the supported format for video
frameRate	Optional	Number	Frame rate for video

camera_memory_source

Type of memory for preview data to be written.

Name	Required	Type	Description
type	Required	String	Type of memory. Currently supports only shared memory.
source	Required	String	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
video	Optional	Object: video	Video info
picture	Optional	Object: picture	Image info

camera_capture_format

Size and format in which images are to be captured.

Name	Required	Type	Description
width	Required	Number	Width of the image to be captured. Default width is 640 pixels.
height	Required	Number	Height of the image to be captured. Default value is 480 pixels.
format	Required	String	Format of the image. Possible values are: JPEG YUV The default value is YUV.
nimage	Optional	Number	Number of images to be captured. This field is required for capturing images in burst mode.
mode	Required	String	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
2	Cannot close device	Device cannot be closed.
3	Cannot open device	Device cannot be opened.
5	Cannot start device	Preview stream cannot be started.
6	Cannot stop device	Preview stream cannot be stopped.
7	Device already closed	Device is already closed.
8	Device is already open	Device is already opened.
9	Device is already started	Preview stream is already started.
10	Device is already stopped	Preview stream is already stopped.
11	Device not opened	Device is not opened.
12	Device not started	Preview stream is not yet started.
13	No Device	There is no device connected corresponding to input ID.
19	Parsing error	Luna command parsing error.
22	Param missing	One or more parameters are missing in luna command.
23	Request Timeout	Requested operation is timed out.
29	Device unsupported	Device is not supported.
30	Format unsupported	Format is not supported.
32	Wrong param	Input parameter is incorrect.
38	Unknown error	Unknown error.
44	Already 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.
45	Cannot write at specified location	Cannot write at the specified location.