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 (SystemV and POSIX). 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
deviceList	Optional	Object array: deviceList	Indicates the list of cameras connected to the device. Note: The method 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. Returns the device handle for this connection instance.

Parameters

Name	Required	Type	Description
id	Required	String	Indicates the 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

Indicates the 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 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.
handle	Optional	Number	Indicates the 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

# 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 (SystemV or POSIX).

The method returns a key for accessing the shared memory, which 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	Indicates the handle for the device obtained using the open() API.
params	Required	Object: camera_memory_source	Defines the type and source of the memory.

Call Returns

Name	Required	Type	Description
key	Optional	Number	Indicates the key for memory access. For System V, key can be accessed directly for camera device buffers For Posix, shared memory fd has to be shared over getFd API for accessing the camera device buffers
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/startPreview '{
"handle":9383,
"params":{
"type":"sharedmemory",
"source":"0"
}
}'

Response:

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

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

Response:

{
"returnValue":true,
"key":9
}

stopPreview

Description

Stops the preview stream.

Parameters

Name	Required	Type	Description
handle	Required	Number	Indicates the handle for the device obtained using the open() API.

Call Returns

Name

Required

Type

Description

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

Response:

{
"returnValue":true
}

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

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

params

Required

Object: camera_capture_format

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

path

Optional

String

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

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

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

Call Returns

Name

Required

Type

Description

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/stopCapture '{
"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	Indicates the handle for the device obtained using the open() API.

Call Returns

Name

Required

Type

Description

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/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	Indicates id of the camera obtained using the getCameraList() API.

Call Returns

Name	Required	Type	Description
info	Optional	Object array: capture_info	Returns information about the camera.
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/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	Indicates the handle for the device obtained using the open() API.
params	Optional	String array	Indicates the list of specific properties for which settings are returned.

Call Returns

Name	Required	Type	Description
params	Optional	Object: camera_properties	Indicates the current properties of the camera.
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

With handle

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

With handle and params

# 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

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

params

Required

Object: camera_properties

Indicates an object containing properties of the camera.

Note: Even though the API succeeds when an empty params object is provided, we recommend that at least one value must be included.

Call Returns

Name

Required

Type

Description

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/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	Indicates the camera handle obtained using the open() API.
params	Required	Object: camera_format	Indicates the size and format of the preview stream.

Call Returns

Name

Required

Type

Description

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/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
subscribe	Required	Boolean	Indicates if subscribed to get notifications. Possible values are: true: Subscribed for notifications false: Not subscribed

Name

Required

Type

Description

Required

Boolean

Indicates if subscribed to get notifications.

Possible values are:

true: Subscribed for notifications
false: Not subscribed

Call Returns

Name	Required	Type	Description
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.
id	Optional	String	Indicates the 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	Indicates the details of camera properties when eventType is properties.
formatInfo	Optional	Object: 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.
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

With subscription

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

getFd

Description

Provides the FD (File Descriptor) for the POSIX shared memory.

Note: It returns the FD d by attaching it using LS2 attach fd interface to the client.

Parameters

Name	Required	Type	Description
handle	Required	Number	Indicates the handle for the device obtained using the open() API.

Call Returns

Name	Required	Type	Description
returnValue	Optional	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.

Name

Required

Type

Description

returnValue

Optional

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/getFd '{"handle": 886}'

Response:

{
"returnValue":true
}

Sample for fetching the fd from getFd response:

getFdCb(LSHandle *lsHandle, LSMessage *message, void *user_data)
{
...
LS::Message ls_message(message);
LS::PayloadRef payload_ref = ls_message.accessPayload();
fd = payload_ref.getFd();
...
}

Objects

camera_properties

Contains the properties of the camera.

Name	Required	Type	Description
autoWhiteBalance	Optional	Number	Indicates the camera auto white balance on/off (true/false)
backlightCompensation	Optional	Boolean	Indicates the camera backlight compensation value Possible values: true false
brightness	Optional	Number	Indicates the camera brightness (0-255)
contrast	Optional	Number	Indicates the camera contrast (0-255)
frequency	Optional	Number	Indicates the camera power line frequency (0-2)
gain	Optional	Number	Indicates the camera gain (0-255)
gamma	Optional	Number	Camera gamma (1-255)
hue	Optional	Number	Indicates the camera hue (-180 ~ 180)
pan	Optional	Number	Indicates the pan value(0-255)
resolution	Optional	Object	Indicates the supported format resolutions in string array format.
saturation	Optional	Number	Indicates the camera saturation (0-255)
sharpness	Optional	Number	Indicates the camera sharpness (0-255)
tilt	Optional	Number	Indicates the tilt value
whiteBalanceTemperature	Optional	Number	Indicates the white balance temperature (0-10000)

deviceList

Contains the list of cameras connected to the webOS device.

Name	Required	Type	Description
id	Optional	String	Indicates the unique camera identifier.

camera_format

Indicates the size and format for the preview stream and images.

Name	Required	Type	Description
width	Required	Number	Indicates the width of the image to be captured. Default: 640 pixels
height	Required	Number	Indicates the height of the image to be captured. Default: 480 pixels
format	Required	String	Indicates the format of the image. Possible values are: JPEG YUV Default: YUV
fps	Required	Number	Indicates the frames per second.

capture_info

Indicates the information about the camera.

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

picture

Indicates the image size and image format.

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

video

Indicates the video size and the video format.

Name	Required	Type	Description
maxWidth	Optional	Number	Indicates the width value.
maxHeight	Optional	Number	Indicates the height value.
format	Optional	String	Gives the supported format for video.
frameRate	Optional	Number	Indicates the video frame rate.

camera_memory_source

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

Name	Required	Type	Description
type	Required	String	Indicates the type of the memory. Possible options: sharedmemory - For System V shared memory. posixshm - For posix shared memory Note: Currently supports only shared memory.
source	Required	String	Indicates the ID of memory source, if the client has created the memory and wants data to be written at that specific address.

Name

Required

Type

Description

type

Required

String

Indicates the type of the memory.

Possible options:

sharedmemory - For System V shared memory.
posixshm - For posix shared memory

Note: Currently supports only shared memory.

source

Required

String

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

details

Indicates the picture and the video details of the camera device.

Name	Required	Type	Description
video	Optional	Object: video	Indicates the video information.
picture	Optional	Object: picture	Indicates the image information.

camera_capture_format

Indicates the size and the format in which images are to be captured.

Name	Required	Type	Description
width	Required	Number	Indicates the width of the image to be captured. Default width: 640 pixels
height	Required	Number	Indicates the height of the image to be captured. Default value: 480 pixels
format	Required	String	Indicates the format of the image. Possible values are: JPEG YUV Default: YUV
nimage	Optional	Number	Indicates the number of images to be captured. Note: The field is required for capturing images in burst mode.
mode	Required	String	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
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.