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.