Media

Media

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

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

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

Methods

Supported Platforms


media.getCurrentPosition

Returns the current position within an audio file.

media.getCurrentPosition(mediaSuccess, [mediaError]);

Parameters

Description

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

Supported Platforms

Quick Example

    // Audio player
    //
    var media = new Media(src, onSuccess, onError);

    // Update media position every second
    var mediaTimer = setInterval(function() {
        // get media position
        media.getCurrentPosition(
            // success callback
            function(position) {
                if (position > -1) {
                    console.log((position/1000) + " 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>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap is ready
    //
    function onDeviceReady() {
        playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
    }

    // Audio player
    //
    var media = null;
    var mediaTimer = null;

    // Play audio
    //
    function playAudio(src) {
        // Create Media object from src
        var media = new Media(src, onSuccess, onError);

        // Play audio
        media.play();

        // Update media position every second
        if (mediaTimer == null) {
            mediaTimer = setInterval(function() {
                // get media position
                media.getCurrentPosition(
                    // success callback
                    function(position) {
                        if (position > -1) {
                            setAudioPosition((position/1000) + " sec");
                        }
                    },
                    // error callback
                    function(e) {
                        console.log("Error getting pos=" + e);
                        setAudioPosition("Error: " + e);
                    }
                );
            }, 1000);
        }
    }

    // Pause audio
    // 
    function pauseAudio() {
        if (media) {
            media.pause();
        }
    }

    // Stop audio
    // 
    function stopAudio() {
        if (media) {
            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 onload="onLoad()">
    <a href="#" class="btn large" onclick="playAudio();">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

Quick Example

    // Audio player
    //
    var 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 = media.getDuration();
        if (dur > 0) {
            clearInterval(timerDur);
            document.getElementById('audio_duration').innerHTML = (dur/1000) + " sec";
        }
   }, 100);

Full Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap is ready
    //
    function onDeviceReady() {
        playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
    }

    // Audio player
    //
    var media = null;
    var mediaTimer = null;

    // Play audio
    //
    function playAudio(src) {
        // Create Media object from src
        var media = new Media(src, onSuccess, onError);

        // Play audio
        media.play();

        // Update media position every second
        if (mediaTimer == null) {
            mediaTimer = setInterval(function() {
                // get media position
                media.getCurrentPosition(
                    // success callback
                    function(position) {
                        if (position > -1) {
                            setAudioPosition((position/1000) + " sec");
                        }
                    },
                    // error callback
                    function(e) {
                        console.log("Error getting pos=" + e);
                        setAudioPosition("Error: " + e);
                    }
                );
            }, 1000);
        }

        // Get duration
        var counter = 0;
        var timerDur = setInterval(function() {
            counter = counter + 100;
            if (counter > 2000) {
                clearInterval(timerDur);
            }
            var dur = media.getDuration();
            if (dur > 0) {
                clearInterval(timerDur);
                document.getElementById('audio_duration').innerHTML = (dur/1000) + " sec";
            }
       }, 100);
    }

    // Pause audio
    // 
    function pauseAudio() {
        if (media) {
            media.pause();
        }
    }

    // Stop audio
    // 
    function stopAudio() {
        if (media) {
            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 onload="onLoad()">
    <a href="#" class="btn large" onclick="playAudio();">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>
    <p id="audio_duration"></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

Quick Example

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

    // Play audio
    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>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap is ready
    //
    function onDeviceReady() {
        playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
    }

    // Audio player
    //
    var media = null;
    var mediaTimer = null;

    // Play audio
    //
    function playAudio(src) {
        // Create Media object from src
        var media = new Media(src, onSuccess, onError);

        // Play audio
        media.play();

        // Update media position every second
        if (mediaTimer == null) {
            mediaTimer = setInterval(function() {
                // get media position
                media.getCurrentPosition(
                    // success callback
                    function(position) {
                        if (position > -1) {
                            setAudioPosition((position/1000) + " sec");
                        }
                    },
                    // error callback
                    function(e) {
                        console.log("Error getting pos=" + e);
                        setAudioPosition("Error: " + e);
                    }
                );
            }, 1000);
        }
    }

    // Pause audio
    // 
    function pauseAudio() {
        if (media) {
            media.pause();
        }
    }

    // Stop audio
    // 
    function stopAudio() {
        if (media) {
            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 onload="onLoad()">
    <a href="#" class="btn large" onclick="playAudio();">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

Quick Example

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

    // Play audio
    media.play();
}

Full Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap is ready
    //
    function onDeviceReady() {
        playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
    }

    // Audio player
    //
    var media = null;
    var mediaTimer = null;

    // Play audio
    //
    function playAudio(src) {
        // Create Media object from src
        var media = new Media(src, onSuccess, onError);

        // Play audio
        media.play();

        // Update media position every second
        if (mediaTimer == null) {
            mediaTimer = setInterval(function() {
                // get media position
                media.getCurrentPosition(
                    // success callback
                    function(position) {
                        if (position > -1) {
                            setAudioPosition((position/1000) + " sec");
                        }
                    },
                    // error callback
                    function(e) {
                        console.log("Error getting pos=" + e);
                        setAudioPosition("Error: " + e);
                    }
                );
            }, 1000);
        }
    }

    // Pause audio
    // 
    function pauseAudio() {
        if (media) {
            media.pause();
        }
    }

    // Stop audio
    // 
    function stopAudio() {
        if (media) {
            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 onload="onLoad()">
    <a href="#" class="btn large" onclick="playAudio();">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.startRecord

Starts recording an audio file.

media.startRecord();

Description

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

Supported Platforms

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 PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    function onLoad() {
        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);
    }

    // PhoneGap 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 onload="onLoad()">
    <p id="media">Recording audio...</p>
    <p id="audio_position"></p>
  </body>
</html>

iOS Quirks


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

Quick Example

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

    // Play audio
    media.play();

    // Pause after 10 seconds
    setTimeout(function() {
        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>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap is ready
    //
    function onDeviceReady() {
        playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
    }

    // Audio player
    //
    var media = null;
    var mediaTimer = null;

    // Play audio
    //
    function playAudio(src) {
        // Create Media object from src
        var media = new Media(src, onSuccess, onError);

        // Play audio
        media.play();

        // Update media position every second
        if (mediaTimer == null) {
            mediaTimer = setInterval(function() {
                // get media position
                media.getCurrentPosition(
                    // success callback
                    function(position) {
                        if (position > -1) {
                            setAudioPosition((position/1000) + " sec");
                        }
                    },
                    // error callback
                    function(e) {
                        console.log("Error getting pos=" + e);
                        setAudioPosition("Error: " + e);
                    }
                );
            }, 1000);
        }
    }

    // Pause audio
    // 
    function pauseAudio() {
        if (media) {
            media.pause();
        }
    }

    // Stop audio
    // 
    function stopAudio() {
        if (media) {
            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 onload="onLoad()">
    <a href="#" class="btn large" onclick="playAudio();">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

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 PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    function onLoad() {
        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);
    }

    // PhoneGap 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 onload="onLoad()">
    <p id="media">Recording audio...</p>
    <p id="audio_position"></p>
  </body>
</html>

iOS Quirks


MediaError

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

Properties

Constants

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