audioPlayer

• Method

play stop getVolume getCurrent getBufferRatio removeEventListener scanAudioLibrary

论坛示例

为帮助用户更好更快的使用模块，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。

模块概述

audioPlayer 是一个音频播放器，使用本模块可实现对音频文件的播放、暂停、停止、跳转、设置音量大小、获取当前播放位置等各种功能。支持对本地、网络音频资源的播放。当播放网络音频时模块会把网络音频资源缓存到本地，并将缓存到本地的音频绝对路径返回给开发者。开发者可以通过 clearCache 接口，手动清除缓存在本地的音频资源，也可以通过 模块的相关接口对单个缓存在本地的音频进行移动、删除等操作。开发者调用 api.clearCache 接口时也会清除所有本模块已缓存的音频文件。

对于缓冲音频文件的进度，开发者可通过 addEventListener 接口监听，也可通过 getBufferPercent 接口获取缓冲进度的百分比。当开发者调用 initPlayer 接口时模块底层会初始化一个播放器的实例对象，并判断是否是需要加载缓冲的资源（网络资源、在iOS上的音乐库资源），若是则进一步判断此音频资源是否已缓存到本地，若已缓存（未缓冲完整也按已缓存处理）则直接播，若未缓存则开始缓冲。

本模块可通过 scanAudioLibrary 接口扫描本地音频资源库 （在 iOS 上仅扫描系统音乐库），获取其标题、歌手、专辑、路径等信息。在 iOS 平台上，存在三种音频资源：1，网络音频；2，APP 沙箱（每个 APP 在系统内相当于一个文件夹，APP 只能访问本文件夹内的文件）内的音频；3，音乐库（系统音乐 APP，可通过 iTunes 同步的音频库）音频；本模块播放第三种音频资源时也会把音频文件缓存到 当前 APP 的沙箱内。

如需支持后台播放功能请参考 config.xml 配置说明文档里关于 BackgroundMode 的配置

配置实例如下：

在 iOS 平台上，当音频在后台播放时，若启动其它播放音频的 APP，则后台播放事件会被挂起。当有电话呼入、呼出或其它占用喇叭的事件发生时，也会打断后台播放音频。被打断播放的事件可通过 addEventListener 接口监听。

本模块 iOS 平台上支持的音频格式有：mp3、mp2、mp1、caf、aif、wav、aac、mp4、3gp；

android 平台上支持的音频格式有：mp3、3gp、ogg、wav

注意：

由于 iOS 系统限制，在 iOS 平台上不支持后台切换播放网络音频资源。

模块接口

initPlayer

初始化音频播放器，并播放。若是网络音频资源则同时开始缓冲音频文件到本地

initPlayer({params}, callback(ret))

path：

• 类型：字符串
• 描述：音频资源地址，支持本地和网络路径（fs://、widget://、 等）

cache：

• 类型：布尔
• 描述：是否支持缓存网络资源

callback(ret)

ret：

• 类型：JSON对象
• 内部字段：

    status: true,        //布尔类型；操作成功状态值，true|false
    duration: 289,       //数字类型；音频总时长，单位为s（当status为true时有值）
    path: ''                //字符串类型；所播放的音频资源在本地的绝对路径，仅当 cache 为 true 时有值
}

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.initPlayer({
    path: 'http://7xisq1.com1.z0.glb.clouddn.com/apicloud/0d0b81b8bd5ab81bda9ca54267eb9b98.mp3',
    cache: false
}, function(ret) {
    if (ret.status) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

play

播放音频，只有当前播放器为暂停、播放完成状态时有效

play()

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.play();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

pause

暂停播放

pause()

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.pause();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stop

停止播放

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.stop();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setVolume

设置音量

setVolume({params})

params

volume：

• 类型：数字
• 描述：（可选项）音量大小（0-1）
• 默认值：0

system：

• 类型：布尔
• 描述：（可选项）是否设置系统音量，若为false表示设置播放器音量，仅支持iOS端
• 默认值：false

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.setVolume({
    volume: 0.6
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getVolume

获取音量

getVolume({params},callback(ret))

params

system：

• 类型：布尔
• 描述：（可选项）是否获取系统音量，若为false表示获取播放器音量，仅支持iOS端
• 默认值：false

callback(ret)

ret：

• 类型：JSON对象
• 内部字段：

{
    volume: 0.5       //数字类型；当前音频播放器的音量，取值范围：0-1
}

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setCurrent

设置播放位置

setCurrent({params})

params

current：

• 类型：数字
• 描述：（可选项）播放位置，取值范围大于 0 不超过当前播放音频的总时长，单位为秒（s）
• 默认值：0

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.setCurrent({
    current: 10
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getCurrent

获取当前播放的位置

getCurrent(callback(ret))

callback(ret)

ret：

• 类型：JSON对象
• 内部字段：

    current: 50       //数字类型；当前播放位置，单位为秒（s）
}

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.getCurrent(function(ret) {
    api.alert({ msg: ret.current });
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getState

获取当前播放器的状态

getState(callback(ret))

callback(ret)

ret：

• 类型：JSON对象
• 内部字段：

{
    state: 'playing'   //字符串类型；当前播放器的状态，取值范围如下：
                           //playing：正在播放
                           //paused：暂停
                           //idle：闲置
                           //finished：播放完成
                           //buffering：正在缓冲
                           //error：出现错误
}

示例代码

var audioPlayer = api.require('audioPlayer');
    api.alert({ msg: ret.state });
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getBufferRatio

getBufferRatio(callback(ret))

callback(ret)

ret：

• 类型：JSON对象
• 内部字段：

{
    ratio: 50       //数字类型；获取的已缓冲的音频文件占音频文件的百分比，取值范围：0-100
}

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.getBufferRatio(function(ret) {
    api.alert({ msg: ret.ratio });
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addEventListener

监听事件

addEventListener({params}, callback(ret))

params

name：

• 类型：字符串
• 描述：（可选项）监听的事件类型
• 默认：playing
• 取值范围：
  • playing：播放进度，每有播放进度改变事件则触发此回调（频率为每秒3次）
  • buffering：网络音频缓冲事件，每有缓冲进度变化时触发此回调（频率为每秒3次）
  • state：播放器状态改变事件

ret：

• 类型：JSON对象
• 内部字段：

示例代码

var audio = api.require('audioPlayer');
audio.addEventListener({
    name: "state"
}, function(ret) {
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

removeEventListener

移除指定事件的监听

removeEventListener({params})

params

name：

• 类型：字符串
• 描述：（可选项）要移除的监听事件类型
• 默认：playing
• 取值范围：
  • playing：播放进度，每有播放进度改变事件则触发此的回调
  • buffering：网络音频缓冲事件，每有缓冲进度变化时触发的回调
  • state：播放器状态改变事件

示例代码

var audio = api.require('audioPlayer');
audio.removeEventListener({
    name: "state"
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearCache

清除缓存到本地的音频文件，本接口只清除本模块缓存的数据，若要清除本 app 缓存的所有数据则调用api.clearCache

clearCache()

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.clearCache();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scanAudioLibrary

扫描本地音频资源，在 iOS 上仅扫描系统音乐库资源

scanAudioLibrary(callback(ret))

callback(ret)

ret：

• 类型：JSON对象
• 内部字段：

{
    audios:[{            //数组类型；获取的音频资源信息组成的数组
       artist: '',       //字符串类型；音频作者
       title: '',        //字符串类型；音频标题
       url: '',          //字符串类型；音频地址
       albumTitle: ''    //字符串类型；音频专辑
       duration:         //数字类型；音频时长；单位：毫秒
    }]
}

示例代码

var audioPlayer = api.require('audioPlayer');
audioPlayer.scanAudioLibrary(function(ret) {
    api.alert({ msg: JSON.stringify(ret) });
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getAttr

获取本地音频文件属性（文件大小和音频时长）

getAttr({params}, callback(ret))

params

path:

• 类型：字符串类型
• 描述：音频的路径 （仅支持 fs://）

callback(ret)

ret:

• 类型：JSON对象
• 描述：返回值

{
    duration : 100000   // 数字类型；音频的时长；单位：ms
    length   : 6434734  // 数字类型；文件大小；单位：byte
}

示例代码

var audioRecorder = api.require('audioPlayer');
audioRecorder.getAttr({
          path: 'fs://recorder/123.mp3'
}, function(ret) {
          alert(JSON.stringify(ret));
});

可用性

iOS系统，Android系统