更新记录

1.0.0（2026-04-07）

第一次发布

平台兼容性

uni-app x(4.74)

xd-bgmusic - 跨平台背景音频播放器

基于原生播放器的背景音频播放插件，支持 HarmonyOS、Android、iOS 三端，提供系统媒体控制能力。

功能特性

• 支持 HarmonyOS、Android、iOS 三端
• HarmonyOS 端基于 AVPlayer + AVSession 实现
• 支持系统媒体控制（通知栏、耳机、蓝牙控制）
• 支持播放/暂停、上一首/下一首、进度调节
• 支持后台播放
• 支持播放速度调节（0.5, 0.8, 1.0, 1.25, 1.5, 2.0）
• 支持循环模式（顺序、单曲、随机、列表）
• 支持收藏状态同步
• 支持歌词显示
• 支持音频设备监听（耳机断开自动暂停、蓝牙连接自动恢复）
• 兼容 uni-app 的 BackgroundAudioManager API

安装

将插件放入项目的 uni_modules 目录即可使用。

使用示例

方式一：函数式 API

import { 
  play, pause, stop, seek, 
  getDuration, getCurrentTime, isPaused,
  setPlaybackRate, getPlaybackRate,
  setLoopMode, getLoopMode,
  setIsFavorite, getIsFavorite,
  setLyric, setSingleLyricText,
  onPlay, onPause, onStop, , , onError, onNext, onPrev, onLoopModeChange,
  destroy 
} from "@/uni_modules/xd-bgmusic";
import type { BgMusicOptions } from "@/uni_modules/xd-bgmusic";

// 播放音频
const options: BgMusicOptions = {
  src: 'https://example.com/audio.mp3',
  title: '歌曲标题',
  singer: '歌手',
  coverImgUrl: 'https://example.com/cover.jpg',
  epname: '专辑名',
  startTime: 0,
  success: (res) => {
    console.log('播放成功', res);
  },
  fail: (err) => {
    console.error('播放失败', err);
  }
};
play(options);

// 暂停
pause();

// 停止
stop();

// 跳转进度（秒）
seek(30);

// 获取状态
const currentTime = getCurrentTime();
const duration = getDuration();
const paused = isPaused();

// 播放速度（支持 0.5, 0.8, 1.0, 1.25, 1.5, 2.0）
setPlaybackRate(1.5);
const rate = getPlaybackRate();

// 循环模式：0-顺序播放, 1-随机播放, 2-单曲循环, 3-列表循环
setLoopMode(2);
const mode = getLoopMode();

// 收藏状态
setIsFavorite(true);
const favorite = getIsFavorite();

// 歌词
setLyric('[00:00.00]歌词内容...');
setSingleLyricText('当前歌词');

// 监听播放事件
onPlay(() => {
  console.log('开始播放');
});

onPause(() => {
  console.log('播放暂停');
});

onStop(() => {
  console.log('播放停止');
});

(() => {
  console.log('播放结束');
});

(() => {
  console.log('当前时间:', getCurrentTime());
  console.log('总时长:', getDuration());
});

onError((err) => {
  console.error('播放错误:', err);
});

onNext(() => {
  console.log('点击了下一首');
});

onPrev(() => {
  console.log('点击了上一首');
});

onLoopModeChange((mode) => {
  console.log('循环模式改变:', mode);
});

// 销毁播放器
destroy();

方式二：BackgroundAudioManager API（兼容 uni-app）

import { getBackgroundAudioManager } from "@/uni_modules/xd-bgmusic";

const bgAudioManager = getBackgroundAudioManager();

// 设置音频信息并播放
bgAudioManager.title = '歌曲标题';
bgAudioManager.singer = '歌手';
bgAudioManager.coverImgUrl = 'https://example.com/cover.jpg';
bgAudioManager.epname = '专辑名';
bgAudioManager.src = 'https://example.com/audio.mp3';

// 播放控制
bgAudioManager.play();
bgAudioManager.pause();
bgAudioManager.stop();
bgAudioManager.seek(30);

// 播放速度
bgAudioManager.playbackRate = 1.5;

// 歌词
bgAudioManager.setLyric('[00:00.00]歌词内容...');
bgAudioManager.setSingleLyricText('当前歌词');

// 获取状态
console.log('时长:', bgAudioManager.duration);
console.log('当前时间:', bgAudioManager.currentTime);
console.log('是否暂停:', bgAudioManager.paused);

// 事件监听
bgAudioManager.onPlay(() => {
  console.log('开始播放');
});

bgAudioManager.onPause(() => {
  console.log('播放暂停');
});

bgAudioManager.onStop(() => {
  console.log('播放停止');
});

bgAudioManager.onEnded(() => {
  console.log('播放结束');
});

bgAudioManager.onTimeUpdate(() => {
  console.log('进度更新:', bgAudioManager.currentTime);
});

bgAudioManager.onError((err) => {
  console.error('播放错误:', err);
});

bgAudioManager.onPrev(() => {
  console.log('上一首');
});

bgAudioManager.onNext(() => {
  console.log('下一首');
});

API 文档

函数式 API

事件监听

BackgroundAudioManager 属性

BgMusicOptions

interface BgMusicOptions {
  src?: string;           // 音频源地址（支持网络地址和本地文件路径）
  title?: string;         // 歌曲标题
  singer?: string;        // 歌手名
  coverImgUrl?: string;   // 封面图片地址
  epname?: string;        // 专辑名
  startTime?: number;     // 开始播放位置（秒）
  success?: (res: BgMusicResult) => void;
  fail?: (res: BgMusicFail) => void;
  complete?: (res: any) => void;
}

循环模式说明

播放速度支持

支持以下播放速度：0.5, 0.8, 1.0, 1.25, 1.5, 2.0

传入其他值时会自动匹配最接近的支持速度。

错误码

平台特性

HarmonyOS

• 使用 AVPlayer 进行音频播放
• 使用 AVSession 实现系统媒体控制
• 支持通知栏媒体控制
• 支持耳机/蓝牙设备控制
• 支持音频设备断开自动暂停、蓝牙连接自动恢复
• 支持后台播放

Android

• 使用原生 MediaPlayer 实现
• 支持后台播放服务
• 支持通知栏媒体控制

iOS

• 使用 AVPlayer 实现
• 支持后台播放
• 支持系统媒体控制

权限配置

HarmonyOS

在 harmony-configs/entry/src/main/module.json5 中配置：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING"
      }
    ],
    "abilities": [
      {
        "backgroundModes": [
          "audioPlayback"
        ]
      }
    ]
  }
}

Android

在 AndroidManifest.xml 中配置：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

iOS

在 Info.plist 中配置：

<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
</array>

注意事项

1. 播放网络音频需要确保服务器支持跨域请求
2. 本地文件路径需要使用绝对路径
3. 后台播放需要在应用配置中开启相应权限
4. 建议在页面卸载时调用 destroy() 释放资源

相关文档

• UTS 语法
• UTS API插件
• HarmonyOS AVPlayer
• HarmonyOS AVSession