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

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7.5
  • Tizen
  • Windows 8

Permissions

Android

app/res/xml/config.xml

<plugin name="Media" value="org.apache.cordova.AudioHandler" />

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

www/plugins.xml

<plugin name="Capture" value="org.apache.cordova.media.MediaCapture" />

iOS

config.xml

<plugin name="Media" value="CDVSound" />

Windows Phone

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

Tizen

No permissions are required.

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.