Tizen WASM Player
Tizen WASM Player: Tizen TV WebAssembly Media Player extension allowing for a low-level elementary media stream playback.
samsung::wasm::ElementaryMediaStreamSource Class Referencefinal

Main class of WASM Player. ElementaryMediaStreamSourceacts as a data source for HTMLMediaElement. More...

#include <elementary_media_stream_source.h>

Public Types

enum  Mode { Mode::kNormal, Mode::kLowLatency, Mode::kVideoTexture }
 
enum  ReadyState {
  ReadyState::kDetached, ReadyState::kClosed, ReadyState::kOpenPending, ReadyState::kOpen,
  ReadyState::kEnded
}
 
enum  AsyncResult {
  AsyncResult::kSuccess, AsyncResult::kOpenInProgressError, AsyncResult::kCloseInProgressError, AsyncResult::kInvalidStateError,
  AsyncResult::kSourceNotAttachedError, AsyncResult::kNoTracksAttachedError, AsyncResult::kUnknownError
}
 

Public Member Functions

 ElementaryMediaStreamSource (Mode latency_mode=Mode::kNormal)
 
 ElementaryMediaStreamSource (const ElementaryMediaStreamSource &)=delete
 
 ElementaryMediaStreamSource (ElementaryMediaStreamSource &&)
 
ElementaryMediaStreamSourceoperator= (const ElementaryMediaStreamSource &)=delete
 
ElementaryMediaStreamSourceoperator= (ElementaryMediaStreamSource &&)
 
 ~ElementaryMediaStreamSource ()
 
bool IsValid () const
 
Result< ElementaryMediaTrackAddTrack (const ElementaryAudioTrackConfig &)
 
Result< ElementaryMediaTrackAddTrack (const ElementaryVideoTrackConfig &)
 
Result< void > RemoveTrack (const ElementaryMediaTrack &)
 
Result< void > Flush ()
 
Result< void > Close (std::function< void(AsyncResult)> on_finished_callback)
 
Result< void > Open (std::function< void(AsyncResult)> on_finished_callback)
 
Result< SecondsGetDuration () const
 
Result< void > SetDuration (Seconds new_duration)
 
Result< ModeGetMode () const
 
Result< ReadyStateGetReadyState () const
 
Result< void > SetListener (ElementaryMediaStreamSourceListener *listener)
 
const char * GetURL () const
 

Friends

class html::HTMLMediaElement
 

Detailed Description

Main class of WASM Player. ElementaryMediaStreamSourceacts as a data source for HTMLMediaElement.

ElementaryMediaStreamSource manages a set of ElementaryMediaTrack objects. ElementaryMediaPackets that media consists of are sent to WASM Player via individual tracks added to the source.

Definition at line 57 of file elementary_media_stream_source.h.

Member Enumeration Documentation

◆ AsyncResult

Defines results of asynchronous operation.
An async operation (such as Open()) can report an error in two ways: with its return value - an error there means the job wasn't started - and with argument passed to callback, which signals incorrect execution of an asnyc job.
AsyncResult describes the latter kind of errors.

Enumerator
kSuccess 

Operation ended with success.

kOpenInProgressError 

A change of state couldn't finish because EMSS was opening. This can happen when Close() was called without waiting for Open() to finish.

kCloseInProgressError 

A change of state couldn't finish because EMSS was closing. This can happen when Open() was called without waiting for Close() to finish.

kInvalidStateError 

Requested operation couldn't be performed in current ready state.

kSourceNotAttachedError 

Requested operation couldn't be performed because EMSS wasn't attached.

kNoTracksAttachedError 

Open() was called with no tracks attached to the source.

kUnknownError 

Unknown error.

Definition at line 178 of file elementary_media_stream_source.h.

◆ Mode

Defines modes in which ElementaryMediaStreamSource can operate. The mode is set in ElementaryMediaStreamSource's constructor and cannot be changed during its lifetime.

Enumerator
kNormal 

This mode is a default mode, appropriate for most playback scenarios.
Pipeline clock is controlled by the platform player when the player works in normal latency mode. Source will buffer packets until they can be rendered according to their pts values.

kLowLatency 

This mode is appropriate for low latency playback scenarios.
Pipeline clock is controlled by the application when the player works in low latency mode. Source will render appended packets as soon as possible and won't perform any internal buffering. Pipeline clock is set according to the pts values of appended packets.

Remarks
  • the application is responsible for maintaining stream synchronization,
  • packets are rendered as soon as possible, so fps is dependent entirely on when packets are appended,
  • media element's time is calculated based on packets' pts values, so they should be set correctly,
  • packets should be tuned for low latency playback (e.g. B-frames are not allowed in video streams).
kVideoTexture 

This mode is appropriate for decoding video into GL texture scenarios.
Pipeline clock is controlled by the platform player. Source will buffer packets until they can be rendered according to their pts values and they will be decoded and put into GL texture. Application should constantly request for new pictures by calling ElementaryMediaTrack::FillTextureWithNextFrame() method. After texture is rendered, application needs to call ElementaryMediaTrack::recycleTexture()' method.

Remarks
This mode is supported on devices which have EmssVersionInfo::has_video_texture set to true.

Definition at line 62 of file elementary_media_stream_source.h.

◆ ReadyState

Enumerates all possible states of ElementaryMediaStreamSource. Current ready state of EMSS can be retrieved with GetReadyState() method, and its change is signalled by ElementaryMediaStreamSourceListener.

Attention
ElementaryMediaStreamSource and html::HTMLMediaElement states should not be confused. ElementaryMediaStreamSource represents state of a source of data, while html::HTMLMediaElement represents state of a multimedia player. As such, ElementaryMediaStreamSource will signal App whether or not multimedia pipeline needs data and can accept Elementary Media Packets. This is not in sync with multimedia player state.
For example, a ReadyState::kEnded source can be associated with a still-playing Media Element. This will occur in Normal Latency mode when App signals end of all tracks but multimedia pipeline has buffered Elementary Media Packets remaining to play.
Enumerator
kDetached 

Not attached to html::HTMLMediaElement. This is the initial state of ElementaryMediaStreamSource object. It is also entered after disconnecting from html::HTMLMediaElement.

kClosed 

Tracks are not configured and player is not initialized. Can't play in this state. ElementaryMediaTrack objects can be added to and removed from ElementaryMediaStreamSource. Track layout can be changed only in this state.
This state will be entered after ElementaryMediaStreamSource is attached to html::HTMLMediaElement, when unrecoverable playback error occurs or on App request.

kOpenPending 

kOpen state was requested, but pipeline state prevents entering it. State will change to ReadyState::kOpen when possible.
This state can be entered both from ReadyState::kClosed state (when opening of Source is requested) and from ReadyState::kOpen state (when pipeline can't accept ES data temporarily).

kOpen 

Player is fully initialized and Elementary Media Stream Source is ready to accept Elementary Packet Data from App via ElementaryMediaTrack objects.
When App finishes configuring tracks, it can request entering this state. Open state will be entered when possible. Some operations (like seek) will trigger a temporary transition to ReadyState::kOpenPending state.

kEnded 

Stream has ended but multimedia pipeline remains initialized. Playback can still be restarted, for example by seek.
This state is entered when App marks active ElementaryMediaTrack objects as ended. ReadyState::kEnded state will revert to ReadyState::kOpen when multimedia pipeline resumes playback (e.g. due to Seek).

Definition at line 122 of file elementary_media_stream_source.h.

Constructor & Destructor Documentation

◆ ElementaryMediaStreamSource() [1/3]

samsung::wasm::ElementaryMediaStreamSource::ElementaryMediaStreamSource ( Mode  latency_mode = Mode::kNormal)
explicit

Creates a source with the given mode. Mode cannot be changed during lifetime of the object.

Parameters
[in]latency_modeCreate a source that uses specified playback mode.

◆ ElementaryMediaStreamSource() [2/3]

samsung::wasm::ElementaryMediaStreamSource::ElementaryMediaStreamSource ( const ElementaryMediaStreamSource )
delete

◆ ElementaryMediaStreamSource() [3/3]

samsung::wasm::ElementaryMediaStreamSource::ElementaryMediaStreamSource ( ElementaryMediaStreamSource &&  )

◆ ~ElementaryMediaStreamSource()

samsung::wasm::ElementaryMediaStreamSource::~ElementaryMediaStreamSource ( )

Member Function Documentation

◆ AddTrack() [1/2]

Result<ElementaryMediaTrack> samsung::wasm::ElementaryMediaStreamSource::AddTrack ( const ElementaryAudioTrackConfig )

Adds an audio track to the source.

Parameters
[in]configA config describing track.
Returns
Result<ElementaryMediaTrack> with operation_result field set to OperationResult::kSuccess and a valid ElementaryMediaTrack object on success, otherwise a code describing the error.
Remarks
  • Tracks can only be added in kClosed state.
  • Only one track of each type can be held by the source at any given time.
  • Audio parameters cannot be changed during the lifetime of the track.

◆ AddTrack() [2/2]

Result<ElementaryMediaTrack> samsung::wasm::ElementaryMediaStreamSource::AddTrack ( const ElementaryVideoTrackConfig )

Adds a video track to the source.

Parameters
[in]configA config describing track.
Returns
Result<ElementaryMediaTrack> with operation_result field set to OperationResult::kSuccess and a valid ElementaryMediaTrack object on success, otherwise a code describing the error.
Remarks
  • Tracks can only be added in kClosed state.
  • Only one track of each type can be held by the source at any given time.
  • As opposed to audio track, some video parameters can change during playback, notably resolution or framerate, by passing packets with new resolution/fps values.

◆ Close()

Result<void> samsung::wasm::ElementaryMediaStreamSource::Close ( std::function< void(AsyncResult)>  on_finished_callback)

Closes the source asynchronously. When the operation is done, the source will be in ReadyState::kClosed state and a callback passed as the argument will be called. During that time it's impossble to request another ready state change.

Parameters
[in]on_finished_callbackA callback notifying end of close. The callback receives AsyncResult informing of the result of the operation.
Returns
Result<void> with operation_result field set to OperationResult::kSuccess on success, otherwise a code describing the error.
See also
AsyncResult

◆ Flush()

Result<void> samsung::wasm::ElementaryMediaStreamSource::Flush ( )

Flushes internal packets' buffers, causing them to drop appended packets.

Returns
Result<void> with operation_result field set to OperationResult::kSuccess on success, otherwise a code describing the error.

◆ GetDuration()

Result<Seconds> samsung::wasm::ElementaryMediaStreamSource::GetDuration ( ) const

Returns the duration of the source.

Returns
Result<Seconds> with operation_result field set to OperationResult::kSuccess and a valid Seconds object representing duration of the source on success, otherwise a code describing the error.

◆ GetMode()

Result<Mode> samsung::wasm::ElementaryMediaStreamSource::GetMode ( ) const

Returns the mode of the source, as set in constructor.

Returns
Result<Mode> with operation_result field set to OperationResult::kSuccess and a valid Mode representing mode of the source on success, otherwise a code describing the error.

◆ GetReadyState()

Result<ReadyState> samsung::wasm::ElementaryMediaStreamSource::GetReadyState ( ) const

Returns current ready state of the source.

Returns
Result<ReadyState> with operation_result field set to OperationResult::kSuccess and a valid ReadyState representing current ready state of the source on success, otherwise a code describing the error.

◆ GetURL()

const char* samsung::wasm::ElementaryMediaStreamSource::GetURL ( ) const

Returns the source's URL received from URL.createObjectURL WebAPI. The URL is bound to the source's lifetime and will be revoked automatically.

Returns
c-style string containing the URL.

◆ IsValid()

bool samsung::wasm::ElementaryMediaStreamSource::IsValid ( ) const

Returns true if source instance is valid. This method should be called after constructor to ensure backend initialized the object properly. If source is invalid all method calls will fail.

Returns
true if source instance is valid, otherwise false.

◆ Open()

Result<void> samsung::wasm::ElementaryMediaStreamSource::Open ( std::function< void(AsyncResult)>  on_finished_callback)

Starts an asynchronous opening operation. When the operation is done, the source will be in ReadyState::kOpen state and a callback passed as the argument will be called. During that time it's impossble to request another ready state change.

Parameters
[in]on_finished_callbackA callback notifying end of open. The callback receives AsyncResult informing of the result of the operation.
Returns
Result<void> with operation_result field set to OperationResult::kSuccess on success, otherwise a code describing the error.
Remarks
This should be called when all tracks are added and configured, and the application is ready to provide data for the source.
See also
AsyncResult

◆ operator=() [1/2]

ElementaryMediaStreamSource& samsung::wasm::ElementaryMediaStreamSource::operator= ( const ElementaryMediaStreamSource )
delete

◆ operator=() [2/2]

ElementaryMediaStreamSource& samsung::wasm::ElementaryMediaStreamSource::operator= ( ElementaryMediaStreamSource &&  )

◆ RemoveTrack()

Result<void> samsung::wasm::ElementaryMediaStreamSource::RemoveTrack ( const ElementaryMediaTrack )

Removes a track from the source. After the operation removed track is still valid and can be re-added to the source again.

Parameters
[in]trackTrack to remove.
Returns
Result<void> with operation_result field set to OperationResult::kSuccess on success, otherwise a code describing the error.
Remarks
  • Tracks can only be removed in kClosed state.

◆ SetDuration()

Result<void> samsung::wasm::ElementaryMediaStreamSource::SetDuration ( Seconds  new_duration)

Sets the duration of the source. Note that this operation is unavailable in Mode::kLowLatency mode.

Parameters
[in]new_durationDuration to be set.
Returns
Result<void> with operation_result field set to OperationResult::kSuccess on success, otherwise a code describing the error.

◆ SetListener()

Result<void> samsung::wasm::ElementaryMediaStreamSource::SetListener ( ElementaryMediaStreamSourceListener listener)

Sets a listener to receive updates about EMSS's state changes. Only one listener can be set: setting another clears the previous one. Pass nullptr to reset the listener

Parameters
[in]listenerListener to be set or nullptr to unset the listener.
Warning
The ownership isn't transferred, and, as such, the listener must outlive the source.
Returns
Result<void> with operation_result field set to OperationResult::kSuccess on success, otherwise a code describing the error.
See also
ElementaryMediaStreamSourceListener

Friends And Related Function Documentation

◆ html::HTMLMediaElement

friend class html::HTMLMediaElement
friend

Definition at line 393 of file elementary_media_stream_source.h.


The documentation for this class was generated from the following file: