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
- src: A URI containing the audio content. (DOMString)
- mediaSuccess: (Optional) The callback that is invoked after a Media object is created. (Function)
- mediaError: (Optional) The callback that is invoked if there was an error. (Function)
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.startRecord: Start recording audio file.
- media.stopRecord: Stop recording audio file.
- media.stop: Stop playing audio file.
Supported Platforms
- Android
- iOS
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.
- 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.
Supported Platforms
- Android
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
- Android
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
- Android
- iOS
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
- Android
- iOS
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
- Android
- iOS
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
- The method name is
startAudioRecord
on iOS.
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
- iOS
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
- Android
- iOS
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
- The method name is
stopAudioRecord
on iOS.
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
)