更新记录

1.2.2（2024-09-26） 下载此版本

  • 修复 app-ios 环境下，调用 destroy 异常问题。
  • 优化其他已知问题。

1.2.1（2024-09-19） 下载此版本

  • 修复安卓 autonext 设置为 false 时，仍然循环播放的问题。
    • 注意：如果想不单曲循环，请设置 loop 为 off，并且同时设置 autonext 为 false。
  • 优化其他已知问题。

1.2.0（2024-05-15） 下载此版本

  • 【重要】新增支持 web 版本。
  • 优化其他已知问题。
查看更多

平台兼容性

Vue2 Vue3
× √
App 快应用 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序
HBuilderX 3.6.8，Android：支持，iOS：支持，HarmonyNext：不确定 × × × × × ×
钉钉小程序 快手小程序 飞书小程序 京东小程序
× × × ×
H5-Safari Android Browser 微信浏览器(Android) QQ浏览器(Android) Chrome IE Edge Firefox PC-Safari
√ √ √ √ √ √ √ √ √

kux-audio-player

kux-audio-player 是一个参考小程序 createInnerAudioContext 设计实现的音频播放插件，方便开发者们简化音频播放实现流程，快速进行业务开发。

提示

该插件基于原生插件实现，需要自定义基座方可正常使用。

插件特色

  • 完全参考小程序API设计
  • 支持单曲循环，列表循环
  • 支持设置播放列表
  • 支持倍速播放
  • 支持快进、快退等
  • 完整的错误规范设计

目录结构

  1. 基础
    1. 入门使用
  2. API
    1. 属性
      1. src
      2. startTime
      3. autoplay
      4. autonext
      5. loop
      6. volume
      7. playbackRate
      8. duration
      9. currentTime
      10. paused
      11. buffered
      12. srcMode
      13. currentIndex
      14. obeyMuteSwitch
    1. 方法
      1. audioPlayer.play()
      2. audioPlayer.pause()
      3. audioPlayer.stop()
      4. audioPlayer.seek()
      5. audioPlayer.destroy()
      6. audioPlayer.onCanplay()
      7. audioPlayer.offCanplay()
      8. audioPlayer.onPlay()
      9. audioPlayer.offPlay()
      10. audioPlayer.onPause()
      11. audioPlayer.offPause()
      12. audioPlayer.onStop()
      13. audioPlayer.offStop()
      14. audioPlayer.onEnded()
      15. audioPlayer.offEnded()
      16. audioPlayer.onTimeUpdate()
      17. audioPlayer.offTimeUpdate()
      18. audioPlayer.onError()
      19. audioPlayer.offError()
      20. audioPlayer.onWaiting()
      21. audioPlayer.offWaiting()
      22. audioPlayer.onSeeking()
      23. audioPlayer.offSeeking()
      24. audioPlayer.onSeeked()
      25. audioPlayer.offSeeked()
      26. audioPlayer.onNext()
      27. audioPlayer.offNext()
  3. 支持格式
  4. 错误码
  5. 类型接口
    1. OnErrorCallback
    2. OnCommonCallback
    3. Loop
    4. IAudioPlayer

基础

入门使用

下载插件后直接导入页面使用即可，参考下面示例代码：

import { createAudioPlayer } from '@/uni_modules/kux-audio-player';

// 创建实例
const audioPlayer = createAudioPlayer();

// 设置音频地址
// #ifdef APP-ANDROID
audioPlayer.src = '/static/ForElise.mp3';
// #endif
// #ifdef APP-IOS
// 这里是补丁方案，下面有对这方面的说明。
audioPlayer.setPlaybackSrc('/static/ForElise.mp3');
// #endif

// 错误监听
audioPlayer.onError((error) => {
    console.log(error);
})

// 可以播放状态监听
audioPlayer.onCanplay(() => {
    console.log('可以播放了，当前音频长度：', audioPlayer.duration);
})

// 播放
const play = () => {
    audioPlayer.play();
}

// 暂停
const pause = () => {
    audioPlayer.pause();
}

// 停止播放
const stop = () => {
    audioPlayer.stop();
}

// 释放音频资源
const destroy = () => {
    audioPlayer.destroy();
}

提示

该插件基于原生插件实现，需要自定义基座方可正常使用。

v1.1.0 及以上版本支持 IOS

API

属性

下面的属性中没有特殊标记 只读 的都默认为可读可写属性。

提示

因为在uni编译器 4.16 及以下版本 uvue 在IOS中存在无法调用 uts 插件的 set 方法的问题，所以插件提供了 IOS 对应的属性设置补丁方法，所有补丁方法都是 setPlayback 开头，下面每个属性都有详细说明。

string src

音频资源的地址，用于直接播放，支持本地地址和网络地址，如果连续设置多次则自动转换为播放列表形式。可以参考下面示例代码。

audioPlayer.src = 'https://mp-fb8424b7-d7c9-4520-b348-fd76c6c8607d.cdn.bspapp.com/media/1777051637.mp3';
audioPlayer.src = '/static/ForElise.mp3';

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackSrc() 方法设置。

如果是单曲播放，且需要切换音频地址，则需要设置 srcMode 属性为 update。

number startTime

开始播放的位置（单位：s），默认为 0

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackStartTime() 方法设置。

boolean autoplay

是否自动开始播放，默认为 false

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackAutoplay() 方法设置。

该属性仅对 App 生效。

boolean autonext

是否自动播放下一曲，src 设置多次时有效，默认为 true

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackAutonext() 方法设置。

Loop loop

循环播放模式，默认为 off

  • off 不循环
  • one 单曲循环
  • all 当前列表循环

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackLoop() 方法设置。

number volume

音量。范围0-1.0。默认为1.0

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackVolume() 方法设置。

number playbackRate

播放速度。范围 0.5-2.0，默认为 1。（Android 需要 6 及以上版本）

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackRates() 方法设置。

该属性仅对 App 有效。

number duration 只读

当前音频的长度（单位 s）。只有在当前有合法的 src 时返回（只读）

number currentTime

当前音频的播放位置（单位 s）。只有在当前有合法的 src 时返回，时间保留小数点后 6 位，改变 currentTime 等同于调用 seek。

提示

可以在 onTimeUpdate 回调函数里面获取该属性实现实时更新播放进度的场景。

v1.1.0 版本的 IOS 需要通过 setPlaybackCurrentTime() 方法设置。

boolean paused 只读

当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放

number buffered 只读

音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲（只读）

string srcMode

设置src时的行为。如果仅仅是单曲播放和单曲切换场景，这个参数则直接设置为 update 即可。

  • push 当前播放列表新增曲目
  • update 更新当前播放曲目地址
  • v1.0.1 及以上版本支持

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackSrcMode() 方法设置。

number currentIndex

当前播放的音频索引，设置多个音频时有效，单个音频时该参数默认为 0

  • v1.0.1 及以上版本支持

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackCurrentIndex() 方法设置。

boolean obeyMuteSwitch

是否遵循系统静音开关，当此参数为 false 时，即使用户打开了静音开关，也能继续发出声音，默认值 true

  • v1.0.1 及以上版本支持
  • 仅对 IOS 生效

提示

v1.1.0 版本的 IOS 需要通过 setPlaybackObeyMuteSwitch() 方法设置。

方法

下面所有方法的实例名称假设为 audioPlayer，实际使用中请替换自己通过 createAudioPlayer 创建的实例名称。

audioPlayer.play()

播放

audioPlayer.pause()

暂停。暂停后的音频再播放会从暂停处开始播放。

audioPlayer.stop()

停止。停止后的音频再播放会从头开始播放。

audioPlayer.seek(number position)

跳转到指定位置，position 单位为s

audioPlayer.destroy()

销毁当前实例

audioPlayer.onCanplay(OnCommonCallback callback)

音频进入可以播放状态，但不保证后面可以流畅播放

audioPlayer.offCanplay()

取消监听 onCanplay 事件

audioPlayer.onPlay(OnCommonCallback callback)

监听音频播放事件

audioPlayer.offPlay()

移除音频播放事件的监听函数

audioPlayer.onPause(OnCommonCallback callback)

监听音频暂停事件

audioPlayer.offPause()

移除音频暂停事件的监听函数

audioPlayer.onStop(OnCommonCallback callback)

监听音频停止事件

audioPlayer.offStop()

移除音频停止事件的监听函数

audioPlayer.onEnded(OnCommonCallback callback)

监听音频自然播放至结束的事件

audioPlayer.offEnded()

移除音频自然播放至结束的事件的监听函数

audioPlayer.onTimeUpdate(OnCommonCallback callback)

监听音频播放进度更新事件

audioPlayer.offTimeUpdate()

移除音频播放进度更新事件的监听函数

audioPlayer.onError(OnErrorCallback callback)

音频播放错误事件

audioPlayer.offError()

取消监听 onError 事件

audioPlayer.onWaiting(OnCommonCallback callback)

监听音频加载中事件。当音频因为数据不足，需要停下来加载时会触发

audioPlayer.offWaiting()

移除音频加载中事件的监听函数

audioPlayer.onSeeking(OnCommonCallback callback)

监听音频进行跳转操作的事件

audioPlayer.offSeeking()

移除音频进行跳转操作的事件的监听函数

audioPlayer.onSeeked(OnCommonCallback callback)

监听音频完成跳转操作的事件

audioPlayer.offSeeked()

移除音频完成跳转操作的事件的监听函数

audioPlayer.onNext(OnCommonCallback callback)

监听即将播放下一曲事件

提示

在播放多个曲目并且 autonext 为 true 时有效。

audioPlayer.offNext()

移除即将播放下一曲事件的监听函数

支持格式

格式 iOS Android
flac ✖ ✅
m4a ✅ ✅
ogg ✖ ✅
ape ✖ ✅
amr ✖ ✅
wma ✖ ✅
wav ✅ ✅
mp3 ✅ ✅
mp4 ✖ ✅
aac ✅ ✅
aiff ✅ ✖
caf ✅ ✖

错误码

errCode 说明
10001 系统错误
10002 网络错误
10003 文件错误
10004 格式错误
-1 未知错误

类型接口

OnErrorCallback

/**
 * 错误回调
 */
export type OnErrorCallback = (error: ApiFail) => void

OnCommonCallback

/**
 * 公共回调
 */
export type OnCommonCallback = () => void

Loop

/**
 * 循环模式
 * + off 不循环
 * + one 单曲循环
 * + all 列表循环
 */
export type Loop = 'off' | 'one' | 'all'

IAudioPlayer

/**
 * 播放器接口定义
 */
export interface IAudioPlayer {
    /**
     * 音频资源的地址，用于直接播放，支持本地地址和网络地址，如果连续设置多次则自动转换为播放列表形式。可以参考下面示例代码。
     * @example
     * ```
     * audioPlayer.src = 'https://mp-fb8424b7-d7c9-4520-b348-fd76c6c8607d.cdn.bspapp.com/media/1777051637.mp3';
     * audioPlayer.src = '/static/ForElise.mp3';
     *
     * ```
     */
    src: string
    /**
     * 设置 `src` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackSrc (src: string): void
    /**
     * 开始播放的位置（单位：s），默认为 0
     */
    startTime: number
    /**
     * 设置 `startTime` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackStartTime (startTime: number): void
    /**
     * 是否自动开始播放，默认为 `false`，在切换音频地址或者初始化的时候有效。
     */
    autoplay: boolean
    /**
     * 设置 `autoplay` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackAutoplay (autoplay: boolean): void
    /**
     * 是否自动播放下一曲，`src` 设置多次时有效，默认为 `true`
     */
    autonext: boolean
    /**
     * 设置 `autonext` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackAutonext (autonext: boolean): void
    /**
     * 循环播放模式，默认为 `off`
     * + off 不循环
     * + one 单曲循环
     * + all 当前列表循环
     */
    loop: Loop
    /**
     * 设置 `loop` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackLoop (loop: Loop): void
    /**
     * 是否遵循系统静音开关，当此参数为 `false` 时，即使用户打开了静音开关，也能继续发出声音，默认值 `true`
     * + `v1.0.1` 及以上版本支持
     */
    obeyMuteSwitch: boolean
    /**
     * 设置 `obeyMuteSwitch` 。IOS属性设置补丁方案，后面版本会移除
     */
    setPlaybackObeyMuteSwitch (obeyMuteSwitch: boolean): void
    /**
     * 音量。范围0-1。默认为1
     */
    volume: number
    /**
     * 设置 `volume` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackVolume (volume: number): void
    /**
     * 播放速度。范围 0.5-2.0，默认为 1。（Android 需要 6 及以上版本）
     */
    playbackRate: number
    /**
     * 设置 `playbackRate` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackRates (rate: number): void
    /**
     * 当前音频的长度（单位 s）。只有在当前有合法的 src 时返回（只读）
     */
    readonly duration: number
    /**
     * 当前音频的播放位置（单位 s）。只有在当前有合法的 src 时返回，时间保留小数点后 6 位，改变 `currentTime` 等同于调用 `seek`。
     */
    currentTime: number
    /**
     * 设置 `currentTime` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackCurrentTime (currentTime: number): void
    /**
     * 当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放
     */
    readonly paused: boolean
    /**
     * 音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲（只读）
     */
    readonly buffered: number
    /**
     * 当前播放的音频索引，设置多个音频时有效，单个音频时该参数默认为 `0`
     * + `v1.0.1` 及以上版本支持
     */
    currentIndex: number
    /**
     * 设置 `currentIndex` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackCurrentIndex (index: number): void
    /**
     * 设置src时的行为
     * + push 当前播放列表新增曲目
     * + update 更新当前播放曲目地址
     * 
     * + `v1.0.1` 及以上版本支持
     */
    srcMode: SrcMode
    /**
     * 设置 `srcMode` 。IOS属性设置补丁方案，后面版本会移除
     * + `v1.0.1` 及以上版本支持
     */
    setPlaybackSrcMode (mode: SrcMode): void
    /**
     * 播放
     */
    play (): void
    /**
     * 暂停。暂停后的音频再播放会从暂停处开始播放
     */
    pause (): void
    /**
     * 停止。停止后的音频再播放会从头开始播放。
     */
    stop (): void
    /**
     * 跳转到指定位置
     * @param {number} position 需要跳转到的指定位置，单位s
     */
    seek (position: number): void
    /**
     * 销毁当前实例
     */
    destroy (): void
    /**
     * 音频播放错误事件
     * @param { OnErrorCallback } 错误事件回调函数
     */
    onError (callback: OnErrorCallback): void
    /**
     * 取消监听 `onError` 事件
     */
    offError (): void
    /**
     * 音频进入可以播放状态，但不保证后面可以流畅播放
     */
    onCanplay (callback: OnCommonCallback): void
    /**
     * 取消监听 `onCanplay` 事件
     */
    offCanplay (): void
    /**
     * 监听音频播放事件
     */
    onPlay (callback: OnCommonCallback): void
    /**
     * 移除音频播放事件的监听函数
     */
    offPlay (): void
    /**
     * 监听音频暂停事件
     */
    onPause (callback: OnCommonCallback): void
    /**
     * 移除音频暂停事件的监听函数
     */
    offPause (): void
    /**
     * 监听音频停止事件
     */
    onStop (callback: OnCommonCallback): void
    /**
     * 移除音频停止事件的监听函数
     */
    offStop (): void
    /**
     * 监听音频自然播放至结束的事件
     */
     (callback: OnCommonCallback): void
    /**
     * 移除音频自然播放至结束的事件的监听函数
     */
    offEnded (): void
    /**
     * 监听音频播放进度更新事件
     */
     (callback: OnCommonCallback): void
    /**
     * 移除音频播放进度更新事件的监听函数
     */
    offTimeUpdate (): void
    /**
     * 监听音频加载中事件。当音频因为数据不足，需要停下来加载时会触发
     */
     (callback: OnCommonCallback): void
    /**
     * 移除音频加载中事件的监听函数
     */
    offWaiting (): void
    /**
     * 监听音频进行跳转操作的事件
     */
    ing (callback: OnCommonCallback): void
    /**
     * 移除音频进行跳转操作的事件的监听函数
     */
    offSeeking (): void
    /**
     * 监听音频完成跳转操作的事件
     */
    ed (callback: OnCommonCallback): void
    /**
     * 移除音频完成跳转操作的事件的监听函数
     */
    offSeeked (): void
    /**
     * 监听即将播放下一曲事件
     */
    onNext (callback: OnCommonCallback): void
    /**
     * 移除即将播放下一曲事件的监听函数
     */
    offNext (): void
}

结语

kux 不生产代码，只做代码的搬运工，致力于提供uts 的 js 生态轮子实现，欢迎各位大佬在插件市场搜索使用 kux 生态插件：https://ext.dcloud.net.cn/search?q=kux

友情推荐

  • TMUI4.0：包含了核心的uts插件基类.和uvue组件库
  • GVIM即时通讯模版：GVIM即时通讯模版，基于uni-app x开发的一款即时通讯模版
  • t-uvue-ui：T-UVUE-UI是基于UNI-APP X开发的前端UI框架
  • UxFrame 低代码高性能UI框架：【F2图表、双滑块slider、炫酷效果tabbar、拖拽排序、日历拖拽选择、签名...】UniAppX 高质量UI库
  • wx-ui 基于uni-app x开发的高性能混合UI库：基于uni-app x开发的高性能混合UI库，集成 uts api 和 uts component，提供了一套完整、高效且易于使用的UI组件和API，让您以更少的时间成本，轻松完成高性能应用开发。
  • firstui-uvue：FirstUI（unix）组件库，一款适配 uni-app x 的轻量、简洁、高效、全面的移动端组件库。
  • easyXUI 不仅仅是UI 更是为UniApp X设计的电商模板库：easyX 不仅仅是UI库，更是一个轻量、可定制的UniAPP X电商业务模板库，可作为官方组件库的补充,始终坚持简单好用、易上手

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

许可协议

MIT协议
评论列表 撰写评论 向官方投诉
加载更多...
插件问答 我要提问

使用中有什么不明白的地方，就向插件作者提问吧~ 我要提问

加载更多...