Work with MediaPlayer objects

The PTMediaPlayer object represents your media player. A PTMediaPlayerItem represents audio or video on your player.

About the MediaPlayerItem class

After a media resource is successfully loaded, TVSDKcreates an instance of the PTMediaPlayerItem class to provide access to that resource.

The PTMediaPlayer resolves the media resource, loads the associated manifest file, and parses the manifest. This is the asynchronous part of the resource loading process. The PTMediaPlayerItem instance is produced after the resource has been resolved, and this instance is a resolved version of a media resource. TVSDK provides access to the newly created PTMediaPlayerItem instance through PTMediaPlayer.currentItem.


You must wait for the resource to be successfully loaded before accessing the media player item.

MediaPlayer object lifecycle

From the moment that you create the PTMediaPlayer instance to the moment when you terminate (reuse or remove) it, this instance completes a series of transitions from one status to another.

Some operations are permitted only when the player is in a particular state. For example, calling play in PTMediaPlayerStatusCreated is not allowed. You can call this status only after the player reaches the PTMediaPlayerStatusReady status.

To work with statuses:

  • You can retrieve the current status of the MediaPlayer object with PTMediaPlayer.status.
  • The list of statuses is defined in PTMediaPlayerStatus.

State-transition diagram for the lifecycle of a MediaPlayer instance:

The following table provides additional details:

PTMediaPlayerStatus Occurs when


Your application requested a new media player by calling playerWithMediaPlayerItem. The newly created player is waiting for you to specify a media player item. This is the media player's initial status.


Your application calls PTMediaPlayer.replaceCurrentItemWithPlayerItem, and the media player is loading.


TVSDK successfully set the media player item.


The content is prepared and ads have been inserted in the timeline, or the ad procedure failed. Buffering or playback can begin.


Your application has called play, so TVSDK is trying to play the video. Some buffering might occur before the video actually plays.


As your application plays and pauses the media, the media player moves between this state and PTMediaPlayerStatusPlaying.


The player reached the end of the stream, and playback has stopped.


Your application has released the media player, which also releases any associated resources. You can no longer use this instance


An error occurred during the process. An error also might affect what your application can do next.


You can use the status to provide feedback on the process (for example, a spinner while waiting for the next status change) or to take the next step in playing the media, such as waiting for the appropriate status before calling the next method.

On this page