Media Playback and Recording

You can play and record audio files using various functionalities, such as play, stop, pause, volume change, and seek to position.

The Media API is mandatory for Tizen Mobile, Wearable, and TV profiles, which means that it is supported on all mobile, wearable, and TV devices. All mandatory APIs are supported on the Tizen emulators.

The main features of the Media API include the following:

Playing audio files

You can start audio file playback.
Seeking position

You can change the playing position.
Changing the volume

You can change the volume during playback.
Using playback callbacks

You can use callbacks to handle playback success and errors, and various status events.
Getting the duration and position

You can get the duration of the audio file, and retrieve the current position.
Recording audio

You can start and stop recording.

Prerequisites

To enable your application to use the media functionality, follow these steps:

To perform any Cordova-related operations, you must wait until Cordova is fully set up (the deviceready event occurs):

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
    console.log('Cordova features now available');
}

To use the Media API (in mobile, wearable, and TV applications), the application has to request permission by adding the following privileges to the config.xml file:

<!--To record audio-->
<tizen:privilege name="http://tizen.org/privilege/mediacapture"/>
<!--To change the volume during playback-->
<tizen:privilege name="http://tizen.org/privilege/volume.set"/>

Play audio files

To implement simple audio file playback, where the audio is played from the beginning to the end, follow these steps:

Place the audio file in a directory on a device. In this example, it is in the owner home directory: /home/owner/content/Music/play.mp3.
Construct a new media object from the audio file. No additional parameters are required:
```
var myMedia = new Media('file:///home/owner/content/Music/play.mp3');
```
Call the play() method:
```
myMedia.play();
```

Release the media resources when they are no longer needed.

Seek position

To change the position of the played file, follow these steps:

Construct a new media object from the audio file:

var myMedia = new Media('file:///home/owner/content/Music/play.mp3');

Start playing:
```
myMedia.play();
```

After 5 seconds, seek the position of 10 seconds:

A timer is registered using the setTimeout() global function.

setTimeout(function() {
    myMedia.seekTo(10000);
    console.log('Playback position has been set to 10 seconds.');
}, 5000);

Stop the media and release after 10 seconds:

setTimeout(function() {
    myMedia.release();
}, 10000);

Change the volume

To change the volume during playback, follow these steps:

Construct a new media object from the audio file:

var myMedia = new Media('file:///home/owner/content/Music/play.mp3');

Start playing:
```
myMedia.play();
```

Mute the volume after 2 seconds:

setTimeout(function() {
    myMedia.setVolume(0.0);
}, 2000);

Set volume to 1.0 after 5 seconds:

setTimeout(function() {
    myMedia.setVolume(1.0);
}, 5000);

Use playback callbacks

You can monitor the playback status changes by defining a status callback for the Media constructor (in mobile, wearable, and TV applications). Each time the status changes, the defined callback is called with a status constant as a parameter. The following table lists the available status constants.

Table: Playback status changes

Constant	Description
`Media.MEDIA_NONE`	File has no status.
`Media.MEDIA_STARTING`	Playback is starting.
`Media.MEDIA_RUNNING`	Playback is running.
`Media.MEDIA_PAUSED`	Playback is paused.
`Media.MEDIA_STOPPED`	Playback is stopped.

To handle playback callbacks, use the following steps:

Define a success callback, which is called when the playback finishes successfully:

var successCallback = function() {
    console.log('Audio file has been played back.');
};

Define an error callback, which is called when an error occurs. The only parameter contains the error code (for a list of error codes, see the MediaError API Reference in mobile, wearable, and TV applications):
```
var errorCallback = function(err) {
    console.log('An error occurred: ' + err.code);
};
```

Define a status callback, which is called when a playback event (such as preparing to playback, running, paused, and stopped) occurs:

var statusCallback = function(status) {
    switch (status) {
        case Media.MEDIA_NONE: console.log('Audio file status is none');
            break;
        case Media.MEDIA_STARTING: console.log('Audio file is starting');
            break;
        case Media.MEDIA_RUNNING: console.log('Audio file is running');
            break;
        case Media.MEDIA_PAUSED: console.log('Audio file is paused');
            break;
        case Media.MEDIA_STOPPED: console.log('Audio file is stopped');
            break;
        default: console.log('Audio file status unknown');
            break;
    }
};

Construct a new media object and pass the callbacks as parameters.

Since the callbacks are optional, you do not need to provide them all. However, to monitor status changes, you must provide the status callback defined in the previous step:
```
var src = 'file:///home/owner/content/Music/play.mp3';
var myMedia = new Media(src, successCallback, errorCallback, statusCallback);
```
Start playing:
```
myMedia.play();
```

Test the callbacks by pausing and resuming playback after 3 and 5 seconds:

setTimeout(function() {
    myMedia.pause();
}, 3000);

setTimeout(function() {
    myMedia.play();
}, 5000);

Get the duration and position

To get the duration of the audio file, and retrieve the current position, follow these steps:

Construct a new media object from an audio file:

var myMedia = new Media('file:///home/owner/content/Music/play.mp3');

Get the duration and print it to the system log. The -1 value means that the duration is unknown:
```
console.log('Audio duration in seconds is ' + myMedia.getDuration());
```
Start playing:
```
myMedia.play();
```

The method for getting the current position is asynchronous, so a callback is used. Define the callback:

var positionCallback = function(position) {
    console.log('Current position in seconds is ' + position);
};

Define the optional callback for errors in retrieving the position. For the specific error codes, see the MediaError API Reference (in mobile, wearable, and TV applications):
```
var errorCallback = function(err) {
    console.log('An error occurred: ' + err.code);
};
```
Request the position. The result is passed asynchronously to the callback function:
```
myMedia.getCurrentPosition(positionCallback, errorCallback);
```

You can set a timer to get the position 5 seconds later:

setTimeout(function() {
    myMedia.getCurrentPosition(positionCallback, errorCallback);
}, 5000);

Something similar to the following example is shown in the system log:

Current position in seconds is 0
Current position in seconds is 4.919

Record audio

To start and stop recording, follow these steps:

Define the optional success and error callbacks:

var successCallback = function() {
    console.log('Started recording audio file.');
};

var errorCallback = function(err) {
    console.log('Error occurred ' + err.code);
};

Construct a media object and pass the name for the new audio file:

var myMedia = new Media('recording.mp3', successCallback, errorCallback);

Start recording:
```
myMedia.startRecord();
```

Stop recording after 10 seconds and release the media object:

setTimeout(function() {
    myMedia.stopRecord();
    console.log('Stopped recording an audio file.');
    myMedia.release();
}, 10000);

Always release the media object when no longer needed.

Dependencies
- Tizen 3.0 and Higher for Mobile
- Tizen 3.0 and Higher for Wearable
- Tizen 3.0 and Higher for TV