Player

You can play audio, video, and tones in your application.

The main player features are:

• Handling audio

  Enables you to play audio and control the playback.

• Handling video

  Enables you to play video.

• Using player features

  Enables you control the player volume, sound mode, display, stream info, and audio effects.

• Streaming playback

  Enables you to set specific URLs for streaming media playback.

The Player API (in mobile and wearable applications) enables your application to play video and sound. It supports 3 content formats: file, network stream, and memory. It also provides the following features:

• Operating general controls for the audio or video content, such as play, pause, resume, and stop
• Moving the audio or video content based on time
• Controlling the volume of the audio or video content based on each instance
• Looping the audio or video content
• Getting information of the audio or video content
• Playing multiple audio streams

The maximum count of a player instance is limited by the system and multimedia resources. The maximum count is a system-wide count and it can be applied depending on the CPU model, CPU speed, CPU core number, CPU load from other applications, and the available memory. Thus, the exact count can be smaller than the maximum count, in which case the prepare functions fail. A reasonable working player count is under 10.

The player works based on the audio session manager policy. This means that an application can be interrupted by another application if a resource is in conflict or it has an audio policy rule to follow. You can change the session's property directly by using the Sound Manager API (in mobile and wearable applications).

The callback interface specifies the functions used to notify the player status during playback events. Since the player engine works asynchronously, you must implement this listener to ensure that the player flows correctly. When each player operation is completed, an event is generated, and the player_completed_cb() function is called. If an error occurs in the player engine, you are notified if you have registered the player_error_cb() callback.

If the player state is changed to ready, the multimedia resource is available and you can get content information of the media. You can also get content information in a playing state in some cases of playback streaming.

Handling Audio

Tizen enables your application to play audio and provides controlling functions for using audio resources. The resources can be media files stored on the device or they can be streamed from a streaming server (defined with a URI) through the network.

The audio formats your application can use include MP3, AAC, WMA, M4A, 3GA, WAV, and AMR. The available formats depend on the target device.

The player_interrupted_cb() function is called when an application is interrupted by another application. The player is paused or moved to an idle state according to the audio policy. You must check the state of the current instance and take appropriate action. If the player is changed to a paused state due to an interruption, the PLAYER_INTERRUPTED_COMPLETED can be called at the end of the interruption. For example, if the application is interrupted by a call, alarm, or notification, the completed message is posted. However, no messages are posted if the interruption has other causes. Make sure you handle the application accordingly when audio switching occurs between various applications.

Multiple instances of the player can be used to play several audio data streams concurrently. This means that your application can play multiple uncompressed audio files at the same time.

The following figure illustrates the general player state changes:

Figure: Player state changes

The following figure illustrates what happens when the player gets interrupted by the system:

Figure: Player states when interrupted by system

Handling Video

Tizen enables your application to play video, and it uses its own user surface. The surface requires a drawing area, so you have to get an overlay region and set it to the player instance to display the drawing area:

1. Get the overlay region or Evas from the Graphics module.

   You can display video on a UI layer with the Evas object as well as on an overlay layer.

2. Create the player instance.
3. Set the surface type and display a handle to the player using the player_set_display() function.

The video formats your application can use include:

• WMV, ASF, MP4, 3GP, AVI, MKV, OGG

  The available formats depend on the target device.

In case of a video interruption, the state can be READY due to the resource restriction in the system.

The following figure illustrates what happens when the player gets interrupted by the system.

Figure: Player states when interrupted by system

Features

The main features of the Player API include:

• Player

  Use the Player API to control audio and video stream.

  After changing to the READY state, properties such as volume, sound type, latency mode, mute mode, and looping mode can be adjusted.

  To learn about these features, see the Player Tutorial.

• Display

  Use the Display API to play video stream.

  After changing to the IDLE state, create the display handle and set the display type.

  To learn about these features, see the Setting Display Parameters.

• Stream Info

  Use the Stream Info API to play video stream.

  After changing to the READY state, you can retrieve stream information.

  To learn about these features, see the Getting Stream Information.

• Audio Effect

  Use the Audio Effect API to set and get the audio effect.

  After changing to the IDLE state, you can adjust the audio effect.

• Subtitle

  Use the Subtitle API to read the subtitle track.

  After changing to the READY state, the subtitle can be read.

  To learn about these features, see the Inserting Subtitles.

Streaming Playback

You can set specific URLs for streaming media playback by using the player_set_uri() function.

Both Hypertext Transfer Protocol (HTTP) and Real Time Streaming Protocol (RTSP) protocols support streaming media playback. The HTTP request header supports the playback of both complete and download-in-progress media files. The index table (atoms) must be moved in front of the file for progressive download.

In case of HTTP streaming, buffering can happen when the player is prepared. You can get the status using the player_set_buffering_cb() function.

Streaming Protocol Features

The following table lists the streaming protocol features supported by the player.

Table: Supported streaming protocol features

Streaming protocol	Supported feature
Hypertext Transfer Protocol (HTTP)	HTTP Streaming
	HTTP Live Streaming
	HTTP Progressive Download Play
Real Time Streaming Protocol (RTSP)	RTSP Streaming