com.webos.service.avoutput

API Summary

This service that wraps audio/video HAL supports controlling of audio and video output.

Overview of the API

(click to expand)

AVOutput is responsible for connecting the input pipeline to the backend video. The Media Framework is responsible for determining the life cycle of a connection and pipeline policy (which application is in ForeGround and has focus, resources etc). Media Framework uses AVOutput APIs to achieve connection and video post-processing.

  • AVOutput does NOT have policy
  • It provides APIs to connect video source (frames from decoder or HDMI etc) to video plane.
  • It provides the HAL abstraction for the backend (i.e. AVOutput will work with HAL or KMS/DRM or ALSA or other hardware abstraction layer)  
  • It provides the interface for h/w video post-processing and scaling - the post processing functionality will be implemented with a plugin design to allow various degrees of functionality based on product.

This service moves from a context (or state) based implementation to a context-less (stateless) implementation of audio and video handling. Since mediaserver manages pipelines for the applications, avoutput  will not hold any context information. avoutput  will expose methods which makes the right HAL calls to connect source to sink and position output as needed.


Open All


video/connect

Description

Connects a video source to a video sink

Parameters

Name

Required

Type

Description

sourceRequiredString

Video source. Possible values are:

  • VDEC
  • JPEG
  • HDMI
  • AVD
sourcePortOptionalNumber (int8_t)

Video port number.

Note: For VDEC, the possible values are 0 and 1.

sinkRequiredString

Video sink. Possible values are: 

  • MAIN
  • SUB

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.
errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

planeIDRequiredNumber (int8_t)

Numeric plane ID of the sink.

Example

luna-send -n 1 -f luna://com.webos.service.avoutput/video/connect '{"source": "VDEC", "sourcePort":1, "sink":"MAIN", "outputMode":"DISPLAY"}'

luna-send -n 1 -f luna://com.webos.service.avoutput/video/connect '{"source": "VDEC", "sourcePort":0, "sink":"SUB", "outputMode":"DISPLAY"}'


video/disconnect

Description

Disconnects video from sink.

Parameters

Name

Required

Type

Description

sinkRequiredString

Video sink. Possible values are: 

  • MAIN
  • SUB

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
errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

luna-send -n 1 -f luna://com.webos.service.avoutput/video/disconnect '{"sink":"MAIN"}'

luna-send -n 1 -f luna://com.webos.service.avoutput/video/disconnect '{"sink":"SUB"}'


video/setMediaData

Description

Sets video media data needed for playback.

Parameters

Name

Required

Type

Description

sink Required String

Video sink.Possible values are:

  • MAIN
  • SUB
contentType Required String

Type of media content. Possible values are:

  • movie
  • photo
  • camera
frameRate Required Number (double)

Video frame rate.

width Required Number (uint32_t)

Video frame width.

height Required Number (uint32_t)

Video frame height.

scanType Required String

Type of scan. Possible values are:

  • deinterlaced
  • interlaced
adaptive Required Boolean

Indicates whether the media is adaptive or progressive.

  • true: Adaptive
  • false: Progressive.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode Required Number (int8_t)

The error code for the failed operation.

errorText Required String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

luna-send -n 1 -f luna://com.webos.service.avoutput/video/setMediaData '{"sink":"MAIN", "contentType":"movie", "frameRate":24,"width":640,"height":480, "adaptive":false, "scanType":"progressive"}


video/getStatus

Description

Lists all video sinks and their status.

Parameters

Name

Required

Type

Description

subscribeRequiredBoolean

Subscribe for notifications when value changes. Possible values are:

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

Note: This returns one entry for each MAIN and SUB.

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
subscribedRequiredBoolean

Indicates if subscribed to get notified when there is a change in value.

  • true - Subscribed for changes
  • false - Not subscribed
errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Subscription Returns

Name

Required

Type

Description

sinkRequiredString

Video sink. Possible values are:

  • MAIN
  • SUB
connectedSourceRequiredString

Video source connected.

Note: Returns 'null' if not connected.

connectedSourcePortRequiredNumber (int8_t)

Port of the source to which sink is connected

mutedRequiredBoolean

Possible values are:

  • true: Video is on mute
  • false: Video is not on mute
frameRateRequiredNumber (double)

Frame rate of video.

widthRequiredNumber (int8_t)

Frame width of video.

scanTypeRequiredString

Type of scan. Possible values are:

  • progressive
  • interlaced
adaptiveRequiredBoolean

Possible values are:

  • true: adaptive
  • false: non- adaptive
fullscreenRequiredBoolean

Possible values are:

  • true : if output is fullscreen
  • false: if otherwise
displayOutputRequiredObject: VideoRect

Specifies display output location.

sourceInputRequiredObject: VideoRect

Specifies source or input cropping location.

opacityRequiredNumber (uint8_t)

Possible values are in the range of 0..255.

  • 0 = Highest transparency value
  • 255 = Highest opacity value
zOrderRequiredNumber (int8_t)

Possible values are:

  • int (0..3) - relative order from Main, Sub1, Sub2, Sub3

Example

luna-send -n 1 -f luna://com.webos.service.avoutput/video/getStatus '{"subscribe":true}'


video/blankVideo

Description

Stop/start data output to video sink. This allows seamless disconnect and connect and avoids invalid data output while reconnection is in progress.

Parameters

Name

Required

Type

Description

sinkRequiredString

Video sink. Possible values are:

  • MAIN
  • SUB

Note: Mute video for specified sink.

blankRequiredBoolean

Possible values are:

  • true: blank/mute video
  • false: unmute the video

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
errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

luna-send -n 1 -f luna://com.webos.service.avoutput/video/blankVideo '{"sink":"MAIN", "blank":true}'

luna-send -n 1 -f luna://com.webos.service.avoutput/video/blankVideo '{"sink":"MAIN", "blank":false}'


video/display/setDisplayWindow

Description

Setup video output location on the screen for specified sink.

Note: Video is actually placed only if setVideoMediaData has been called.
Otherwise the values are stored and video is placed after subsequent setVideoMediaData call.

Parameters

Name

Required

Type

Description

sinkRequiredString

Video sink. Possible values are:

  • MAIN
  • SUB
fullScreenRequiredBoolean

Possible values are:

  • true: output is fullscreen
  • false: use data from displayOuput
displayOutputOptionalObject: VideoRect

Display output rectangle.

Note: Required if fullscreen is false.

sourceInputOptionalObject: VideoRect

Source input rectangle.

Note: Full video frame if not set.

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
errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example 1:

Verify video position and size is correctly changed - the video should be placed in bottom right corner:

luna-send -n 1 luna://com.webos.service.avoutput/video/display/setDisplayWindow '{"sink":"MAIN", "fullScreen":false, "displayOutput": {"x":1000, "y":500, "width": 920, "height":580}}'

Example 2:

Verify video source rect is correctly changed - the video should be zoomed in to center 2x:

luna-send -n 1 luna://com.webos.service.avoutput/video/display/setDisplayWindow '{"sink":"MAIN", "fullScreen":false, "displayOutput": {"x":1000, "y":500, "width": 920, "height":580}, "sourceInput":{"x":80, "y":60, "width":160,"height":120}}'

Example 3:

Verify fullscreen mode:

luna-send -n 1 luna://com.webos.service.avoutput/video/display/setDisplayWindow '{"sink":"MAIN", "fullScreen":true}'

Example 4:

Verify opacity, the video should become almost transparent:

luna-send -n 1 luna://com.webos.service.avoutput/video/display/setDisplayWindow '{"sink":"MAIN", "fullScreen":true, "opacity":100}'


video/display/setCompositing

Description

Set compositing parameters for the video sinks.
This maps directly to adapter call and changes the compositing parameters for both video outputs simultaneously.

Parameters

Name

Required

Type

Description

mainOpacityRequiredNumber (uint8_t)

Possible values are:

  • int (0..255) - Range of output opacity values that can be specified.
  • 0 = Highest transparency value,
  • 255 = Highest opacity value.
mainZorderRequiredNumber (uint8_t)

Possible values are:

  • int (0..3) - specify relative order between Main and Sub,
  • 0 = bottom,
  • 3 = top.
subOpacityRequiredNumber (uint32_t) array

Possible values are:

  • int (0..255) - Range of output opacity values that can be specified.
  • 0 = Highest transparency value,
  • 255 = Highest opacity value.
subZorderRequiredNumber (uint32_t) array

Possible values are:

  • int (0..3) - specify relative order between Main and Sub,
  • 0 = bottom,
  • 3 = top.

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
errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

luna-send -n 1 luna://com.webos.service.avoutput/video/display/setVideoCompositing '{"mainOpacity": 255, "subOpacity":100, "mainZOrder":0, "subZOrder": 1}'


video/display/getOutputCapabilities

Description

Helper method to query the set video limits

Parameters

None

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
numPlanesRequiredNumber (int8_t)

Total hardware planes available with platform for rendering

outputCapabilityRequiredObject array

sinkId: string - one of ["MAIN", "SUB0", "SUB1", ...]

minDownscaleSize: See "VideoSize" object.

maxUpscaleSize: See "VideoSize" object.

errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

luna-send -n 1 luna://com.webos.service.avoutput/video/display/getOutputCapabilities '{"subscribe":true}'


audio/connect

Description

Connects audio source to audio sink.
Note: In case it's already connected, will disconnect from previous sink automatically.

Parameters

Name

Required

Type

Description

source Required String

Audio source. Possible values are: 

  • ADEC
  • MIXER
  • LOW_DELAY_MIXER
sourcePort Optional String

Audio port number.

Note: For ADEC, the possible values are 0 and 1.

sink Required String

Audio sink. Possible values are:

  • MAIN
  • SUB
outputMode Required String

Mode of output. Possible values are:

  • tv_speaker
  • external_speaker
  • soundbar
  • simplink
  • bt_soundbar
  • lineout
  • headphone, ...
audioType Required String

Type of the audio.

Note: Only when ADEC is specified.

Possible values are:

  • media
  • phone
  • test
  • ringtone
  • default_app
  • voice
  • alert
  • notification
  • text_to_speech
  • game_media
  • game_directmedia
  • system_music
  • media_mix

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details
errorCode Required String

The error code for the failed operation.

errorText Required String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

luna-send -n 1 -f luna://com.webos.service.avoutput/audio/connect '{"source": "ADEC", "sourcePort":1, "sink":"MAIN", "outputMode":"tv_speaker", "audioType":"media"}'


audio/disconnect

Description

Disconnect from audio sink.
No change is done if not connected.

Parameters

Name

Required

Type

Description

sourceRequiredString

Audio source. Possible values are: 

  • ADEC
  • MIXER
  • LOW_DELAY_MIXER
sourcePortOptionalNumber (int8_t)

Audio port number

Note: For ADEC, the possible values are 0 and 1.

sinkRequiredString

Audio sink. Possible values are:

  • MAIN
  • SUB

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
errorCodeRequiredNumber (int8_t)

The error code for the failed operation.

errorTextRequiredString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

luna-send -n 1 -f luna://com.webos.service.avoutput/audio/disconnect '{"sink":"MAIN", "source": "ADEC", "sourcePort":1}'

luna-send -n 1 -f luna://com.webos.service.avoutput/audio/disconnect '{"sink":"SUB", "source": "ADEC", "sourcePort":1}'


Objects

VideoRect

Object to represent the video window coordinates.

Name

Required

Type

Description

xRequiredNumber (int32_t)

Horizontal offset from top left of the screen or origin (0,0)

yRequiredNumber (int32_t)

Vertical offset from top left of the screen

widthRequiredNumber (int32_t)

Width of the video window

heightRequiredNumber (int32_t)

Height of the video window

VideoSize

Object to represent video size.

Name

Required

Type

Description

widthRequiredNumber (int32_t)

Width of the plane

heightRequiredNumber (int32_t)

Height of the plane


ERROR REFERENCES

Error Code

Error Text

Error Description

1Unknown error

General Service error: API_ERROR_UNKNOWN   1  "Unknown error"

10Not implemented

General Service error: API_ERROR_NOT_IMPLEMENTED  10 "Not implemented"

20Driver error while executing the command

Driver error: API_ERROR_HAL_ERROR    20  "Driver error while executing the command"

100Video not connected

Video error: API_ERROR_VIDEO_NOT_CONNECTED    100   "Video not connected"

200Audio not connected

Audio error: API_ERROR_AUDIO_NOT_CONNECTED   200  "Audio not connected"


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