top

NaCl Player Use Cases

This article presents main NaCl Player use cases. The NaCl Player API call sequence is included for each presented scenario.

This article presents detailed use cases of NaCl Player, grouped basing on the used data source. Please refer to the NaCl Player Introduction article for the simplified use cases and the data sources introduction.

ESDataSource scenarios

ESDataSource allows a playback of content demuxed by the application.

ESDataSource basic scenario for clear content

The flow below describes a basic playback of clear content containing audio and video data Elementary Streams.

  1. Create a MediaPlayer object.

  2. Create objects derived from MediaEventsListener and BufferingListener classes and register them in the MediaPlayer object.

  3. Create an ESDataSource object.

  4. Add a video stream to ESDataSource:

  5. Repeat the step 4. for an audio stream.

  6. Attach the ESDataSource object to the media player by calling the MediaPlayer::AttachDataSource() method.

  7. Buffer video Elementary Stream packets in the ElementaryStream object associated with the ESDataSource object:
    a. download a chunk of the video stream,
    b. demux the downloaded chunk and extract packet data,
    c. call the ElementaryStream::AppendPacket() method for each of the extracted Elementary Stream packets,
    d. NaCl Player decodes the Elementary Stream packets and renders the resulting video frame on the screen.

Note

In the ESDataSource scenario steps a. and b. are implemented entirely by the application.

  1. Repeat the step 7. for the audio Elementary Stream.
  2. Handle a BufferingListener::OnBufferingComplete() event, indicating that enough packet data has been buffered and a playback may be started:
    • call the MediaPlayer::Play() method to start the playback,
    • repeat the step 7. to keep the playback going.
  3. [optional] Change the representation (an example for the video stream):
Note

All packets sent before calling to the ElementaryStream::InitializeDone() method are assumed to be assigned to the last valid (i.e. successfully confirmed by InitializeDone()) configuration.

  1. When streams end, call the ESDataSource::SetEndOfStream() method.

ESDataSource extended scenario for DRM-protected content

The flow below describes a basic playback of DRM-protected content consisting of audio and video data (Elementary Streams). Steps that differ from the basic scenario are listed in bold.

  1. Create a MediaPlayer object.
  2. Create objects derived from MediaEventsListener and BufferingListener classes and register them in the MediaPlayer object.
  3. Create an object derived from the DRMListener class and register it in the MediaPlayer object.
  4. Create an ESDataSource object.
  5. Add a video stream to ESDataSource:
  6. Repeat the step 5. for an audio stream.
  7. Attach the ESDataSource object to the media player by calling the MediaPlayer::AttachDataSource() method.
  8. Handle a DRMListener::OnLicenseRequest() event:
  9. Buffer video Elementary Stream packets in the player:
Note

In the ESDataSource scenario steps a. and b. are implemented entirely by the application.

  1. Repeat the step 9. for the audio Elementary Stream.
  2. Execute steps 9.-11. from the basic scenario.

ESDataSource extended scenario for a custom DRM system

The flow below describes a basic playback of content protected by a custom DRM system and containing both audio and video data Elementary Streams. Steps that differ from the basic scenario are listed in bold.

  1. Execute steps 1.-6. from the basic scenario.
  2. Buffer video Elementary Stream packets in the player:
    • download a chunk of the video stream,
    • demux the downloaded chunk and extract packet data,
    • decrypt packet data using a protection scheme used by the custom DRM system,
    • call the ElementaryStream::AppendPacket() method for each of the extracted Elementary Stream packets,
    • NaCl Player decodes the Elementary Stream packets and renders resulting video frame on the screen.
Note

In the ESDataSource with custom DRM protection scenario steps a., b. and c. are implemented entirely by the application.

  1. Repeat the step 2. for the audio Elementary Stream.
  2. Execute steps 9.-11. from the basic scenario.

URLDataSource scenarios

URLDataSource allows a playback of content from a URL address.

URLDataSource basic scenario for all content types

The flow below describes a basic playback of content using URLDataSource. The scenario is the same for both DRM-protected and clear content.

Note

Please note that a custom DRM system scenario is not supported by the URLDataSource.

  1. Create a MediaPlayer object.
  2. Create objects derived from MediaEventsListener and BufferingListener classes and register them in the MediaPlayer object.
  3. Create a URLDataSource object, with a URL address to media as an construction argument.
  4. Attach the URLDataSource object to the media player by calling the MediaPlayer::AttachDataSource() method.
  5. Handle the BufferingListener::OnBufferingComplete() event, indicating that enough data has been buffered and a playback may be started:
  6. [optional] Change the representation by calling the MediaPlayer::SelectTrack() method.
  7. When the multimedia content playback position reaches the end of the played streams, the application is notified with the MediaEventsListener::OnEnded() event.

URLDataSource extended scenario for internal subtitles

The flow below describes how to handle internal subtitles in the URLDataSource scenario. Points that differ from the basic scenario are listed in bold.

Important

Please note that internal subtitles are only available in URLDataSource.

  1. Execute steps 1.-2. from the basic scenario.
  2. Create an object derived from the SubtitleListener class and register it in the MediaPlayer object.
  3. Execute steps 3.-5. from the basic scenario (a playback starts in this step).
  4. Handle a SubtitleListener::OnShowSubtitle() event:
    • display a subtitle received in the event for a given duration.
  5. [optional] Change a subtitle track by calling the MediaPlayer::SelectTrack() method.
  6. Execute steps 6.-7. from the basic scenario.

Any data source scenario for external subtitles

The flow below describes how to add external subtitles to NaCl Player. This scenario applies to any data source, so it can be combined with both ESDataSource and URLDataSource scenarios. Points that differ from other scenarios are listed in bold.

  1. Create a MediaPlayer object and prepare used listeners.
  2. Create an object derived from the SubtitleListener class and register it in the MediaPlayer object.
  3. Call MediaPlayer::AddExternalSubtitles() to add subtitles from a URL address.
  4. Create, configure and attach any type of MediaDataSource.
  5. Start the playback.
  6. Handle a SubtitleListener::OnShowSubtitle() event:
    • display a subtitle received in the event for a given duration