audioPlayer

来自于：开发者立即使用

initPlayer play pause stop setVolume getVolume setCurrent getCurrent getState getBufferRatio addEventListener removeEventListener clearCache scanAudioLibrary getAttr

论坛示例

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

模块概述

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

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

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

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

配置实例如下：

  1. <preference name="backgroundMode" value="audio"/>

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

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

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

注意：

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

audioPlayer - 图1

模块接口

initPlayer

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

initPlayer({params}, callback(ret))

params

path：

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

cache：

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

callback(ret)

ret：

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

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

play

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

play()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

pause

暂停播放

pause()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stop

停止播放

stop()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setVolume

设置音量

setVolume({params})

params

volume：

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

system：

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

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getVolume

获取音量

getVolume({params},callback(ret))

params

system：

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

callback(ret)

ret：

  • 类型：JSON对象
  • 内部字段：
  1. {
  2.     volume: 0.5       //数字类型；当前音频播放器的音量，取值范围：0-1
  3. }

示例代码

  1. var audioPlayer = api.require('audioPlayer');
  2. audioPlayer.getVolume(function(ret) {
  3.     api.alert({ msg: ret.volume });
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setCurrent

设置播放位置

setCurrent({params})

params

current：

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

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getCurrent

获取当前播放的位置

getCurrent(callback(ret))

callback(ret)

ret：

  • 类型：JSON对象
  • 内部字段：
  1. {
  2.     current: 50       //数字类型；当前播放位置，单位为秒（s）
  3. }

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getState

获取当前播放器的状态

getState(callback(ret))

callback(ret)

ret：

  • 类型：JSON对象
  • 内部字段：
  1. {
  2.     state: 'playing'   //字符串类型；当前播放器的状态，取值范围如下：
  3.                            //playing：正在播放
  4.                            //paused：暂停
  5.                            //idle：闲置
  6.                            //finished：播放完成
  7.                            //buffering：正在缓冲
  8.                            //error：出现错误
  9. }

示例代码

  1. var audioPlayer = api.require('audioPlayer');
  2. audioPlayer.getState(function(ret) {
  3.     api.alert({ msg: ret.state });
  4. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getBufferRatio

获取已缓冲的音频文件占音频文件的百分比

getBufferRatio(callback(ret))

callback(ret)

ret：

  • 类型：JSON对象
  • 内部字段：
  1. {
  2.     ratio: 50       //数字类型；获取的已缓冲的音频文件占音频文件的百分比，取值范围：0-100
  3. }

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

addEventListener

监听事件

addEventListener({params}, callback(ret))

params

name：

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

callback(ret)

ret：

  • 类型：JSON对象
  • 内部字段：
  1. {
  2.     current: 30       //数字类型；当前播放位置，单位为s，仅当 name 为 playing 时有值
  3.     received: 100,     //数字类型；缓冲到本地的数据大小，单位为 byte，仅当 name 为 buffering 时有值 
  4.     expected: 100,     //数字类型；尚未缓冲的数据大小，单位为 byte，仅当 name 为 buffering 时有值 
  5.     speed: 100         //数字类型；缓冲速度大小，单位为 byte，  仅当 name 为 buffering 时有值
  6.     state: 'playing'   //字符串类型；当前播放器的状态，仅当 name 为 state 时有效；取值范围如下：
  7.                            //playing：正在播放
  8.                            //paused：暂停
  9.                            //idle：闲置
  10.                            //finished：播放完成
  11.                            //buffering：正在缓冲
  12.                            //error：出现错误
  13. }

示例代码

  1. var audio = api.require('audioPlayer');
  2. audio.addEventListener({
  3.     name: "state"
  4. }, function(ret) {
  5.     alert(ret.state);
  6. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

removeEventListener

移除指定事件的监听

removeEventListener({params})

params

name：

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

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearCache

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

clearCache()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scanAudioLibrary

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

scanAudioLibrary(callback(ret))

callback(ret)

ret：

  • 类型：JSON对象
  • 内部字段：
  1. {
  2.     audios:[{            //数组类型；获取的音频资源信息组成的数组
  3.        artist: '',       //字符串类型；音频作者
  4.        title: '',        //字符串类型；音频标题
  5.        url: '',          //字符串类型；音频地址
  6.        albumTitle: ''    //字符串类型；音频专辑
  7.        duration:         //数字类型；音频时长；单位：毫秒
  8.     }]
  9. }

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getAttr

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

getAttr({params}, callback(ret))

params

path:

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

callback(ret)

ret:

  • 类型：JSON对象
  • 描述：返回值
  1. {
  2.     duration : 100000   // 数字类型；音频的时长；单位：ms
  3.     length   : 6434734  // 数字类型；文件大小；单位：byte
  4. }

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本