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 is invoked after a Media object has completed the current play/record or stop action. (Function) +
+mediaError: (Optional) The callback that is invoked if there was an error. (Function) +
+mediaStatus: (Optional) The callback that is invoked to indicate status changes. (Function) +

+Constants +

+ +

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

+ +

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

+Methods +

+ +

+media.getCurrentPosition: Returns the current position within an audio file.
+media.getDuration: Returns the duration of an audio file.
+media.play: Start or resume playing audio file.
+media.pause: Pause playing audio file.
+media.release: Releases the underlying OS'es audio resources.
+media.seekTo: Moves the position within the audio file.
+media.startRecord: Start recording audio file.
+media.stopRecord: Stop recording audio file.
+media.stop: Stop playing 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" />
+

+ +

Bada

+ +

manifest.xml

+ +

<Privilege>
+    <Name>RECORDING</Name>
+</Privilege>
+

+ +

BlackBerry WebWorks

+ +

www/plugins.xml

+ +

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

+ +

iOS

+ +

config.xml

+ +

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

+ +

webOS

+ +

No permissions are required.
+

+ +

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 as to how your application interacts with other media. See http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh184838(v=vs.92).aspx
+

+ +

media.getCurrentPosition

+ +

Returns the current position within an audio file.

+ +

media.getCurrentPosition(mediaSuccess, [mediaError]);
+

+ +

+Parameters +

+ +

+mediaSuccess: The callback that is called with the current position in seconds.
+mediaError: (Optional) The callback that is called if there was an error.

+Description +

+ +

Function media.getCurrentPosition is an asynchronous function that returns the current position of the underlying audio file of a Media object. Also updates the _position parameter within the Media object.

+ +

+Supported Platforms +

+ +

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

+Quick Example +

+ +

    // Audio player
+    //
+    var my_media = new Media(src, onSuccess, onError);
+
+    // Update media position every second
+    var mediaTimer = setInterval(function() {
+        // get media position
+        my_media.getCurrentPosition(
+            // success callback
+            function(position) {
+                if (position > -1) {
+                    console.log((position) + " sec");
+                }
+            },
+            // error callback
+            function(e) {
+                console.log("Error getting pos=" + e);
+            }
+        );
+    }, 1000);
+

+ +

+Full Example +

+ +

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                  "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>Media Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        }
+
+        // Audio player
+        //
+        var my_media = null;
+        var mediaTimer = null;
+
+        // Play audio
+        //
+        function playAudio(src) {
+            // Create Media object from src
+            my_media = new Media(src, onSuccess, onError);
+
+            // Play audio
+            my_media.play();
+
+            // Update my_media position every second
+            if (mediaTimer == null) {
+                mediaTimer = setInterval(function() {
+                    // get my_media position
+                    my_media.getCurrentPosition(
+                        // success callback
+                        function(position) {
+                            if (position > -1) {
+                                setAudioPosition((position) + " sec");
+                            }
+                        },
+                        // error callback
+                        function(e) {
+                            console.log("Error getting pos=" + e);
+                            setAudioPosition("Error: " + e);
+                        }
+                    );
+                }, 1000);
+            }
+        }
+
+        // Pause audio
+        // 
+        function pauseAudio() {
+            if (my_media) {
+                my_media.pause();
+            }
+        }
+
+        // Stop audio
+        // 
+        function stopAudio() {
+            if (my_media) {
+                my_media.stop();
+            }
+            clearInterval(mediaTimer);
+            mediaTimer = null;
+        }
+
+        // onSuccess Callback
+        //
+        function onSuccess() {
+            console.log("playAudio():Audio Success");
+        }
+
+        // onError Callback 
+        //
+        function onError(error) {
+            alert('code: '    + error.code    + '\n' + 
+                  'message: ' + error.message + '\n');
+        }
+
+        // Set audio position
+        // 
+        function setAudioPosition(position) {
+            document.getElementById('audio_position').innerHTML = position;
+        }
+
+        </script>
+      </head>
+      <body>
+        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
+        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
+        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
+        <p id="audio_position"></p>
+      </body>
+    </html>
+

+ +

media.getDuration

+ +

Returns the duration of an audio file.

+ +

media.getDuration();
+

+ +

+Description +

+ +

Function media.getDuration is a synchronous function that returns the duration of the audio file in seconds, if known. If the duration is unknown, a value of -1 is returned.

+ +

+Supported Platforms +

+ +

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

+Quick Example +

+ +

    // Audio player
+    //
+    var my_media = new Media(src, onSuccess, onError);
+
+    // Get duration
+    var counter = 0;
+    var timerDur = setInterval(function() {
+        counter = counter + 100;
+        if (counter > 2000) {
+            clearInterval(timerDur);
+        }
+        var dur = my_media.getDuration();
+        if (dur > 0) {
+            clearInterval(timerDur);
+            document.getElementById('audio_duration').innerHTML = (dur) + " sec";
+        }
+   }, 100);
+

+ +

+Full Example +

+ +

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                          "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>Media Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        }
+
+        // Audio player
+        //
+        var my_media = null;
+        var mediaTimer = null;
+
+        // Play audio
+        //
+        function playAudio(src) {
+            // Create Media object from src
+            my_media = new Media(src, onSuccess, onError);
+
+            // Play audio
+            my_media.play();
+
+            // Update my_media position every second
+            if (mediaTimer == null) {
+                mediaTimer = setInterval(function() {
+                    // get my_media position
+                    my_media.getCurrentPosition(
+                        // success callback
+                        function(position) {
+                            if (position > -1) {
+                                setAudioPosition((position) + " sec");
+                            }
+                        },
+                        // error callback
+                        function(e) {
+                            console.log("Error getting pos=" + e);
+                            setAudioPosition("Error: " + e);
+                        }
+                    );
+                }, 1000);
+            }
+        }
+
+        // Pause audio
+        // 
+        function pauseAudio() {
+            if (my_media) {
+                my_media.pause();
+            }
+        }
+
+        // Stop audio
+        // 
+        function stopAudio() {
+            if (my_media) {
+                my_media.stop();
+            }
+            clearInterval(mediaTimer);
+            mediaTimer = null;
+        }
+
+        // onSuccess Callback
+        //
+        function onSuccess() {
+            console.log("playAudio():Audio Success");
+        }
+
+        // onError Callback 
+        //
+        function onError(error) {
+            alert('code: '    + error.code    + '\n' + 
+                  'message: ' + error.message + '\n');
+        }
+
+        // Set audio position
+        // 
+        function setAudioPosition(position) {
+            document.getElementById('audio_position').innerHTML = position;
+        }
+
+        </script>
+      </head>
+      <body>
+        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
+        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
+        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
+        <p id="audio_position"></p>
+      </body>
+    </html>
+

+ +

media.pause

+ +

Pauses playing an audio file.

+ +

media.pause();
+

+ +

+Description +

+ +

Function media.pause is a synchronous function that pauses playing an audio file.

+ +

+Supported Platforms +

+ +

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

+Quick Example +

+ +

// Play audio
+//
+function playAudio(url) {
+    // Play the audio file at url
+    var my_media = new Media(url,
+        // success callback
+        function() {
+            console.log("playAudio():Audio Success");
+        },
+        // error callback
+        function(err) {
+            console.log("playAudio():Audio Error: "+err);
+    });
+
+    // Play audio
+    my_media.play();
+
+    // Pause after 10 seconds
+    setTimeout(function() {
+        media.pause();
+    }, 10000);        
+}
+

+ +

+Full Example +

+ +

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                          "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>Media Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        }
+
+        // Audio player
+        //
+        var my_media = null;
+        var mediaTimer = null;
+
+        // Play audio
+        //
+        function playAudio(src) {
+            // Create Media object from src
+            my_media = new Media(src, onSuccess, onError);
+
+            // Play audio
+            my_media.play();
+
+            // Update my_media position every second
+            if (mediaTimer == null) {
+                mediaTimer = setInterval(function() {
+                    // get my_media position
+                    my_media.getCurrentPosition(
+                        // success callback
+                        function(position) {
+                            if (position > -1) {
+                                setAudioPosition((position) + " sec");
+                            }
+                        },
+                        // error callback
+                        function(e) {
+                            console.log("Error getting pos=" + e);
+                            setAudioPosition("Error: " + e);
+                        }
+                    );
+                }, 1000);
+            }
+        }
+
+        // Pause audio
+        // 
+        function pauseAudio() {
+            if (my_media) {
+                my_media.pause();
+            }
+        }
+
+        // Stop audio
+        // 
+        function stopAudio() {
+            if (my_media) {
+                my_media.stop();
+            }
+            clearInterval(mediaTimer);
+            mediaTimer = null;
+        }
+
+        // onSuccess Callback
+        //
+        function onSuccess() {
+            console.log("playAudio():Audio Success");
+        }
+
+        // onError Callback 
+        //
+        function onError(error) {
+            alert('code: '    + error.code    + '\n' + 
+                  'message: ' + error.message + '\n');
+        }
+
+        // Set audio position
+        // 
+        function setAudioPosition(position) {
+            document.getElementById('audio_position').innerHTML = position;
+        }
+
+        </script>
+      </head>
+      <body>
+        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
+        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
+        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
+        <p id="audio_position"></p>
+      </body>
+    </html>
+

+ +

media.play

+ +

Starts or resumes playing an audio file.

+ +

media.play();
+

+ +

+Description +

+ +

Function media.play is a synchronous function that starts or resumes playing an audio file.

+ +

+Supported Platforms +

+ +

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

+Quick Example +

+ +

// Play audio
+//
+function playAudio(url) {
+    // Play the audio file at url
+    var my_media = new Media(url,
+        // success callback
+        function() {
+            console.log("playAudio():Audio Success");
+        },
+        // error callback
+        function(err) {
+            console.log("playAudio():Audio Error: "+err);
+    });
+
+    // Play audio
+    my_media.play();
+}
+

+ +

+Full Example +

+ +

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                          "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>Media Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        }
+
+        // Audio player
+        //
+        var my_media = null;
+        var mediaTimer = null;
+
+        // Play audio
+        //
+        function playAudio(src) {
+            if (my_media == null) {
+                // Create Media object from src
+                my_media = new Media(src, onSuccess, onError);
+            } // else play current audio
+            // Play audio
+            my_media.play();
+
+            // Update my_media position every second
+            if (mediaTimer == null) {
+                mediaTimer = setInterval(function() {
+                    // get my_media position
+                    my_media.getCurrentPosition(
+                        // success callback
+                        function(position) {
+                            if (position > -1) {
+                                setAudioPosition((position) + " sec");
+                            }
+                        },
+                        // error callback
+                        function(e) {
+                            console.log("Error getting pos=" + e);
+                            setAudioPosition("Error: " + e);
+                        }
+                    );
+                }, 1000);
+            }
+        }
+
+        // Pause audio
+        // 
+        function pauseAudio() {
+            if (my_media) {
+                my_media.pause();
+            }
+        }
+
+        // Stop audio
+        // 
+        function stopAudio() {
+            if (my_media) {
+                my_media.stop();
+            }
+            clearInterval(mediaTimer);
+            mediaTimer = null;
+        }
+
+        // onSuccess Callback
+        //
+        function onSuccess() {
+            console.log("playAudio():Audio Success");
+        }
+
+        // onError Callback 
+        //
+        function onError(error) {
+            alert('code: '    + error.code    + '\n' + 
+                  'message: ' + error.message + '\n');
+        }
+
+        // Set audio position
+        // 
+        function setAudioPosition(position) {
+            document.getElementById('audio_position').innerHTML = position;
+        }
+
+        </script>
+      </head>
+      <body>
+        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
+        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
+        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
+        <p id="audio_position"></p>
+      </body>
+    </html>
+

+ +

+BlackBerry WebWorks Quirks +

+ +

BlackBerry devices support a limited number of simultaneous audio channels. CDMA devices only support a single audio channel. Other devices support up to two simultaneous channels. Attempting to play more audio files then the supported amount will result in previous playback being stopped.

+iOS Quirk +

+ +

numberOfLoops

+ +

Pass in this option to the play method to specify the number of times you want the media file to play. e.g:

+ +

var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
+myMedia.play({ numberOfLoops: 2 })
+

+
playAudioWhenScreenIsLocked
+ +
Pass in this option to the play method to specify whether you want to play the audio of the media file when the screen is locked (this defaults to true if not set). If this is set to true, it will ignore the state of the hardware mute button. e.g:
+ +
```
var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
+myMedia.play({ playAudioWhenScreenIsLocked : false })
+
```
+
+
order of file search
+ +
When only a file name or simple path is provided, iOS will search in the www for the file and then in the application documents/tmp directory.
+ +
```
var myMedia = new Media("audio/beer.mp3")
+myMedia.play()  // will first look for file in www/audio/beer.mp3 then in <application>/documents/tmp/audio/beer.mp3
+
```
+

media.release

+ +

Releases the underlying operating systems audio resources.

+ +

media.release();
+

+ +

+Description +

+ +

Function media.release is a synchronous function that releases the underlying operating systems audio resources. This function is particularly important for Android as there are a finite amount of OpenCore instances for media playback. Developers should call the 'release' function when they no longer need the Media resource.

+ +

+Supported Platforms +

+ +

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

+Quick Example +

+ +

    // Audio player
+    //
+    var my_media = new Media(src, onSuccess, onError);
+
+    my_media.play();
+    my_media.stop();
+    my_media.release();
+

+ +

+Full Example +

+ +

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                          "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>Media Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        }
+
+        // Audio player
+        //
+        var my_media = null;
+        var mediaTimer = null;
+
+        // Play audio
+        //
+        function playAudio(src) {
+            // Create Media object from src
+            my_media = new Media(src, onSuccess, onError);
+
+            // Play audio
+            my_media.play();
+
+            // Update my_media position every second
+            if (mediaTimer == null) {
+                mediaTimer = setInterval(function() {
+                    // get my_media position
+                    my_media.getCurrentPosition(
+                        // success callback
+                        function(position) {
+                            if (position > -1) {
+                                setAudioPosition((position) + " sec");
+                            }
+                        },
+                        // error callback
+                        function(e) {
+                            console.log("Error getting pos=" + e);
+                            setAudioPosition("Error: " + e);
+                        }
+                    );
+                }, 1000);
+            }
+        }
+
+        // Pause audio
+        // 
+        function pauseAudio() {
+            if (my_media) {
+                my_media.pause();
+            }
+        }
+
+        // Stop audio
+        // 
+        function stopAudio() {
+            if (my_media) {
+                my_media.stop();
+            }
+            clearInterval(mediaTimer);
+            mediaTimer = null;
+        }
+
+        // onSuccess Callback
+        //
+        function onSuccess() {
+            console.log("playAudio():Audio Success");
+        }
+
+        // onError Callback 
+        //
+        function onError(error) {
+            alert('code: '    + error.code    + '\n' + 
+                  'message: ' + error.message + '\n');
+        }
+
+        // Set audio position
+        // 
+        function setAudioPosition(position) {
+            document.getElementById('audio_position').innerHTML = position;
+        }
+
+        </script>
+      </head>
+      <body>
+        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
+        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
+        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
+        <p id="audio_position"></p>
+      </body>
+    </html>
+

+ +

media.seekTo

+ +

Sets the current position within an audio file.

+ +

media.seekTo(milliseconds);
+

+ +

+Parameters +

+ +

+milliseconds: The position to set the playback position within the audio in milliseconds. .

+Description +

+ +

Function media.seekTo is an asynchronous function that updates the current position of the underlying audio file of a Media object. Also updates the _position parameter within the Media object.

+ +

+Supported Platforms +

+ +

Android
BlackBerry WebWorks (OS 6.0 and higher)
iOS
Windows Phone 7 and 8
Tizen
Windows 8

+Quick Example +

+ +

    // Audio player
+    //
+    var my_media = new Media(src, onSuccess, onError);
+    my_media.play();
+    // SeekTo to 10 seconds after 5 seconds
+    setTimeout(function() {
+        my_media.seekTo(10000);
+    }, 5000);
+

+ +

+Full Example +

+ +

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                  "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>Media Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        }
+
+        // Audio player
+        //
+        var my_media = null;
+        var mediaTimer = null;
+
+        // Play audio
+        //
+        function playAudio(src) {
+            // Create Media object from src
+            my_media = new Media(src, onSuccess, onError);
+
+            // Play audio
+            my_media.play();
+            // Update media position every second
+            mediaTimer = setInterval(function() {
+                // get media position
+                my_media.getCurrentPosition(
+                    // success callback
+                    function(position) {
+                        if (position > -1) {
+                            setAudioPosition(position + " sec");
+                        }
+                    },
+                    // error callback
+                    function(e) {
+                        console.log("Error getting pos=" + e);
+                    }
+                );
+            }, 1000);
+            // SeekTo to 10 seconds after 5 seconds
+            setTimeout(function() {
+                my_media.seekTo(10000);
+            }, 5000);
+        }
+
+        // Stop audio
+        // 
+        function stopAudio() {
+            if (my_media) {
+                my_media.stop();
+            }
+            clearInterval(mediaTimer);
+            mediaTimer = null;
+        }
+
+        // onSuccess Callback
+        //
+        function onSuccess() {
+            console.log("playAudio():Audio Success");
+        }
+
+        // onError Callback 
+        //
+        function onError(error) {
+            alert('code: '    + error.code    + '\n' + 
+                  'message: ' + error.message + '\n');
+        }
+
+        // Set audio position
+        // 
+        function setAudioPosition(position) {
+            document.getElementById('audio_position').innerHTML = position;
+        }
+
+        </script>
+      </head>
+      <body>
+        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
+        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
+        <p id="audio_position"></p>
+      </body>
+    </html>
+

+ +

+BlackBerry WebWorks Quirks +

+ +

This API is not supported on BlackBerry OS 5 devices.

media.startRecord

+ +

Starts recording an audio file.

+ +

media.startRecord();
+

+ +

+Description +

+ +

Function media.startRecord is a synchronous function that starts recording an audio file.

+ +

+Supported Platforms +

+ +

Android
BlackBerry WebWorks (OS 5.0 and higher)
iOS
Windows Phone 7 and 8
Windows 8

+Quick Example +

+ +

// Record audio
+// 
+function recordAudio() {
+    var src = "myrecording.mp3";
+    var mediaRec = new Media(src,
+        // success callback
+        function() {
+            console.log("recordAudio():Audio Success");
+        },
+
+        // error callback
+        function(err) {
+            console.log("recordAudio():Audio Error: "+ err.code);
+        });
+
+    // Record audio
+    mediaRec.startRecord();
+}
+

+ +

+Full Example +

+ +

<!DOCTYPE html>
+<html>
+  <head>
+    <title>Device Properties Example</title>
+
+    <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+    <script type="text/javascript" charset="utf-8">
+
+    // Wait for Cordova to load
+    //
+    document.addEventListener("deviceready", onDeviceReady, false);
+
+    // Record audio
+    // 
+    function recordAudio() {
+        var src = "myrecording.amr";
+        var mediaRec = new Media(src, onSuccess, onError);
+
+        // Record audio
+        mediaRec.startRecord();
+
+        // Stop recording after 10 sec
+        var recTime = 0;
+        var recInterval = setInterval(function() {
+            recTime = recTime + 1;
+            setAudioPosition(recTime + " sec");
+            if (recTime >= 10) {
+                clearInterval(recInterval);
+                mediaRec.stopRecord();
+            }
+        }, 1000);
+    }
+
+    // Cordova is ready
+    //
+    function onDeviceReady() {
+        recordAudio();
+    }
+
+    // onSuccess Callback
+    //
+    function onSuccess() {
+        console.log("recordAudio():Audio Success");
+    }
+
+    // onError Callback 
+    //
+    function onError(error) {
+        alert('code: '    + error.code    + '\n' + 
+              'message: ' + error.message + '\n');
+    }
+
+    // Set audio position
+    // 
+    function setAudioPosition(position) {
+        document.getElementById('audio_position').innerHTML = position;
+    }
+
+    </script>
+  </head>
+  <body>
+    <p id="media">Recording audio...</p>
+    <p id="audio_position"></p>
+  </body>
+</html>
+

+ +

+Android Quirks +

+ +

Android devices record audio in Adaptive Multi-Rate format. The specified file should end with a .amr extension.

+BlackBerry WebWorks Quirks +

+ +

BlackBerry devices record audio in Adaptive Multi-Rate format. The specified file must end with a .amr extension.

+iOS Quirks +

+ +

iOS only records to files of type .wav and returns an error if the file name extension is not correct.
If a full path is not provided the recording will be placed in the /documents/tmp directory. This can be accessed via the File apis using LocalFileSystem.TEMPORARY. Subdirectories are not created at record time and must already exist. Thus, myRecording.wav will work but recordings/myRecording.wav will not if the recordings directory does not already exist at /documents/tmp/. +
+
Files can be recorded and played back using the documents URI:
+ +
```
var myMedia = new Media("documents://beer.mp3")
+
```
+

+Tizen Quirks +

+ +

This API is not supported on Tizen devices.

media.stop

+ +

Stops playing an audio file.

+ +

media.stop();
+

+ +

+Description +

+ +

Function media.stop is a synchronous function that stops playing an audio file.

+ +

+Supported Platforms +

+ +

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

+Quick Example +

+ +

// Play audio
+//
+function playAudio(url) {
+    // Play the audio file at url
+    var my_media = new Media(url,
+        // success callback
+        function() {
+            console.log("playAudio():Audio Success");
+        },
+        // error callback
+        function(err) {
+            console.log("playAudio():Audio Error: "+err);
+    });
+
+    // Play audio
+    my_media.play();
+
+    // Pause after 10 seconds
+    setTimeout(function() {
+        my_media.stop();
+    }, 10000);        
+}
+

+ +

+Full Example +

+ +

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                          "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>Media Example</title>
+
+        <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+        <script type="text/javascript" charset="utf-8">
+
+        // Wait for Cordova to load
+        //
+        document.addEventListener("deviceready", onDeviceReady, false);
+
+        // Cordova is ready
+        //
+        function onDeviceReady() {
+            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
+        }
+
+        // Audio player
+        //
+        var my_media = null;
+        var mediaTimer = null;
+
+        // Play audio
+        //
+        function playAudio(src) {
+            // Create Media object from src
+            my_media = new Media(src, onSuccess, onError);
+
+            // Play audio
+            my_media.play();
+
+            // Update my_media position every second
+            if (mediaTimer == null) {
+                mediaTimer = setInterval(function() {
+                    // get my_media position
+                    my_media.getCurrentPosition(
+                        // success callback
+                        function(position) {
+                            if (position > -1) {
+                                setAudioPosition((position) + " sec");
+                            }
+                        },
+                        // error callback
+                        function(e) {
+                            console.log("Error getting pos=" + e);
+                            setAudioPosition("Error: " + e);
+                        }
+                    );
+                }, 1000);
+            }
+        }
+
+        // Pause audio
+        // 
+        function pauseAudio() {
+            if (my_media) {
+                my_media.pause();
+            }
+        }
+
+        // Stop audio
+        // 
+        function stopAudio() {
+            if (my_media) {
+                my_media.stop();
+            }
+            clearInterval(mediaTimer);
+            mediaTimer = null;
+        }
+
+        // onSuccess Callback
+        //
+        function onSuccess() {
+            console.log("playAudio():Audio Success");
+        }
+
+        // onError Callback 
+        //
+        function onError(error) {
+            alert('code: '    + error.code    + '\n' + 
+                  'message: ' + error.message + '\n');
+        }
+
+        // Set audio position
+        // 
+        function setAudioPosition(position) {
+            document.getElementById('audio_position').innerHTML = position;
+        }
+
+        </script>
+      </head>
+      <body>
+        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
+        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
+        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
+        <p id="audio_position"></p>
+      </body>
+    </html>
+

+ +

media.stopRecord

+ +

Stops recording an audio file.

+ +

media.stopRecord();
+

+ +

+Description +

+ +

Function media.stopRecord is a synchronous function that stops recording an audio file.

+ +

+Supported Platforms +

+ +

Android
BlackBerry WebWorks (OS 5.0 and higher)
iOS
Windows Phone 7 and 8
Windows 8

+Quick Example +

+ +

// Record audio
+// 
+function recordAudio() {
+    var src = "myrecording.mp3";
+    var mediaRec = new Media(src,
+        // success callback
+        function() {
+            console.log("recordAudio():Audio Success");
+        },
+
+        // error callback
+        function(err) {
+            console.log("recordAudio():Audio Error: "+ err.code);
+        });
+
+    // Record audio
+    mediaRec.startRecord();
+
+    // Stop recording after 10 seconds
+    setTimeout(function() {
+        mediaRec.stopRecord();
+    }, 10000);
+}
+

+ +

+Full Example +

+ +

<!DOCTYPE html>
+<html>
+  <head>
+    <title>Device Properties Example</title>
+
+    <script type="text/javascript" charset="utf-8" src="cordova-2.6.0.js"></script>
+    <script type="text/javascript" charset="utf-8">
+
+    // Wait for Cordova to load
+    //
+    document.addEventListener("deviceready", onDeviceReady, false);
+
+    // Record audio
+    // 
+    function recordAudio() {
+        var src = "myrecording.mp3";
+        var mediaRec = new Media(src, onSuccess, onError);
+
+        // Record audio
+        mediaRec.startRecord();
+
+        // Stop recording after 10 sec
+        var recTime = 0;
+        var recInterval = setInterval(function() {
+            recTime = recTime + 1;
+            setAudioPosition(recTime + " sec");
+            if (recTime >= 10) {
+                clearInterval(recInterval);
+                mediaRec.stopRecord();
+            }
+        }, 1000);
+    }
+
+    // Cordova is ready
+    //
+    function onDeviceReady() {
+        recordAudio();
+    }
+
+    // onSuccess Callback
+    //
+    function onSuccess() {
+        console.log("recordAudio():Audio Success");
+    }
+
+    // onError Callback 
+    //
+    function onError(error) {
+        alert('code: '    + error.code    + '\n' + 
+              'message: ' + error.message + '\n');
+    }
+
+    // Set audio position
+    // 
+    function setAudioPosition(position) {
+        document.getElementById('audio_position').innerHTML = position;
+    }
+
+    </script>
+  </head>
+  <body>
+    <p id="media">Recording audio...</p>
+    <p id="audio_position"></p>
+  </body>
+</html>
+

+ +

+Tizen Quirks +

+ +

This API is not supported on Tizen devices.

MediaError

+ +

A MediaError object is returned to the mediaError callback function when an error occurs.

+ +

+Properties +

+ +

+code: One of the predefined error codes listed below.
+message: Error message describing the details of the error.

+Constants +

+ +

MediaError.MEDIA_ERR_ABORTED
MediaError.MEDIA_ERR_NETWORK
MediaError.MEDIA_ERR_DECODE
MediaError.MEDIA_ERR_NONE_SUPPORTED

+Description +

+ +

The MediaError object is returned to the user through the mediaError callback function when an error occurs.

+ +

mediaError

+ +

A user specified callback function that is invoked when there is an error in media functions.

+ +

function(error) {
+    // Handle the error
+}
+

+ +

+Parameters +

+ +

+error: The error returned by the device. (MediaError)

Media

API Reference

Guides

+Parameters +

+Constants +

+Methods +

+Additional ReadOnly Parameters +

+Supported Platforms +

+Permissions +

Android

app/res/xml/config.xml

app/AndroidManifest.xml

Bada

manifest.xml

BlackBerry WebWorks

www/plugins.xml

iOS

config.xml

webOS

Windows Phone

Properties/WPAppManifest.xml

Tizen

Windows Phone Quirks

+Parameters +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+BlackBerry WebWorks Quirks +

+iOS Quirk +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+Parameters +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+BlackBerry WebWorks Quirks +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+Android Quirks +

+BlackBerry WebWorks Quirks +

+iOS Quirks +

+Tizen Quirks +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+Description +

+Supported Platforms +

+Quick Example +

+Full Example +

+Tizen Quirks +

+Properties +

+Constants +

+Description +

+Parameters +