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

(click to expand)

See Summary.


Open All


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: media playback pipeline

Media server also supports run-time installation of additional pipelines but that is outside the scope of this API document.

payload Optional Object: payload

Represents the JSON payload object for a specific type of pipeline.

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. 
errorCode Optional Number

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorText Optional String

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaId Required String

Unique identifier of the loaded media / camera pipeline which is used for subsequent operations

Example

# luna-send -n 1 luna://com.webos.media/load

'{

    "uri":"file:///media/internal/bolt.mp4",

    "type":"media",

    "payload":

    {

        "option":

        {

            "appId":"com.webos.app.browser"

        }

    }

}'


unload

Description

The unload method unloads the pipeline and releases all AV resources.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the loaded media/camera pipeline.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. 
errorCodeOptionalString

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media/camera pipeline which is requested to unload.

Example

# luna-send -n 1 luna://com.webos.media/unload

'{

    "mediaId":"_rq1Mnm10xRTDto"

}'


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:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

The notifyForeground method may fail because of:

  • Command sent with wrong JSON format.
  • missing connectionId (required field).
  • Unexisting connectionId.

Example

# luna-send -n 1 luna://com.webos.media/notifyForeground

'{

    "connectionId":"_rq1Mnm10xRTDto"

}'


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:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

The notifyBackground method may fail because of:

  • Command sent with wrong JSON format.
  • missing connectionId (required field).
  • Unexisting connectionId.

Example

# luna-send -n 1 luna://com.webos.media/notifyBackground

'{

    "connectionId":"_g6V8ae3SWqJ8in"

}'


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

mediaIdRequiredString

Unique identifier of the loaded media/camera pipeline.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed
errorCodeOptionalNumber

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media pipeline which is requested to subscribe.

Example

# luna-send -n 1 luna://com.webos.media/subscribe

'{

    "mediaId":"_nePLk54ziXgMRj"

}'


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

mediaIdRequiredString

Unique identifier of the loaded media/camera pipeline.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media pipeline which is requested to subscribe.

Example

# luna-send -n 1 luna://com.webos.media/attach

'{

    "mediaId":"_nePLk54ziXgMRj"

}'


play

Description

The play method requests the media server to play the media object.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the loaded media/camera pipeline.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed
errorCodeOptionalNumber

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media/camera pipeline which is requested to play.

Example

# luna-send -n 1 luna://com.webos.media/play

'{

    "mediaId":"_nePLk54ziXgMRj"

}'


pause

Description

The pause method requests the media server to pause the media object.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the loaded media / camera pipeline.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed
errorCodeOptionalNumber

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media / camera pipeline which is requested to pause.

Example

# luna-send -n 1 luna://com.webos.media/pause

'{

    "mediaId":"_nePLk54ziXgMRj"

}'


seek

Description

The seek method seeks the media object to a specified time position.

Parameters

Name

Required

Type

Description

positionRequiredNumber

Position (in milliseconds) from the start position to seek position.

mediaIdRequiredString

Unique identifier of the loaded media / camera pipeline.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media pipeline which is requested to seek.

Example

# luna-send -n 1 luna://com.webos.media/seek

'{

    "position":64935,

    "mediaId":"_D5iJSA41gj4YZL"

}'


registerPipeline

Description

Unmanaged Pipeline Only

The registerPipeline method registers with 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

typeRequiredString

Type of pipeline to register

  • ref
  • media
  • sim

Call Returns

Name

Required

Type

Description

connectionIdRequiredString

Unique identifier of the registered pipeline.

Example

# luna-send -n 1 luna://com.webos.media/registerPipeline

'{

    "type":"media"

}'


unregisterPipeline

Description

Unmanaged Pipeline

The unregisterPipeline method unregisters pipeline with Resource Manager.

Parameters

Name

Required

Type

Description

connectionIdRequiredString

Unique identifier of the pipeline to unregister.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed
errorCodeOptionalNumber

errorCode is always returned as 0.

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty. 

Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media pipeline which is requested.

Example

# luna-send -n 1 luna://com.webos.media/unregisterPipeline

'{

    "mediaId":"_D5iJSA41gj4YZL"

}'


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

resourcesRequiredObject: resources

Object of resource name, quantity, and index.

Resources can hold more than one set of resource, quantity, and index.

For example: {"resources":"[{"resource":"VDEC","qty":1},[{"resource":"ADEC","qty":1}]"}

connectionIdRequiredString

Unique identifier of the pipeline to acquire resource.

Call Returns

Name

Required

Type

Description

returnValueRequiredString

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

Example

# luna-send -n 1 luna://com.webos.media/acquire

'{

    "resources":

    "[

        {

            "resource":"VDEC",

            "qty":1

        },

        {

            "resource":"ADEC",

            "qty":1

        }

    ]",

    "connectionId":"_nePLk54ziXgMRj"

}

RETURN:

acquireComplete
{"resources":[{"qty":1,"resource":"VDEC","index":1},{"qty":1,"resource":"ADEC","index":1}],"state":true,"connectionId":"_nePLk54ziXgMRj"}


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

resourcesRequiredObject: resources

Object of resource name, quantity, and index.

Resources can hold more than one set of resource, quantity, and index.

For example: {"resources":"[{"resource":"VDEC","qty":1},[{"resource":"ADEC","qty":1}]"}

connectionIdRequiredString

Unique identifier of the pipeline to acquire resource.

Example

luna-send -n 1 luna://com.webos.media/tryAcquire '{"resources":"[{"resource":"VDEC","qty":1},{"resource":"ADEC","qty":1}]","connectionId":"_nePLk54ziXgMRj"}

RETURN:
acquireComplete
{"resources":[{"qty":1,"resource":"VDEC","index":1},{"qty":1,"resource":"ADEC","index":1}],"state":true,"connectionId":"_nePLk54ziXgMRj"}


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

resourcesRequiredObject: resources

Object of resource name, quantity, and index.

Resources can hold more than one set of resource, quantity, and index.

For example: {"resources":"[{"resource":"VDEC","qty":1},[{"resource":"ADEC","qty":1}]"}

connectionIdRequiredString

Unique identifier of the pipeline to release resource.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Possible values are:

  • true: For released resources.
  • false: For malformed request.

Example

# luna-send -n 1 luna://com.webos.media/release

'{

    "resources":

    "[

        {

            "resource":"VDEC",

            "qty":1,

            "index":0

        },

        {

            "resource":"ADEC",

            "qty":1,

            "index":0

        }

    ]",

    "connectionId":"_TMvOb6cbC56t1Y"

}


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

subscribedRequiredBoolean

Returns true if the subscriber was successfully added.

returnValueRequiredBoolean

True if subscribed is true.

mediaPipelinesRequiredObject array

Contains the AppID-PID mappings 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.

 

Subscription Returns

Name

Required

Type

Description

procUpdateRequiredObject

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.

Example

# luna-send -n 1 luna://com.webos.media/trackAppProcesses '{0}'

 

RETURN: JSON Array of current Media Pipelines and associate process information

[{"appId":string, "pid":int, "exec":bool},{"appId":string, "pid":int, "exec":bool}, ... ]


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

mediaIdOptionalString

Unique identifier of the Media Object

stateOptionalBoolean

Indicates whether the media content is available and ready to display.

  • true: The media content is available and ready to display
  • false: The media content is not available

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

Example

luna-send -n 1 luna://com.webos.media/mediaContentReady '{"state":<1/0>,"mediaId":""}'

RETURN: no response received other than luna-bus message delivery confirmation. true/false.


setVideoInfo

Description

Media Content Provider must send event when media content containers are parsed.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the Media Object

widthRequiredNumber (int32_t)

Width of video content

heightRequiredNumber (int32_t)

Height of video content

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.

Example

luna-send -n 1 luna://com.webos.media/setVideoInfo '{"mediaId":"","width":320,"height":24}'

RETURN: no return is generated other than luna bus message delivery confirmation 


registerMedia

Description

Media Content Provider (unmanaged) must register with Media Display Controller to allow proper management of video content and displays or audio outputs.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the Media Object to be registered

appIdRequiredString

Application ID

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

mediaIdOptionalString

Unique identifier of the Media Object registered

Example

# luna-send -n 1 luna://com.webos.media/registerMedia '{"mediaId":"", "appId":""}


unregisterMedia

Description

Media Content Provider must unregister with Media Display Controller before terminating

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the Media Object to be unregistered

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorTextOptionalString

Indicates the reason for the failure of the operation.

errorCodeOptionalNumber

The error code for the failed operation.

mediaIdOptionalString

Unique identifier of the Media Object unregistered

Example

# luna-send -n 1 luna://com.webos.media/unregisterMedia '{"mediaId":""}


focus

Description

Media application sets Media Object currently in focus.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the Media Object currently in focus

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. 
errorTextOptionalString

Indicates the reason for the failure of the operation.

errorCodeOptionalNumber

The error code for the failed operation.

mediaIdOptionalString

Unique identifier of the Media Object

Example

# luna-send -n 1 luna://com.webos.media/focus '{"mediaId": ""}'


switchToFullScreen

Description

Set full screen on Media Object.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the Media Object

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorTextOptionalString

Indicates the reason for the failure of the operation. 

errorCodeOptionalNumber

The error code for the failed operation.

mediaIdOptionalString

Unique identifier of the Media Object

Example

# luna-send -n 1 luna://com.webos.media/switchToFullScreen '{"mediaId": "_nePLk54ziXgMRj"}'


setVisibility

Description

Sets visibility of Media Object.

Parameters

Name

Required

Type

Description

mediaIdRequiredString

Unique identifier of the Media Object

visibleRequiredBoolean

Indicates Media Object visibility state.

  • true: Set to visible state
  • false: Set to invisible state 

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorTextOptionalString

Indicates the reason for the failure of the operation.

errorCodeOptionalNumber

The error code for the failed operation.

mediaIdRequiredString

Unique identifier of the Media Object

Example

# luna-send -n 1 luna://com.webos.media/setVisibility '{"mediaId":"_nePLk54ziXgMRj", "visible": true}'


unsubscribe

Description

Unsubscribes from media pipeline related events.

Parameters

Name

Required

Type

Description

mediaIdOptionalString

Unique identifier of the Media Object to unsubscribe

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed.
errorCodeOptionalNumber

errorCode is always returned as 0. 

Errors with the arguments will be annunciated in the logs.

errorTextOptionalString

errorText is always empty.

 Errors with the arguments will be annunciated in the logs.

mediaIdRequiredString

Unique identifier of the loaded media pipeline which is requested to unsubscribe.

Example

# luna-send -n 1 luna://com.webos.media/unsubscribe '{"mediaId":"_gmkaR0OtGWxr6z"}'


getActivePipelines

Description

Get JSON formatted output of currently active Media Pipelines.

Parameters

None

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.

  • true: Managed
  • false: Not managed
is_foreground Optional Boolean

Indicates whether Media Object is currently in the foreground or not

  • true: Media Object is currently in the foreground
  • false: Media Object is currently in the background
mediaState Optional String

Current state of Media Content Provider

  • MEDIA_LOAD - Media is loaded and ready to play
  • MEDIA_UNLOAD - Media is unloaded
  • MEDIA_PLAY - Media is currently in play state
  • MEDIA_PAUSE - Media is in pause state
  • MEDIA_STOP - Media is in stop state
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

  • PIPELINE_STARTING - Media pipeline is starting but currently unable to process or respond to commands
  • PIPELINE_RESTARTING - Media pipeline is being restarted due to crash recovery or resume from Resource Manager Policy Action
  • PIPELINE_RUNNING - Media pipeline is running and able to process and respond to commands
  • PIPELINE_MEDIA_LOADED - Media pipeline has loaded and valid media content
  • PIPELINE_SUSPENDED - Media pipeline has been suspended due to Resource Manager Policy Action

 

is_focus Optional String

Media Object is currently selected for focus.

NOTE: Focus is not the same thing as "visible".

timestamp Optional String

Time stamp 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

  • PLAY
  • SEEK
  • LOAD
  • notifyForeground
  • notifyActivity

Example

luna-send -n 1 luna://com.webos.media/getActivePipelines '{0}'

RETURN: JSON array of pipelines and current their current state

[{

"resource":[{"resource":"VDEC","index":1},{"resource":"ADEC","index":1}],

"pid":9654,

"type":"ref",

"id":"_kFY53CLtTsSZcg",

"mdc":{

"states":["Background","Idle","Unfocused","Visible","ContentReady"],

"connections":[]

},

"is_managed":true,

"is_foreground":false,

"mediaState":"load",

"policy_state":0,

"uri":"file:////media_files/rat.mp4",

"appId":"app1",

"processState":"media_loaded",

"is_focus":false,

"timestamp":72753748386738

}]


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

mediaIdRequiredString

Unique identifier of the media object.

volumeRequiredNumber

The volume to be set. Can be set to any value between 0 and 100.

easeOptionalObject: ease

Object to specify the easing (fade-in and fade-out) properties for the media object.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

  • true: Indicates success of the operation.
  • false: Indicates failure in the operation. Errors with the arguments will be provided in the logs.
errorCodeOptionalNumber

errorCode is always returned as 0. 

Errors with the arguments will be specified in the logs.

errorTextOptionalString

errorText is always empty.

Errors with the arguments will be specified in the logs.

mediaIdOptionalString

Unique identifier of the media object.

Example

luna-send -n  1  -f luna://com.webos.media/setVolume '{"mediaId" : "_ydG1XT5JIXV2BK", "volume" : 60, "ease" : {"duration" : 0, "type" : "Linear"}}'


getForegroundAppInfo

Description

Provides the application's foreground information.

Parameters

None

Call Returns

Name

Required

Type

Description

appIdOptionalString

Application id

pipelineIdOptionalString

Pipeline id

playStateNowOptionalString

Current playback status

isFullScreenOptionalBoolean

Specifies if the app is in full screen mode.

positionXOptionalNumber (int32_t)

X Position of window

positionYOptionalNumber (int32_t)

Y Position of window

widthOptionalNumber (int32_t)

Width of the app window.

heightOptionalNumber (int32_t)

Height of the app window.

Example

luna-send -n 1 -f luna://com.webos.media/getForegroundAppInfo '{}'


Objects

WindowObject

Defines source and destination window parameters.

Name

Required

Type

Description

xRequiredNumber

Upper left corner x coordinate location

yRequiredNumber

Upper left corner y coordinate location

widthRequiredNumber

Window's width

heightRequiredNumber

Window's height

ResponseObject

Provide a detailed description of the object. Limit to 2-3 paragraphs.

Name

Required

Type

Description

returnValueOptionalBoolean

Return value of command. Command succeeded true/false.

errorCodeOptionalNumber

Error Code (if failure) of command.

errorTextOptionalString

Human readable and HMI/UX displayable text of reported error. If any.

mediaIdOptionalString

Media ID

ease

Defines the ease (fade-in and fade-out) properties for the media object.

Name

Required

Type

Description

durationOptionalNumber

Duration (in msec) for the easing effect (fade-in and fade-out).

Value can be between 0 and 60000. 

Default duration is 0.

typeOptionalString

Easing mode for the media object.

Possible values:

  • Linear: The volume fades constantly or linearly.
  • InCubic: The volume fades slowly at beginning in cubical way.
  • OutCubic: The volume fades quickly at beginning in cubical way.

Default value: Linear

PreloadObject

Provide a application ID (AppID)

Name

Required

Type

Description

appIdOptionalString

Application ID (AppID)

"appId":"com.webos.app.browser"


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 String

Unique identifier of 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 String

Unique identifier of 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 String

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 String

Unique identifier of requested pipeline to seek.

playing

The playing event is raised once, in reponse to the play method, when a specified media piple has transitioned into the playing state. 

Call Returns

Name

Required

Type

Description

mediaId Required String

Unique identifier of 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 String

Unique identifier of 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 String

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 String

Current time at which the media is being played.

mediaId Required String

Unique identifier of pipeline which reports current time.

sourceInfo

The sourceInfo event provides information of the media that has just been loaded.

 

Example:

{
"sourceInfo":
    {
    "numPrograms":1,
    "container":"ISO MP4\/M4A",
    "seekable":true,
    "trickable":true,
    "programInfo":
        [
            {
            "duration":162098,
            "numAudioTracks":1,
            "audioTrackInfo":
                [
                    {
                    "bitRate":0,
                    "language":"Track0",
                    "codec":"aac",
                    "profile":"lc",
                    "level":2,
                    "sampleRate":44.1,
                    "channels":1,
                    "audioType":0
                    }
                ],
            "numVideoTracks":1,
            "videoTrackInfo":
                [
                    {
                    "angleNumber":0,
                    "level":3,
                    "width":320,
                    "height":240,
                    "codec":"mp4v",
                    "profile":"simple",
                    "frameRate":15,
                    "progressive":true
                    }
                ],
            "numSubtitleTracks":0,
            "subtitleTrackInfo":""
            }
        ],
    "mediaId":"_uGpza1oKRuwfgU"
    }
}

Call Returns

Name

Required

Type

Description

container Required String

Media format (container type) of source

  • "RAW","WAV","MP3", "AAC", "RA", "AVI", "MP4", "MPEG1", "MPEG2", "ASF", "MKV", "PS", "TS", "RM", "FLV", "F4V", "ISM"
numPrograms Required String

Number of programs in the media.

seekable Optional String

Flag indicating whether the media supports seek operations. 

  • To send information that the content is available for seek, set seekable to true.
  • To send information that the content is not available for seek, set seekable to false.
trickable Optional String

Flag indicating whether the media supports trick operations. 

  • To send information that the content is available for trick play, set trickable to true.
  • To send information that the content is available for trick play,, set trickable to true.
programInfo:duration Required String

Total duration in milli-seconds of the program.

programInfo:parentControl Optional String

Optional pass through value.

programInfo:numAudioTracks Optional String

Number of audio tracks.

programInfo:audioTrackInfo Optional String

Array of objects that contain information about individual audio tracks.

programInfo should include number of audioTrackInfo object specified in numAudioTracks.

programInfo:audioTrackInfo:language Optional String

Language of the audio track.

programInfo:audioTrackInfo:codec Optional String

Codec needed to decode the audio track.

programInfo:audioTrackInfo:profile Optional String

Profile of audio codec used.

programInfo:audioTrackInfo:level Optional String

Level of audio codec used.

programInfo:audioTrackInfo:bitRate Optional String

Bit rate quality at which the audio is being received.

programInfo:audioTrackInfo:sampleRate Optional String

Samples of audio carried per second, measured in kHz.

programInfo:audioTrackInfo:channels Optional String

Number of audio channels present in the audio track.

programInfo:audioTrackInfo:pid Optional String

Packet Id associated with streams.

programInfo:audioTrackInfo:ctag Optional String

Component tag information in MPEG-TS standard used to classify each stream in PMT (program map table).

programInfo:audioTrackInfo:audioDescription Optional String

Description of the audio track content.

programInfo:audioTrackinfo:audioType Required String

Information for MHEG and HBBTV.

programInfo:numVideoTracks Optional String

Number of video tracks.

programInfo:videoTrackInfo Optional String

Array of objects that contain information about individual video tracks.

programInfo should include number of videoTrackInfo object specified in numVideoTracks.

programInfo:videoTrackInfo:angleNumber Optional String

Index of the camera angle of the video.

programInfo:videoTrackInfo:codec Optional String

Codec that is required to decode and play the video.

programInfo:videoTrackInfo: profile Optional String

Profile of video codec used.

programInfo:videoTrackInfo: level Optional String

Level of video codec used.

programInfo:videoTrackInfo:width Required String

Width of the video.

programInfo:videoTrackInfo:height Required String

Height of the video.

programInfo:videoTrackInfo:aspectRatio Optional String

Ratio of Input video.

programInfo:videoTrackInfo:pixelAspectRatio Optional String

Aspect ratio of Input video pixel. Format: "n:n" e.g. "1:1"

programInfo:videoTrackInfo:bitrate Optional String

Bit rate quality at  which the video is being played.

programInfo:videoTrackInfo:frameRate Optional String

Number of frames per second at which the video is being played or recorded.

programInfo:videoTrackInfo:pid Optional String

Packet Id associated with streams.

programInfo:videoTrackInfo:ctag Optional String

Component tag information in MPEG-TS standard used to classify each stream in PMT (program map table).

programInfo:videoTrackInfo:progressive Required String

Flag indicating progressive information.

  • To send information that the content is composed as progressive format, set progressive to true.
  • To send information that the content is composed as interleaved format, set progressive to false.

The default value of progressive is true.

programInfo:numSubtitleTracks Optional String

Number of subtitle tracks.

programInfo:subtitleTrackInfo Optional String

Array of objects that contain information about individual subtitle tracks.

programInfo should include number of subtitleTrackInfo object specified in numSubtitleTracks.

programInfo:subtitleTrackInfo:language Optional String

Language in which the subtitles will be presented.

programInfo:subtitleTrackInfo:pid Optional String

Packet Id associated with streams.

programInfo:subtitleTrackInfo:ctag Optional String

Component tag information in MPEG-TS standard used to classify each stream in PMT (program map table).

programInfo:subtitleTrackInfo:type Optional String

Subtitle type information

  • bmp
  • pes
  • text
programInfo:subtitleTrackInfo:compositionPageId Optional String

Property to determine track for DVB subtitle.

programInfo:subtitleTrackInfo:ancilaryPageId Optional String

Property to determine track for DVB subtitle

programInfo:subtitleTrackInfo:hearingImpared Optional String

Flag to set hearing Impared option.

  • To send information that the content is support hearing Impared option, set hearingImpared to true.
  • To send information that the content is not support hearing Impared option, set hearingImpared to false.

The default value of hearingImpared is false.

programInfo:subtitleType Optional String

Type of subtitle. 

programInfo:mediaId Required String

Unique identifier of pipeline which reports source's information.

videoInfo

The videoInfo event provides information related to video.

Call Returns

Name

Required

Type

Description

width Required String

Actual width value of input video (before crop in video decoder. Used fot UI presentation)

height Required String

Actual height value of input video (before crop in video decoder. Used fot UI presentation)

aspectRatio Optional String

Ratio between width and height.

Format: n:n

For example:  16:9, 4:3

pixelAspectRatio Optional String

Aspect ratio of Input video pixel.

Format: n:n

For example:  1:1

frameRate Required String

Number of frames per second at which the video is being played.

bitRate Optional String

Bit rate value of content.

mode3D Required String

3D Mode information.

  • check_board
  • column_interleave
  • line_interleave_half
  • side_side_half_LR 
  • side_side_half_RL
  • top_bottom
  • frame_sequential
  • dual_stream
  • bottom_top
  • side_side_full_LR
  • side_side_full_RL
  • 2d
actual3D Required String

Actual 3D mode information which is determined after acquiring resources.

  • check_board
  • column_interleave
  • line_interleave_half
  • side_side_half_LR
  • side_side_half_RL
  • top_bottom
  • frame_sequential
  • dual_stream
  • bottom_top
  • side_side_full_LR
  • side_side_full_RL 
  • 2d
scanType Required String

Flag indicating progressive information.

  • true: progressive
  • false: interlace
mediaId Required String

Unique identifier of pipeline which sending the states.

audioInfo

The audioInfo event provides information related to audio.

Call Returns

Name

Required

Type

Description

sampleRate Required String

Samples of audio carried per second, measured in kHz.

channels Required String

Number of audio channels.

mediaId Required String

Unique identifier of pipeline which sending information.

error

The error event reports errors thrown by pipelines. 

Call Returns

Name

Required

Type

Description

errorCode Optional String

Error code from the service.

errorText Optional String

Error code description from the service.

mediaId Required String

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 Object: resources

Object of resource name, quantity, and index.

Resources can hold more than one set of resource, qty, and index.

e.g.){"resources":"[{"resource":"VDEC","qty":1,"index":0},[{"resource":"ADEC","qty":1,"index":0}]"}

state Required String

Flag indicating the result of acquire request.

  • To send information that resource acquisitionn is successfully performed, set state to true.
  • To send information that resource acquisitionn is failed, set state to false.
connectionId Required String

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 String

Type of pipeline that made a new request.

This is the pipeline requesting the additional resources.

requestor_name Required String

Name of pipeline that made new request.

This is the pipeline requesting the additional resources.

action Required String

Action requested to do at the pipeline when this policyAction is delivered.

resources Required Object: policyAction_resources

Insufficient resource list.

connectionId Required String

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 String

Media id of addressed pipeline.

x Required String

x coordinate of active region

y Required String

y coordinate of active region

width Required String

width of active region

height Required String

height of active region


ERROR REFERENCES

Error Code

Error Text

Error Description

600PolicyAction

Media related errors reported by the media pipeline are reported in to several categories.

  • RM category related errors are reported in the 600 range.
  • For managed pipelines
601Resource Allocation Error

Media related errors reported by the media pipeline are reported in to several categories.

  • RM category related errors are reported in the 600 range.
  • For managed pipelines

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