Media

The Media object provides the ability to record and play back audio files on a device.

var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);

NOTE: The current implementation does not adhere to a W3C specification for media capture, and is provided for convenience only. A future implementation will adhere to the latest W3C specification and may deprecate the current APIs.

Parameters

• src: A URI containing the audio content. (DOMString)

• mediaSuccess: (Optional) The callback that executes after a Media object has completed the current play, record, or stop action. (Function)

• mediaError: (Optional) The callback that executes if an error occurs. (Function)

• mediaStatus: (Optional) The callback that executes to indicate status changes. (Function)

Constants

The following constants are reported as the only parameter to the mediaStatus callback:

• Media.MEDIA_NONE = 0;
• Media.MEDIA_STARTING = 1;
• Media.MEDIA_RUNNING = 2;
• Media.MEDIA_PAUSED = 3;
• Media.MEDIA_STOPPED = 4;

Methods

• [media.getCurrentPosition](media.getCurrentPosition.html): Returns the current position within an audio file.

• [media.getDuration](media.getDuration.html): Returns the duration of an audio file.

• [media.play](media.play.html): Start or resume playing an audio file.

• [media.pause](media.pause.html): Pause playback of an audio file.

• [media.release](media.release.html): Releases the underlying operating system's audio resources.

• [media.seekTo](media.seekTo.html): Moves the position within the audio file.

• [media.setVolume](media.setVolume.html): Set the volume for audio playback.

• [media.startRecord](media.startRecord.html): Start recording an audio file.

• [media.stopRecord](media.stopRecord.html): Stop recording an audio file.

• [media.stop](media.stop.html): Stop playing an audio file.

Additional ReadOnly Parameters

• position: The position within the audio playback, in seconds.
  • Not automatically updated during play; call getCurrentPosition to update.
• duration: The duration of the media, in seconds.

Supported Platforms

• Amazon Fire OS
• Android
• BlackBerry WebWorks 5.0+
• iOS
• Windows Phone 7.5
• Tizen
• Windows 8

Accessing the Feature

As of version 3.0, Cordova implements device-level APIs as plugins. Use the CLI's plugin command, described in The Command-Line Interface, to add or remove this feature for a project:

    $ cordova plugin add org.apache.cordova.media 
    $ cordova plugin ls
    [ 'org.apache.cordova.media' ]
    $ cordova plugin rm org.apache.cordova.media 

These commands apply to all targeted platforms, but modify the platform-specific configuration settings described below:

• Amazon Fire OS

    (in app/res/xml/config.xml)
    <feature name="Media">
        <param name="android-package" value="org.apache.cordova.media.AudioHandler" />
    </feature>
  
    (in app/AndroidManifest.xml)
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  

• Android

    (in app/res/xml/config.xml)
    <feature name="Media">
        <param name="android-package" value="org.apache.cordova.media.AudioHandler" />
    </feature>
  
    (in app/AndroidManifest.xml)
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  

• BlackBerry WebWorks

    (in www/plugins.xml)
    <feature name="Capture">
        <param name="blackberry-package" value="org.apache.cordova.media.MediaCapture" />
    </feature>
  

• iOS (in the named application directory's config.xml)

    <feature name="Media">
        <param name="ios-package" value="CDVSound" />
    </feature>
  

• Windows Phone (in Properties/WPAppManifest.xml)

    <Capabilities>
        <Capability Name="ID_CAP_MEDIALIB" />
        <Capability Name="ID_CAP_MICROPHONE" />
        <Capability Name="ID_HW_FRONTCAMERA" />
        <Capability Name="ID_CAP_ISV_CAMERA" />
        <Capability Name="ID_CAP_CAMERA" />
    </Capabilities>
  

  Reference: Application Manifest for Windows Phone

Some platforms may support this feature without requiring any special configuration. See Platform Support for an overview.

Windows Phone Quirks

• Only one media file can be played back at a time.

• There are strict restrictions on how your application interacts with other media. See the Microsoft documentation for details.