Mandatory, Supported by Tizen Wearable emulator

Media API

This plugin provides the ability to record and play back audio files on a device.

This plugin defines a global Media Constructor.

Original documentation: Cordova Media.

Remark: Usage of cordova API needs http://tizen.org/privilege/filesystem.read privilege.

Remark: In order to access files, a proper privilege has to be defined additionally:

for accessing only internal storage using this API, a privilege http://tizen.org/privilege/mediastorage must be provided,
for accessing only external storage using this API, a privilege http://tizen.org/privilege/externalstorage must be provided,
for accessing internal and external storage using this API, privileges (http://tizen.org/privilege/mediastorage and http://tizen.org/privilege/externalstorage) must be provided.
Storage privileges are privacy-related privileges and there is a need of asking user directly with proper pop-up. Please refer to Privacy Privilege API for more details.

Since: 3.0

1. Interfaces
- 1.1. Media
- 1.2. MediaError
- 1.3. MediaErrorCallback
- 1.4. StatusChangeCallback
- 1.5. PositionSuccessCallback
2. Related Feature
3. Full WebIDL

Summary of Interfaces and Methods

Interface	Method
Media	void getCurrentPosition (PositionSuccessCallback positionSuccessCallback, optional MediaErrorCallback errorCallback) double getDuration () void pause () void play () void release () void seekTo (double position) void setVolume (double volume) void startRecord () void stopRecord () void stop ()
MediaError
MediaErrorCallback	void onerror (MediaError error)
StatusChangeCallback	void onchanged (short status)
PositionSuccessCallback	void onsuccess (double position)

1. Interfaces

1.1. Media

The Media interface provides the audio object.

  [Constructor(DOMString src, optional SuccessCallback? successCallback, optional MediaErrorCallback? errorCallback,
               optional StatusChangeCallback? mediaStatus)]
  interface Media {
    const short MEDIA_NONE = 0;
    const short MEDIA_STARTING = 1;
    const short MEDIA_RUNNING = 2;
    const short MEDIA_PAUSED = 3;
    const short MEDIA_STOPPED = 4;
    attribute DOMString src;
    attribute SuccessCallback? successCallback;
    attribute MediaErrorCallback? errorCallback;
    attribute StatusChangeCallback? statusCallback;
    void getCurrentPosition(PositionSuccessCallback positionSuccessCallback, optional MediaErrorCallback errorCallback);
    double getDuration();
    void pause();
    void play();
    void release();
    void seekTo(double position);
    void setVolume(double volume);
    void startRecord();
    void stopRecord();
    void stop();
  };

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

var myMedia = new Media(src, successCallback, errorCallback, statusCallback);

Constructors

Constructor (DOMString, SuccessCallback?, MediaErrorCallback?, StatusChangeCallback?)

Constants

MEDIA_NONE

MEDIA_STARTING

MEDIA_RUNNING

MEDIA_PAUSED

MEDIA_STOPPED

Above constants are reported as the only parameter to the mediaStatus callback.

Since: 3.0

Attributes

DOMString src
A URI containing the audio content.

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read
SuccessCallback successCallback [nullable]
The callback that executes after a Media object has completed the current play, record, or stop action.

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read
MediaErrorCallback errorCallback [nullable]
The callback that executes if an error occurs.

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read
StatusChangeCallback statusCallback [nullable]
The callback that executes to indicate status changes.

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Methods

getCurrentPosition

Returns the current position within an audio file in seconds.

void getCurrentPosition(PositionSuccessCallback positionSuccessCallback, optional MediaErrorCallback errorCallback);

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Parameters:

positionSuccessCallback: The callback that is passed the current position in seconds.
errorCallback [optional]: The callback to execute if an error occurs.

Code example:

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

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

positionSuccessCallback = function(position)
{
  console.log("Current position is " + position);
};

var src = "file:///home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback);

myMedia.play();

setTimeout(function()
{
  myMedia.getCurrentPosition(positionSuccessCallback);
}, 2000);

Output example:

Audio file has been played back
Current position is 2.000

getDuration

Returns the duration of an audio file in seconds. If the duration is unknown, it returns a value of -1.

double getDuration();

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

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

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

var src = "file:///home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback);

var duration = myMedia.getDuration();
console.log("Audio duration is " + duration);

Output example:

Audio duration is 281.035

pause

Pauses playing an audio file.

void pause();

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

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

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

statusCallback = function(status)
{
  if (status == Media.MEDIA_PAUSED)
  {
    console.log("Audio file has been paused");
  }
};

var src = "file:///home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback, statusCallback);

myMedia.play();

/* Pause after 2 seconds. */
setTimeout(function()
{
  myMedia.pause();
}, 2000);

Output example:

Audio file has been paused

play

Starts or resumes playing an audio file.

void play();

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

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

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

var src = "file:///home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback);

myMedia.play();

Output example:

Audio file has been played back

release

Releases the underlying operating system's audio resources. Applications should call the release function for any Media resource that is no longer needed.

void release();

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

successCallback = function()
{
  console.log("Audio file has been stopped or released");
};

errorCallback = function(err)
{
  console.log("An error occurred: " + err.message);
};

var src = "file://home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback);

myMedia.play();
myMedia.stop();
myMedia.release();

Output example:

Audio file has been stopped or released
Audio file has been stopped or released

seekTo

Sets the current position within an audio file.

void seekTo(double position);

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Parameters:

position: The position to set the playback position within the audio, in milliseconds.

Code example:

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

errorCallback = function(err)
{
  console.log("An error occurred: " + err.message);
};

var src = "file://home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback);

myMedia.play();

/* SeekTo to 10 seconds after 5 seconds. */
setTimeout(function()
{
  myMedia.seekTo(10000);
  console.log("Playback position has been set to 10 seconds");
}, 5000);

Output example:

Playback position has been set to 10 seconds
Audio file has been played back

setVolume

Set the volume for an audio file.

void setVolume(double volume);

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/volume.set

Privilege: http://tizen.org/privilege/filesystem.read

Parameters:

volume: The volume to set for playback. The value must be within the range of 0.0 to 1.0.

Code example:

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

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

var src = "file://home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback);

myMedia.play();

/* Mute volume after 2 seconds. */
setTimeout(function()
{
  myMedia.setVolume(0.0);
  console.log("Playback volume has been muted");
}, 2000);

/* Set volume to 1.0 after 5 seconds. */
setTimeout(function()
{
  myMedia.setVolume(1.0);
  console.log("Playback volume has been set to 1.0");
}, 5000);

Output example:

Playback volume has been muted
Playback volume has been set to 1.0
Audio file has been played back

startRecord

Starts recording an audio file.

void startRecord();

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/mediacapture

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

successCallback = function()
{
  console.log("Started recording an audio file");
};

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

var src = "recordAudio.mp3";
var myRecMedia = new Media(src, successCallback, errorCallback);

myRecMedia.startRecord();

Output example:

Started recording an audio file

stopRecord

Stops recording an audio file.

void stopRecord();

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/mediacapture

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

successCallback = function()
{
  console.log("Started recording an audio file");
};

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

var src = "recordAudio.mp3";
var myRecMedia = new Media(src, successCallback, errorCallback);

myRecMedia.startRecord();

/* Stop recording after 10 seconds. */
setTimeout(function()
{
  myRecMedia.stopRecord();
  console.log("Stopped recording an audio file");
}, 10000);

Output example:

Started recording an audio file
Stopped recording an audio file

stop

Stops playing an audio file.

void stop();

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Code example:

successCallback = function()
{
  console.log("Audio file has been stopped");
};

errorCallback = function(err)
{
  console.log("Error occurred " + err.message);
};

var src = "file://home/app/content/Documents/play.mp3";
var myMedia = new Media(src, successCallback, errorCallback);

myMedia.play();

/* Stop after 10 seconds. */
setTimeout(function()
{
  myMedia.stop();
}, 10000);

Output example:

Audio playback has been stopped

1.2. MediaError

A MediaError object is returned to the MediaErrorCallback function when an error occurs.

  interface MediaError {
    const short MEDIA_ERR_ABORTED = 1;
    const short MEDIA_ERR_NETWORK = 2;
    const short MEDIA_ERR_DECODE = 3;
    const short MEDIA_ERR_NONE_SUPPORTED = 4;
    readonly attribute short code;
  };

Since: 3.0

Attributes

readonly short code
One of the predefined error codes listed above.

Since: 3.0

1.3. MediaErrorCallback

Basic error callback.

  [Callback=FunctionOnly, NoInterfaceObject] interface MediaErrorCallback {
    void onerror(MediaError error);
  };

Since: 3.0

Methods

onerror

Success

void onerror(MediaError error);

Since: 3.0

Parameters:

error: Error object containing some information about the error.

1.4. StatusChangeCallback

The callback function used to return status of the Media object.

  [Callback=FunctionOnly, NoInterfaceObject] interface StatusChangeCallback {
    void onchanged(short status);
  };

Since: 3.0

Methods

onchanged

Called when the status of the Media object has been changed.

void onchanged(short status);

Since: 3.0

Parameters:

status: The status of the Media object. It is equal to one of the Media interface constant: MEDIA_NONE, MEDIA_STARTING, MEDIA_RUNNING, MEDIA_PAUSED or MEDIA_STOPPED.

1.5. PositionSuccessCallback

The callback function used to return current position of the Media object.

  [Callback=FunctionOnly, NoInterfaceObject] interface PositionSuccessCallback {
    void onsuccess(double position);
  };

Since: 3.0

Methods

onsuccess

Called when getting current position of the media file is retrieved successfully.

void onsuccess(double position);

Since: 3.0

Parameters:

position: The current position of the media file.

2. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

If an application uses startRecord() or stopRecord(), declare the following feature requirements in the config file:

http://tizen.org/feature/microphone

http://tizen.org/feature/camera

http://tizen.org/feature/media.audio_recording

For more information, see Application Filtering.

3. Full WebIDL

module Media {
  [Constructor(DOMString src, optional SuccessCallback? successCallback, optional MediaErrorCallback? errorCallback,
               optional StatusChangeCallback? mediaStatus)]
  interface Media {
    const short MEDIA_NONE = 0;
    const short MEDIA_STARTING = 1;
    const short MEDIA_RUNNING = 2;
    const short MEDIA_PAUSED = 3;
    const short MEDIA_STOPPED = 4;
    attribute DOMString src;
    attribute SuccessCallback? successCallback;
    attribute MediaErrorCallback? errorCallback;
    attribute StatusChangeCallback? statusCallback;
    void getCurrentPosition(PositionSuccessCallback positionSuccessCallback, optional MediaErrorCallback errorCallback);
    double getDuration();
    void pause();
    void play();
    void release();
    void seekTo(double position);
    void setVolume(double volume);
    void startRecord();
    void stopRecord();
    void stop();
  };
  interface MediaError {
    const short MEDIA_ERR_ABORTED = 1;
    const short MEDIA_ERR_NETWORK = 2;
    const short MEDIA_ERR_DECODE = 3;
    const short MEDIA_ERR_NONE_SUPPORTED = 4;
    readonly attribute short code;
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface MediaErrorCallback {
    void onerror(MediaError error);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface StatusChangeCallback {
    void onchanged(short status);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface PositionSuccessCallback {
    void onsuccess(double position);
  };
};

Media API

Table of Contents

Summary of Interfaces and Methods

1. Interfaces

1.1. Media

Constructors

Constants

Attributes

Methods

1.2. MediaError

Attributes

1.3. MediaErrorCallback

Methods

1.4. StatusChangeCallback

Methods

1.5. PositionSuccessCallback

Methods

2. Related Feature

3. Full WebIDL