音频播放器管理器

导入模块

import audiokit from '@system.audiokit'

接口定义

方法

查询系统中可用的音频播放器 AudioPlayer 对象列表。

方法

查询系统中处于活跃状态的音频播放器 AudioPlayer 对象。

方法

监听系统中音频播放器的变化。callback 的参数 PlayerEvent 为通知事件，此方法返回的 ID 可使用 unsubscribe() 方法来解除监听。

PlayerEvent 的类型签名：

type PlayerEvent = {
  notify: string; // 变化事件类型
  player: string; // 变化播放器名字
}

变化事件类型

• active：系统当前活跃的播放器发生改变
• append：系统中添加了播放器
• remove：系统中移除了播放器

方法

取消播放器变化监听，subscribeID 是 subscribe() 方法返回的 ID 值。

AudioPlayer 对象

类型签名

interface AudioPlayer {
  src: string,
  name: string,
  icon: string,
  mode: string,
  status: string,
  duration: number,
  position: number,
  songAttribute: object,
  volume: number,

  play(): void,
  pause(): void,
  stop(): void,
  release(): void,
  next(): void,
  previous(): void,  

  onplay?: () => void,
  onpause?: () => void,
  onstop?: () => void,
  oninterrupt?: (action: {interruptHint: number}) => void,
  ontimeupdate?: () => void,
  onerror?: (err: {msg: string})=> void,
  onended?: () => void,
  onnext?: () => void,
  onprevious?: () => void,
  onsongattribute?: () => void,
  onmodechanged?: () => void,
}

• AudioPlayer 对象（以下简称：audiokit.Player）与 system.media 模块中创建的 AudioPlayer 对象（以下简称：media.Player），为不同的js对象，但是它们管理同一个播放器，同时 audiokit.Player 对象较 media.Player 对象多一些功能，例如：next()、previous() 等方法，用户通过 audiokit.Player 对象执行的 play() 等操作，也会通知给 media.Player 对象的监听。

读取 • 设置

设置或读取需要播放音频的 url。支持本地资源路径与使用http、https协议的网络资源路径（例如：https://www.rt-thread.com/service/test/001.mp3）。下面是一个设置 src 然后开始播放的简单示例：

import audiokit from '@system.audiokit'
// 查询系统中处于活跃状态的音频播放器
let player = audiokit.getActivePlayer()
if (player != null) {
  // 首先停止当前正在播放的音频
  player.stop()
  // 设置需要播放的音频url
  player.src = 'https://www.rt-thread.com/service/test/001.mp3'
  // 开始播放音频
  player.play()
}

读取 • 设置

播放器对象的名字，如果不设置，默认为创建播放器的应用名。需要注意的是，播放器对象的名字并不是全局不唯一，并不能使用名字来标识播放器对象。

读取 • 设置

播放器对象的图标 url。支持本地资源路径

读取 • 设置

播放模式。该属性对应的功能应由播放器应用实现，播放器对象默认不处理，只提供该属性。

• sequential：顺序播放
• random：随机播放
• singleloop：单曲循环
• listloop：列表循环

读取

读取当前播放状态

• play：正在播放状态
• pause：暂停播放状态
• stop：停止播放状态
• ended：播放结束状态
• error：播放错误状态

读取

音频总时长，单位：秒

读取 • 设置

当前音频播放的时间位置，单位：秒

读取 • 设置

歌曲属性对象

类型签名

type songAttribute = {
  title: string; // 歌曲的名称
  artist: string; // 表演者的名称，可以是个人或者乐队
  album: string; // 歌曲所属的专辑名称
  year: string; // 歌曲的发行年份
  genre: string; // 歌曲的类型，例如流行、摇滚、古典等
  track: string; // 当前歌曲在专辑中的编号，例如："1/12" 表示第1首，共12首
  coverArt: string; // 歌曲封面图片的url
  lyrics: string; // 歌词文本的 url
  comments: string; // 额外信息，如版权备注等
}

songAttribute对象与AudioPlayer对象一样是一个Proxy对象，即不能使用JSON序列化与反序列化，也不能在响应式框架中引用。下面是一个简单的使用示例：

// 设置歌曲的名字
this.player.songAttribute.title = "未知"
// 设置歌曲演唱者
this.player.songAttribute.artist = "未知"
// 查看歌曲的名字
console.dir(this.player.songAttribute.title)

读取 • 设置

当前播放器的音量，范围：[0.0, 1.0]

方法

开始播放在 src 属性中指定的音频

• 如果在调用此方法之前未设置 src 属性，会导致播放失败，触发 onerror 事件；
• 此方法为同步接口，执行此接口后，需要等待 onplay 事件或者 onerror 事件来判定播放成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

下面是一个调用play() 接口的简单示例：

import audiokit from '@system.audiokit'
// 查询系统中处于活跃状态的音频播放器
let player = audiokit.getActivePlayer()
if (player != null) {
  // 首先停止当前正在播放的音频
  player.stop()
  // 设置需要播放的音频url
  player.src = 'https://www.rt-thread.com/service/test/001.mp3'
  // 设置 onplay 事件
  player.onplay = () => { console.dir("开始播放") }
  // 设置 onerror 事件
  player.onerror = () => { console.dir("播放错误") }
  // 开始播放音频
  player.play()
}

方法

暂停播放当前音频

• 此方法为同步接口，执行此接口后，需要等待 onpause 事件或者 onerror 事件来判定暂停成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

方法

停止音频播放，可以通过 play 重新播放音频

• 此方法为同步接口，执行此接口后，需要等待 onstop 事件或者 onerror 事件来判定停止成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

方法

释放音频资源

• 执行此接口会停止播放当前音频，需要等待 onstop 事件或者 onerror 事件来判定停止成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

方法

通知播放器应用，播放下一首。执行此接口后，会触发 onnext 事件通知监听此事件的播放器应用，由播放器应用执行歌曲切换的逻辑。

方法

通知播放器应用，播放下一首。执行此接口后，会触发 onprevious 事件通知监听此事件的播放器应用，由播放器应用执行歌曲切换的逻辑。

设置

在音频 play 成功后的回调事件

设置

在音频 pause 成功后的回调事件

设置

在音频 stop 成功后的回调事件

设置

发生音频打断事件时的回调函数，当前音频被其他有相同音频类型的音频抢夺时，被停止或者恢复的通知。或者当前音频被当外部设备操作打断的通知。

action 参数的 interruptHint 指示打断事件的类型：

• 1：音频恢复 （如：来电恢复）
• 2：音频暂停 （如：来电打断）
• 3：音频暂停 （如：彻底停止）

以下示例演示注册 oninterrupt 回调函数的方法，该函数会在事件发生时调用：

player.oninterrupt = (action) => {
  console.log(action.interruptHint)
}

设置

在 position 属性更新时会触发的回调事件

设置

play pause stop 事件发生错误的回调事件，发生错误时， 对应的 onplay 等不会被触发

设置

在音频播放结束后的回调事件

设置

需要播放下一曲时的回调事件

设置

需要播放上一曲时的回调事件

设置

歌曲属性对象发生变化时的回调事件

设置

播放模式发生变化时的回调事件