Audio · Html5+參考

# [audio]() Audio模塊用于提供音頻的錄制和播放功能，可調用系統的麥克風設備進行錄音操作，也可調用系統的揚聲器設備播放音頻文件。通過plus.audio獲取音頻管理對象。 ### 常量： - [ROUTE_SPEAKER](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.ROUTE_SPEAKER): 設備的揚聲器音頻輸出線路 - [ROUTE_EARPIECE](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.ROUTE_EARPIECE): 設備聽筒音頻輸出線路 ### 方法： - [getRecorder](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.getRecorder): 獲取當前設備的錄音對象 - [createPlayer](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.createPlayer): 創建音頻播放對象 ### 對象： - [AudioRecorder](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioRecorder): 錄音對象 - [AudioPlayer](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer): 音頻播放對象 - [RecordOption](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.RecordOption): JSON對象，調用麥克風設備進行錄音的參數 ### 回調方法： - [RecordSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.RecordSuccessCallback): 錄音操作成功回調 - [PlaySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.PlaySuccessCallback): 播放音頻文件操作成功回調 - [AudioErrorCallback](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioErrorCallback): 音頻操作失敗回調 ### 權限： permissions ~~~ "Audio": { "description": "訪問音頻設備" } ~~~ # [ROUTE_SPEAKER]() 設備的揚聲器音頻輸出線路 ~~~ plus.audio.ROUTE_SPEAKER; ~~~ ### 說明： Number 類型音頻輸出線路常量，值為0。音頻播放時在設備的揚聲器輸出。 # [ROUTE_EARPIECE]() 設備聽筒音頻輸出線路 ~~~ plus.audio.ROUTE_EARPIECE; ~~~ ### 說明： Number 類型音頻輸出線路常量，值為1。音頻播放時在設備的聽筒輸出。 # [getRecorder]() 獲取當前設備的錄音對象 ~~~ AudioRecorder plus.audio.getRecorder(); ~~~ ### 說明：獲取當前設備的錄音對象，進行錄音操作，錄音對象是設備的獨占資源，在同一時間僅可執行一個錄音操作，否則可能會導致操作失敗。 ### 參數： ### 返回值： [AudioRecorder](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioRecorder) : 錄音對象 ### 平臺支持： - Android - 2.2+ (支持): 支持錄制"amr"、"3gp"等格式文件。 - iOS - 4.3+ (支持): 支持錄制"wav"、"aac"、"amr"等格式文件。 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Audio Example</title> <script type="text/javascript"> // 擴展API加載完畢后調用onPlusReady回調函數 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 擴展API加載完畢，現在可以正常調用擴展API function onPlusReady() { r = plus.audio.getRecorder(); } function startRecord() { if ( r == null ) { alert( "Device not ready!" ); return; } r.record( {filename:"_doc/audio/"}, function () { alert( "Audio record success!" ); }, function ( e ) { alert( "Audio record failed: " + e.message ); } ); } function stopRecord() { r.stop(); } </script> </head> <body> <input type="button" value="Start Record" onclick="startRecord();"/> <br/> <input type="button" value="Stop Record" onclick="stopRecord();"/> </body> </html> ~~~ # [createPlayer]() 創建音頻播放對象 ~~~ AudioPlayer plus.audio.createPlayer( path ); ~~~ ### 說明：創建一個音頻文件播放對象，用于打開音頻文件并播放。可通過path參數指定要播放的音頻文件。創建后返回播放對象，通過Audio.play方法開始播放。 ### 參數： - path: *( String ) 必選 *音頻文件路徑要播放的音頻文件的路徑，僅支持本地路徑，不支持網絡路徑。 ### 返回值： [AudioPlayer](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer) : 音頻播放對象 ### 平臺支持： - Android - 2.2+ (支持): 支持aac、3gp、amr、mp3、mp4、mid、ogg、wav等格式文件。 - iOS - 4.3+ (支持): 支持aac、aiff、mp3、mid、wav、amr等格式文件。 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Audio Example</title> <script type="text/javascript"> // 擴展API加載完畢后調用onPlusReady回調函數 document.addEventListener( "plusready", onPlusReady, false ); // 擴展API加載完畢，現在可以正常調用擴展API function onPlusReady() { } var p = null; function startPlay() { if ( plus.audio == undefined ) { alert( "Device not ready!" ); } p = plus.audio.createPlayer( "_Doc/Audio/test.mp3" ); p.play( function () { alert( "Audio play success!" ); }, function ( e ) { alert( "Audio play error: " + e.message ); } ); } function stopPlay() { p.stop(); } </script> </head> <body> <input type="button" value="Start Play" onclick="startPlay();"/> <br/> <input type="button" value="Stop Play" onclick="stopPlay();"/> </body> </html> ~~~ # [AudioRecorder]() 錄音對象 ~~~ interface AudioRecorder { readonly attribute DOMString[] supportedSamplerates; readonly attribute DOMString[] supportedFormats; function record( option, successCB, errorCB ); function stop(); } ~~~ ### 屬性： - [supportedSamplerates](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioRecorder.supportedSamplerates): 數組，設備錄音支持的采用率 - [supportedFormats](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioRecorder.supportedFormats): 數組，設備錄音支持的文件格式 ### 方法： - [record](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioRecorder.record): 調用設備麥克風進行錄音操作 - [stop](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioRecorder.stop): 結束錄音操作 # [supportedSamplerates]() 數組，設備錄音支持的采用率 ### 說明： DOMString 類型只讀屬性屬性類型為Array(DOMString)，若不支持此屬性則返回空數組對象。支持的錄音采樣率，字符串格式為“采樣頻率”，如“8000”；其單位為Hz。 # [supportedFormats]() 數組，設備錄音支持的文件格式 ### 說明： DOMString 類型只讀屬性屬性類型為Array(DOMString)，若不支持此屬性則返回空數組對象。支持的錄音文件的格式，字符串格式為文件格式后綴名，如"amr"、"mp3"、"aac"、"wav"等。 ### 平臺支持： - Android - 2.2+ (支持): Android平臺支持"amr"、"3gp"格式，默認為"amr"。 - iOS - 4.5+ (支持): iOS平臺支持"aac"、"wav"格式，默認為"wav"。 # [record]() 調用設備麥克風進行錄音操作 ~~~ void recorder.record( option, successCB, errorCB ); ~~~ ### 說明：調用設備麥克風開始錄音操作，錄音完成需調用stop方法停止。錄音完成后將通過successCB回調返回錄音后的文件數據。 ### 參數： - option: *( [RecordOption](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.RecordOption) ) 必選 *設置錄音的參數 - successCB: *( [RecordSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.RecordSuccessCallback) ) 必選 *錄音操作成功回調函數 - errorCB: *( [AudioErrorCallback](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioErrorCallback) ) 可選 *錄音操作錯誤回調函數 ### 返回值： void : 無 ### 示例： ~~~ // 錄音操作 var r = plus.audio.getRecorder(); r.record( {filename:"_doc/audio/"}, function () { alert( "Audio record success!" ); }, function ( e ) { alert( "Audio record failed: " + e.message ); } ); ~~~ # [stop]() 結束錄音操作 ~~~ void recorder.stop(); ~~~ ### 說明：結束錄音操作，通知設備完成錄音操作。錄音完成后將調用record方法中傳入的successCB回調返回錄音文件。 ### 參數：無 ### 返回值： void : 無 ### 示例： ~~~ // 錄音操作 var r = plus.audio.getRecorder(); r.record( {filename:"_doc/audio/"}, function () { alert( "Audio record success!" ); }, function ( e ) { alert( "Audio record failed: " + e.message ); } ); // ...... // 停止錄音 r.stop(); ~~~ # [AudioPlayer]() 音頻播放對象 ~~~ interface AudioPlayer { function void play( successCB, errorCB ); function void pause(); function void resume(); function void stop(); function void seekTo( position ); function Number getDuration(); function Number getPosition(); function void setRoute( route ); } ~~~ ### 說明：音頻播放對象，用于音頻文件的播放。不能通過new方法直接創建，只能通過audio.createPlayer方法創建。 ### 方法： - [play](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.play): 開始播放音頻 - [pause](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.pause): 暫停播放音頻 - [resume](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.resume): 恢復播放音頻 - [stop](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.stop): 停止播放音頻 - [seekTo](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.seekTo): 跳到指定位置播放音頻 - [getDuration](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.getDuration): 獲取音頻流的總長度 - [getPosition](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.getPosition): 獲取音頻流當前播放的位置 - [setRoute](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioPlayer.setRoute): 設置音頻輸出線路 # [play]() 開始播放音頻 ~~~ void player.play( successCB, errorCB ); ~~~ ### 參數： - successCB: *( [PlaySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.PlaySuccessCallback) ) 必選 *播放音頻操作成功回調函數當音頻文件播放完成時回調。 - errorCB: *( [AudioErrorCallback](http://www.dcloud.io/docs/api/zh_cn/audio.shtml#plus.audio.AudioErrorCallback) ) 可選 *播放音頻操作錯誤回調函數當音頻文件播放發生錯誤時回調。 ### 返回值： void : 無 ### 示例： ~~~ // 播放操作 var p = plus.audio.createPlayer(); p.play( function () { alert( "Audio play success!" ); }, function ( e ) { alert( "Audio play failed: " + e.message ); } ); ~~~ # [pause]() 暫停播放音頻 ~~~ void player.pause(); ~~~ ### 說明：需先調用createPlayer方法創建音頻播放對象，并開始播放。音頻播放對象在播放狀態才能暫停，在其它狀態調用此方法無任何作用。 ### 參數： ### 返回值： void : 無 ### 示例： ~~~ // 播放操作 var p = plus.audio.createPlayer(); p.play( function () { alert( "Audio play success!" ); }, function ( e ) { alert( "Audio play failed: " + e.message ); } ); // ...... // 暫停播放 p.pause(); ~~~ # [resume]() 恢復播放音頻 ~~~ void player.resume(); ~~~ ### 說明：音頻播放對象在暫停狀態才能恢復播放，在其它狀態調用此方法無任何作用。 ### 參數： ### 返回值： void : 無 ### 示例： ~~~ // 播放操作 var p = plus.audio.createPlayer(); p.play( function () { alert( "Audio play success!" ); }, function ( e ) { alert( "Audio play failed: " + e.message ); } ); // ...... // 暫停播放 p.pause(); // ...... // 恢復播放 p.resume(); ~~~ # [stop]() 停止播放音頻 ~~~ void player.stop(); ~~~ ### 說明：停止播放音頻，音頻播放對象在播放或暫停狀態才能停止播放，在其它狀態調用此方法無任何作用。停止播放后如果需要繼續播放，則需調用play方法重新開始播放。 ### 參數： ### 返回值： void : 無 ### 示例： ~~~ // 播放操作 var p = plus.audio.createPlayer(); p.play( function () { alert( "Audio play success!" ); }, function ( e ) { alert( "Audio play failed: " + e.message ); } ); // ...... // 停止播放 p.stop(); ~~~ # [seekTo]() 跳到指定位置播放音頻 ~~~ void player.seekTo( position ); ~~~ ### 說明：跳到指定位置播放音頻，音頻播放對象在播放或暫停狀態才能跳到指定播放音頻，在其它狀態調用此方法無任何作用。 ### 參數： - position: *( Number ) 必選 *音頻播放要跳到的位置，單位為s ### 返回值： void : 無 # [getDuration]() 獲取音頻流的總長度 ~~~ Number player.getDuration(); ~~~ ### 說明：獲取音頻流的總長度，單位為秒，若長度未知則返回-1。如果還未獲取到音頻流信息則返回NaN，此時需要延遲獲取此信息。 ### 參數： ### 返回值： Number : 音頻流的總長度 # [getPosition]() 獲取音頻流當前播放的位置 ~~~ Number player.getPosition(); ~~~ ### 說明：獲取音頻流當前播放的位置（已播放的長度），單位為s。 ### 參數： ### 返回值： Number : 當前音頻播放的位置，單位為s，如果音頻文件未準備好則返回0。 # [setRoute]() 設置音頻輸出線路 ~~~ void player.setRoute( route ); ~~~ ### 說明：可在音頻文件開始播放前或播放的過程中改變音頻輸出線路，默認使用揚聲器（plus.audio.ROUTE_SPEAKER）輸出線路。 ### 參數： - route: *( Number ) 必選 *音頻播放時輸出線路常量可設置audio的ROUTE_*常量值，設置后立即生效。 ### 返回值： void : 無 ### 示例： ~~~ // 播放操作 var p = plus.audio.createPlayer(); // 切換到聽筒線路 p.setRoute( plus.audio.ROUTE_EARPIECE ); p.play( function () { alert( "Audio play success!" ); }, function ( e ) { alert( "Audio play failed: " + e.message ); } ); //... // 切換到揚聲器線路 p.setRoute( plus.audio.ROUTE_SPEAKER ); ~~~ # [RecordOption]() JSON對象，調用麥克風設備進行錄音的參數 ### 屬性： - filename: *(DOMString 類型)*保存錄音文件的路徑可設置具體文件名，也可只設置路徑，如果以“/”結尾則表明是路徑，文件名由錄音程序自動生成。如未設置則使用默認目錄生成隨機文件名稱，默認目錄為應用%APPID%下的documents目錄。 - samplerate: *(DOMString 類型)*錄音文件的采樣率需通過supportedSamplerates屬性獲取設備支持的采樣率，若設置無效的值，則使用系統默認的采樣率。 - format: *(DOMString 類型)*錄音文件的格式需通過supportedFormats屬性獲取設備支持的錄音格式，若設置無效的值，則使用系統默認的錄音格式。 ### 平臺支持 - Android - 2.2+ (支持): Android平臺支持"amr"、"3gp"格式，默認為"amr"。 - iOS - 4.5+ (支持): iOS平臺支持"wav"、"aac"、"amr"格式，默認為"wav"。 # [RecordSuccessCallback]() 錄音操作成功回調 ~~~ void onSuccess( recordFile ) { // Get record file code. } ~~~ ### 說明：麥克風錄音操作成功的回調函數，在錄音操作完成調用stop()方法時調用。 ### 參數： - recordFile: *( DOMString ) 必選 *錄音操作保存的音頻文件路徑 ### 返回值： void : 無 # [PlaySuccessCallback]() 播放音頻文件操作成功回調 ~~~ void onCompleted() { // Play audio file completed code. } ~~~ ### 說明：麥克風錄音操作成功的回調函數，在錄音操作完成調用stop()方法時調用。 ### 參數： ### 返回值： void : 無 # [AudioErrorCallback]() 音頻操作失敗回調 ~~~ void onError( error ) { // Handle audio error } ~~~ ### 參數： - error: *( DOMException ) 必選 *音頻操作的錯誤信息 ### 返回值： void : 無