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 10
  • 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 10

      (in www/config.xml)
  <feature name="Media" value="Media" />

  • 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.