Tracks are used to deliver either audio or video frames to WASM Player. More...

#include <elementary_media_track.h>

Public Types
enum	CloseReason { CloseReason::kSourceClosed, CloseReason::kSourceError, CloseReason::kSourceDetached, CloseReason::kSourceSuspended, CloseReason::kTrackDisabled, CloseReason::kTrackEnded, CloseReason::kTrackSeeking, CloseReason::kUnknown }

enum	ActiveDecodingMode { ActiveDecodingMode::kHardware, ActiveDecodingMode::kSoftware }

enum	TrackType { TrackType::kAudio, TrackType::kVideo, TrackType::kUnknown }
	Enumerates track types. Can be obtained by `GetType()`. More...

Public Member Functions
	ElementaryMediaTrack ()

	~ElementaryMediaTrack ()

	ElementaryMediaTrack (const ElementaryMediaTrack &)=delete

ElementaryMediaTrack &	operator= (const ElementaryMediaTrack &)=delete

	ElementaryMediaTrack (ElementaryMediaTrack &&)

ElementaryMediaTrack &	operator= (ElementaryMediaTrack &&)

bool	IsValid () const

TrackType	GetType () const
	Returns a `TrackType` of this track. More...

Result< void >	AppendPacket (const ElementaryMediaPacket &packet)

Result< void >	AppendPacketAsync (const ElementaryMediaPacket &packet)

Result< void >	AppendEncryptedPacket (const EncryptedElementaryMediaPacket &)

Result< void >	AppendEncryptedPacketAsync (const EncryptedElementaryMediaPacket &)

Result< void >	AppendEndOfTrack (SessionId session_id)

Result< void >	AppendEndOfTrackAsync (SessionId session_id)

Result< void >	FillTextureWithNextFrame (GLuint texture_id, std::function< void(OperationResult)> finished_callback)

Result< void >	FillTextureWithNextFrameSync (GLuint texture_id)

Result< ActiveDecodingMode >	GetActiveDecodingMode () const

Result< SessionId >	GetSessionId () const

Result< bool >	IsOpen () const

Result< void >	RecycleTexture (GLuint texture_id)

Result< void >	RegisterCurrentGraphicsContext ()

Result< void >	SetMediaKey (MediaKey *key)

Result< void >	SetListener (ElementaryMediaTrackListener *listener)

Friends
class	ElementaryMediaStreamSource

Detailed Description

Tracks are used to deliver either audio or video frames to WASM Player.

Each instance of this class represents a single elementary media track (either audio or video). The track object allows sending ElementaryMediaPackets to platform for a playback.

Valid track objects can only be obtained through a call to ElementaryMediaStreamSource::AddTrack().

Definition at line 36 of file elementary_media_track.h.

Member Enumeration Documentation

◆ ActiveDecodingMode

enum samsung::wasm::ElementaryMediaTrack::ActiveDecodingMode

strong

Enumerates possible data decoding modes. Can be obtained by GetActiveDecodingMode() to check what decoding mode is selected for a particular track.

Enumerator
kHardware	Track is using platform hardware decoder.
kSoftware	Track is using platform software decoder.

Definition at line 72 of file elementary_media_track.h.

◆ CloseReason

enum samsung::wasm::ElementaryMediaTrack::CloseReason

strong

Enumerates track close reasons. Values of this enum are passed to ElementaryMediaTrackListener::OnTrackClosed() to inform about the reason of the close.

Enumerator
kSourceClosed	`ElementaryMediaStreamSource` state changed to `ElementaryMediaStreamSource::ReadyState::kClosed`.
kSourceError	Source was closed due to an error.
kSourceDetached	Source was detached from `html::HTMLMediaElement`.
kSourceSuspended	This `ElementaryMediaStreamSource` has been suspended.
kTrackDisabled	This `ElementaryMediaTrack` has been disabled.
kTrackEnded	This `ElementaryMediaTrack` has ended.
kTrackSeeking	This `ElementaryMediaTrack` has started seeking.
kUnknown	Track has closed due to an unspecified error; generally, this shouldn't happen.

Definition at line 41 of file elementary_media_track.h.

◆ TrackType

enum samsung::wasm::ElementaryMediaTrack::TrackType

strong

Enumerates track types. Can be obtained by GetType().

Enumerator
kAudio	This is an audio track.
kVideo	This is a video track.
kUnknown	Unknown track type, usually a result of track being invalid (i.e. `IsValid()` is `false`).

Definition at line 80 of file elementary_media_track.h.

Constructor & Destructor Documentation

◆ ElementaryMediaTrack() [1/3]

samsung::wasm::ElementaryMediaTrack::ElementaryMediaTrack ( )

Default constructor, creates an invalid ElementaryMediaTrack object. It can be further replaced with a proper one, received with a call to ElementaryMediaStreamSource::AddTrack().

◆ ~ElementaryMediaTrack()

samsung::wasm::ElementaryMediaTrack::~ElementaryMediaTrack ( )

◆ ElementaryMediaTrack() [2/3]

samsung::wasm::ElementaryMediaTrack::ElementaryMediaTrack ( const ElementaryMediaTrack & )

delete

◆ ElementaryMediaTrack() [3/3]

samsung::wasm::ElementaryMediaTrack::ElementaryMediaTrack ( ElementaryMediaTrack && )

Member Function Documentation

◆ AppendEncryptedPacket()

Result<void> samsung::wasm::ElementaryMediaTrack::AppendEncryptedPacket ( const EncryptedElementaryMediaPacket & )

Appends a given EncryptedElementaryMediaPacket to the track.

Remarks

It is recommended to use AppendEncryptedPacketAsync() method to append encrypted packets over this method due to performance reasons (decrypting packets takes some time, doing it synchronously may decrease performance).
AppendEncryptedPacket() cannot be called on the main thread.
AppendEncryptedPacket() and AppendEncryptedPacketAsync() calls for the same track can be mixed.

Parameters

[in] packet A packet to append.

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

◆ AppendEncryptedPacketAsync()

Result<void> samsung::wasm::ElementaryMediaTrack::AppendEncryptedPacketAsync ( const EncryptedElementaryMediaPacket & )

Appends a given EncryptedElementaryMediaPacket to the track, but decrypts it asynchronously.

AppendEncryptedPacketAsync() will validate the packet and return result synchronously. However, packet decryption will be executed asynchronously. If decryption error occurs, it will be signaled via ElementaryMediaTrackListener::OnAppendError() event.

Remarks

It is recommended to use this method to append encrypted packets over AppendEncryptedPacket() due to performance reasons (decrypting packets takes some time, doing it asynchronously will improve performance).
AppendEncryptedPacketAsync() can be called both on the main thread and on side threads.
AppendEncryptedPacket() and AppendEncryptedPacketAsync() calls for the same track can be mixed.

Parameters

[in] packet A packet to append.

Returns: Result<void> with operation_result field set to OperationResult::kSuccess if packet validation and append to track was successful, otherwise a code describing the error.

◆ AppendEndOfTrack()

Result<void> samsung::wasm::ElementaryMediaTrack::AppendEndOfTrack ( SessionId session_id )

Appends a special end-of-track packet to the source.

Upon processing this packet, the track will end. It is advised to end all tracks at a similar time. Operation will end once end of track is queued in Media Player's packet buffer.

A track that has ended will close and therefore emit the ElementaryMediaTrackListener::OnTrackClosed() event. When tracks associated with ElementaryMediaStreamSource end, the source changes it's state to ElementaryMediaStreamSource::ReadyState::kEnded.

Remarks: AppendEndOfTrack() cannot be called on the main thread.

Parameters

[in] session_id Id of the session the end of track packet should belong to.

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

◆ AppendEndOfTrackAsync()

Result<void> samsung::wasm::ElementaryMediaTrack::AppendEndOfTrackAsync ( SessionId session_id )

Appends a special end-of-track packet to the source asynchronously.

Upon processing this packet, the track will end. It is advised to end all tracks at a similar time.

AppendEndOfTrackAsync() returns result synchronously when track starts closing or an error occurs.

If AppendEndOfTrackAsync() returns success synchronously but if in the meantime SessionId changes or seek operation starts, track will not be closed and an error informing that end of track append is aborted will be signaled via ElementaryMediaTrackListener::OnAppendError() event.

A track that has ended will close and therefore emit the ElementaryMediaTrackListener::OnTrackClosed() event. When tracks associated with ElementaryMediaStreamSource end, the source changes it's state to ElementaryMediaStreamSource::ReadyState::kEnded.

Remarks: AppendEndOfTrackAsync() can be called both on the main thread and on side threads.

Parameters

[in] session_id Id of the session the end of track packet should belong to.

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

◆ AppendPacket()

Result<void> samsung::wasm::ElementaryMediaTrack::AppendPacket ( const ElementaryMediaPacket & packet )

Appends a given ElementaryMediaPacket to the track.

Remarks

AppendPacket() cannot be called on the main thread.
AppendPacket() and AppendPacketAsync() calls for the same track can be mixed.

Parameters

[in] packet A packet to append.

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

◆ AppendPacketAsync()

Result<void> samsung::wasm::ElementaryMediaTrack::AppendPacketAsync ( const ElementaryMediaPacket & packet )

Appends a given ElementaryMediaPacket to the track asynchronously.

For clear packets, AppendPacketAsync() is functionally equivalent to AppendPacket() (i.e. it will validate the packet and return result synchronously).

Remarks

AppendPacketAsync() can be called both on the main thread and on side threads.
AppendPacket() and AppendPacketAsync() calls for the same track can be mixed.

Parameters

[in] packet A packet to append.

Returns: Result<void> with operation_result field set to OperationResult::kSuccess if packet validation and append to track was successful, otherwise a code describing the error.

◆ FillTextureWithNextFrame()

Result<void> samsung::wasm::ElementaryMediaTrack::FillTextureWithNextFrame	(	GLuint	texture_id,
		std::function< void(OperationResult)>	finished_callback
	)

Fills a provided texture with a decoded video frame.

The texture should be rendered as soon as possible after it's received. Player will resolve finished_callback when playback time reaches the point when a frame associated with the texture should be displayed.

Player will decode frames sent with ElementaryMediaTrack::AppendPacket() but won't render them on HTMLMediaElement when ElementaryMediaStreamSource is in the ElementaryMediaStreamSource::Mode::kVideoTexture mode. Instead, their contents can be accessed by calling this method repeatedly.

Remarks

When texture_id is processed, it must be freed with ElementaryMediaTrack::RecycleTexture().
Sets the texture to the GL_TEXTURE_EXTERNAL_OES type.
This mode is supported only on devices which have EmssVersionInfo::has_video_texture set to true.

Warning

Can be called only on the main thread.
Can only be called in the ElementaryMediaStreamSource::Mode::kVideoTexture mode of ElementaryMediaStreamSource.
Valid only for video tracks.

Parameters

texture_id	A texture that will be filled with video frame.
finished_callback	A callback which will be called when `texture_id` is ready and should be rendered by App.

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

See also: ElementaryMediaTrack::RegisterCurrentGraphicsContext(); ElementaryMediaTrack::RecycleTexture()

◆ FillTextureWithNextFrameSync()

Result<void> samsung::wasm::ElementaryMediaTrack::FillTextureWithNextFrameSync ( GLuint texture_id )

Fills a provided texture with a decoded video frame synchronously. This method blocks until texture is available and assigned to texture_id.

The texture should be rendered as soon as possible after it's received.

Player will decode frames sent with ElementaryMediaTrack::AppendPacket() but won't render them on HTMLMediaElement when ElementaryMediaStreamSource is in the ElementaryMediaStreamSource::Mode::kVideoTexture mode. Instead, their contents can be accessed by calling this method repeatedly.

Remarks

When texture_id is processed, it must be freed with ElementaryMediaTrack::RecycleTexture().
Sets the texture to the GL_TEXTURE_EXTERNAL_OES type.
This mode is supported only on devices which have EmssVersionInfo::has_video_texture set to true.

Warning

This method may not return instantly if WASM Player's internal decoded frame queue is empty. This method will block until a decoded frame is available and as a blocking method it cannot be called on the main thread.
Can only be called in the ElementaryMediaStreamSource::Mode::kVideoTexture mode of ElementaryMediaStreamSource.
Valid only for video tracks.

Parameters

texture_id A texture that will be filled with video frame.

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

See also: ElementaryMediaTrack::RegisterCurrentGraphicsContext(); ElementaryMediaTrack::RecycleTexture()

◆ GetActiveDecodingMode()

Result<ActiveDecodingMode> samsung::wasm::ElementaryMediaTrack::GetActiveDecodingMode ( ) const

Returns decoder mode used for track.

Returns: Result<::ActiveDecodingMode> with the operation_result field set to OperationResult::kSuccess and a valid ActiveDecodingMode identifying the active decoding mode, otherwise a code describing an error.

See also: ActiveDecodingMode

◆ GetSessionId()

Result<SessionId> samsung::wasm::ElementaryMediaTrack::GetSessionId ( ) const

Returns id of the currently active session.

Remarks: This should be used sparingly, because calling this method can be slow. It's recommended to obtain an initial value of session_id using GetSessionId() and receive further updates with the ElementaryMediaTrackListener::OnSessionIdChanged() event.

Returns: Result<SessionId> with the operation_result field set to OperationResult::kSuccess and a valid SessionId identifying the current session on a success, otherwise a code describing an error.

See also: SessionId; ElementaryMediaPacket::session_id; ElementaryMediaTrackListener::OnSessionIdChanged

◆ GetType()

TrackType samsung::wasm::ElementaryMediaTrack::GetType ( ) const

Returns a TrackType of this track.

◆ IsOpen()

Result<bool> samsung::wasm::ElementaryMediaTrack::IsOpen ( ) const

Returns the current state of this track.

An open track can accept ElementaryMediaPacket objects. Tracks open just before source enters ElementaryMediaStreamSource::ReadyState::kOpen state.

A closed track can't accept ElementaryMediaPacket objects. Tracks close just after source leaves ElementaryMediaStreamSource::ReadyState::kOpen state.

Returns: Result<Seconds> with operation_result field set to OperationResult::kSuccess and true if the track is open, otherwise false on success or a code describing the error.

◆ IsValid()

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

Returns true if the track instance is valid. All methods calls on an invalid track will fail.

Returns: true if track instance is valid, otherwise false.

◆ operator=() [1/2]

ElementaryMediaTrack& samsung::wasm::ElementaryMediaTrack::operator= ( const ElementaryMediaTrack & )

delete

◆ operator=() [2/2]

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

◆ RecycleTexture()

Result<void> samsung::wasm::ElementaryMediaTrack::RecycleTexture ( GLuint texture_id )

Release decoder buffers associated with the texture with texture_id. Should be called after painting the frame has been completed, as number of frames App can request simultaneously is limited by Platform.

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

Warning

Can only be called in the ElementaryMediaStreamSource::Mode::kVideoTexture mode of ElementaryMediaStreamSource.
Valid only for video track.
Regular canvas is not available to worker contexts - when using it, method has to be called on main thread.
Offscreen canvas is available to both: window and worker contexts, in such case method can be called on any thread.

Parameters

texture_id A texture that will be recycled.

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

See also: ElementaryMediaTrack::FillTextureWithNextFrame(); ElementaryMediaTrack::RegisterCurrentGraphicsContext()

◆ RegisterCurrentGraphicsContext()

Result<void> samsung::wasm::ElementaryMediaTrack::RegisterCurrentGraphicsContext ( )

Binds Player with an OpenGL graphics context associated with this WASM module.

Must be called before the ElementaryMediaTrack::FillTextureWithNextFrame() method is called for the first time.

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

Warning

Bind current graphic context with OpenGLES first. Otherwise no action will be performed.
Can only be called in the ElementaryMediaStreamSource::Mode::kVideoTexture mode of ElementaryMediaStreamSource.
Valid only for video track.
Regular canvas is not available to worker contexts - when using it, method has to be called on main thread.
Offscreen canvas is available to both: window and worker contexts, in such case method can be called on any thread.

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

See also: ElementaryMediaTrack::FillTextureWithNextFrame(); ElementaryMediaTrack::RecycleTexture()

◆ SetListener()

Result<void> samsung::wasm::ElementaryMediaTrack::SetListener ( ElementaryMediaTrackListener * listener )

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

Parameters

[in] listener Listener to be set or nullptr to unset the listener.

Warning: The ownership isn't transferred, and, as such, the listener must outlive the track.

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

See also: ElementaryMediaTrackListener

◆ SetMediaKey()

Result<void> samsung::wasm::ElementaryMediaTrack::SetMediaKey ( MediaKey * key )

Sets media keys used for decrypting packets in this track.

Parameters

[in] key A MediaKey to be used by this track.

Warning: The ownership isn't transferred, and, as such, the key must outlive the track.

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

See also: MediaKey

Friends And Related Function Documentation

◆ ElementaryMediaStreamSource

friend class ElementaryMediaStreamSource

friend

Definition at line 463 of file elementary_media_track.h.

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

elementary_media_track.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ ActiveDecodingMode

◆ CloseReason

◆ TrackType

Constructor & Destructor Documentation

◆ ElementaryMediaTrack() [1/3]

◆ ~ElementaryMediaTrack()

◆ ElementaryMediaTrack() [2/3]

◆ ElementaryMediaTrack() [3/3]

Member Function Documentation

◆ AppendEncryptedPacket()

◆ AppendEncryptedPacketAsync()

◆ AppendEndOfTrack()

◆ AppendEndOfTrackAsync()

◆ AppendPacket()

◆ AppendPacketAsync()

◆ FillTextureWithNextFrame()

◆ FillTextureWithNextFrameSync()

◆ GetActiveDecodingMode()

◆ GetSessionId()

◆ GetType()

◆ IsOpen()

◆ IsValid()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ RecycleTexture()

◆ RegisterCurrentGraphicsContext()

◆ SetListener()

◆ SetMediaKey()

Friends And Related Function Documentation

◆ ElementaryMediaStreamSource