com.webos.media

Note
This API has been available since API level 11.

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

      acquire

      ACG: media.operation
      • Added: API level 11

      Description

      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.

      Note:

      • 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

      resourcesRequiredObject: resources

      See "resources" object.

      connectionIdRequiredString

      Indicates the unique identifier of the pipeline to acquire resources.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredString

      Indicates the status of the 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.

      Example

      Example code

      # 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,
              "resource": "DISP0",
              "index": 3
          }],
          "state": true,
          "connectionId": "_UZRkgE3EJgXvwl"
      }

      attach

      ACG: media.operation
      • Added: API level 11

      Description

      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.

      Note: 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

      Indicates the 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.
      errorCodeRequiredNumber

      The error code for the operation

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

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

      Example

      Example code

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

      Response:

      {  
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_IsGbw614gu7xRB"
      }

      getActivePipelines

      ACG: media.query
      • Added: API level 11

      Description

      Gets JSON formatted output of currently active media pipelines.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdOptionalString

      Indicates unique identifier of the media object.

      Call Returns

      Name

      Required

      Type

      Description

      IdOptionalString

      Indicates unique identifier of the media object.

      typeOptionalString

      Indicates the type of media.

      pidOptionalNumber (int16_t)

      Indicates the process id of media content provider.

      is_managedOptionalBoolean

      Indicates whether media Content Provider is a managed pipeline or not.

      • true: Managed
      • false: Not managed
      is_foregroundOptionalBoolean

      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
      mediaStateOptionalString

      Indicates the current state of Media Content Provider.

      Possible values are:

      • 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_stateOptionalBoolean

      Media is currently selected for Resource Management Policy Action and is in suspended state

      uriOptionalString

      Indicate the uri of media object.

      appIdOptionalString

      Indicates the application id of application using media object.

      processStateOptionalString

      Indicates the status of the media content provider process.

      Possible values are:

      • 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_focusOptionalString

      Indicates that the media object is currently selected for focus.

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

      timestampOptionalString

      Indicates the timestamp of the 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 are: 

      • PLAY
      • SEEK
      • LOAD
      • notifyForeground
      • notifyActivity
      resourcesRequiredObject array: resources

      See "resources" object.

      mediaIdOptionalString

      Indicates mediaId of the object.

      errorCodeOptionalNumber

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextOptionalString

      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.

      returnValueOptionalBoolean

      Indicates the status of operation.

      Possible values are:

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

      Example

      Example code

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

      Response: 

      [
         {
            "pid":1521,
            "resources":[
               {
                  "resource":"ADEC",
                  "index":3
               },
               {
                  "resource":"VDEC",
                  "index":3
               }
            ],
            "type":"media",
            "id":"_IzddeO9d8fP1jO",
            "is_managed":true,
            "mediaState":"play",
            "is_foreground":true,
            "policy_state":0,
            "uri":"http://media.w3.org/2010/05/sintel/trailer.mp4",
            "appId":"com.webos.app.enactbrowser",
            "processState":"media_loaded",
            "is_focus":false,
            "timestamp":1423867226706,
            "mediaId":"_IzddeO9d8fP1jO"
         }
      ]

      getDisplayId

      ACG: media.query
      • Added: API level 21

      Description

      Gets information about the display on which the specified application instance is launched.

      Note: This method supports multi-screen playback. 

      Parameters

      Name

      Required

      Type

      Description

      instanceIdRequiredString

      Indicates the unique identifier of the application instance.

      Call Returns

      Name

      Required

      Type

      Description

      displayIdOptionalNumber

      Indicates the identifier of the display used.

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
      errorCodeOptionalNumber

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Example

      Example: For application launched in primary screen

      # luna-send -n 1 -f luna://com.webos.media/getDisplayId '{"instanceId": "9582089b-3a1c-4a37-acf8-83df8d1b6eec0"}'

      Response:

      {
          "displayId": 0,
          "returnValue": true
      }

      Example: For application launched in secondary screen

      # luna-send -n 1 -f luna://com.webos.media/getDisplayId '{"instanceId": "df6d8057-611d-4080-b5ba-0de59f2a40210"}'

      Response:

      {
          "displayId": 1,
          "returnValue": true
      }

      getForegroundAppInfo

      ACG: media.query
      • Added: API level 11

      Description

      Provides the application's foreground information.

      Parameters

      None

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed.
      appIdRequiredString

      Indicates the application ID (appId).

      acbsRequiredObject array: acbs

      Contains an array of objects that gives details of the media. (pipeline ID, playstate, position and so on)

      Example

      Example code

      # 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.enactbrowser",
         "returnValue":true
      }

      getPipelineState

      ACG: media.query
      • Added: API level 21

      Description

      Requests the media server to retrieve pipeline state information.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates the unique identifier of the loaded media/camera pipeline.

      Call Returns

      Name

      Required

      Type

      Description

      errorCodeOptionalNumber

      The error code for the operation.

      Returns 0 when the returnValue is true and returns '-1' if JSON parsing fails.

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Operation is successful.
      • false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
      errorTextOptionalString

      Indicates the reason for the failure of the operation. 

      Returns "No Error" if there is no failure.

      dataOptionalObject: data

      Pipeline state information.

      mediaIdOptionalString

      Media ID of the object.

      Error Codes Reference

      Error Code

      Error Text

      Error Description

      -1Method "getPipelineState" for category "/" was not handled

      JSON parsing fails.  

       
      0No Error

      when the returnValue is true

       

      Example

      Example scenario

      # luna-send -n 2 -f luna://com.webos.media/getPipelineState '{"mediaId":"_pwvgD9ivrcVkYV"}'

      Response:

      {
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "data":"{\"seekPos\":0,\"loadCompleted\":{\"mediaId\":\"_pwvgD9ivrcVkYV\"},\"currentTime\":52249,\"seekDone\":{\"mediaId\":\"_pwvgD9ivrcVkYV\"},\"bufferingEnd\":{\"mediaId\":\"_pwvgD9ivrcVkYV\"},\"videoInfo\":{\"video\":{\"codec\":0,\"width\":854,\"frame_rate\":{\"num\":0,\"den\":1},\"bitrate\":0,\"height\":480}},\"mediaState\":\"play\",\"subscription\":true,\"endOfStream\":{\"mediaId\":\"_pwvgD9ivrcVkYV\"},\"bufferingStart\":{\"mediaId\":\"_pwvgD9ivrcVkYV\"},\"playing\":{\"mediaId\":\"_pwvgD9ivrcVkYV\"},\"bufferRange\":{\"beginTime\":52249,\"endTime\":52,\"remainingTime\":1,\"percent\":100},\"procState\":\"media_loaded\",\"sourceInfo\":{\"audio_streams\":[{\"codec\":0,\"sample_rate\":48000,\"bit_rate\":80000}],\"duration\":52250,\"programs\":[{\"video_stream\":1,\"audio_stream\":1}],\"video_streams\":[{\"video\":{\"codec\":0,\"width\":854,\"frame_rate\":{\"num\":0,\"den\":1},\"bitrate\":0,\"height\":480}}],\"container\":\"\",\"seekable\":true}}",
         "mediaId":"_pwvgD9ivrcVkYV"
      }

      load

      ACG: media.operation
      • Added: API level 11

      Description

      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

      uriRequiredString

      Indicates the uri of the media object.

      Example: http://mymovie.mp4, file://mymovie.mp4 

      typeRequiredString

      Indicates the type of pipeline to load.

      Note:

      • Currently,  media playback pipeline is supported.
      • The media server also supports run-time installation of additional pipelines which is outside the scope of this API document.
      • type : "camera" supported for Open / Auto to preview the supported USB camera
      payloadOptionalObject: payload

      See "payload" 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.
      errorCodeRequiredNumber

      The error code for the operation.

      Note: Currently, it returns '0' even when the returnValue is true and returns '-1' if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

      Indicates the unique identifier of the loaded media/camera pipeline which is used for subsequent operations.

      Example

      Example code

      # 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.enactbrowser",
               "windowId":"_Window_Id_2"
            }
         }
      }'

      Response:

      {  
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_Pvzj2FRn42sL99"
      }

      Example: Load camera with System V shared memory

      # luna-send -n 1 luna://com.webos.media/load '{
         "uri":"camera://com.webos.service.camera2/7010",
         "payload":{
            "option":{
               "appId":"com.webos.app.mediaevents-test",
               "windowId":"_Window_Id_1",
               "videoDisplayMode":"Textured",
               "width":640,
               "height":480,
               "format":"JPEG",
               "frameRate":30,
               "memType":"shmem",
               "memSrc":"7010"
            }
         },
         "type":"camera"
      }'

      Response:

      {
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_puV0o3WTEsbgDt"
      }

      Note: For Open Emulator, while executing the luna-send command directly in console, send "windowId" as empty. The first frame of camera data directly displays on the emulator window.

      Example : Load camera with Posix shared memory

      # luna-send -n 1 luna://com.webos.media/load '{
         "uri":"camera://com.webos.service.camera2/7010",
         "payload":{
            "option":{
               "appId":"com.webos.app.mediaevents-test",
               "windowId":"_Window_Id_1",
               "videoDisplayMode":"Textured",
               "width":640,
               "height":480,
               "format":"JPEG",
               "frameRate":30,
               "memType":"posixshm",
               "memSrc":"9",

               "handle":4286
            }
         },
         "type":"camera"
      }'

      Response:

      {
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_puV0o3WTEsbgDt"
      }

      Note: For Open Emulator, while executing the luna-send command directly in console, send "windowId" as empty. The first frame of camera data directly displays on the emulator window.

      Example : Load camera with MMAP mode

      # luna-send -n 1 luna://com.webos.media/load '{
         "uri":"camera://com.webos.service.camera2/7010",
         "payload":{
            "option":{
               "appId":"com.webos.app.mediaevents-test",
               "windowId":"_Window_Id_1",
               "videoDisplayMode":"Textured",
               "width":640,
               "height":480,
               "format":"JPEG",
               "frameRate":30,
               "memType":"device",
               "memSrc":"/dev/video1"
            }
         },
         "type":"camera"
      }'

      Response:

      {
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_puV0o3WTEsbgDt"
      }

      Note: For Open Emulator, while executing the luna-send command directly in console, send "windowId" as empty. The first frame of camera data directly displays on the emulator window.

      Example : Load camera with DMABUF mode

      # luna-send -n 1 luna://com.webos.media/load '{
         "uri":"camera://com.webos.service.camera2/7010",
         "payload":{
            "option":{
               "appId":"com.webos.app.mediaevents-test",
               "windowId":"_Window_Id_1",
               "videoDisplayMode":"Textured",
               "width":640,
               "height":480,
               "format":"JPEG",
               "frameRate":30,
               "memType":"device",
               "memSrc":"/dev/video1",

               "iomode":2
            }
         },
         "type":"camera"
      }'

      Response:

      {
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_puV0o3WTEsbgDt"
      }

      notifyActivity

      ACG: media.operation
      • Added: API level 11

      Description

      Notifies the media server that the specific pipeline is currently in use. This command raises the timestamp record of the corresponding pipeline to lessen the chance to be picked as the target for a policyAction, which would require the pipeline to release its resources.

      Parameters

      Name

      Required

      Type

      Description

      connectionIdRequiredString

      Indicates the unique identifier of the registered pipeline.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

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

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Example

      Example code

      # luna-send -n 1 -f luna://com.webos.media/notifyActivity '{
         "connectionId":"_EYv0VPazu3aGo0"
      }'

      Response:

      {
          "returnValue": true
      }

      notifyBackground

      ACG: media.operation
      • Added: API level 11

      Description

      Marks a pipeline as background. This API is called when the media object in question is carded, deleted, or otherwise removed from view. 

      Note: Background video content is not currently visible on the display surface.

      Parameters

      Name

      Required

      Type

      Description

      connectionIdRequiredString

      Indicates the unique identifier of the registered pipeline.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

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

      Note: The notifyBackground method may fail because of:

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

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Example

      Example code

      # luna-send -n 1 -f luna://com.webos.media/notifyBackground '{
         "connectionId":"_c5zE4w2k7rqmC5"
      }'

      Response:

      {
          "returnValue": true
      }

      notifyForeground

      ACG: media.operation
      • Added: API level 11

      Description

      Marks a pipeline as foreground. This API is called when the media object in question is un-carded and made visible.

      Note: Foreground pipeline video content is currently visible on the display surface.

      Parameters

      Name

      Required

      Type

      Description

      connectionIdRequiredString

      Indicates the unique identifier of the registered pipeline.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

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

      Note: The notifyForeground method may fail because of:

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

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Example

      Example code

      # luna-send -n 1 -f luna://com.webos.media/notifyForeground '{
         "connectionId":"_z6SJt11Yx0mVp1"
      }'

      Response:

      {
         "returnValue":true
      }

      notifyPipelineStatus

      ACG: media.operation
      • Added: API level 21

      Description

      Notifies the playback status of media pipelines.

      Parameters

      Name

      Required

      Type

      Description

      connectionIdRequiredString

      Indicates the unique identifier of the media pipeline.

      pipelineStatusRequiredString

      Indicates the pipeline status.

      Possible values are: 

      • load
      • play
      • pause
      • unload
      pidOptionalNumber

      Indicates the Process ID of the 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. Check the "errorCode" and "errorText" fields for details.
      errorCodeOptionalNumber

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Error Codes Reference

      Error Code

      Error Text

      Error Description

      -1Method "notifyPipelineStatus" for category "/" was not handled

      JSON parsing fails. 

       

      0No Error

      when the return value is true

      Example

      Example code

      # luna-send -n 1 -f luna://com.webos.media/notifyPipelineStatus '{"connectionId":"_gu6P54bK8fkGgo","pipelineStatus":"pause","pid":3190}'

      Response:

      {
          "returnValue": true
      }

      pause

      ACG: media
      • Added: API level 11

      Description

      Requests the media server to pause the media object.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates the unique identifier of the loaded media/camera pipeline.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed.
      errorCodeRequiredNumber

      The error code for the operation

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

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

      Example

      Example code

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

      Response:

      {  
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_IsGbw614gu7xRB"
      }

      play

      ACG: media.operation
      • Added: API level 11

      Description

      Requests the media server to play the media object.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates the 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.
      errorCodeRequiredNumber

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

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

      Example

      Example code

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

      Response:

      {  
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_IsGbw614gu7xRB"
      }

      reacquire

      ACG: media.operation
      • Added: API level 21

      Description

      Dynamically adds more resources to the pipeline.

      Parameters

      Name

      Required

      Type

      Description

      connectionIdRequiredString

      The unique identifier of the pipeline to add resources.

      resourcesRequiredString

      Resource list to be allocated.

      Note: Resources information must be provided as a stringified form of one of the following objects:

      • resources (recommended)
      • resources_new (supported to provide backward compatibility)

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Operation is successful.
      • false: Operation has failed. Check the 'errorCode' and 'errorText' fields.
      errorCodeOptionalNumber

      The error code for the failed operation.

      errorTextOptionalString

      The reason for the failure of the operation. See the 'Error Codes' section of this method for details.

      mediaIdOptionalString

      Indicates the unique identifier of the loaded media pipeline which is requested.

      Note: This parameter is returned only in error cases.

      Error Codes Reference

      Error Code

      Error Text

      Error Description

      601Resource Allocation Error

      This error occurs when there is failure in releasing already acquired resources.

      602Invalid Payload

      This error occurs when invalid payload is detected.

      603Resources not Provided

      This error occurs when argument "resources" is not provided.

      604ConnectionId Not Provided

      This error occurs when "argument" connection id is not provided.

      605Invalid Connection

      This error occurs when provided "connection id" is not available.

      606Internal Error

      This error occurs when an internal error occurs.

      607Invalid Resource

      This error occurs when provided with improper resource.

      Example

      Example : Reacquire using resources_new object

      # luna-send -n 1 -f luna://com.webos.media/reacquire '{
          "connectionId": "_dqEYC2bXztCwsj",
          "resources":"{
              \"new\":\"[{\\\"qty\\\":3,\\\"resource\\\":\\\"VDEC\\\"}]\",
              \"old\":\"[{\\\"index\\\":31,\\\"resource\\\":\\\"VDEC\\\"}]\"}"
      }'

      Response:

      {
          "returnValue": true
      }

      Example : Reacquire using resources object (recommended approach)

      # luna-send -n 1 luna://com.webos.media/reacquire '{
          "resources": "[{\"resource\":\"VDEC\",\"qty\":3}]",
          "connectionId": "_ABQqg8An9msDLC"
      }'

      Response:

      {
          "returnValue": true
      }

      registerMedia

      ACG: media.operation
      Retired
      • Added: API level 11
      • Deprecated: API level 21
      • Retired: API level 23

      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

      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

      Example code

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

       

      Response:

      {
          "returnValue": true
      }

      registerPipeline

      ACG: media.operation
      • Added: API level 11

      Description

      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.

      Note: This method is applicable for unmanaged pipelines only. For managed pipelines, this is taken care of internally by the mediaserver.

      Parameters

      Name

      Required

      Type

      Description

      typeRequiredString

      Indicates the type of pipeline to register.

      Possible values are:

      • "ref"
      • "media"
      • "sim"
      appIdOptionalString

      Application ID

      Call Returns

      Name

      Required

      Type

      Description

      connectionIdRequiredString

      Indicates the unique identifier of the registered pipeline.

      returnValueOptionalBoolean

      Indicates the status of the 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.

      Example

      Example code

      # luna-send -n 1 -f luna://com.webos.media/registerPipeline '{
         "type":"media"
      }'

      Response:

      {
          "connectionId": "_KXpMET1Sxc1eGO"
      }

      release

      ACG: media.operation
      • Added: API level 11

      Description

      Informs media server the resources are released correctly and are not being used anymore.

      Note: This method is applicable for unmanaged pipelines only.

      Parameters

      Name

      Required

      Type

      Description

      resourcesRequiredString

      Resource information.

      Note: Resources information must be provided as a stringified form of one of the "resources" object.

      connectionIdRequiredString

      Indicates the unique identifier of the pipeline to release resources.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of operation. Possible values are:

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

      The error code for the failed operation.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Error Codes Reference

      Error Code

      Error Text

      Error Description

      -1Method \"release\" for category \"/\" was not handled

      JSON parsing fails.

      602Invalid Payload

      This error occurs when invalid payload is detected.

      603Resources not Provided

      This error occurs when argument "resources" is not provided.

      604ConnectionId Not Provided

      This error occurs when "argument" connection id is not provided.

      605Invalid Connection

      This error occurs when provided "connection id" is not available

      607Invalid Resource

      This error occurs when provided with improper resource.

      608Resource Release Error

      This error occurs when there is failure in releasing resources.

      Example

      Example code

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

      seek

      ACG: media.operation
      • Added: API level 11

      Description

      Seeks the media object to a specified time position.

      Parameters

      Name

      Required

      Type

      Description

      positionRequiredNumber

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

      mediaIdRequiredString

      Indicates the unique identifier of the loaded media/camera pipeline.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed.
      errorCodeRequiredNumber

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

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

      Example

      Example code

      # luna-send -n 1 -f luna://com.webos.media/seek '{
         "position":64935,
         "mediaId":"_IsGbw614gu7xRB"
      }'

      Response:

      {  
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_IsGbw614gu7xRB"
      }

      setPlayRate

      ACG: media.operation
      • Added: API level 11

      Description

      Sets the pipeline media play rate.

      Parameters

      Name

      Required

      Type

      Description

      playRateRequiredNumber (double)

      Indicates the play back rate for the media.

      mediaIdRequiredString

      Indicates the unique identifier for the requested loaded media pipeline.

      audioOutputRequiredBoolean

      Determine to mute audio

      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.
      errorCodeRequiredNumber

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

      Indicates the unique identifier of the media object.

      Error Codes Reference

      Error Code

      Error Text

      Error Description

      -1Method "setPlayRate" for category "/" was not handled

      JSON parsing fails. 

       

      0No Error

      when the returnValue is true

       

      Example

      Example code

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

      setVolume

      ACG: media.operation
      • Added: API level 11

      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.

      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.
      errorCodeRequiredNumber

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

      Unique identifier of the media object.

      Example

      Example code

      # luna-send -n  1 -f luna://com.webos.media/setVolume '{"mediaId":"_IsGbw614gu7xRB","volume":60}'

      Response:

      {  
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_IsGbw614gu7xRB"
      }

      startCameraRecord

      ACG: media.operation
      • Added: API level 11

      Description

      Starts camera recording. Camera pipeline stores streamed data from the camera and microphone (if required) at the specified location. 

      Parameters

      Name

      Required

      Type

      Description

      locationRequiredString

      Indicates the path for storing the recorded file.

      formatRequiredString

      Indicates the format in which data is stored.

      Possible values are:

      • MP4 - file format MP4 ( .mp4) file gets generated
      mediaIdRequiredString

      Indicates the unique identifier of the camera pipeline obtained using the load() API.

      audioRequiredBoolean

      Indicates whether the audio data from the microphone also has to be recorded along with video.

      Possible values are:

      • true: Include audio data along with video
      • false: Does not include audio data along with video

      Note: For Signage, record with audio is not supported.

      audioSrcRequiredString

      Indicates the name of the microphone device from which the audio data has to be captured.

      Note: Supports only one audio source (pcm_input).

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
      errorCodeOptionalNumber

      The error code for the failed operation.

      Note: errorCode always defaults to 0. Details of the error will be available in the logs.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Note: errorText is always empty. Details of the error will be available in the logs.

      mediaIdRequiredString

      Indicates the unique identifier of the camera pipeline.

      Example

      Example : Camera recording without audio

      # luna-send -n 1 luna://com.webos.media/startCameraRecord '{
         "mediaId" :"_5nxnM2Xiw55PYS" ,
         "location":"/media/internal/",
         "format" :"MP4",
         "audio":false,
         "audioSrc":"pcm_input"
      }'

      Example : Camera recording with audio

      # luna-send -n 1 luna://com.webos.media/startCameraRecord '{
         "mediaId" :"_5nxnM2Xiw55PYS" ,
         "location":"/media/internal/",
         "format" :"MP4",
         "audio":true,
         "audioSrc":"pcm_input"
      }'

      stopCameraRecord

      ACG: media.operation
      • Added: API level 11

      Description

      Requests media server to stop camera recording and change to the preview state.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates the unique identifier of the camera pipeline obtained using the load() API.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
      errorCodeOptionalNumber

      The error code for the failed operation.

      Note: errorCode always defaults to 0. Details of the error will be available in the logs.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Note: errorText is always empty. Details of the error will be available in the logs.

      mediaIdRequiredString

      Indicates the unique identifier of the camera pipeline.

      Example

      Example code

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

      subscribe

      ACG: media.operation
      • Added: API level 11

      Description

      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

      Indicates the 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

      The error code for the operation

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextOptionalString

      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.

      mediaIdOptionalString

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

      subscriptionOptionalString

      Indicates the current subscription status.

      Possible values are:

      • true: Subscription is ON
      • false: Subscription is OFF

      Subscription Returns

      Name

      Required

      Type

      Description

      loadCompletedOptionalObject

      See "loadCompleted" event.

      seekDoneOptionalObject

      See "seekDone" event.

      endOfStreamOptionalObject

      See "endOfStream" event.

      currentTimeOptionalObject

      See "currentTime" event.

      bufferRangeOptionalObject

      See "bufferRange" event.

      bufferingStartOptionalObject

      See "bufferingStart" event.

      bufferingEndOptionalObject

      See "bufferingEnd" event.

      sourceInfoOptionalObject

      See "sourceInfo" event.

      videoInfoOptionalObject

      See "videoInfo" event.

      audioInfoOptionalObject

      See "audioInfo" event.

      errorOptionalObject

      See "error" event.

      Example

      Example code

      # luna-send -n 2 -f luna://com.webos.media/subscribe '{
         "mediaId":"_rTNwzp81clPsxX"
      }'

      Response:

      {
          "subscription": true
      }
      {
          "errorCode": 0,
          "returnValue": true,
          "errorText": "No Error",
          "mediaId": "_rTNwzp81clPsxX"
      }

      takeCameraSnapshot

      ACG: media.operation
      • Added: API level 11

      Description

      Captures a frame from the camera preview.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates the unique identifier of the camera pipeline which is obtained using the load() API.

      locationRequiredString

      Indicates the path of the captured image to be stored.

      formatRequiredString

      Indicates the format of the frame is to be captured.

      Possible values are:

      • jpg
      widthRequiredNumber

      Indicates the width of the captured image in pixels.

      Note: Width should be within the range supported by the camera hardware.

      heightRequiredNumber

      Indicates the height of the captured image in pixels.

      Note: Height should be within the range supported by the camera hardware.

      pictureQualityRequiredNumber

      Indicates the percentage of the picture quality.

      Possible values are:

      • 0-100

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
      errorCodeOptionalNumber

      The error code for the failed operation.

      Note: errorCode always defaults to 0. Details of the error will be available in the logs.

      errorTextOptionalString

      Indicates the reason for the failure of the operation.

      Note: errorText is always empty. Details of the error will be available in the logs.

      mediaIdRequiredString

      Indicates the unique identifier the camera pipeline.

      Example

      Example code

      # luna-send -n 1 luna://com.webos.media/takeCameraSnapshot '{
         "mediaId":"",
         "location":"/tmp/",
         "format":"jpg",
         "width":640,
         "height":480,
         "pictureQuality":30
      }'

      trackAppProcesses

      ACG: media.devutility
      • Added: API level 11

      Description

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

      Note: The return value of the method contains an array of the PIDs of all currently existing pipelines mapped to the corresponding appIDs.

      Parameters

      None

      Call Returns

      Name

      Required

      Type

      Description

      subscribedRequiredBoolean

      Returns true if the subscriber was successfully added.

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed.
      mediaPipelinesRequiredObject array: mediaPipelines

      See "mediaPipelines" object.

      subscriptionRequiredBoolean

      Indicates the current subscription status.

      Possible values are:

      • true: Subscription is ON
      • false: Subscription is OFF

      Subscription Returns

      Name

      Required

      Type

      Description

      procUpdateRequiredObject: procUpdate

      See "procUpdate" object.

      Example

      Example code

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

      tryAcquire

      ACG: media.operation
      • Added: API level 11

      Description

      Tries to acquire resources from mediaserver.

      Note:

      • 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

      See "resources" object.

      connectionIdRequiredString

      Indicates the unique identifier of the pipeline to acquire resources.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the 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.

      Example

      Example code

      # 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,
              "resource": "DISP0",
              "index": 3
          }],
          "state": true,
          "connectionId": "_7P3y7e9AcPv8t1"
      }

      unload

      ACG: media.operation
      • Added: API level 11

      Description

      Unloads the pipeline and releases all AV resources.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates the 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. 
      errorCodeRequiredString

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

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

      Example

      Example code

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

      Response:

      {
         "errorCode":0,
         "returnValue":true,
         "errorText":"No Error",
         "mediaId":"_Pvzj2FRn42sL99"
      }

      unregisterPipeline

      ACG: media.operation
      • Added: API level 11

      Description

      Unregisters pipeline with Resource Manager.

      Note: This method is applicable to unmanaged pipelines only.

      Parameters

      Name

      Required

      Type

      Description

      connectionIdRequiredString

      Indicates the unique identifier of the pipeline to unregister.

      Call Returns

      Name

      Required

      Type

      Description

      returnValueRequiredBoolean

      Indicates the status of the operation.

      Possible values are:

      • true: Indicates that the operation was successful.
      • false: Indicates that the operation failed.
      errorCodeRequiredNumber

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

      Indicates the unique identifier of the loaded media pipeline which is requested.

      Example

      Example code

      # luna-send -n 1 -f luna://com.webos.media/unregisterPipeline '{
         "connectionId":"_KXpMET1Sxc1eGO"
      }'

      Response:

      {
          "errorCode": 0,
          "returnValue": true,
          "errorText": "No Error",
          "mediaId": "_KXpMET1Sxc1eGO"
      }

      unsubscribe

      ACG: media.operation
      • Added: API level 11

      Description

      Unsubscribes from media pipeline related events.

      Parameters

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates the 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.
      errorCodeRequiredNumber

      The error code for the operation.

      Note: Currently, it returns 0 even when the returnValue is true and returns -1 if JSON parsing fails.  

      errorTextRequiredString

      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.

      mediaIdOptionalString

      Indicates the unique identifier of the loaded media pipeline requested to unsubscribe.

      Error Codes Reference

      Error Code

      Error Text

      Error Description

      -1Method \"unsubscribe\" for category \"/\" was not handled

      JSON parsing fails.

      Example

      Example code

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

      Response:

      {
          "errorCode": 0,
          "returnValue": true,
          "errorText": "No Error",
          "mediaId": "_gmkaR0OtGWxr6z"
      }

      Objects

      ResourceDetails

      Details of the resource.

      Name

      Required

      Type

      Description

      resourceRequiredString

      Name of resource to acquire.

      Possible values are:

      • VDEC: video decoder resources.
      • ADEC: audio decoder resources.
      • DISP: display resources.
      qtyOptionalNumber

      Quantity of resources to acquire.

      Range: [1, 32] (depends on the configuration).

      Note: Only applicable for the resource to be acquired.

      indexOptionalNumber

      Specific index of resources to be released.

      Range: [0, 31] (depends on the configuration).

      Note: Only applicable for the resource to be released.

      ResponseObject

      Provides 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

      acbs

      Array of objects that gives details of media for foreground application (such as pipeline Id, playstate, position, etc.)

      Name

      Required

      Type

      Description

      pipelineIdRequiredString

      Pipeline id

      playStateNowRequiredString

      Current playback status

      playStateNextRequiredString

      Next playback status

      isFullScreenRequiredBoolean

      Specifies if the app is in full screen mode.

      positionXRequiredNumber (int32_t)

      X Position of window

      positionYRequiredNumber (int32_t)

      Y Position of window

      widthRequiredNumber (int32_t)

      Width of the app window.

      heightRequiredNumber (int32_t)

      Height of the app window.

      audioInfo

      Provides information related to audio.

      Name

      Required

      Type

      Description

      codecOptionalString

      Codec information

      bitrateOptionalNumber (int64_t)

      Bit rate value of content.

      sample_rateOptionalNumber (int32_t)

      Samples of audio carried per second, measured in kHz.

      data

      Provides information related to the current state of the pipeline.

      Name

      Required

      Type

      Description

      endOfStreamOptionalObject: mediaId

      Indicates if the pipeline has reached the end of stream.

      loadCompletedOptionalObject: mediaId

      Indicates whether the pipeline is in the loaded state.

      currentTimeOptionalNumber (int64_t)

      Current time at which the media is being played.

      bufferingEndOptionalObject: mediaId

      Indicates pipeline is in play state after filling buffers.

      bufferingStartOptionalObject: mediaId

      Indicates pipeline is temporarily paused internally in order to buffer more data.

      videoInfoOptionalObject: videoInfo

      Video information.

      sourceInfoOptionalObject: sourceInfo

      Source information.

      subscriptionRequiredString

      Indicates if events are subscribed for the pipeline with subscribe method.

      Possible values are:

      • true: Subscription is ON
      • false: Subscription is OFF
      mediaStateRequiredString

      Pipeline playback state.

      Possible values are:

      • load
      • preload
      • unload
      • play
      • pause
      • stop
      procStateRequiredString

      Media Pipeline process state.

      Possible values are:

      • starting
      • running
      • media_loaded
      • restarting
      • stop
      • suspended
      bufferRangeOptionalObject

      See "bufferRange" event parameters

      playingOptionalObject: mediaId

      Indicates if the pipeline is playing.

      pausedOptionalObject: mediaId

      Indicates if the pipeline is paused.

      seekDoneOptionalObject: mediaId

      Indicates seek request is completed.

      seekPosOptionalNumber (int64_t)

      Position to which seek is done.

      display_attr

      Provides detailed information for display resource.

      Name

      Required

      Type

      Description

      crtc-idRequiredNumber (int32_t)

      Crtc id of display

      plane-idRequiredNumber (uint32_t)

      Plane id of display

      conn-idRequiredNumber (int32_t)

      Connector id of display

      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

      numRequiredNumber (int32_t)

      Numerator of frame rate

      denRequiredNumber (int32_t)

      Denominator of frame rate

      mediaId

      Unique identifier of the loaded media/camera pipeline.

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Indicates mediaId of the object.

      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

      appIdRequiredString

      Indicates application id

      pidRequiredNumber

      Indicates process id of pipeline

      option

      Provides parameters used in the load/preload API.

      Name

      Required

      Type

      Description

      appIdRequiredString

      Indicates the application id.

      windowIdRequiredString

      Indicates the windowId attached to the video sink. 

      The value should be specified in the format: "_Window_Id_X" (X is number).

      Note: The value should be given by the surface manager before the load API is called.

      videoDisplayModeOptionalString

      Indicates the display mode of the pipeline.

      Default: Textured

      Note: Only Textured value is supported.

      display-pathOptionalNumber

      Indicates the display path.

      Default: 0

      Note:

      • Multiple values can be supported if a device has multiple screens (i.e., 0 for primary display, 1 for secondary display).
      • It is only applicable to Open.
      widthOptionalNumber

      Indicates the width of the image to be taken from the camera device. The value can vary from supported width of the image.

      Note: This is required when load API is used for the camera.

      heightOptionalNumber

      Indicates the height of the image to be taken from the camera device. The value can vary from supported height of the image.

      Note: This is required when the load API is used for the camera.

      formatOptionalString

      Indicates the type of the camera data to be taken from the camera device.

      Possible values are:

      • JPEG
      • YUY2

      Note: This is required when the load API is used for the camera.

      frameRateOptionalNumber

      Indicates the number of frames captured per sec from a camera device.

      Based on the camera supported values, provide the frameRate such as 30 / 15 and so on.

      Note: This is required when the load API is used for the camera.

      memTypeOptionalString

      Indicates the type of access with camera device.

      Possible values are:

      • device
      • shmem
      • posixshm

      Note: This is required when the load API is used for the camera.

      memSrcOptionalString

      Indicates the source of the camera data.

      Possible value: Device node like  "/dev/video0" /  shared memory key "7010" ( which is returned by camera service ).

      Note: This is required when the load API is used for the camera.

      handleOptionalNumber

      Indicates the handle for the device obtained using the open() API of camera service. This parameter is required only when "memType" is "posixshm" for camera functionality.

      iomodeOptionalNumber

      Represents the memory mode value which are defined using an enum like mmap, user pointer & dma buffer, when "memType" is "device" for camera functionality.

      Possible values are:

      • 0 - mmap (default mode)
      • 1 - user pointer (not supported)
      • 2 - dma buffer
      cameraIdOptionalString

      Reserved.

      Note: Applications are advised not to use this parameter.

      payload

      Payload format used in load API. It represents the JSON payload object for a specific type of pipeline.

      Name

      Required

      Type

      Description

      optionOptionalObject: option

      See "option" object.

      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

      appIdRequiredString

      Indicates application ID. 

      pidRequiredNumber

      Indicates process ID of pipeline.

      execRequiredBoolean

      Provides information on the mapping status of app ID and a pipeline. Possible values are:

      • true: when a pipeline app ID mapping is added
      • false: when a pipeline app ID mapping is destroyed.

      programs

      Provides audio/video stream information.

      Name

      Required

      Type

      Description

      video_streamRequiredNumber (int32_t)

      The number of video streams in program.

      audio_streamRequiredNumber (int32_t)

      The number of audio streams in program.

      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,
              },
              {
                  "resource": "VDEC",
                  "qty": 1,
                  "index": 3
              },
              {
                  "resource": "ADEC",
                  "qty": 1,
                  "index": 3
              }
          ]
      }

      Name

      Required

      Type

      Description

      qtyOptionalNumber

      Quantity of resource to acquire.

      Note: Below points applicable to Open and Open-Emulator as per current configuration

      1. Resource quantity range.
        1. For VDEC 32.
        2. For ADEC 3.
        3. For DISP 3.
      2. It is mandatory for "acquire' and 'reacquire" API means 'Required' field for 'acquire' and 'reacquire' API is 'Yes'
      indexOptionalNumber

      Specific index of resource to acquire.

      Note: Below points applicable to Open and Open-Emulator as per current configuration

      1. Resource range values.
        1. For VDEC 0 - 31.
        2. For VDEC 0 - 3.
        3. For VDEC 0 - 3.
      2. It is mandatory for 'release' and 'reacquire' API means 'Required' field for 'release' and 'reacquire' API is 'Yes'
      resourceOptionalString

      Name of resource to acquire.

      Possible values are:

      • VDEC: Source of video decoder.
      • ADEC: Source of audio decoder.
      • DISPX: Display resource. X corresponds to display starting with 0. If a device has more than one display, there can be multiple display resources (example: DISP0, DISP1).

      Note:

      • VDEC maximum resources count is 32 for current configuration.
      • ADEC maximum resources count is 3 for current configuration.
      • DISP maximum resources count is 3 for current configuration.
      • It is mandatory for 'acquire', 'reacquire' ND 'release' API means 'Required' field for 'acquire', 'reacquire' and 'release' API is 'Yes'

      resources_new

      Object indicating the new and old resource.

      Name

      Required

      Type

      Description

      oldRequiredObject array: ResourceDetails

      The resources to be released.

      newRequiredObject array: ResourceDetails

      The resources to be acquired.

      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

      programsRequiredObject array: programs

      See "programs" object.

      seekableRequiredBoolean

      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.
      video_streamsRequiredObject array: videoInfo

      See "videoInfo" object.

      audio_streamsRequiredObject array: audioInfo

      See "audioInfo" object.

      containerOptionalString

      Media format (container type) of source

      • "RAW","WAV","MP3", "AAC", "RA", "AVI", "MP4", "MPEG1", "MPEG2", "ASF", "MKV", "PS", "TS", "RM", "FLV", "F4V", "ISM"
      durationRequiredNumber (int64_t)

      Total duration in milli-seconds of the program.

      videoInfo

      Provides information related to video.

      Name

      Required

      Type

      Description

      widthRequiredNumber (uint32_t)

      Actual width value of input video (before cropping in video decoder. Used for UI presentation.)

      heightRequiredNumber (uint32_t)

      Actual height value of input video (before cropping in video decoder. Used for UI presentation.)

      frameRateRequiredObject: frameRate

      See "frameRate" object.

      codecOptionalString

      Codec information.

      bitRateOptionalNumber (uint64_t)

      Bit rate value of content.

      Signals/Events

      acquireComplete 

      The acquireCompete event is invoked when the acquire request is performed and the result comes out.

      Call Returns

      Name

      Required

      Type

      Description

      resourcesRequiredObject

      See "resources" object.

      stateRequiredBoolean

      Flag indicating the result of acquire request.

      • To send information that resource acquisition is successfully performed, set state to true.
      • To send information that resource acquisition failed, set state to false.
      connectionIdRequiredString

      Unique identifier of the pipeline to acquire resource.

      audioInfo

      The audioInfo event provides information related to audio.

      Call Returns

      Name

      Required

      Type

      Description

      audioInfoRequiredObject: audioInfo

      See "audioInfo" object.

      bufferRange

      Indicates the buffering range of the particular media content. It is raised multiple times when specific media is loaded.

      Call Returns

      Name

      Required

      Type

      Description

      beginTimeRequiredNumber

      Starting time of the bufferRange of the media.

      endTimeRequiredNumber

      End time of the bufferRange of the media.

      mediaIdRequiredString

      Unique identifier of pipeline reports bufferRange.

      percentRequiredNumber

      Percent of the total buffer the current buffer range represents.

      bufferingEnd

      Indicates the pipeline is resuming playback after filling buffers.

      Call Returns

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Unique identifier of the pipeline that buffering is complete.

      bufferingStart

      Indicates the pipeline is temporarily pausing playback internally in order to buffer more data.

      Call Returns

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Unique identifier of the pipeline that starts buffering.

      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

      currentTimeRequiredNumber (int64_t)

      Current time at which the media is being played.

      mediaIdRequiredString

      Unique identifier of pipeline which reports current time.

      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

      mediaIdOptionalString

      Unique identifier of detached pipeline.

      endOfStream

      The endOfStream event is raised when a specific media has received all of its data.

      Call Returns

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Unique identifier of pipeline met end of stream.

      error

      The error event reports errors thrown by pipelines. 

      Call Returns

      Name

      Required

      Type

      Description

      errorCodeOptionalNumber

      Error code from the service.

      errorTextOptionalString

      Error code description from the service.

      mediaIdRequiredString

      Unique identifier of pipeline sending error information.

      loadCompleted

      The loadCompleted event is raised when a specific media pipeline has been successfully loaded.

      Call Returns

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Unique identifier of the loaded pipeline.

      paused

      The paused event is raised when a specific media has been successfully paused.

      Call Returns

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Unique identifier of the requested pipeline to pause.

      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

      mediaIdRequiredString

      Unique identifier of the requested pipeline to play.

      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_typeRequiredString

      Type of pipeline that made a new request.

      This is the pipeline requesting the additional resources.

      requestor_nameRequiredString

      Name of pipeline that made new request.

      This is the pipeline requesting additional resources.

      actionRequiredString

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

      resourcesRequiredObject

      See "resources" object.

      connectionIdRequiredString

      Unique identifier of the pipeline to get policyAction event

      seekDone

      The seekDone event is raised when a seek operation for a media has been successfully completed.

      Call Returns

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Unique identifier of the requested pipeline to seek.

      sourceInfo

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

      Call Returns

      Name

      Required

      Type

      Description

      sourceInfoRequiredObject: sourceInfo

      See "sourceInfo" object.

      unloadCompleted

      The unloadCompleted event is raised when a specific media pipeline has been successfully unloaded.

      Call Returns

      Name

      Required

      Type

      Description

      mediaIdRequiredString

      Unique identifier of the unloaded pipeline.

      videoInfo

      The videoInfo event provides information related to video.

      Call Returns

      Name

      Required

      Type

      Description

      videoInfoRequiredObject: videoInfo

      See "videoInfo" object.

      API Error Codes Reference

      Error Code

      Error Text

      Error Description

      600PolicyAction

      Media related errors reported by the media pipeline are reported into 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 into several categories.

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

      Contents