# [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 : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS