Main Use Cases
This topic describes the main media playback use cases for the NaCl Player API.
Related Info
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:
- Create a MediaPlayer object.
- Create objects derived from the MediaEventsListener and BufferingListener classes, and register them in the
MediaPlayer
object. - 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 theMediaPlayer::AddExternalSubtitles()
function to specify the external subtitle URL. - Create a
URLDataSource
object, using the media content URL as a construction parameter. - Attach the
URLDataSource
object to the media player by calling theMediaPlayer::AttachDataSource()
function. - When the
BufferingListener::OnBufferingComplete()
event notifies that enough data has been buffered and playback can be started, call theMediaPlayer::Play()
function to start playback. - To implement subtitles, handle the
SubtitleListener::OnShowSubtitle()
event to display the received subtitle for a specified duration. - To switch the representation or the subtitle track, call the
MediaPlayer::SelectTrack()
function. - 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:
-
Create a MediaPlayer object.
-
Create objects derived from the MediaEventsListener and BufferingListener classes, and register them in the
MediaPlayer
object. -
Register optional listeners:
-
To implement subtitles, create an object derived from the SubtitleListener class and register it in the
MediaPlayer
object, and call theMediaPlayer::AddExternalSubtitles()
function to specify the external subtitle URL.NoteElementary stream playback does not support internal subtitles. -
To implement platform-supported DRM decryption, create an object derived from the DRMListener class and register it in the
MediaPlayer
object.
-
-
Create an
ESDataSource
object. -
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).
-
Add video and audio streams to the
ESDataSource
object:- Call the
ESDataSource::AddStream()
function to obtain a VideoElementaryStream or an AudioElementaryStream object and register respective listeners. - Configure the
VideoElementaryStream
orAudioElementaryStream
object parameters, such as resolution and frame rate for video, sample rate and number of channels for audio, and codec-specific data. - To implement platform-supported DRM decryption, set the DRM initialization data using the
ElementaryStream::SetDRMInitData()
function. - Confirm the stream configuration by calling the
ElementaryStream::InitializeDone()
function.
- Call the
-
Attach the
ESDataSource
object to the media player by calling theMediaPlayer::AttachDataSource()
function. -
To implement platform-supported DRM, handle the
DRMListener::OnLicenseRequest()
event:- Download the required license.
- Install the license using the
MediaPlayer::SetDRMSpecificData(DRMOperation_InstallLicense)
function.
-
To buffer packets from the
VideoElementaryStream
andAudioElementaryStream
objects:- Download a chunk of the stream.
- Demux the downloaded chunk and extract the packet data.
- 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.
- For each packet, call the
ElementaryStream::AppendPacket()
function. If you implement pull mode, this call should be a result of handling theElementaryStreamListener::OnNeedData()
event.NoteTo implement platform-supported DRM decryption, call theElementaryStream::AppendEncryptedPacket()
function instead of theElementaryStream::AppendPacket()
function.
The packets are decoded and the resulting video and audio are presented.
-
When the
BufferingListener::OnBufferingComplete()
event notifies that enough data has been buffered and playback can be started, call theMediaPlayer::Play()
function to start playback. -
To implement subtitles, handle the
SubtitleListener::OnShowSubtitle()
event to display the received subtitle for a specified duration. -
To continue playback, continue buffering video and audio packets if in push mode, or handle
ElementaryStreamListener
events appropriately if in pull mode. -
To change the stream representation during playback:
- Configure the
VideoElementaryStream
orAudioElementaryStream
object parameters. - Confirm the new configuration by calling the
ElementaryStream::InitializeDone()
function.
NoteThe new configuration takes effect only after calling theElementaryStream::InitializeDone()
function. - Configure the
-
When the streams end, call the
ESDataSource::SetEndOfStream()
function.