uni.getBackgroundAudioManager()

支持格式

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

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

缓存说明

• App-Android 平台播放的网络音频，默认会缓存到应用cache目录的uni-audio/background文件夹下，默认大小为100M，超过后会根据最近最少使用的缓存算法自动进行清除；
• App-iOS 平台暂不支持Cache功能；

关于Cookie与UA

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

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

getBackgroundAudioManager 兼容性

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

返回值

类型
BackgroundAudioManager
名称 类型 必备 默认值 兼容性 描述 duration number 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 当前音频的长度（单位：s），只有在当前有合法的 src 时返回 currentTime number 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 当前音频的播放位置（单位：s），只有在当前有合法的 src 时返回 paused boolean 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放 src string 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 音频的数据源，默认为空字符串，当设置了新的 src 时，会自动开始播放 ，目前支持的格式有 m4a, aac, mp3, wav startTime number 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 音频开始播放的位置（单位：s） buffered number 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲 title string 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 音频标题，用于做原生音频播放器音频标题。原生音频播放器中的分享功能，分享出去的卡片标题，也将使用该值。 epname string 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 专辑名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值 singer string 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 歌手名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值 coverImgUrl string 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 封面图url，用于做原生音频播放器背景图。原生音频播放器中的分享功能，分享出去的卡片配图及背景也将使用该图。 webUrl string 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - x x x x 页面链接，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值 protocol string 是 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - x x x x 音频协议。默认值为 'http'，设置 'hls' 可以支持播放 HLS 协议的直播音频 playbackRate number 否 - Web 微信小程序 Android Android uni-app x UTS 插件 iOS iOS uni-app x UTS 插件 - - 4.41 4.41 4.41 4.41 播放的倍率。可取值： 0.5/0.8/1.0/1.25/1.5/2.0，默认值为1.0。（仅 App 支持）

BackgroundAudioManager 的方法

play(): void;

播放

play 兼容性

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

pause(): void;

暂停

pause 兼容性

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

seek(position: number): void;

跳转到指定位置，单位 s

seek 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
position	number	是	-	-	-

stop(): void;

停止

stop 兼容性

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

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

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

onCanplay 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

背景音频播放事件

onPlay 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

背景音频暂停事件

onPause 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

背景音频停止事件

onStop 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

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

onEnded 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

音频进行 seek 操作事件

onSeeking 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

音频完成 seek 操作事件

onSeeked 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

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

onTimeUpdate 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

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

onPrev 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

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

onNext 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

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

背景音频播放错误事件

onError 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: ICreateBackgroundAudioFail) => void	是	-	-	-

ICreateBackgroundAudioFail 的属性值

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

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

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

onWaiting 兼容性

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

参数

名称	类型	必填	默认值	兼容性	描述
callback	(result: any) => void	是	-	-	-

参见

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

示例

hello uni-app x

该 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>
			<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,
			}
		},
		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;
			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(() => {
				console.log("播放结束");
				this.playing = false;
				this.currentTime = 0;
				this.isPlayEnd = true;
				(this.$refs["slider"] as UniSliderElement).value = 0
			})
			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;
			},
		}
	}
</script>

<style>
	.image {
		width: 150rpx;
		height: 150rpx;
	}

	.page-body-text {
		padding: 0 30rpx;
	}

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

	.page-body-info {
		padding-bottom: 50rpx;
	}

	.time-big {
		font-size: 60rpx;
		margin: 20rpx;
	}

	.slider {
		width: 630rpx;
	}

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

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

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

通用类型

GeneralCallbackResult

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

注意

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