PhoneGap API帮助文档翻译—Media(媒体)
文章源自:http://blog.csdn.net/phonegapcn/article/details/6702883
Media对象提供录制和回放设备上的音频文件的能力。
var media = new Media(src, mediaSuccess, [mediaError]);
参数:
- src:一个包含音频内容的URI。(DOMString类型)
- mediaSuccess:(可选项)当一个Media对象完成当前的播放、录制或停止操作时触发的回调函数。(函数类型)
- mediaError:(可选项)当出现错误时调用的回调函数。(函数类型)
- mediaStatus:(可选项)当状态发生变化的时候调用的回调函数。(函数类型)
方法:
- media.getCurrentPosition:返回一个音频文件的当前位置。
- media.getDuration:返回一个音频文件的总时长。
- media.play:开始或恢复播放音频文件。
- media.pause:暂停播放音频文件。
- media.release:释放底层操作系统的音频资源。
- media.seekTo:在音频文件中移动到相应的位置。
- media.startRecord:开始录制音频文件。
- media.stopRecord:停止录制音频文件。
- media.stop:停止播放音频文件。
另外的只读属性:
- _position:以秒为单位的音频播放位置,播放过程中不会自动更新,通过调用getCurrentPosition进行更新。
- _duration:以秒为单位的媒体时长。
支持的平台:
- Android
- iOS
media.getCurrentPosition:返回返回一个音频文件的当前的位置。
media.getCurrentPosition(mediaSuccess, [mediaError]);
参数:
- mediaSuccess:成功的回调函数,返回当前的位置。
- mediaError:(可选项)如果发生错误时调用的回调函数。
说明:
media.getCurrentPosition是一个异步函数,用户返回一个Media对象所指向的音频文件的当前位置,同时会对Media对象的_position参数进行更新。
支持的平台:
- Android
- iOS
简单的范例:
// 音频播放器 var my_media = new Media(src, onSuccess, onError); // 每秒更新一次媒体播放到的位置 var mediaTimer = setInterval(function() { // 获得媒体位置 my_media.getCurrentPosition( // 获得成功后调用的回调函数 function(position) { if (position > -1) { console.log((position/1000) + " sec"); } }, // 发生错误后调用的回调函数 function(e) { console.log("Error getting pos=" + e); } ); }, 1000);
完整的范例:
<!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="phonegap.js"></script> <script type="text/javascript" charset="utf-8"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // PhoneGap加载完毕 function onDeviceReady() { playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3"); } // 音频播放器 var my_media = null; var mediaTimer = null; // 播放音频 function playAudio(src) { // 从目标文件创建Media对象 my_media = new Media(src, onSuccess, onError); // 播放音频 my_media.play(); // 每秒更新一次媒体播放到的位置 if (mediaTimer == null) { mediaTimer = setInterval(function() { // 获取媒体播放到的位置 my_media.getCurrentPosition( //获取成功后调用的回调函数 function(position) { if (position > -1) { setAudioPosition((position/1000) + " sec"); } }, // 发生错误后调用的回调函数 function(e) { console.log("Error getting pos=" + e); setAudioPosition("Error: " + e); } ); }, 1000); } } // 暂停音频播放 function pauseAudio() { if (my_media) { my_media.pause(); } } // 停止音频播放 function stopAudio() { if (my_media) { my_media.stop(); } clearInterval(mediaTimer); mediaTimer = null; } // 创建Media对象成功后调用的回调函数 function onSuccess() { console.log("playAudio():Audio Success"); } // 创建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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 :返回音频文件的时间长度。
说明:media.getDuration是一个同步函数,如果音频时长已知的话则返回以秒为单位的音频文件时长,如果时长不可知的话则返回-1。
支持的平台:
- Android
- iOS
简单的范例:
// 音频播放器 var my_media = new Media(src, onSuccess, onError); // 获得时间长度 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/1000) + " sec"; } }, 100);
完整的范例:
<!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="phonegap.js"></script> <script type="text/javascript" charset="utf-8"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // PhoneGap加载完毕 function onDeviceReady() { playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3"); } // 音频播放器 var my_media = null; var mediaTimer = null; // 播放音频 function playAudio(src) { // 从目标文件创建Media对象 my_media = new Media(src, onSuccess, onError); // 播放音频 my_media.play(); // 每秒更新一次媒体播放到的位置 if (mediaTimer == null) { mediaTimer = setInterval(function() { // 获取媒体播放到的位置 my_media.getCurrentPosition( // 获取成功后调用的回调函数 function(position) { if (position > -1) { setAudioPosition((position/1000) + " sec"); } }, // 发生错误后调用的回调函数 function(e) { console.log("Error getting pos=" + e); setAudioPosition("Error: " + e); } ); }, 1000); } } // 暂停音频播放 function pauseAudio() { if (my_media) { my_media.pause(); } } // 停止音频播放 function stopAudio() { if (my_media) { my_media.stop(); } clearInterval(mediaTimer); mediaTimer = null; } // 创建Media对象成功后调用的回调函数 function onSuccess() { console.log("playAudio():Audio Success"); } // 创建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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:开始或恢复播放一个音频文件。
说明:media.play是一个用于开始或恢复播放音频文件的同步函数。
支持的平台:
- Android
- iOS
简单的范例:
// 播放音频文件 function playAudio(url) { // 播放url指向的音频文件 var my_media = new Media(url, // 播放成功后调用的回调函数 function() { console.log("playAudio():Audio Success"); }, // 播放出错后调用的回调函数 function(err) { console.log("playAudio():Audio Error: "+err); }); // 播放音频文件 my_media.play(); }
完整的范例:
<!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="phonegap.js"></script> <script type="text/javascript" charset="utf-8"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // PhoneGap加载完毕 function onDeviceReady() { playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3"); } // 音频播放器 var my_media = null; var mediaTimer = null; // 播放音频文件 function playAudio(src) { // 从目标文件创建Media对象 my_media = new Media(src, onSuccess, onError); // 播放音频 my_media.play(); // 每秒更新一次媒体播放到的位置 if (mediaTimer == null) { mediaTimer = setInterval(function() { // 获取媒体播放到的位置 my_media.getCurrentPosition( // 获取成功后调用的回调函数 function(position) { if (position > -1) { setAudioPosition((position/1000) + " sec"); } }, // 发生错误后调用的回调函数 function(e) { console.log("Error getting pos=" + e); setAudioPosition("Error: " + e); } ); }, 1000); } } // 暂停音频播放 function pauseAudio() { if (my_media) { my_media.pause(); } } // 停止音频播放 function stopAudio() { if (my_media) { my_media.stop(); } clearInterval(mediaTimer); mediaTimer = null; } // 创建Media对象成功后调用的回调函数 function onSuccess() { console.log("playAudio():Audio Success"); } // 创建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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:暂停播放一个音频文件。
说明:media.pause是一个用于暂停播放音频文件的同步函数。
支持的平台:
- Android
- iOS
简单的范例:
// 播放音频 function playAudio(url) { // 播放url指向的音频文件 var my_media = new Media(url, // 获取成功后调用的回调函数 function() { console.log("playAudio():Audio Success"); }, // 发生错误后调用的回调函数 function(err) { console.log("playAudio():Audio Error: "+err); } ) // 播放音频 my_media.play(); // 暂停10秒钟 setTimeout(function() { media.pause(); }, 10000); }
完整的范例:
<!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="phonegap.js"></script> <script type="text/javascript" charset="utf-8"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // PhoneGap加载完毕 function onDeviceReady() { playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3"); } // 音频播放器 var my_media = null; var mediaTimer = null; // 播放音频 function playAudio(src) { // 从目标播放文件创建Media对象 my_media = new Media(src, onSuccess, onError); // 播放音频 my_media.play(); // 每秒更新一次媒体播放到的位置 if (mediaTimer == null) { mediaTimer = setInterval(function() { // 获取媒体播放到的位置 my_media.getCurrentPosition( // 获取成功后调用的回调函数 function(position) { if (position > -1) { setAudioPosition((position/1000) + " sec"); } }, // 发生错误后调用的回调函数 function(e) { console.log("Error getting pos=" + e); setAudioPosition("Error: " + e); } ); }, 1000); } } // 暂停音频播放 function pauseAudio() { if (my_media) { my_media.pause(); } } // 停止音频播放 function stopAudio() { if (my_media) { my_media.stop(); } clearInterval(mediaTimer); mediaTimer = null; } // 创建Media对象成功后调用的回调函数 function onSuccess() { console.log("playAudio():Audio Success"); } // 创建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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.release:释放底层操作系统音频资源。
说明:media.release是一个用于释放系统音频资源的同步函数。该函数对于Android系统尤为重要,因为Android系统的OpenCore(多媒体核心)的实例是有限的。开发者需要在他们不再需要相应Media资源时调用“release”函数释放它。
支持的平台:
- Android
- iOS
简单的范例:
// 音频播放器 var my_media = new Media(src, onSuccess, onError); my_media.play(); my_media.stop(); my_media.release();
完整的范例:
<!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="phonegap.js"></script> <script type="text/javascript" charset="utf-8"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // PhoneGap加载完毕 function onDeviceReady() { playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3"); } // 音频播放器 var my_media = null; var mediaTimer = null; // 播放音频 function playAudio(src) { // 从目标播放文件创建Media对象 my_media = new Media(src, onSuccess, onError); // 播放音频 my_media.play(); // 每秒更新一次媒体播放到的位置 if (mediaTimer == null) { mediaTimer = setInterval(function() { // 获取媒体播放到的位置 my_media.getCurrentPosition( // 获取成功后调用的回调函数 function(position) { if (position > -1) { setAudioPosition((position/1000) + " sec"); } }, // 发生错误后调用的回调函数 function(e) { console.log("Error getting pos=" + e); setAudioPosition("Error: " + e); } ); }, 1000); } } // 暂停音频播放 function pauseAudio() { if (my_media) { my_media.pause(); } } // 停止音频播放 function stopAudio() { if (my_media) { my_media.stop(); } clearInterval(mediaTimer); mediaTimer = null; } // 创建Media对象成功后调用的回调函数 function onSuccess() { console.log("playAudio():Audio Success"); } // 创建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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.startRecord
开始录制一个音频文件。
说明:media.startRecord是用于开始录制一个音频文件的同步函数。
支持的平台:
- Android
- iOS
简单的范例:
// 录制音频 function recordAudio() { var src = "myrecording.mp3"; var mediaRec = new Media(src, // 新建Media对象成功后调用的回调函数 function() { console.log("recordAudio():Audio Success"); }, // 新建Media对象出错后调用的回调函数 function(err) { console.log("recordAudio():Audio Error: "+ err.code); } ); // 录制音频 mediaRec.startRecord(); }
完整的范例:
<!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"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // 录制音频 function recordAudio() { var src = "myrecording.mp3"; var mediaRec = new Media(src, onSuccess, onError); // 开始录制音频 mediaRec.startRecord(); // 10秒钟后停止录制 var recTime = 0; var recInterval = setInterval(function() { recTime = recTime + 1; setAudioPosition(recTime + " sec"); if (recTime >= 10) { clearInterval(recInterval); mediaRec.stopRecord(); } }, 1000); } // PhoneGap加载完毕 function onDeviceReady() { recordAudio(); } // 创建Media对象成功后调用的回调函数 function onSuccess() { console.log("recordAudio():Audio Success"); } // 创建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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>
iOS 的特异情况:用于录制的文件必须已经存在并是.wav类型,可以通过File API来进行文件的创建。
media.stop
停止播放一个音频文件。
说明:media.stop函数是一个用于停止播放音频文件的同步函数。
支持的平台:
- Android
- iOS
简单的范例:
// 播放音频 function playAudio(url) { // 播放url指向的音频文件 var my_media = new Media(url, // 新建Media对象成功后调用的回调函数 function() { console.log("playAudio():Audio Success"); }, // 新建Media对象出错后调用的回调函数 function(err) { console.log("playAudio():Audio Error: "+err); } ); // 播放音频 my_media.play(); // 10秒钟后暂停播放 setTimeout(function() { my_media.stop(); }, 10000); }
完整的范例:
<!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="phonegap.js"></script> <script type="text/javascript" charset="utf-8"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // PhoneGap加载完毕 function onDeviceReady() { playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3"); } // 音频播放器 var my_media = null; var mediaTimer = null; // 播放音频 function playAudio(src) { // 从目标播放文件创建Media对象 my_media = new Media(src, onSuccess, onError); // 播放音频 my_media.play(); // 每秒更新一次媒体播放到的位置 if (mediaTimer == null) { mediaTimer = setInterval(function() { // 获取媒体播放到的位置 my_media.getCurrentPosition( // 获取成功后调用的回调函数 function(position) { if (position > -1) { setAudioPosition((position/1000) + " sec"); } }, // 发生错误后调用的回调函数 function(e) { console.log("Error getting pos=" + e); setAudioPosition("Error: " + e); } ); }, 1000); } } // 暂停音频播放 function pauseAudio() { if (my_media) { my_media.pause(); } } // 停止音频播放 function stopAudio() { if (my_media) { my_media.stop(); } clearInterval(mediaTimer); mediaTimer = null; } // 创建Media对象成功后调用的回调函数 function onSuccess() { console.log("playAudio():Audio Success"); } // 创建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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:停止录制一个音频文件。
说明:media.stopRecord是用于停止录制一个音频文件的同步函数。
支持的平台:
- Android
- iOS
简单的范例:
// 录制音频 function recordAudio() { var src = "myrecording.mp3"; var mediaRec = new Media(src, // 新建Media对象成功后调用的回调函数 function() { console.log("recordAudio():Audio Success"); }, // 新建Media对象出错后调用的回调函数 function(err) { console.log("recordAudio():Audio Error: "+ err.code); } ); // 开始录制音频 mediaRec.startRecord(); // 10秒后停止录制 setTimeout(function() { mediaRec.stopRecord(); }, 10000); }
完整的范例:
<!DOCTYPE html> <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"> // 等待加载PhoneGap document.addEventListener("deviceready", onDeviceReady, false); // 录制音频 function recordAudio() { var src = "myrecording.mp3"; var mediaRec = new Media(src, onSuccess, onError); // 开始录制音频 mediaRec.startRecord(); // 10秒后停止录制 var recTime = 0; var recInterval = setInterval(function() { recTime = recTime + 1; setAudioPosition(recTime + " sec"); if (recTime >= 10) { clearInterval(recInterval); mediaRec.stopRecord(); } }, 1000); } // PhoneGap加载完毕 function onDeviceReady() { recordAudio(); } // 新建Media对象成功后调用的回调函数 function onSuccess() { console.log("recordAudio():Audio Success"); } // 新建Media对象出错后调用的回调函数 function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // 设置音频播放位置 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>
MediaError
属性:
- code:一个在下面常量列表中定义的错误代码。
- message:用于描述错误细节的错误信息。
常量:
- MediaError.MEDIA_ERR_ABORTED:媒体中断错误
- MediaError.MEDIA_ERR_NETWORK:网络错误
- MediaError.MEDIA_ERR_DECODE:编码错误
- MediaError.MEDIA_ERR_NONE_SUPPORTED:格式不支持
说明:当发生错误时,一个MediaError对象将通过mediaError回调函数传递给用户。