# audio

Audio模块用于提供音频的录制和播放功能，可调用系统的麦克风设备进行录音操作，也可调用系统的扬声器设备播放音频文件。通过plus.audio获取音频管理对象。

## 常量：

- ROUTE_SPEAKER: 设备的扬声器音频输出线路
- ROUTE_EARPIECE: 设备听筒音频输出线路

## 方法：

- getRecorder: 获取当前设备的录音对象
- createPlayer: 创建音频播放对象

## 对象：

- AudioRecorder: 录音对象
- AudioPlayer: 音频播放对象
- RecordOptions: JSON对象，调用麦克风设备进行录音的参数

## 回调方法：

- RecordSuccessCallback: 录音操作成功回调
- PlaySuccessCallback: 播放音频文件操作成功回调
- AudioErrorCallback: 音频操作失败回调

## 权限：

5+功能模块（permissions）

    {
    // ...
    "permissions":{
    	// ...
    	"Audio": {
    		"description": "音频"
    	}
    }
    }

# AudioRecorder

录音对象

    interface AudioRecorder {
    	readonly attribute String[] supportedSamplerates;
    	readonly attribute String[] supportedFormats;
    	function record( option, successCB, errorCB );
    	function stop();
    }

## 属性：

- supportedSamplerates: 数组，设备录音支持的采用率
- supportedFormats: 数组，设备录音支持的文件格式

## 方法：

- record: 调用设备麦克风进行录音操作
- 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: 开始播放音频
- pause: 暂停播放音频
- resume: 恢复播放音频
- stop: 停止播放音频
- seekTo: 跳到指定位置播放音频
- getDuration: 获取音频流的总长度
- getPosition: 获取音频流当前播放的位置
- setRoute: 设置音频输出线路

# RecordOptions

JSON对象，调用麦克风设备进行录音的参数

## 属性：

- channels: (String 类型 )录音声道

  可取值： "mono" - 单声道录音； "stereo" - 立体声道录音。 默认值为"mono"。

- filename: (String 类型 )保存录音文件的路径

  可设置具体文件名，也可只设置路径，如果以“/”结尾则表明是路径，文件名由录音程序自动生成。 如未设置则使用默认目录生成随机文件名称，默认目录为应用%APPID%下的documents目录。

- samplerate: (String 类型 )录音文件的采样率

  需通过supportedSamplerates属性获取设备支持的采样率，若设置无效的值，则使用系统默认的采样率。

- format: (String 类型 )录音文件的格式

  需通过supportedFormats属性获取设备支持的录音格式，若设置无效的值，则使用系统默认的录音格式。

# RecordSuccessCallback

录音操作成功回调

    void onSuccess( recordFile ) {
    	// Get record file code.
    }

## 说明：

麦克风录音操作成功的回调函数，在录音操作完成调用stop()方法时调用。

## 参数：

- recordFile: ( String ) 必选 录音操作保存的音频文件路径

## 返回值：

void : 无

# PlaySuccessCallback

播放音频文件操作成功回调

    void onCompleted() {
    	// Play audio file completed code.
    }

## 说明：

音频播放操作成功的回调函数，在音频播放完成或调用stop()方法时触发。

## 参数：

无

## 返回值：

void : 无

# AudioErrorCallback

音频操作失败回调

    void onError( error ) {
    	// Handle audio error
    }

## 参数：

- error: ( DOMException ) 必选 音频操作的错误信息

## 返回值：

void : 无