audioPlayer

来自于:开发者

模块概述

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

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

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

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

配置实例如下:

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

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

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

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

注意:

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

模块接口

initPlayer

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

initPlayer({params}, callback(ret))

params

path:

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

cache:

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

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

停止播放

stop()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

setVolume

设置音量

setVolume({params})

params

volume:

  • 类型:数字
  • 描述:(可选项)音量大小(0-1)
  • 默认值:0

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getVolume

获取音量

getVolume(callback(ret))

callback(ret)

ret:

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

示例代码

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

可用性

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');
audioPlayer.getState(function(ret) {
    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:播放器状态改变事件

callback(ret)

ret:

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

示例代码

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

可用性

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: ''    //字符串类型;音频专辑
    }]
}

示例代码

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系统

可提供的1.0.0及更高版本