Initializing WASM Player

This topic covers how to initialize the Tizen WASM Player.

To make Media Player work with the WASM player, the following prerequisites and setup operations need to be met:

Setting Up ElementaryMediaStreamSource as a Source Object

In the WASM Player, the ElementaryMediaStreamSource class acts as a source object for HTMLMediaElement. To set up ElementaryMediaStreamSource and HTMLMediaElement to work together:

  1. Create the HTMLMediaElement object:

    auto html_media_element = std::make_unique<samsung::html::HTMLMediaElement>(element_id);
    
    Note

    The HTMLMediaElement class connects to either a <video> or an <audio> element in a HTML document hosting the WebAssembly module. The HTML element is chosen by the element_id specified during construction.

  2. Create an object implementing the HTMLMediaElementListener interface and associate it with the media element. This step is optional, but the events generated by the media element are essential for creating a functional media player.

    1. Define a custom implementation of HTMLMediaElementListener:

      class MyMediaElementListener : public samsung::html::HTMLMediaElementListener {
        // Override virtual methods that the application uses
      };
      
    2. Instantiate the custom listener and associate it with the HTMLMediaElement object:

      auto my_media_element_listener = std::make_unique<MyMediaElementListener>();
      html_media_element->SetListener(my_media_element_listener.get());
      
      Note

      The HTMLMediaElement::SetListener() method does not take ownership of the listener. Make sure that the listener outlives the media element object.

  3. Create the ElementaryMediaStreamSource object:

    using LatencyMode = samsung::wasm::ElementaryMediaStreamSource::LatencyMode;
    using RenderingMode = samsung::wasm::ElementaryMediaStreamSource::RenderingMode;
    
    auto elementary_media_stream_source = std::make_unique<samsung::wasm::ElementaryMediaStreamSource>(LatencyMode::kNormal, RenderingMode::kMediaElement);
    
    Note

    Choose LatencyMode::kNormal to set up the WASM Player to work in normal latency mode, LatencyMode::kLow for low latency mode and LatencyMode::kUltraLow for ultra low latency mode.
    Choose RenderingMode::kMediaElement to set up the WASM Player to work in Media Element rendering mode or RenderingMode::kVideoTexture for Video Texture rendering mode.

  4. Create an object implementing the ElementaryMediaStreamSourceListener interface and associate it with the source. This step is optional, but the events generated by the source are essential for creating a functional media player.

    1. Define a custom implementation of ElementaryMediaStreamSourceListener:

      class MySourceListener : public samsung::wasm::ElementaryMediaStreamSourceListener {
        // Override virtual methods that the application uses
      };
      
    2. Instantiate the custom listener and associate it with the ElementaryMediaStreamSource object:

      auto my_source_listener = std::make_unique<MySourceListener>();
      elementary_media_stream_source->SetListener(my_source_listener.get());
      
      Note

      The ElementaryMediaStreamSource::SetListener() method does not take ownership of the listener. Make sure it outlives the source object.

  5. Attach ElementaryMediaStreamSource to HTMLMediaElement:

    html_media_element->SetSrc(elementary_media_stream_source.get());
    
    Note

    When created, ElementaryMediaStreamSource is set to the ReadyState::kDetached state, preventing any operations on the source. Attaching it to HTMLMediaElement changes the source's state to ReadyState::kClosed, allowing configuration of media tracks.

Adding ElementaryMediaTracks to ElementaryMediaStreamSource

Once ElementaryMediaStreamSource is created and attached to HTMLMediaElement, the application must configure the tracks that take part in the media playback. Depending on its needs, the application can add up to one video track and up to one audio track to the source, as described below.

Preparing Video Track Configuration

To prepare an ElementaryVideoStreamTrackConfig structure, fill it with an initial configuration of a video track:

samsung::wasm::ElementaryVideoStreamTrackConfig conf;
conf.mimeType = "video/mp4; codecs=\"hev1.1.6.L93.B0\""; // h265
conf.extradata = { /* codec extradata */ };
conf.width = 1920;
conf.height = 1080;
conf.framerateNum = 60;
conf.framerateDen = 1;
conf.decodingMode = samsung::wasm::DecodingMode::kHardware;
Note

The configuration provided when a video track is added is an initial configuration of the track. If the configuration changes during the stream playback (for example, due to an adaptive streaming), the existing track can be reconfigured.

Note

For information on supported codecs and configurations, see Samsung Smart TV Media Specifications.

Preparing Audio Track Configuration

To prepare an ElementaryAudioStreamTrackConfig structure, fill it with a configuration of an audio track:

samsung::wasm::ElementaryAudioStreamTrackConfig conf;
conf.mimeType = "audio/mp4; codecs=\"mp4a.40.2\""; // AAC
conf.extradata = { /* codec extradata */ };
conf.sampleFormat = samsung::wasm::SampleFormat::kPlanarF32;
conf.channelLayout = samsung::wasm::ChannelLayout::kStereo;
conf.samplesPerSecond = 48000;
conf.decodingMode = samsung::wasm::DecodingMode::kHardware;
Note

The configuration provided when an audio track is added is the final configuration of the track. Changing configuration during the stream runtime is not possible.

Adding a Track to the Source

As soon as a track's configuration is ready, the track can be added to the source. This procedure is the same for both audio and video tracks.

  1. Add a track to the source:

    auto track = elementary_media_stream_source->AddTrack(conf);
    
  2. Create an object implementing the ElementaryMediaTrackListener interface and associate it with the track. This step is optional, but the events generated by the track are essential for implementing certain media player functionalities.

    1. Define a custom implementation of ElementaryMediaTrackListener:
      class MyTrackListener : public samsung::wasm::ElementaryMediaTrackListener {
        // Override virtual methods that the application uses
      };
      
    1. Instantiate the custom listener and associate it with the ElementaryMediaTrack object:
      auto my_track_listener = std::make_unique<MyTrackListener>();
      track->SetListener(my_track_listener.get());
      
      Note

      The ElementaryMediaTrack::SetListener() method does not take ownership of the listener. Make sure that the listener outlives the track object.

Setting Media Duration

Duration of media should be set on the ElementaryMediaStreamSource instance during initialization:

auto content_duration = samsung::wasm::Seconds{42};
elementary_media_stream_source->SetDuration(content_duration);

Once set, the duration is not fixed. It can be changed during runtime if the playback scenario requires it.

Note

Media duration cannot be set in the low latency modes, where duration is automatically set to infinite.

Completing Media Player Initialization

When the app has configured the track layout, ElementaryMediaStreamSource can be initialized by putting it in ReadyState::kOpen and thus enabling playback.

Request ElementaryMediaStreamSource to open:

using OperationResult = samsung::wasm::OperationResult;

elementary_media_stream_source->Open([](OperationResult result) {
  if (result != OperationResult::kSuccess) {
    // handle errors
  }
});

Running the Open() operation on the source immediately puts it in the ReadyState::kOpenPending state. That means the source will enter the ReadyState::kOpen state as soon as possible, however this is not necessarily immediately after the Open() operation finishes.