com.webos.media
API Summary
Provides access to the functionality provided by the webOS media server. The webOS media server supports both managed and unmanaged pipelines. For managed pipelines, com.webos.media provides high-level methods to control the playback of media content (e.g. load, play, seek). For unmanaged pipelines, com.webos.media provides low-level methods for resource management and display control.
Direct use of com.webos.media by application developers is strongly discouraged. Instead, the media interfaces native to a particular application framework (e.g. Web, QT, SDL/NDL) should be used.
Overview of the API
See Summary.
Methods
load
Description
The load method loads a new pipeline for the specified URI. The media server returns a unique id to the client which is used for subsequent operations on the pipeline.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| uri | Required | String | The URI of the media object. For example, http://mymovie.mp4, file://mymovie.mp4 |
| type | Required | String | Determines which type of pipeline to load. Currently, the following pipeline types are supported:
Media server also supports run-time installation of additional pipelines, but that is outside the scope of this API document. |
| payload | Optional | Object: payload | See "payload" object. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media/camera pipeline which is used for subsequent operations. |
Example
# luna-send -n 1 -f luna://com.webos.media/load '{"uri": "https://media.w3.org/2010/05/sintel/trailer.mp4","type": "media","payload": {"option": {"appId": "com.webos.app.browser","display-path": 0}}}'
Response:
{
"errorCode":0,
"returnValue":true,
"errorText":"No Error",
"mediaId":"_Pvzj2FRn42sL99"
}
unload
Description
The unload method unloads the pipeline and releases all AV resources.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the loaded media/camera pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | String | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media/camera pipeline which is requested to unload. |
Example
# luna-send -n 1 -f luna://com.webos.media/unload '{"mediaId":"_Pvzj2FRn42sL99"}'
Response:
{
"errorCode":0,
"returnValue":true,
"errorText":"No Error",
"mediaId":"_Pvzj2FRn42sL99"
}
notifyForeground
Description
The notifyForeground method marks a pipeline as foreground.
This API is called when the media object in question is un-carded and made visible.
Foreground pipeline video content is currently visible on the display surface
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| connectionId | Required | String | Unique identifier of the registered pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
The notifyForeground method may fail because of:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/notifyForeground '{"connectionId": "_z6SJt11Yx0mVp1"}'
Response:
{
"returnValue": true
}
notifyBackground
Description
The notifiyBackground method marks a pipeline as background.
This API is called when the media object in question is carded, deleted, or otherwise removed from view.
Background video content is not currently visible on the display surface
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| connectionId | Required | String | Unique identifier of the registered pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
The notifyBackground method may fail because of:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/notifyBackground '{"connectionId": "_c5zE4w2k7rqmC5"}'
Response:
{
"returnValue": true
}
subscribe
Description
The subscribe method subscribes the media client to receive events from a media pipeline.
These events, described in the tables above, allow the media client (generally an app or test tool) to monitor pipeline status (including playback position) and adjust their internal state appropriately.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the loaded media/camera pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the operation Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media pipeline which is requested to subscribe. |
| subscription | Optional | String | Indicates the current subscription status. Possible values are:
|
Example
# luna-send -n 2 -f luna://com.webos.media/subscribe '{ "mediaId": "_rTNwzp81clPsxX"}'
Response:
{
"subscription": true
}
{
"errorCode": 0,
"returnValue": true,
"errorText": "No Error",
"mediaId": "_rTNwzp81clPsxX"
}
attach
Description
The attach method allows to transfer the control of a pipeline to be handed over to a different client. When this occurs, the original client gets notified that it got detached from the pipeline and can no longer control the pipeline.
This method was added to address a specific early boot situation where the pipeline was initially created by one client process and then another client process takes over control of the pipeline.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the loaded media/camera pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media pipeline which is requested to subscribe. |
Example
# luna-send -n 1 -f luna://com.webos.media/attach '{"mediaId":"_IsGbw614gu7xRB"}'
Response:
{
"errorCode":0,
"returnValue":true,
"errorText":"No Error",
"mediaId":"_IsGbw614gu7xRB"
}
play
Description
The play method requests the media server to play the media object.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the loaded media/camera pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media/camera pipeline which is requested to play. |
Example
# luna-send -n 1 -f luna://com.webos.media/play '{ "mediaId":"_IsGbw614gu7xRB"}'
Response:
{
"errorCode":0,
"returnValue":true,
"errorText":"No Error",
"mediaId":"_IsGbw614gu7xRB"
}
pause
Description
The pause method requests the media server to pause the media object.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the loaded media/camera pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media/camera pipeline which is requested to pause. |
Example
# luna-send -n 1 -f luna://com.webos.media/pause '{"mediaId":"_IsGbw614gu7xRB"}'
Response:
{
"errorCode":0,
"returnValue":true,
"errorText":"No Error",
"mediaId":"_IsGbw614gu7xRB"
}
seek
Description
The seek method seeks the media object to a specified time position.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| position | Required | Number | Position (in milliseconds) from the start position to seek position. |
| mediaId | Required | String | Unique identifier of the loaded media/camera pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media pipeline which is requested to seek. |
Example
# luna-send -n 1 -f luna://com.webos.media/seek '{"position":64935,"mediaId":"_IsGbw614gu7xRB"}'
Response:
{
"errorCode":0,
"returnValue":true,
"errorText":"No Error",
"mediaId":"_IsGbw614gu7xRB"
}
registerPipeline
Description
Unmanaged Pipeline Only
The registerPipeline method registers with the Resource Manager. Session is persistent across all start/end transaction and acquire/release cycles. Registered clients and their current resource requirements will be tracked by Resource Manager. Param type as specified in Resource Manager configuration file pipeline settings.
For Managed Pipelines, this is taken care of internally by the mediaserver.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| type | Required | String | Type of pipeline to register
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| connectionId | Required | String | Unique identifier of the registered pipeline. |
| returnValue | Optional | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/registerPipeline '{"type": "media"}'
Response:
{
"connectionId": "_KXpMET1Sxc1eGO"
}
unregisterPipeline
Description
Unmanaged Pipeline
The unregisterPipeline method unregisters pipeline with Resource Manager.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| connectionId | Required | String | Unique identifier of the pipeline to unregister. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media pipeline which is requested. |
Example
# luna-send -n 1 -f luna://com.webos.media/unregisterPipeline '{"connectionId": "_KXpMET1Sxc1eGO"}'
Response:
{
"errorCode": 0,
"returnValue": true,
"errorText": "No Error",
"mediaId": "_KXpMET1Sxc1eGO"
}
acquire
Description
The acquire method requests resources from the mediaserver.
Typical usage is to request the number of audio and video decoders or other hardware components used by the pipeline.
Acquire calls can be used to dynamically add more resources to the pipeline. This allows the pipeline to dynamically grow or shrink without monopolizing the resources from startup. Each time a resource is acquired, the indexes of the newly acquired resources are included in the acquireComplete event.
The types and quantities of resources available to be managed are specified in the file umediaserver_resource_config.txt.in file.
This file is customized for each hardware platform.
If required to satisfy the acquisition of requested resources, a policyAction may be issued to other pipelines, forcing them to release their resources.
For format and list of acquired resources see acquireComplete event.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| resources | Required | Object: resources | See "resources" object. |
| connectionId | Required | String | Unique identifier of the pipeline to acquire resource. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | String | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/acquire '{
"resources": "[{\"resource\":\"DISP0\",\"qty\":1}, {\"resource\":\"VDEC\",\"qty\":1},{\"resource\":\"ADEC\",\"qty\":1}]",
"connectionId": "_UZRkgE3EJgXvwl"
}'
Response:
{
"returnValue": true
}
acquireComplete
{
"resources": [{
"qty": 1,
"resource": "ADEC",
"index": 3
}, {
"qty": 1,
"resource": "VDEC",
"index": 3
}, {
"qty": 1,
"display_attr": {
"crtc-id": 43,
"plane-id": 44,
"conn-id": 19
},
"resource": "DISP0",
"index": 3
}],
"state": true,
"connectionId": "_UZRkgE3EJgXvwl"
}
tryAcquire
Description
Try to acquire resources from mediaserver.
This API will not issue policyAction to other pipelines in order to force them to release resources.
If there are insufficient resources to honor the request without issuing a policyAction, the request will fail.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| resources | Required | Object: resources | See "resources" object. |
| connectionId | Required | String | Unique identifier of the pipeline to acquire resource. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 luna://com.webos.media/tryAcquire '{
"resources": "[{\"resource\":\"DISP0\",\"qty\":1},{\"resource\":\"VDEC\",\"qty\":1},{\"resource\":\"ADEC\",\"qty\":1}]",
"connectionId": "_7P3y7e9AcPv8t1"
}'
Response:
{
"returnValue": true
}
acquireComplete
{
"resources": [{
"qty": 1,
"resource": "ADEC",
"index": 3
}, {
"qty": 1,
"resource": "VDEC",
"index": 3
}, {
"qty": 1,
"display_attr": {
"crtc-id": 43,
"plane-id": 44,
"conn-id": 19
},
"resource": "DISP0",
"index": 3
}],
"state": true,
"connectionId": "_7P3y7e9AcPv8t1"
}
release
Description
Unmanaged Pipeline
The release method informs media server the resources are released correctly and are not being used anymore.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| resources | Required | Object: resources | See "resources" object. |
| connectionId | Required | String | Unique identifier of the pipeline to release resource. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/release '{
"resources": "[{\"resource\":\"DISP0\",\"qty\":1,\"index\":3},{\"resource\":\"VDEC\",\"qty\":1,\"index\":3},{\"resource\":\"ADEC\",\"qty\":1,\"index\":3}]",
"connectionId": "_QY7tkX1XEfBct3"
}'
Response:
{
"returnValue": true
}
notifyActivity
Description
Unmanaged Pipeline
The notifyActivity method notifies media server that the specific pipeline is currently in use. This command raises time stamp record of the corresponding pipeline to lessen chance to be picked as the target for a policyAction, which would require the pipeline to release its resources. This method is providing a specific capability for TVService and should not be used elsewhere.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| connectionId | Required | String | Unique identifier of the registered pipeline. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/notifyActivity '{"connectionId": "_EYv0VPazu3aGo0"}'
Response:
{
"returnValue": true
}
trackAppProcesses
Description
The trackAppProcesses method subscribes to messages containing the mapping of application ID (AppID) and pipeline process ID (PID), i.e. it returns information about which application each managed pipeline belongs to.
The return value of the method contains an array of the PIDs of all currently existing pipelines mapped to the corresponding AppIDs.
The subscription messages contain information about changes to these mappings, i.e. new mappings when a pipeline is associated with an application or destroyed mappings when a pipeline exits.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| subscribed | Required | Boolean | Returns true if the subscriber was successfully added. |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| mediaPipelines | Required | Object array: mediaPipelines | See "mediaPipelines" object. |
| subscription | Required | Boolean | Indicates the current subscription status. Possible values are:
|
Subscription Returns
Name | Required | Type | Description |
|---|---|---|---|
| procUpdate | Required | Object: procUpdate | See "procUpdate" object. |
Example
# luna-send -n 2 -f luna://com.webos.media/trackAppProcesses '{}'
Response:
{
"subscription": true
}
{
"subscribed": true,
"mediaPipelines": [
{
"appId": "com.webos.app.enactbrowser",
"pid": 1685
}
],
"returnValue": true
}
Subscription Response:
{
"procUpdate": {
"appId": "com.webos.app.enactbrowser",
"exec": false,
"pid": 1685
}
}
contentReady
Description
Media Content Providers must send contentReady event when the first frame or buffer of valid media data is available to display or output to speakers.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Optional | String | Unique identifier of the media object |
| state | Optional | Boolean | Indicates whether the media content is available and ready to display.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/contentReady '{"state": true,"mediaId": "_dPEZRY4C47nwBZ"}'
Response:
{
"returnValue": true
}
setVideoInfo
Description
Media Content Provider must send an event when media content containers are parsed.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| videoInfo | Required | Object: videoInfo | See "videoInfo" object. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/setVideoInfo '{ "videoInfo":{ "width":854,"frameRate":{ "num":24,"den":1},"mediaId":"_IiQr7B7P1zDGbd","height":480}}'
Response:
{
"returnValue": true
}
registerMedia
Description
Media Content Provider (unmanaged) must register with Media Display Controller to allow proper management of video content and displays or audio outputs.
NOTE: In managed case, this API is internally invoked from 'load' API. Thus, using this API with load is strongly discouraged.
(Duplicated calls for same mediaId are not allowed.)
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object to be registered |
| appId | Required | String | Application ID |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| mediaId | Optional | String | Unique identifier of the media object registered |
Example
# luna-send -n 1 -f luna://com.webos.media/registerMedia '{"mediaId":"_IsGbw614gu7xRB", "appId":"com.webos.app.browser"}'
Response:
{
"returnValue": true
}
unregisterMedia
Description
Media Content Provider must unregister with Media Display Controller before terminating
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object to be unregistered |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| errorCode | Optional | Number | The error code for the failed operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/unregisterMedia '{"mediaId": "_IsGbw614gu7xRB"}'
Response:
{
"returnValue": true
}
focus
Description
Media application sets media object currently in focus.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object currently in focus |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| errorCode | Optional | Number | The error code for the failed operation. |
| mediaId | Optional | String | Unique identifier of the media object |
Example
# luna-send -n 1 -f luna://com.webos.media/focus '{"mediaId": "_rWmN6P17iENX5aD"}'
Response:
{
"returnValue": true
}
setDisplayWindow
Description
Set video source and destination window sizes.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object |
| source | Optional | Object: WindowObject | Source window size
|
| destination | Optional | Object: WindowObject | Destination window size
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| errorCode | Optional | Number | The error code for the failed operation. |
| mediaId | Optional | String | Unique identifier of the media object |
Example
# luna-send -n 1 -f luna://com.webos.media/setDisplayWindow '{
"source":{
"x":0,
"y":0,
"width":1920,
"height":1080
},
"destination":{
"x":0,
"y":0,
"width":1920,
"height":1080
},
"mediaId":"_IsGbw614gu7xRB"
}'
Response:
{
"returnValue":true,
}
switchToFullScreen
Description
Set full screen on media object.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| errorCode | Optional | Number | The error code for the failed operation. |
Example
# luna-send -n 1 -f luna://com.webos.media/switchToFullScreen '{"mediaId": "_MTr6o3sZayV7S5"}'
Response:
{
"returnValue": true
}
setVisibility
Description
Sets the visibility of media object.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object |
| visible | Required | Boolean | Indicates media object visibility state.
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorText | Optional | String | Indicates the reason for the failure of the operation. |
| errorCode | Optional | Number | The error code for the failed operation. |
| mediaId | Optional | String | Unique identifier of the media object |
Example
# luna-send -n 1 -f luna://com.webos.media/setVisibility '{ "mediaId":"_nePLk54ziXgMRj", "visible": true}'
Response:
{
"returnValue": true
}
unsubscribe
Description
Unsubscribes from media pipeline related events.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Optional | String | Unique identifier of the media object to unsubscribe |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the loaded media pipeline which is requested to unsubscribe. |
Example
# luna-send -n 1 -f luna://com.webos.media/unsubscribe '{ "mediaId":"_gmkaR0OtGWxr6z"}'
Response:
{
"errorCode": 0,
"returnValue": true,
"errorText": "No Error",
"mediaId": "_gmkaR0OtGWxr6z"
}
getActivePipelines
Description
Get JSON formatted output of currently active media pipelines.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| Id | Optional | String | Unique identifier of the media object |
| type | Optional | String | Media type |
| pid | Optional | Number (int16_t) | Process ID of Media Content Provider |
| mdc | Optional | String | Media Display Controller state |
| is_managed | Optional | Boolean | Indicates whether Media Content Provider is a managed pipeline or not.
|
| is_foreground | Optional | Boolean | Indicates whether media object is currently in the foreground or not
|
| mediaState | Optional | String | Current state of Media Content Provider
|
| policy_state | Optional | Boolean | Media is currently selected for Resource Management Policy Action and is in suspended state |
| uri | Optional | String | URI of media object |
| appId | Optional | String | Application ID of application using media object |
| processState | Optional | String | State of Media Content Provider process
|
| is_focus | Optional | String | Media object is currently selected for focus. NOTE: Focus is not the same thing as "visible". |
| timestamp | Optional | String | Timestamp of last activity on Media Content Provider pipeline. Pipeline activity is used to adjust the Resource Manager Policy Action Candidate Selection Policy. Events which update pipeline activity
|
| resources | Required | Object array: resources | See "resources" object. |
| mediaId | Optional | String | Media Id of the object |
| errorCode | Optional | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| returnValue | Optional | Boolean | Indicates the status of operation. Possible values are:
|
Example
# luna-send -n 1 -f luna://com.webos.media/getActivePipelines '{ "mediaId":"_IsGbw614gu7xRB"}'
Response: JSON array of pipelines and current their current state
[
{
"resources": [
{
"resource": "ADEC",
"index": 3
},
{
"resource": "VDEC",
"index": 3
},
{
"resource": "DISP0",
"index": 3
}
],
"pid": 1272,
"type": "media",
"id": "_IsGbw614gu7xRB",
"mdc": {
"states": [
"Foreground",
"ContentNotReady",
"Unfocused",
"Visible",
"AudioConnecting",
"OffScreen"
],
"connections": [
"DISP0_MAIN"
]
},
"is_managed": true,
"mediaState": "play",
"is_foreground": true,
"policy_state": 0,
"uri": "https://media.w3.org/2010/05/sintel/trailer.mp4",
"appId": "com.webos.app.enactbrowser",
"processState": "media_loaded",
"is_focus": false,
"timestamp": 16304803045079
}
]
setVolume
Description
Sets the volume for the specified media object. Additionally, it specifies the ease (fade-in and fade-out) properties for the media object.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the media object. |
| volume | Required | Number | The volume to be set. Can be set to any value between 0 and 100. |
| ease | Optional | Object: ease | Object to specify the easing (fade-in and fade-out) properties for the media object. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of the operation.
|
| errorCode | Required | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the media object. |
Example
# luna-send -n 1 -f luna://com.webos.media/setVolume '{"mediaId":"_IsGbw614gu7xRB","volume":60,"ease":{ "duration":0,"type":"Linear"}}'
Response:
{
"errorCode":0,
"returnValue":true,
"errorText":"No Error",
"mediaId":"_IsGbw614gu7xRB"
}
getForegroundAppInfo
Description
Provides the application's foreground information.
Parameters
None
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | String | Application ID |
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| acbs | Required | Object array: acbs | Array of objects that gives details of the media (pipeline ID, playstate, position etc.) |
Example
# luna-send -n 1 -f luna://com.webos.media/getForegroundAppInfo '{}'
Response:
{
"acbs": [
{
"positionY": 0,
"playStateNow": "",
"width": 0,
"height": 0,
"isFullScreen": false,
"pipelineId": "",
"positionX": 0,
"playStateNext": ""
}
],
"appId": "com.webos.app.browser",
"returnValue": true
}
setPlayRate
Description
Sets the pipeline media play rate.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| playRate | Required | Number (double) | Playback rate for the media. |
| mediaId | Required | String | Unique identifier of the loaded media pipeline which is requested. |
| audioOutput | Required | Boolean | Determine to mute audio |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Required | Number | The error code for the operation. Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails. |
| errorText | Required | String | Indicates the reason for the failure of the operation. Note: Currently, it returns "No Error" even when the returnValue is true. If JSON parsing fails, then errorText is updated accordingly. |
| mediaId | Optional | String | Unique identifier of the media object |
Example
# luna-send -n 1 -f luna://com.webos.media/setPlayRate '{"playRate": 2.0,"mediaId": "_QnGGXr7BdWsOV1","audioOutput":true}'
Response:
{
"errorCode": 0,
"returnValue": true,
"errorText": "No Error",
"mediaId": "_QnGGXr7BdWsOV1"
}
startCameraRecord
Description
Starts camera recording.
The camera pipeline stores streamed data from the camera at the specified location.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| location | Required | String | Path for storing the recorded file. |
| format | Required | String | Format in which data is stored. Possible values are:
|
| mediaId | Required | String | Unique identifier of the camera pipeline. Obtained using the load() API. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. Note: errorCode always defaults to 0. Details of the error will be available in the logs. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. Note: errorText is always empty. Details of the error will be available in the logs. |
| mediaId | Required | String | Unique identifier of the camera pipeline. |
Example
# luna-send -n 1 luna://com.webos.media/startCameraRecord '{ "mediaId":"_JtLZrGoEAoRa1d","location":"/media/internal/","format":"h264"}'
stopCameraRecord
Description
Requests media server to stop camera recording and change to the preview state.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the camera pipeline. Obtained using the load() API. |
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. Note: errorCode always defaults to 0. Details of the error will be available in the logs. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. Note: errorText is always empty. Details of the error will be available in the logs. |
| mediaId | Required | String | Unique identifier the camera pipeline. |
Example
# luna-send -n 1 luna://com.webos.media/stopCameraRecord '{ "mediaId" : "_JtLZrGoEAoRa1d"}'
takeCameraSnapshot
Description
Captures a frame from the camera preview.
Parameters
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | String | Unique identifier of the camera pipeline. Obtained using the load() API. |
| location | Required | String | Path where the captured image is to be stored. |
| format | Required | String | Format in which the frame is to be captured. Possible values are:
|
| width | Required | Number | Width of the captured image in pixels. Note: This should be within the range supported by the camera hardware. |
| height | Required | Number | Height of the captured image in pixels. Note: This should be within the range supported by the camera hardware. |
| pictureQuality | Required | Number | Percentage of picture quality. Possible values are:
|
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
| errorCode | Optional | Number | The error code for the failed operation. Note: errorCode always defaults to 0. Details of the error will be available in the logs. |
| errorText | Optional | String | Indicates the reason for the failure of the operation. Note: errorText is always empty. Details of the error will be available in the logs. |
| mediaId | Required | String | Unique identifier the camera pipeline. |
Example
# luna-send -n 1 luna://com.webos.media/takeCameraSnapshot '{"mediaId":"","location":"/tmp/","format":"jpg","width":640,"height":480,"pictureQuality":30}'
Objects
WindowObject
Defines source and destination window parameters.
Name | Required | Type | Description |
|---|---|---|---|
| x | Required | Number | Upper left corner x coordinate location |
| y | Required | Number | Upper left corner y coordinate location |
| width | Required | Number | Window's width |
| height | Required | Number | Window's height |
ResponseObject
Provide a detailed description of the object. Limit to 2-3 paragraphs.Name | Required | Type | Description |
|---|---|---|---|
| returnValue | Optional | Boolean | Return value of command. Command succeeded true/false. |
| errorCode | Optional | Number | Error Code (if failure) of command. |
| errorText | Optional | String | Human readable and HMI/UX displayable text of reported error. If any. |
| mediaId | Optional | String | Media ID |
ease
Defines the ease (fade-in and fade-out) properties for the media object.
Name | Required | Type | Description |
|---|---|---|---|
| duration | Optional | Number | Duration (in msec) for the easing effect (fade-in and fade-out). Value can be between 0 and 60000. Default duration is 0. |
| type | Optional | String | Easing mode for the media object. Possible values:
Default value: Linear |
resources
Object of resource name, quantity, and index.
Resources can hold more than one set of resource, quantity, and index.
Example:
{
"resources": " [{
"resource": "DISP0",
"qty": 1,
"index": 3,
"display_attr": {
"crtc-id": 43,
"plane-id": 44,
"conn-id": 19
},
},
{
"resource": "VDEC",
"qty": 1,
"index": 3
},
{
"resource": "ADEC",
"qty": 1,
"index": 3
}
]
}
Name | Required | Type | Description |
|---|---|---|---|
| resource | Required | String | Name of resource to acquire. Possible values are:
|
| qty | Optional | Number | Quantity of resource to acquire. |
| index | Optional | Number | Specific index of resource to acquire. |
| display_attr | Optional | Object: display_attr | See "display_attr" object. |
videoInfo
Provides information related to video.
Name | Required | Type | Description |
|---|---|---|---|
| width | Required | Number (uint32_t) | Actual width value of input video (before cropping in video decoder. Used for UI presentation.) |
| height | Required | Number (uint32_t) | Actual height value of input video (before cropping in video decoder. Used for UI presentation.) |
| frameRate | Required | Object: frameRate | See "frameRate" object. |
| codec | Optional | String | Codec information. |
| bitRate | Optional | Number (uint64_t) | Bit rate value of content. |
frameRate
Provides information about the number of frames per second at which the video is being played.
It is represented as a combination of numerator and denominator.
Name | Required | Type | Description |
|---|---|---|---|
| num | Required | Number (int32_t) | Numerator of frame rate |
| den | Required | Number (int32_t) | Denominator of frame rate |
audioInfo
Provides information related to audio.
Name | Required | Type | Description |
|---|---|---|---|
| codec | Optional | String | Codec information |
| bitrate | Optional | Number (int64_t) | Bit rate value of content. |
| sample_rate | Optional | Number (int32_t) | Samples of audio carried per second, measured in kHz. |
mediaPipelines
Contains the AppID-PID mapping of the currently running pipelines. Returns an empty array if no pipelines associated with any applications.
Each array element is an object of type {"appId": string, "pid": number}. If the appId string is empty it means the pipeline was loaded without an application ID being provided.
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | String | Indicates application id |
| pid | Required | Number | Indicates process id of pipeline |
procUpdate
The procUpdate object value is an object of type: {"appId" : string, "exec" : bool, "pid" : number}
where exec is true when a pipeline appid mapping is added and false when it is destroyed.
If the appId string is empty it means the pipeline was loaded without an application ID being provided.
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | String | Indicates application ID. |
| pid | Required | Number | Indicates process ID of pipeline. |
| exec | Required | Boolean | Provides information on the mapping status of app ID and a pipeline. Possible values are:
|
payload
Payload format used in load API. It represents the JSON payload object for a specific type of pipeline.
Name | Required | Type | Description |
|---|---|---|---|
| option | Optional | Object: option | See "option" object. |
option
Provides parameters used in load/preload API.
Name | Required | Type | Description |
|---|---|---|---|
| appId | Required | String | Indicates application id |
| display-path | Optional | Number | Indicates display path(default value: 0). Multiple values can be supported if a device has multiple screens (i.e., 0 for primary display, 1 for secondary display). It is only applied to Open. |
programs
Provides audio/video stream information.
Name | Required | Type | Description |
|---|---|---|---|
| video_stream | Required | Number (int32_t) | The number of video streams in program. |
| audio_stream | Required | Number (int32_t) | The number of audio streams in program. |
sourceInfo
Provides information of the media that has just been loaded.
Example:
{
"sourceInfo": {
"programs": [{
"audio_stream": 1,
"video_stream": 1
}],
"seekable": true,
"video_streams": [{
"width": 854,
"frame_rate": {
"num": 24,
"den": 1
},
"bitrate": 535929,
"height": 480
}],
"audio_streams": [{
"sample_rate": 48000,
"bit_rate": 0
}],
"container": "",
"duration": 52209
}
}
Name | Required | Type | Description |
|---|---|---|---|
| programs | Required | Object array: programs | See "programs" object. |
| seekable | Required | Boolean | Flag indicating whether the media supports seek operations.
|
| video_streams | Required | Object array: videoInfo | See "videoInfo" object. |
| audio_streams | Required | Object array: audioInfo | See "audioInfo" object. |
| container | Optional | String | Media format (container type) of source
|
| duration | Required | Number (int64_t) | Total duration in milli-seconds of the program. |
display_attr
Provides detailed information for display resource.
Name | Required | Type | Description |
|---|---|---|---|
| crtc-id | Required | Number (int32_t) | Crtc id of display |
| plane-id | Required | Number (uint32_t) | Plane id of display |
| conn-id | Required | Number (int32_t) | Connector id of display |
acbs
Array of objects that gives details of media for foreground application (such as pipeline Id, playstate, position, etc.)
Name | Required | Type | Description |
|---|---|---|---|
| pipelineId | Required | String | Pipeline id |
| playStateNow | Required | String | Current playback status |
| playStateNext | Required | String | Next playback status |
| isFullScreen | Required | Boolean | Specifies if the app is in full screen mode. |
| positionX | Required | Number (int32_t) | X Position of window |
| positionY | Required | Number (int32_t) | Y Position of window |
| width | Required | Number (int32_t) | Width of the app window. |
| height | Required | Number (int32_t) | Height of the app window. |
Signals/Events
loadCompleted
The loadCompleted event is raised when a specific media pipeline has been successfully loaded.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| loadCompleted | Required | Number (int32_t) | Unique identifier of the loaded pipeline. |
unloadCompleted
The unloadCompleted event is raised when a specific media pipeline has been successfully unloaded.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | Number (int32_t) | Unique identifier of the unloaded pipeline. |
detached
The detached event is raised when a specific media has been detached from the client by another client attaching to the corresponding pipeline. The detached event is related to the attach command. Attach allows to transfer the control of a pipeline to be handed over to a different client. When that happens the original client gets notified that it got detached from the pipeline and is hence no longer able to control the pipeline. This feature is related to fast boot scenarios where we have a mini-app controlling media upon initial launch and the control is handed over to the real/full application once the system has started in full.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Optional | Number (int32_t) | Unique identifier of detached pipeline. |
seekDone
The seekDone event is raised when a seek operation for a media has been successfully completed.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | Number (int32_t) | Unique identifier of the requested pipeline to seek. |
playing
The playing event is raised once, in response to the play method, when a specified media pipeline has transitioned into the playing state.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | Number (int32_t) | Unique identifier of the requested pipeline to play. |
paused
The paused event is raised when a specific media has been successfully paused.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | Number (int32_t) | Unique identifier of the requested pipeline to pause. |
endOfStream
The endOfStream event is raised when a specific media has received all of its data.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | Number (int32_t) | Unique identifier of pipeline met end of stream. |
currentTime
The currentTime event is raised multiple times when a specific media is playing. It indicates the progress of the media being played and provides the current time at which the media is being played.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| currentTime | Required | Number (int32_t) | Current time at which the media is being played. |
| mediaId | Required | Number (int32_t) | Unique identifier of pipeline which reports current time. |
sourceInfo
The sourceInfo event provides information about the media that has just been loaded.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| sourceInfo | Required | Number (int32_t) | See "sourceInfo" object. |
videoInfo
The videoInfo event provides information related to video.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| videoInfo | Required | Number (int32_t) | See "videoInfo" object. |
audioInfo
The audioInfo event provides information related to audio.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| audioInfo | Required | Number (int32_t) | See "audioInfo" object. |
error
The error event reports errors thrown by pipelines.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| errorCode | Optional | Number (int32_t) | Error code from the service. |
| errorText | Optional | Number (int32_t) | Error code description from the service. |
| mediaId | Required | Number (int32_t) | Unique identifier of pipeline sending error information. |
acquireComplete
The acquireCompete event is invoked when the acquire request is performed and the result comes out.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| resources | Required | Number (int32_t) | See "resources" object. |
| state | Required | Number (int32_t) | Flag indicating the result of acquire request.
|
| connectionId | Required | Number (int32_t) | Unique identifier of the pipeline to acquire resource. |
policyAction
The policyAction event is invoked when the resources are short of quantity to playing new media content and request pipeline to release regarding resource.
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| requestor_type | Required | Number (int32_t) | Type of pipeline that made a new request. This is the pipeline requesting the additional resources. |
| requestor_name | Required | Number (int32_t) | Name of pipeline that made new request. This is the pipeline requesting additional resources. |
| action | Required | Number (int32_t) | Action requested to do at the pipeline when this policyAction is delivered. |
| resources | Required | Number (int32_t) | See "resources" object. |
| connectionId | Required | Number (int32_t) | Unique identifier of the pipeline to get policyAction event |
activeRegion
This event will notify video object of overlay rectangle (active region) video frame is being rendered to. This event is relevant for auto layout mode (see switchToAutoLayout method for more info).
Call Returns
Name | Required | Type | Description |
|---|---|---|---|
| mediaId | Required | Number (int32_t) | Media ID of the addressed pipeline. |
| x | Required | Number (int32_t) | x coordinate of active region |
| y | Required | Number (int32_t) | y coordinate of active region |
| width | Required | Number (int32_t) | width of active region |
| height | Required | Number (int32_t) | height of active region |
API Error Codes Reference
Error Code | Error Text | Error Description |
|---|---|---|
| 600 | PolicyAction | Media related errors reported by the media pipeline are reported into several categories.
|
| 601 | Resource Allocation Error | Media related errors reported by the media pipeline are reported into several categories.
|