uMediaClient API Reference

API Summary

Provides access to the functionality offered by the webOS media server.

Note: Instead of using the raw luna uMS API service, the uMediaClient API service can be used to control playback of audio/video files and streams.

Overview of the API

uMediaClient

Controls the playback of the audio/video files and streams instead of using the raw luna uMS API.

Type Definitions

Alias	Type Definition	Description
AudioStreamClass	AudioStreamClass	Indicates the type of the the AudioStreamClass.
std::string	std::string	std::string
const std::string&	const std::string&	const std::string&
EaseType	EaseType	Indicates the kind of EaseType.
std::string&	std::string&	std::string&
const buffer_range_t&	const buffer_range_t&	See the bufferRange object.
const ums::source_info_t&	const ums::source_info_t&	See the sourceInfo object.
const ums::video_info_t&	const ums::video_info_t&	See the videoInfo object.
const ums::audio_info_t&	const ums::audio_info_t&	See the audioInfo object.
rational_t	rational_t	See the frameRate object.
std::vector<program_info_t>	std::vector<program_info_t>	See the programs object.
std::vector<video_info_t>	std::vector<video_info_t>	See the videoInfo object.
std::vector<audio_info_t>	std::vector<audio_info_t>	See the audioInfo object.

Structures

videoInfo

Provides information related to the video.

Name	Type	Description
width	uint32_t	Indicates the actual width value of input video ( Before cropping in the video decoder. Used for UI presentation).
height	uint32_t	Indicates the actual height value of input video ( Before cropping in the video decoder. Used for UI presentation).
frameRate	typedef rational_t	See "frameRate" object.
codec	typedef std::string	Indicates the codec information.
bitRate	unsigned long	Indicates the bitRate value of the content.

frameRate

Provides information about the number of frames per second at which the video is being played.

The frameRate is represented as a combination of numerator and denominator.

Name	Type	Description
num	int32_t	Indicates the numerator of the frame rate.
den	int32_t	Indicates the denominator of the frame rate.

audioInfo

Provides information related to the audio.

Name	Type	Description
codec	typedef std::string	Indicates the codec information.
bitrate	int64_t	Indicates the bitrate value of content.
sample_rate	int32_t	Indicates the samples of the audio carried per second (measured in kHz).

programs

Provides the audio/video stream information.

Name	Type	Description
video_stream	int32_t	Indicates the number of video streams in program.
audio_stream	int32_t	Indicates the number of audio streams in the program.

sourceInfo

Provides information of the media that has just been loaded.

Name	Type	Description
container	typedef std::string	Indicates the media format (container type) of source. Possible values are: RAW WAV MP3 AAC RA AVI MP4 MPEG1 MPEG2 ASF MKV PS TS RM FLV F4V ISM
duration	int64_t	Indicates the total duration of the program (in milliseconds).
seekable	bool	Indicates if the media supports the seek operations. Possible values are: true: The content is available for seek false: The content is not available for seek.
programs	typedef std::vector<program_info_t>	See the programs object.
video_streams	typedef std::vector<video_info_t>	See the videoInfo object.
audio_streams	typedef std::vector<audio_info_t>	See the audioInfo object.

bufferRange

Provides data of the current buffer for the specified stream.

Name	Type	Description
beginTime	int32_t	Indicates the starting time of the bufferRange of the media.
endTime	int32_t	Indicates the end time of the bufferRange of the media.
remainingTime	int32_t	Indicates the amount of time remaining beyond the buffer range from current time.
percent	int32_t	Indicates the percentage of the total buffer represented by the current buffer range.

Methods

load

Description

Requests media server to load the new pipeline.

The load is a blocking call which returns after pipeline process is properly created, so the return means whether the pipeline process is properly created or not.

Since the load functions return value just after pipeline process created, pipeline's completion of load is not guaranteed at the time of return. End of load process is only guaranteed by onLoadCompleted.

The audioClass parameter was used at the initial stage of development and load command with string type "type" parameter was added from WebOS 1.0.

Syntax

load (typedef std::string uri, typedef AudioStreamClass audioClass, [typedef std::string payload])

Parameters

Name	Required	Type	Description
uri	Required	typedef std::string	Indicates the uri of the media object. Example: http://mymovie.mp4, file://mymovie.mp4
audioClass	Required	typedef AudioStreamClass	Indicates the type of the the AudioStreamClass. Possible values are: kFile kMedia kGapless kCamera kAudioStreamRingtone kAudioStreamAlert kAudioStreamMedia kAudioStreamNotification kAudioStreamFeedback kAudioStreamFlash kAudioStreamNavigation kAudioStreamVoicedial kAudioStreamVoip kAudioStreamCalendar kAudioStreamAlarm kAudioStreamDefaultapp kAudioStreamVvm kAudioStreamAlsa kAudioStreamFake kAudioStreamNone
payload	Optional	typedef std::string	Indicates the JSON object containing the pipeline specific parameters.

uri

Required

typedef std::string

Indicates the uri of the media object.

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

audioClass

Required

typedef AudioStreamClass

Indicates the type of the the AudioStreamClass.

Possible values are:

kFile
kMedia
kGapless
kCamera
kAudioStreamRingtone
kAudioStreamAlert
kAudioStreamMedia
kAudioStreamNotification
kAudioStreamFeedback
kAudioStreamFlash
kAudioStreamNavigation
kAudioStreamVoicedial
kAudioStreamVoip
kAudioStreamCalendar
kAudioStreamAlarm
kAudioStreamDefaultapp
kAudioStreamVvm
kAudioStreamAlsa
kAudioStreamFake
kAudioStreamNone

payload

Optional

typedef std::string

Indicates the JSON object containing the pipeline specific parameters.

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout

loadAsync

Description

Requests media server to load a new pipeline.

loadAsync is a non-blocking call which returns immediately. Return of loadAsync means whether the load command is properly sent by luna communication or not.

Since the loadAsync functions return value just after sending luna command, pipeline's completion of load is not guaranteed at the time of return. End of load process is only guaranteed by onLoadCompleted.

AudioStreamClass audioClass parameter was used at the initial stage of development and load command with string type "type" parameter was added from WebOS 1.0.

Syntax

loadAsync (typedef std::string uri, typedef AudioStreamClass audioClass, [typedef std::string payload])

Parameters

Name	Required	Type	Description
uri	Required	typedef std::string	Indicates the uri of the media object. Example: http://mymovie.mp4, file://mymovie.mp4
audioClass	Required	typedef AudioStreamClass	Indicates the type of the the AudioStreamClass. Possible values are: kFile kMedia kGapless kCamera kAudioStreamRingtone kAudioStreamAlert kAudioStreamMedia kAudioStreamNotification kAudioStreamFeedback kAudioStreamFlash kAudioStreamNavigation kAudioStreamVoicedial kAudioStreamVoip kAudioStreamCalendar kAudioStreamAlarm kAudioStreamDefaultapp kAudioStreamVvm kAudioStreamAlsa kAudioStreamFake kAudioStreamNone
payload	Optional	typedef std::string	Indicates the JSON object containing the pipeline specific parameters.

uri

Required

typedef std::string

Indicates the uri of the media object.

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

audioClass

Required

typedef AudioStreamClass

Indicates the type of the the AudioStreamClass.

Possible values are:

kFile
kMedia
kGapless
kCamera
kAudioStreamRingtone
kAudioStreamAlert
kAudioStreamMedia
kAudioStreamNotification
kAudioStreamFeedback
kAudioStreamFlash
kAudioStreamNavigation
kAudioStreamVoicedial
kAudioStreamVoip
kAudioStreamCalendar
kAudioStreamAlarm
kAudioStreamDefaultapp
kAudioStreamVvm
kAudioStreamAlsa
kAudioStreamFake
kAudioStreamNone

payload

Optional

typedef std::string

Indicates the JSON object containing the pipeline specific parameters.

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

unload

Description

Unloads the pipeline and releases all AV resources.

Syntax

unload ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

notifyForeground

Description

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

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

Syntax

notifyForeground ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

notifyBackground

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.

Syntax

notifyBackground ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

attach

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

Syntax

attach (typedef const std::string& mediaId)

Parameters

Name	Required	Type	Description
mediaId	Required	typedef const std::string&	Indicates the unique identifier of the loaded media/camera pipeline.

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

play

Description

Requests the media server to play the media object.

Syntax

play ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

pause

Description

Requests the media server to pause the media object.

Syntax

pause ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

seek

Description

Seeks the media object to a specified time position.

Syntax

seek (int64_t position)

Parameters

Name	Required	Type	Description
position	Required	int64_t	Indicates the position (in milliseconds) from the start position to seek position.

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

setVolume

Description

Sets the volume for the specified media object. Additionally, it specifies the ease (fade-in and fade-out) properties for the media object.

Syntax

setVolume (const int32_t volume, [const int32_t duration], [typedef EaseType type])

Parameters

Name	Required	Type	Description
volume	Required	const int32_t	Indicates the volume to be set. Possible volume range: 0~100
duration	Optional	const int32_t	Indicates the duration time for the easing effect.
type	Optional	typedef EaseType	Indicates the kind of EaseType. Possible values are: kEaseTypeLinear kEaseTypeInCubic kEaseTypeOutCubic

volume

Required

const int32_t

Indicates the volume to be set.

Possible volume range: 0~100

duration

Optional

const int32_t

Indicates the duration time for the easing effect.

type

Optional

typedef EaseType

Indicates the kind of EaseType.

Possible values are:

kEaseTypeLinear
kEaseTypeInCubic
kEaseTypeOutCubic

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

preload

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.

NOTE: The difference between load and preload is hardware resource acquisition. For the preload, there is no real hardware acquisition. After calling the preload method, the load method must be invoked to acquire hardware resources.

Syntax

preload (typedef std::string uri, typedef AudioStreamClass audioClass, [typedef std::string payload])

Parameters

Name	Required	Type	Description
uri	Required	typedef std::string	Indicates the uri of the media object. Example: http://mymovie.mp4, file://mymovie.mp4
audioClass	Required	typedef AudioStreamClass	Indicates the type of the the AudioStreamClass. Possible values are: kFile kMedia kGapless kCamera kAudioStreamRingtone kAudioStreamAlert kAudioStreamMedia kAudioStreamNotification kAudioStreamFeedback kAudioStreamFlash kAudioStreamNavigation kAudioStreamVoicedial kAudioStreamVoip kAudioStreamCalendar kAudioStreamAlarm kAudioStreamDefaultapp kAudioStreamVvm kAudioStreamAlsa kAudioStreamFake kAudioStreamNone
payload	Optional	typedef std::string	Indicates the JSON object containing the pipeline specific parameters.

uri

Required

typedef std::string

Indicates the uri of the media object.

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

audioClass

Required

typedef AudioStreamClass

Indicates the type of the the AudioStreamClass.

Possible values are:

kFile
kMedia
kGapless
kCamera
kAudioStreamRingtone
kAudioStreamAlert
kAudioStreamMedia
kAudioStreamNotification
kAudioStreamFeedback
kAudioStreamFlash
kAudioStreamNavigation
kAudioStreamVoicedial
kAudioStreamVoip
kAudioStreamCalendar
kAudioStreamAlarm
kAudioStreamDefaultapp
kAudioStreamVvm
kAudioStreamAlsa
kAudioStreamFake
kAudioStreamNone

payload

Optional

typedef std::string

Indicates the JSON object containing the pipeline specific parameters.

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

setPlayRate

Description

Sets the pipeline media play rate.

Syntax

setPlayRate (double rate, [bool audioOutput])

Parameters

Name	Required	Type	Description
rate	Required	double	Indicates the play back rate for the media.
audioOutput	Optional	bool	Indicates if the audio is in mute.

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

startCameraRecord

Description

Starts camera recording. Camera pipeline stores streamed data from the camera at the specified location.

Syntax

startCameraRecord (typedef std::string& location, typedef std::string& format)

Parameters

Name	Required	Type	Description
location	Required	typedef std::string&	Indicates the path for storing the recorded file.
format	Required	typedef std::string&	Indicates the format in which data is stored. Possible values are: h264 (currently supports only H264 TS format)

location

Required

typedef std::string&

Indicates the path for storing the recorded file.

format

Required

typedef std::string&

Indicates the format in which data is stored.

Possible values are:

h264 (currently supports only H264 TS format)

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

stopCameraRecord

Description

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

Syntax

stopCameraRecord ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

takeCameraSnapshot

Description

Captures a frame from the camera preview.

Syntax

takeCameraSnapshot (typedef std::string& location, typedef std::string& format, int32_t width, int32_t height, int32_t pictureQuality)

Parameters

Name	Required	Type	Description
location	Required	typedef std::string&	Indicates the path of the captured image to be stored.
format	Required	typedef std::string&	Indicates the format of the frame is to be captured. Possible values are: jpg
width	Required	int32_t	Indicates the width of the captured image in pixels. Note: Width should be within the range supported by the camera hardware.
height	Required	int32_t	Indicates the height of the captured image in pixels. Note: Height should be within the range supported by the camera hardware.
pictureQuality	Required	int32_t	Indicates the percentage of the picture quality. Possible value range: 0-100

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

getMediaId

Description

Gets the mediaId for the client.

Syntax

getMediaId ()

Parameters

None

Returns

Name	Required	Type	Description
string	Required	typedef std::string	Indicates the unique ID of the loaded pipeline.

getPipelineState

Description

Gets the pipeline's status which is attached to the client.

Note: The pipeline status is delivered as a luna event.

Syntax

getPipelineState ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

logPipelineState

Description

Prints the pipeline status as known by the uMS at the log file.

Syntax

logPipelineState ()

Parameters

None

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

setPipelineDebugState

Description

Set the pipeline's debug state for the gstreamer.

Syntax

setPipelineDebugState (typedef std::string& debug_state)

Parameters

Name	Required	Type	Description
debug_state	Required	typedef std::string&	Indicates the JSON object containing the pipeline specific parameters.

Returns

Name	Required	Type	Description
bool	Required	bool	Indicates the result of sending the request to the uMS by the luna communication. Possible values are: true: The command is sent without an error false: The command is failed to be sent. (Wrong format or Timeout)

bool

Required

bool

Indicates the result of sending the request to the uMS by the luna communication.

Possible values are:

true: The command is sent without an error
false: The command is failed to be sent. (Wrong format or Timeout)

Events

onLoadCompleted

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

onPreloadCompleted

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

onUnloadCompleted

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

onDetached

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

onSeekDone

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

onBufferingStart

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

onBufferingEnd

Indicates that the pipeline is resuming playback after filling the buffers.

onBufferRange

The onBufferRange event provides data of the current buffer of a specified stream.

Parameters

Name	Required	Type	Description
bufferRange	Required	typedef const buffer_range_t&	See "bufferRange" object.

onPlaying

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

onPaused

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

onEndOfStream

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

onCurrentTime

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.

Parameters

Name	Required	Type	Description
currentTime	Required	int64_t	Indicates the current time at which the media is being played.

onSourceInfo

Provides information about the media that has just been loaded.

Parameters

Name	Required	Type	Description
sourceInfo	Required	typedef const ums::source_info_t&	See "sourceInfo" object.

onVideoInfo

Provides information related to the video.

Parameters

Name	Required	Type	Description
videoInfo	Required	typedef const ums::video_info_t&	See "videoInfo" object.

onAudioInfo

Provides information related to the audio.

Parameters

Name	Required	Type	Description
audioInfo	Required	typedef const ums::audio_info_t&	See "audioInfo" object.

onError

Reports errors thrown by the pipelines.

Parameters

Name	Required	Type	Description
onPlayingerrorCode	Required	int64_t	Indicates the error code from the service.
errorText	Required	typedef const std::string&	Indicates the reason for the failure of the operation.

onUserDefinedChanged

Delivers application specific events with the agreement of applications and pipelines (or players).

Parameters

Name	Required	Type	Description
message	Required	const char *	Indicates the user defined data.