Media Playback

You can play different audio formats and video in your application.

The main media playback features are described below:

Handling audio

Enables you to play audio and control the playback.
Handling video

Enables you to play video.
Using the player features

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

Enables you to set specific URLs for streaming media playback.
Using the WAV player

Enables you to play audio in the WAVE format.
Using the tone player

Enables you to play tones.

Audio Player

You can play audio and control functions for using audio resources. The resources can be media files stored on the device in a file or memory, or they can be streamed from a streaming server (defined with a URI) through the network.

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

You can use multiple instances of the player 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

Player state changes

The PlaybackInterrupted event of the Tizen.Multimedia.Player class is triggered when the application is interrupted by another application. The player is paused or moved to the Idle state according to the audio session manager (ASM) policy. You must check the state of the current instance and take appropriate action.

Video Player

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. To get an overlay region and set it to the player instance, follow the steps below:

Get the UI component to display from the graphics module.

You can display video on a UI layer of Evas, Xamarin, and NUI.
Create the player instance.
Create the display instance with the UI component you got.
Set the display to the player using the Display property of the Tizen.Multimedia.Player class.

The supported video formats include WMV, ASF, MP4, 3GP, AVI, MKV, and OGG. The available formats depend on the target device.

In the case of a video interruption, the player 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

Player states when interrupted by system

Player Features

The Tizen.Multimedia.Player class provides the following features:

Operating general controls for the audio and video content, such as play, pause, resume, and stop

The player has events you can use to receive notifications of player status changes during playback. Since the player engine works asynchronously, you must implement event handlers to ensure that the player flows correctly. When each player’s operation is completed, the PlaybackCompleted event of the Tizen.Multimedia.Player class is raised. If an error occurs in the player engine, you can be notified through the ErrorOccurred event.
Modifying playback properties

After the player state is changed to Ready, you can modify various playback properties, such as volume, sound type, latency mode, mute mode, and looping mode.
Moving the audio and video content based on time
Controlling the volume of the audio and video content based on each instance

The player works based on the audio session manager policy. This means that an application can be interrupted by another application. You can change the policy directly by using the Tizen.Multimedia.AudioStreamPolicy class.
Getting information about the audio and video content

After the player state is changed to Ready, the multimedia resource is available and you can get content information from the media. You can also get content information in the Playing state, in some cases of playback streaming.
Playing multiple audio streams

The maximum number of player instances is limited by the system and multimedia resources. The maximum number 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 number can be smaller than the maximum number, in which case the prepare methods fail. A reasonable working player number is under 10. To free up system resources, stop unneeded players.
Display

Use the Display property of the Tizen.Multimedia.Player class to play a video stream.

After the player state is changed to Idle, create the display and set the display settings.
Stream information

Use the StreamInfo property of the Tizen.Multimedia.Player class to play a video stream.

After the player state is changed to Ready, you can retrieve stream properties.
Audio effect

Use the AudioEffect property of the Tizen.Multimedia.Player class to set and get audio effects for the playback.

After the player state is changed to Idle, you can adjust the audio effects.
Subtitles

Use the SetSubtitle() method of the Tizen.Multimedia.Player class to set a path for inserting subtitles into a video file.

After the player state is changed to Ready, you can read the subtitle track.
Spherical Video Playback

Use the SphericalVideo property of the Tizen.Multimedia.Player class to set the rendering attributes for spherical video playback.

Playback streams

You can set specific URLs for streaming media playback with the Tizen.Multimedia.MediaUriSource class.

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.

For HTTP streaming, buffering can happen when the player is prepared. You can receive the status using the BufferingProgressChanged event of the Tizen.Multimedia.Player class.

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

Table: Supported streaming protocol features

You can scroll this table.

Streaming protocol	Supported feature
Hypertext Transfer Protocol (HTTP)	HTTP streaming
Hypertext Transfer Protocol (HTTP)	HTTP live streaming
Hypertext Transfer Protocol (HTTP)	HTTP progressive download play
Real Time Streaming Protocol (RTSP)	RTSP streaming

WAV player

The Tizen.Multimedia.WavPlayer class allows you to play audio resources (media files stored on the device). Use it to play audio and control playback. You can use the WAV and OGG audio formats.

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

Tone player

You can play a tone or a list of tones using the Tizen.Multimedia.TonePlayer class.

To play tones, use a DTMF (Dual Tone Multi Frequency) preset frequency. The possible values are defined in the Tizen.Multimedia.ToneType enumeration.

You can start and stop playing a tone, and play a tone for a specified duration.

Prerequisites

To use the methods and properties of the media playback classes, include the Tizen.Multimedia namespace in your application:


                C#
                
                    Copy
                    
                
            
using Tizen.Multimedia;

Prepare the player

To initialize the player for use, proceed as follows:

Create a instance of the Tizen.Multimedia.Player class:


                C#
                
                    Copy
                    
                
            
var player = new Player();

To receive notifications, add event handlers to the appropriate events of the Tizen.Multimedia.Player class:

To receive notifications about playback interruptions, register an event handler for the PlaybackInterrupted event:


                C#
                
                    Copy
                    
                
            
player.PlaybackInterrupted += (object sender, PlaybackInterruptedEventArgs e)
{
    Tizen.Log.Info(LogTag, $"Current player state is {player.State}");
    /// If the state is Paused, update the UI (for example, button)
};

The playback is interrupted and the event is raised when, for example, another multimedia application is run. The player state automatically changes to Paused or Idle according to the session policy.

To receive a notification when the playback ends, register an event handler for the PlaybackCompleted event:


                C#
                
                    Copy
                    
                
            
player.PlaybackCompleted += (object sender, EventArgs e)
{
   Tizen.Log.Info(LogTag, "Playback End");
};

To receive notifications about player errors during playback, register an event handler for the ErrorOccurred event:
```
                C#
                
                    Copy
                    
                
            
player.ErrorOccurred += (object sender, PlayerErrorOccurredEventArgs e)
{
    Tizen.Log.Error(LogTag, $"Playback failed, error = {e.Error}");
};
```
The player error event is raised when the player stops working due to an error. You can use the event to try to recover from the error. For example, try to change the player state to Ready by calling the Stop() method of the Tizen.Multimedia.Player class, and then reset the player by calling the Unprepare() method.

Play an audio file

To play an audio file, proceed as follows:

After creating the player, specify the audio file to play by creating an instance of the Tizen.Multimedia.MediaUriSource class with the path to the audio file, and setting that as the Source property of the Tizen.Multimedia.Player class instance you want to play the file with:
```
                C#
                
                    Copy
                    
                
            
player.SetSource(new MediaUriSource(audioPath));
```

Prepare the player for playback using the PrepareAsync() method of the Tizen.Multimedia.Player class:


                C#
                
                    Copy
                    
                
            
await player.PrepareAsync();

The method changes the player state from Idle to Ready, which is required to start playback.

Start playing the audio file using the Start() method:


                C#
                
                    Copy
                    
                
            
player.Start();

This changes the player state from Ready to Playing. The audio file plays until you call the Stop() or Pause() method.

Play a video file

To play a video file, proceed as follows:

After creating the player, specify the video file to play by creating an instance of the Tizen.Multimedia.MediaUriSource class with the path to the audio file, and setting that as the Source property of the Tizen.Multimedia.Player class instance you want to play the file with:
```
                C#
                
                    Copy
                    
                
            
player.Source = new MediaUriSource(videoPath);
```

To set the display on which the video is played, use the Display property of the Tizen.Multimedia.Player class.

For example, to set the display on a Xamarin-based application, first create an instance of the custom renderer such as VideoView() based on VisualElementRenderer class. Cast it to an instance of the Tizen.Multimedia.MediaView class, and finally set that instance as the Display property:


                C#
                
                    Copy
                    
                
            
var mediaView = new VideoView();

mediaView.NativeViewCreated += (s, e) =>
{
    player.Display = new Display((Tizen.Multimedia.MediaView)(s as VideoView).NativeView);
};

Prepare the player for playback using the PrepareAsync() method of the Tizen.Multimedia.Player class:


                C#
                
                    Copy
                    
                
            
await player.PrepareAsync();

This method changes the player state from Idle to Ready, which is required to start playback.

Play the video file, using the Start() method:


                C#
                
                    Copy
                    
                
            
player.Start();

This changes the player state from Ready to Playing. The video file plays until you call the Stop() or Pause() method.

Stop the player

To stop and reset the player, proceed as follows:

Stop the player using the Stop() method of the Tizen.Multimedia.Player class:


                C#
                
                    Copy
                    
                
            
player.Stop();

Reset the player using the Unprepare() method:


                C#
                
                    Copy
                    
                
            
player.Unprepare();

After the player is reset, it is in the Idle state.

Configure the video playback display

You set the display parameters of a video file with the DisplaySettings property of the Tizen.Multimedia.Player class, which takes an instance of the Tizen.Multimedia.PlayerDisplaySettings class as its value:

Make sure that the display is set, and the player prepared and started.

To make the display visible:

Check whether the display is already visible using the IsVisible property of the Tizen.Multimedia.PlayerDisplaySettings class:


                C#
                
                    Copy
                    
                
            
Tizen.Log.Info(LogTag, $"Display visible = {player.DisplaySettings.IsVisible}");

If the display is not visible, make it visible by setting the IsVisible property to true:


                C#
                
                    Copy
                    
                
            
if (player.DisplaySettings.IsVisible == false)
{
    player.DisplaySettings.IsVisible = true;
}

Set the display mode using the Mode property, which takes the display mode as a value of the Tizen.Multimedia.PlayerDisplayMode enumeration:


                C#
                
                    Copy
                    
                
            
player.DisplaySettings.Mode = PlayerDisplayMode.FullScreen;

Set the display rotation using the Rotation property, which takes the display rotation as a value of the Tizen.Multimedia.Rotation enumeration:


                C#
                
                    Copy
                    
                
            
player.DisplaySettings.Rotation = Rotation.Rotate90;

Retrieve stream information

To retrieve information about the audio and video streams, proceed as follows:

Prepare and start the player, and set the display parameters.

Note
To retrieve the stream information, the player state must be either Playing or Paused.

Retrieve the following stream information:

Duration

Retrieve the total media running time (in milliseconds) using the GetDuration() method of the Tizen.Multimedia.StreamInfo class:


                C#
                
                    Copy
                    
                
            
Tizen.Log.Info(LogTag, $"Duration = {player.StreamInfo.GetDuration()}");

Audio stream details

Retrieve the audio stream details using the GetAudioProperties() method. The method returns an instance of the Tizen.Multimedia.AudioStreamProperties struct containing the audio sample rate (in Hz), number of audio channels (1 for mono or 2 for stereo), and audio bit rate (in Hz):


                C#
                
                    Copy
                    
                
            
var audioProperties = player.StreamInfo.GetAudioProperties();

Tizen.Log.Info(LogTag, $"Sample rate = {audioProperties.SampleRate}, Channels = {audioProperties.Channels}, Bit rate = {audioProperties.BitRate}");

Video stream details

Retrieve the video stream details using the GetVideoProperties() method. The method returns an instance of the Tizen.Multimedia.VideoStreamProperties struct containing the video size, number of frames per second, and video bit rate (in Hz):


                C#
                
                    Copy
                    
                
            
var videoProperties = player.StreamInfo.GetVideoProperties();

Tizen.Log.Info(LogTag, $"Video size = {videoProperties.Size}, Fps = {videoProperties.Fps}, Bit rate = {videoProperties.BitRate}");

Audio and video codec names

Retrieve the audio and video codec names using the GetAudioCodec() and the GetVideoCodec() methods:


                C#
                
                    Copy
                    
                
            
Tizen.Log.Info(LogTag, $"Audio codec = {player.StreamInfo.GetAudioCodec()}");
Tizen.Log.Info(LogTag, $"Video codec = {player.StreamInfo.GetVideoCodec()}");

Content metadata

Retrieve information about the album, artist, author, genre, title, and year using the GetMetadata() method. The available metadata attributes are defined in the Tizen.Multimedia.StreamMetadataKey enumeration:


                C#
                
                    Copy
                    
                
            
Tizen.Log.Info(LogTag, $"Album = {player.StreamInfo.GetMetadata(StreamMetadataKey.Album)}");
Tizen.Log.Info(LogTag, $"Artist = {player.StreamInfo.GetMetadata(StreamMetadataKey.Artist)}");
Tizen.Log.Info(LogTag, $"Author = {player.StreamInfo.GetMetadata(StreamMetadataKey.Author)}");
Tizen.Log.Info(LogTag, $"Genre = {player.StreamInfo.GetMetadata(StreamMetadataKey.Genre)}");
Tizen.Log.Info(LogTag, $"Title = {player.StreamInfo.GetMetadata(StreamMetadataKey.Title)}");
Tizen.Log.Info(LogTag, $"Year = {player.StreamInfo.GetMetadata(StreamMetadataKey.Year)}");

Album artwork

Retrieve the album artwork using the GetAlbumArt() method. The method returns the encoded artwork image:


                C#
                
                    Copy
                    
                
            
byte[] imageData = player.StreamInfo.GetAlbumArt();

Insert subtitles

To insert subtitles to a video file, set the subtitle path using the SetSubtitle() method of the Tizen.Multimedia.Player class:


                C#
                
                    Copy
                    
                
            
player.SetSubtitle(subtitlePath);

Start and stop the WAV player

To start and stop the WAV player, proceed as follows:

To play a WAV file, use the StartAsync() method of the Tizen.Multimedia.WavPlayer class:


                C#
                
                    Copy
                    
                
            
await WavPlayer.StartAsync(wavPath, new AudioStreamPolicy(AudioStreamType.Media));

To set the path of your WAV file, you potentially need to retrieve the default path for audio files.

To stop the WAV player, use the StartAsync() method with the cancellationToken parameter:


                C#
                
                    Copy
                    
                
            
var cancellationTokenSource = new CancellationTokenSource();

WavPlayer.StartAsync(wavPath, new AudioStreamPolicy(AudioStreamType.Media), cancellationTokenSource);

cancellationTokenSource.Cancel();

Playing a tone

To start and stop playing a tone, proceed as follows:

To start playback, use the StartAsync() method of the Tizen.Multimedia.TonePlayer class.

The first parameter defines the tone type as a value of the Tizen.Multimedia.ToneType enumeration:


                C#
                
                    Copy
                    
                
            
await TonePlayer.StartAsync(ToneType.Default, new AudioStreamPolicy(AudioStreamType.Media), -1);

To stop playback, use the StartAsync() method with the cancellationToken parameter:


                C#
                
                    Copy
                    
                
            
var cancellationTokenSource = new CancellationTokenSource();

TonePlayer.StartAsync(ToneType.Default, new AudioStreamPolicy(AudioStreamType.Media), -1, cancellationTokenSource);

cancellationTokenSource.Cancel();

Playing a tone for a specified duration

To play a tone for a specified duration, use the StartAsync() method of the Tizen.Multimedia.TonePlayer class with the duration parameter (the number of milliseconds you want playback to last). When you set the duration to a specified time, playback stops automatically after that time:


                C#
                
                    Copy
                    
                
            
await TonePlayer.StartAsync(ToneType.Default, new AudioStreamPolicy(AudioStreamType.Media), duration);

Dependencies
- Tizen 4.0 and Higher