uni.getBackgroundAudioManager() @getbackgroundaudiomanager

展示全部

# uni.getBackgroundAudioManager()

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

支持格式

格式	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，超过后会根据最近最少使用的缓存算法自动进行清除；
4.51 版本以上 App-iOS 平台支持Cache功能，缓存路径、默认大小和自动清理机制和 Android 一样；

关于Cookie与UA

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

# getBackgroundAudioManager 兼容性

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

# 返回值

类型

BackgroundAudioManager

名称类型必备默认值兼容性描述

duration

number

是

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

currentTime

number

是

当前音频的播放位置（单位：s），只有在当前有合法的 src 时返回

paused

boolean

是

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

src

string

是

音频的数据源，默认为空字符串，当设置了新的 src 时，会自动开始播放，目前支持的格式有 m4a, aac, mp3, wav

startTime

number

是

音频开始播放的位置（单位：s）

buffered

number

是

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

title

string

是

音频标题，用于做原生音频播放器音频标题。原生音频播放器中的分享功能，分享出去的卡片标题，也将使用该值。

epname

string

是

专辑名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值

singer

string

是

歌手名，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值

coverImgUrl

string

是

封面图url，用于做原生音频播放器背景图。原生音频播放器中的分享功能，分享出去的卡片配图及背景也将使用该图。

webUrl

string

是

页面链接，原生音频播放器中的分享功能，分享出去的卡片简介，也将使用该值

protocol

string

是

音频协议。默认值为 'http'，设置 'hls' 可以支持播放 HLS 协议的直播音频

playbackRate

number

否

播放的倍率。可取值： 0.5/0.8/1.0/1.25/1.5/2.0，默认值为1.0。（仅 App 支持）

audioType

string

否

需要基础库： 3.4.8

音频类型。可设置 "audio" 和 "music" 两种值，默认为 "audio"。不同音频类型对应的播放器样式不一样（实验特性，目前仅iOS和Android端支持）

referrerPath

string

否

需要基础库： 3.4.8

关联页面路径。设置后，当点击播放器上的小程序跳转链接时，将跳转到这个关联页面路径（实验特性，目前仅Android端支持）

referrerPolicy

string

否

需要基础库： 2.13.0

origin: 发送完整的referrer; no-referrer: 不发送。格式固定为 https://servicewechat.com/{appid}/{version}/page-frame.html，其中 {appid} 为小程序的 appid，{version} 为小程序的版本号，版本号为 0 表示为开发版、体验版以及审核版本，版本号为 devtools 表示为开发者工具，其余为正式版本；

# 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

系统错误

1107602

网络错误

1107603

文件错误

1107604

格式错误

1107605

未知错误

1107609

播放路径不能为空

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	是	-	-	-

# 参见

# 示例

hello uni-app x

该 API 不支持 Web，请运行 hello uni-app x 到 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;
      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(() => {
				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

是

错误信息

# 注意

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

运营产品

uni-ad uni统计 uni发行 uni安全专题

开发者服务

问答社区开发者后台

技术文档

uni-app文档 uniCloud文档原生开发者支持文档 HBuilder文档

生态服务

插件市场 OAuth用户开放平台

关于我们： DCloud官网案例需求墙许可协议加入我们赞助我们

联系我们：商务合作：bd@dcloud.io 广告合作：uniad@dcloud.io

DCloud.io 数字天堂（北京）网络技术有限公司是

HTML5中国产业联盟发起单位

京公网安备：11010802035340号

国家信息安全等级保护三级，证书编号：11010813802-20001