Main Use Cases

This topic describes the main media playback use cases for the NaCl Player API.

---

Related Info

• NaCl Player API

---

The NaCl (Native Client) Player API allows you to play content from URL or elementary stream sources, with or without DRM protection and subtitles.

For more information on code implementation, see API Usage and Developing Playback Applications.

Playing Media from URL Data Sources

You can use the URLDataSource class to play content from a specified URL, with or without platform-supported DRM protection. You can also implement subtitles.

To implement playback from a URL data source:

1. Create a MediaPlayer object.
2. Create objects derived from the MediaEventsListener and BufferingListener classes, and register them in the MediaPlayer object.
3. To implement subtitles, create an object derived from the SubtitleListener class and register it in the MediaPlayer object.
   
   To implement external subtitles, you must also call the MediaPlayer::AddExternalSubtitles() function to specify the external subtitle URL.
4. Create a URLDataSource object, using the media content URL as a construction parameter.
5. Attach the URLDataSource object to the media player by calling the MediaPlayer::AttachDataSource() function.
6. When the BufferingListener::OnBufferingComplete() event notifies that enough data has been buffered and playback can be started, call the MediaPlayer::Play() function to start playback.
7. To implement subtitles, handle the SubtitleListener::OnShowSubtitle() event to display the received subtitle for a specified duration.
8. To switch the representation or the subtitle track, call the MediaPlayer::SelectTrack() function.
9. When the playback position reaches the end of the stream, the application is notified with the MediaEventsListener::OnEnded() event.

Playing Media from Elementary Streams

You can use the ESDataSource class to play content containing elementary streams demuxed by the application, with or without platform-supported or custom DRM protection. You can also implement external subtitles.

Application logic may be using player in push or pull mode. In push mode the application controls when data should be sent. In pull mode player sends events to application indicating when data should be sent.

To implement playback from elementary stream sources:

1. Create a MediaPlayer object.

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

3. Register optional listeners:

   1. To implement subtitles, create an object derived from the SubtitleListener class and register it in the MediaPlayer object, and call the MediaPlayer::AddExternalSubtitles() function to specify the external subtitle URL.

      NoteElementary stream playback does not support internal subtitles.

   2. To implement platform-supported DRM decryption, create an object derived from the DRMListener class and register it in the MediaPlayer object.

4. Create an ESDataSource object.

5. If in pull mode, implement class derived from the ElementaryStreamListener, and create one instance of it for each elementary stream (of course you can implement more than one class, e.g. one for audio stream and other for video stream).

6. Add video and audio streams to the ESDataSource object:

   1. Call the ESDataSource::AddStream() function to obtain a VideoElementaryStream or an AudioElementaryStream object and register respective listeners.
   2. Configure the VideoElementaryStream or AudioElementaryStream object parameters, such as resolution and frame rate for video, sample rate and number of channels for audio, and codec-specific data.
   3. To implement platform-supported DRM decryption, set the DRM initialization data using the ElementaryStream::SetDRMInitData() function.
   4. Confirm the stream configuration by calling the ElementaryStream::InitializeDone() function.

7. Attach the ESDataSource object to the media player by calling the MediaPlayer::AttachDataSource() function.

8. To implement platform-supported DRM, handle the DRMListener::OnLicenseRequest() event:

   1. Download the required license.
   2. Install the license using the MediaPlayer::SetDRMSpecificData(DRMOperation_InstallLicense) function.

9. To buffer packets from the VideoElementaryStream and AudioElementaryStream objects:

   1. Download a chunk of the stream.
   2. Demux the downloaded chunk and extract the packet data.
   3. If you use a custom DRM system, decrypt the packet data.
      NoteWhen using elementary stream data sources, downloading, demuxing, and custom DRM decrypting must be handled by the application.
   4. For each packet, call the ElementaryStream::AppendPacket() function. If you implement pull mode, this call should be a result of handling the ElementaryStreamListener::OnNeedData() event.
      NoteTo implement platform-supported DRM decryption, call the ElementaryStream::AppendEncryptedPacket() function instead of the ElementaryStream::AppendPacket() function.

   The packets are decoded and the resulting video and audio are presented.

10. When the BufferingListener::OnBufferingComplete() event notifies that enough data has been buffered and playback can be started, call the MediaPlayer::Play() function to start playback.

11. To implement subtitles, handle the SubtitleListener::OnShowSubtitle() event to display the received subtitle for a specified duration.

12. To continue playback, continue buffering video and audio packets if in push mode, or handle ElementaryStreamListener events appropriately if in pull mode.

13. To change the stream representation during playback:

    1. Configure the VideoElementaryStream or AudioElementaryStream object parameters.
    2. Confirm the new configuration by calling the ElementaryStream::InitializeDone() function.
    NoteThe new configuration takes effect only after calling the ElementaryStream::InitializeDone() function.

14. When the streams end, call the ESDataSource::SetEndOfStream() function.