# [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 : 无