uni.getBackgroundAudioManager() GitCode GitHub

获取全局唯一的背景音频管理器 backgroundAudioManager

背景音频，常见于音乐播放、听书等场景。在页面关闭、应用切换到后台时，仍然可以继续播放，并且可以在手机的通知栏里进行播放、暂停、拖进度等操作。

支持格式

格式	Android	iOS	HarmonyOS
mp3	√	√	√
mp4	√	√	x
m4a	√	√	√
wav	√	√	√
aac	√	√	√
flac	√	√	x
aiff	x	√	x
amr	√	x	√
ape	√	x	x
caf	x	√	x
ogg	√	x	√
wma	√	x	x

• web平台的支持取决于浏览器的实现，一般浏览器上述音频格式均支持
• 小程序平台支持的格式见各家小程序的文档
• HarmonyOS 平台使用 AudioPlayer 实现

缓存说明

• App-Android 平台播放的网络音频，默认会缓存到应用cache目录的uni-audio/background文件夹下，默认大小为100M，超过后会根据最近最少使用的缓存算法自动进行清除；
• 4.51 版本以上 App-iOS 平台支持Cache功能，缓存路径、默认大小和自动清理机制和 Android 一样；

关于Cookie与UA

• App 平台会将应用的Cookie与UA信息自动带入到请求链接

getBackgroundAudioManager 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
x	4.41	4.41	4.41	4.61

返回值

类型
BackgroundAudioManager
名称 类型 必备 默认值 兼容性 描述 duration number 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 当前音频的长度（单位：s），只有在当前有合法的 src 时返回 currentTime number 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 当前音频的播放位置（单位：s），只有在当前有合法的 src 时返回 paused boolean 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放 src string 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 音频的数据源，默认为空字符串，当设置了新的 src 时，会自动开始播放 ，目前支持的格式有 m4a, aac, mp3, wav startTime number 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 音频开始播放的位置（单位：s） buffered number 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 x 音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲 title string 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 4.61 音频标题，用于做原生音频播放器音频标题。原生音频播放器中的分享功能，分享出去的卡片标题，也将使用该值。 epname string 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 4.61 专辑名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值 singer string 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 4.61 歌手名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值 coverImgUrl string 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 4.61 封面图url，用于做原生音频播放器背景图。原生音频播放器中的分享功能，分享出去的卡片配图及背景也将使用该图。 webUrl string 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - x x x x 页面链接，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值 protocol string 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - x x x x 音频协议。默认值为 'http'，设置 'hls' 可以支持播放 HLS 协议的直播音频 playbackRate number 否 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 x 播放的倍率。可取值： 0.5/0.8/1.0/1.25/1.5/2.0，默认值为1.0。（仅 App 支持） cache boolean 是 - Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x 4.41 4.71 4.71 4.71 x 是否缓存线上音频资源，默认值为true，当设置false时，不会缓存资源到本地，直播地址需要主动设置为false audioType string 否 - Web 微信小程序 Android iOS HarmonyOS x 4.41 - - - 需要基础库： 3.4.8 音频类型。可设置 "audio" 和 "music" 两种值，默认为 "audio"。不同音频类型对应的播放器样式不一样（实验特性，目前仅iOS和Android端支持） referrerPath string 否 - Web 微信小程序 Android iOS HarmonyOS x 4.41 - - - 需要基础库： 3.4.8 关联页面路径。设置后，当点击播放器上的小程序跳转链接时，将跳转到这个关联页面路径（实验特性，目前仅Android端支持） referrerPolicy string 否 - Web 微信小程序 Android iOS HarmonyOS x 4.41 - - - 需要基础库： 2.13.0 origin: 发送完整的referrer; no-referrer: 不发送。格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 为小程序的 appid，{version} 为小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本；

BackgroundAudioManager 的方法

play(): void;

play 播放

play 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

pause(): void;

pause 暂停

pause 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

seek(position: number): void;

seek 跳转到指定位置，单位 s

seek 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
position	number	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

stop(): void;

stop 停止

stop 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

onCanplay(callback: (result: any) => void): void;

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

onCanplay 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onPlay(callback: (result: any) => void): void;

onPlay 背景音频播放事件

onPlay 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onPause(callback: (result: any) => void): void;

onPause 背景音频暂停事件

onPause 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onStop(callback: (result: any) => void): void;

onStop 背景音频停止事件

onStop 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onEnded(callback: (result: any) => void): void;

onEnded 背景音频自然播放结束事件

onEnded 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onSeeking(callback : (result : any) => void) : void;

onSeeking 音频进行 seek 操作事件

onSeeking 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onSeeked(callback : (result : any) => void) : void;

onSeeked 音频完成 seek 操作事件

onSeeked 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onTimeUpdate(callback: (result: any) => void): void;

onTimeUpdate 背景音频播放进度更新事件

onTimeUpdate 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onPrev(callback: (result: any) => void): void;

onPrev 用户在系统音乐播放面板点击上一曲事件

onPrev 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onNext(callback: (result: any) => void): void;

onNext 用户在系统音乐播放面板点击下一曲事件

onNext 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onError(callback : (result : ICreateBackgroundAudioFail) => void) : void;

onError 背景音频播放错误事件

onError 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	4.61

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: ICreateBackgroundAudioFail) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

ICreateBackgroundAudioFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	错误码
合法值 兼容性 描述 1107601 Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 系统错误 1107602 Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 网络错误 1107603 Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 文件错误 1107604 Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 格式错误 1107605 Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 未知错误 1107609 Web 微信小程序 Android iOS iOS uni-app x UTS 插件 HarmonyOS x - 4.41 4.41 4.41 - 播放路径不能为空
errSubject	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	统一错误主题（模块）名称
data	any	否	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	错误信息中包含的数据
cause	Error	否	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

onWaiting(callback: (result: any) => void): void;

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

onWaiting 兼容性

Web	微信小程序	Android	iOS	iOS uni-app x UTS 插件	HarmonyOS
x	-	4.41	4.41	4.41	x

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

参见

• 相关 Bug
• 参见uni-app相关文档
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

示例

示例为 alpha 分支：hello uni-app x（alpha）

master 分支：hello uni-app x（master）

该 API 不支持 Web，请运行 hello uni-app x 到 App 平台体验

扫码体验（手机浏览器跳转到App直达页）

扫码体验

<template>
	<view>
		<page-head :title="title"></page-head>
		<view class="uni-padding-wrap">
			<text>
				注意：1.离开当前页面后背景音乐将保持播放；\n
				2. 硬退出app、调用stop api、播放结束都会清理后台控制中心和锁屏信息显示
			</text>
			<boolean-data :defaultValue="false" title="是否循环播放" @change="setLoop"></boolean-data>
			<view class="uni-common-mt">
				<slider ref="slider" :value="position" :min="0" :max="duration" @changing="onchanging"
					@change="onchange"></slider>
			</view>
			<view class="page-body-buttons">
				<template v-if="playing">
					<view class="page-body-button" @tap="stop">
						<image class="image" src="/static/stop.png"></image>
					</view>
					<view class="page-body-button" @tap="pause" style="margin-top: 20px;">
						<image class="image" src="/static/pause.png"></image>
					</view>
				</template>
				<template v-if="!playing">
					<view class="page-body-button" @tap="play">
						<image class="image" src="/static/play.png"></image>
					</view>
				</template>
				<view class="page-body-button"></view>
			</view>
		</view>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				title: 'backgroundAudio',
				bgAudioMannager: null as BackgroundAudioManager | null,
				dataUrl: 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3',
				playing: false,
				playTime: 0,
				formatedPlayTime: '00:00:00',
				count: 100,
				isPlayEnd: false,
				duration: 100,
				currentTime: 0,
				_isChanging: false,
				buffered: 0,
				isLoop: false
			}
		},
		computed: {
			position() {
				return this.isPlayEnd ? 0 : this.currentTime;
			},
		},
		onLoad: function () {
			let bgAudioMannager = uni.getBackgroundAudioManager();
			bgAudioMannager.title = '致爱丽丝' + this.count;
			bgAudioMannager.epname = '专辑名：致爱丽丝' + this.count
			bgAudioMannager.singer = '歌手：暂无' + this.count;
			bgAudioMannager.coverImgUrl = 'https://web-assets.dcloud.net.cn/unidoc/zh/Alice.jpeg';
			bgAudioMannager.src = this.dataUrl;
			this.currentTime = bgAudioMannager.currentTime
			this.duration = bgAudioMannager.duration
			bgAudioMannager.onCanplay(() => {
				console.log("音频进入可以播放状态事件");
				this.buffered = bgAudioMannager.buffered;
				this.duration = bgAudioMannager.duration
			})
			bgAudioMannager.onPlay(() => {
				console.log("开始播放");
				this.playing = true;
			})
			bgAudioMannager.onPause(() => {
				console.log("暂停播放");
				this.playing = false;
			})
			bgAudioMannager.onStop(() => {
				console.log("停止播放");
				this.playing = false;
			})
			bgAudioMannager.onEnded(() => {
				if (this.isLoop == false) {
					console.log("播放结束");
					this.playing = false;
					this.currentTime = 0;
					this.isPlayEnd = true;
					(this.$refs["slider"] as UniSliderElement).value = 0
				} else {
					console.log("播放结束, 开始循环播放");
					this.bgAudioMannager!.src = this.dataUrl;
					this.bgAudioMannager?.play()
				}
			})
			bgAudioMannager.onNext(() => {
				this.count++
				console.log("下一曲", this.count);
				this.bgAudioMannager?.stop()
				bgAudioMannager.title = '致爱丽丝' + this.count;
				bgAudioMannager.singer = '歌手：暂无' + this.count;
				this.dataUrl = 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3'
				bgAudioMannager.coverImgUrl = 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/music-a.png';
				this.bgAudioMannager!.src = this.dataUrl;
				this.bgAudioMannager?.play()
			})
			bgAudioMannager.onPrev(() => {
				this.count--
				console.log("上一曲", this.count);
				this.bgAudioMannager?.stop()
				bgAudioMannager.title = '致爱丽丝' + this.count;
				bgAudioMannager.singer = '歌手：暂无' + this.count;
				this.dataUrl = 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3'
				bgAudioMannager.coverImgUrl = 'https://web-assets.dcloud.net.cn/unidoc/zh/Alice.jpeg';
				this.bgAudioMannager!.src = this.dataUrl;
				this.bgAudioMannager?.play()
			})
			bgAudioMannager.onSeeking(() => {
				console.log('音频进行 seek 操作事件');
			})
			bgAudioMannager.onSeeked(() => {
				console.log('音频完成 seek 操作事件');
			})
			bgAudioMannager.onWaiting(() => {
				console.log('音频加载中事件');
			})
			bgAudioMannager.onTimeUpdate(() => {
				console.log('onTimeUpdate', bgAudioMannager.currentTime)
				if (this._isChanging) { return; }
				this.currentTime = this.bgAudioMannager!.currentTime;
				this.buffered = this.bgAudioMannager!.buffered;
				console.log('onTimeUpdateCb', this.currentTime)

				// #ifdef MP
				// 微信小程序安卓端过早的时机获取的buffered、duration为0，改为在此处获取
				if (this.bgAudioMannager!.duration === 0) {
					this.buffered = this.bgAudioMannager!.buffered;
					this.duration = this.bgAudioMannager!.duration
				}
				// #endif
				if (this.currentTime > this.buffered) {
					console.log('缓冲不足');
				}
			})
			bgAudioMannager.onError((err) => {
				console.log('播放出错err', err);
			})
			this.bgAudioMannager = bgAudioMannager;
			this.playing = !bgAudioMannager.paused
			console.log('currentTime=', this.bgAudioMannager!.currentTime, this.bgAudioMannager!.currentTime == 0)
		},
		methods: {
			play: function () {
				console.log('play')
				this.isPlayEnd = false;
				this.bgAudioMannager!.play()
			},
			pause: function () {
				this.bgAudioMannager?.pause();
			},
			stop: function () {
				this.bgAudioMannager?.stop();
				this.playing = false
			},
			onchanging() {
				this._isChanging = true;
			},
			onchange(e : UniSliderChangeEvent) {
				let pos = e.detail.value;
				console.log('pos', pos);
				this.bgAudioMannager!.seek(pos);
				this._isChanging = false;
			},
			setLoop() {
				this.isLoop = !this.isLoop;
				console.log('当前是否设置循环播放，loop= ', this.isLoop);
			}
		}
	}
</script>

<style>
	.image {
		width: 75px;
		height: 75px;
	}

	.page-body-text {
		padding: 0 15px;
	}

	.page-body-wrapper {
		margin-top: 0;
	}

	.page-body-info {
		padding-bottom: 25px;
	}

	.time-big {
		font-size: 30px;
		margin: 10px;
	}

	.slider {
		width: 315px;
	}

	.play-time {
		width: 100%;
		padding: 10px 0;
		display: flex;
		justify-content: space-between;
		box-sizing: border-box;
	}

	.page-body-buttons {
		display: flex;
		justify-content: center;
		margin-top: 50px;
		flex-direction: column;
	}

	.page-body-button {
		flex-direction: row;
		justify-content: center;
	}
</style>

通用类型

GeneralCallbackResult

名称	类型	必备	默认值	兼容性	描述
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS - 4.41 - - -	错误信息

注意

1，audio默认开启了缓存策略