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:

Since: 3.0

Table of Contents


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?)
The Media interface provides interface and functions to manage audio objects.
Media(DOMString src, optional SuccessCallback? successCallback, optional MediaErrorCallback? errorCallback,
      optional StatusChangeCallback? mediaStatus);

Since: 3.0

  • TypeError
    • Is thrown if any of the input parameters has incorrect type.

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);
      };
    };