# audio

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

## 常量：

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

## 方法：

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

## 对象：

- AudioRecorder: 录音对象
- AudioPlayer: 音频播放对象
- AudioPlayerEvent: 音频播放控件事件类型
- AudioPlayerStyles: 音频播放对象的参数
- AudioRecorderStyles: 音频录制的参数

## 回调方法：

- 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 close();
        function Boolean isPaused();
    	function void play(successCB, errorCB);
    	function void pause();
    	function void resume();
    	function void stop();
    	function void seekTo(position);
    	function Number getBuffered();
    	function Number getDuration();
    	function Number getPosition();
    	function void setRoute(route);
    	function void setSessionCategory(category);
    }

## 说明：

音频播放对象，用于音频文件的播放。不能通过new方法直接创建，只能通过audio.createPlayer方法创建。

## 方法：

- addEventListener: 添加事件监听器
- close: 关闭音频播放对象
- getBuffered: 音频缓冲的时间点
- getDuration: 获取音频的总长度
- getPosition: 获取音频的当前播放位置
- getStyles: 音频播放的参数
- isPaused: 当前是否暂停或停止状态
- play: 播放音频
- pause: 暂停播放
- removeEventListener: 移除事件监听器
- resume: 恢复播放
- seekTo: 跳到指定位置
- stop: 停止播放
- setRoute: 音频输出线路
- setSessionCategory: 设置音频播放模式
- setStyles: 设置音频播放的参数

# AudioPlayerEvent

音频播放控件事件类型

## 常量：

- "canplay": (String 类型 )音频可以播放事件
- "play": (String 类型 )音频播放事件
- "pause": (String 类型 )音频暂停事件
- "stop": (String 类型 )音频停止事件
- "ended": (String 类型 )音频自然播放结束事件
- "error": (String 类型 )音频播放错误事件
- "waiting": (String 类型 )音频加载中事件
- "seeking": (String 类型 )音频进行seek操作事件
- "seeked": (String 类型 )音频完成seek操作事件
- "prev": (String 类型 )上一曲操作事件

  用户在后台播放控制器上点击上一曲按钮时触发，未开启后台控制器则不触发此事件。

- "next": (String 类型 )下一曲操作事件

  用户在后台播放控制器上点击下一曲按钮时触发，未开启后台控制器则不触发此事件。

# AudioPlayerStyles

音频播放对象的参数

## 属性：

- autoplay: (Boolean 类型 )是否自动开始播放

  true - 自动开始播放； false - 不自动开始播放。 默认值为false。

- backgroundControl: (Boolean 类型 )是否开启后台控制器

  开启后应用切换到后台可继续播放音频。 iOS平台在系统锁屏界面显示播放控件；Android平台暂不支持。

- coverImgUrl: (String 类型 )封面图地址

  在后台播放控制器上显示，未开启后台控制器则不显示。

- epname: (String 类型 )专辑名

  在后台播放控制器上显示，未开启后台控制器则不显示。

- loop: (Boolean 类型 )是否循环播放

  true - 循环播放； false - 不循环播放。 默认值为false。

- singer: (String 类型 )歌手名

  在后台播放控制器上显示，未开启后台控制器则不显示。

- src: (String 类型 )音频资源的地址

  支持本地路径和网络路径。

- startTime: (Number 类型 )开始播放的位置

  单位为秒（s），默认值为0。

- title: (String 类型 )音频标题

  在后台播放控制器上显示，未开启后台控制器则不显示。

- volume: (Number 类型 )音量

  取值范围为0-1，默认值为1。

# AudioRecorderStyles

音频录制的参数

## 属性：

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