AVSession 音频/视频播控切换实现指南
问题描述
在 HarmonyOS 应用中,当从音频播控切换到视频播控时,如果先销毁 audio session 再创建 video session,会出现以下问题:
- createAVSession 报错:"session is existed"
- 通知栏为空,不显示播控状态
解决方案
核心思路:使用单一 AVSession,通过更新 metadata 动态切换音频/视频模式,而非销毁重建。
文件结构
entry/src/main/ets/
├── common/
│ └── AVSessionManager.ts # AVSession 管理器(单例)
└── pages/
└── MediaControlPage.ets # 播控演示页面(完整示例)
核心实现
1. AVSessionManager(单例管理器)
关键特性:
- ✅ 单例模式,全局唯一实例
- ✅ 初始化时创建一次 Session(使用 video 类型)
- ✅ 通过 setAVMetadata 切换音频/视频模式
- ✅ 支持播放状态管理(播放/暂停/停止)
主要方法:
// 初始化 Session(只调用一次)
await sessionManager.initialize(context, MediaType.VIDEO)
// 切换到音频模式
await sessionManager.switchToAudioMode(metadata)
// 切换到视频模式
await sessionManager.switchToVideoMode(metadata)
// 设置播放状态
await sessionManager.setPlaybackState(PlaybackState.PLAYING)
// 销毁 Session(应用退出时调用)
await sessionManager.destroy()
2. 为什么使用 video 类型?
// 推荐:使用 video 类型,同时兼容音频和视频
this.session = await avSession.createAVSession(
context,
MediaType.VIDEO, // 使用 video 类型
'local'
);
// 然后通过 setAVMetadata 的 mediaType 字段区分
await this.session.setAVMetadata({
mediaType: avSession.MediaType.TYPE_AUDIO // 或 TYPE_VIDEO
});
原因:
- video 类型的 Session 可以同时处理音频和视频场景
- 避免频繁销毁和重建导致的时序问题
- 通知栏状态更稳定
3. 切换模式的正确方式
// 错误做法:销毁重建
await oldSession.deactivate();
await oldSession.destroy();
const newSession = await createAVSession(...); // 可能报错 "session is existed"
// 正确做法:更新 metadata
await session.setAVMetadata({
title: '新标题',
mediaType: avSession.MediaType.TYPE_AUDIO // 切换为音频
});
使用示例
MediaControlPage 完整示例
MediaControlPage.ets 是一个完整的 AVSession 播控演示页面,包含以下功能:
1. 核心结构
import { AVSessionManager, MediaType, PlaybackState, MediaMetadata } from '../common/AVSessionManager';
@Entry({ routeName: ROUTE_NAME_MEDIA_CONTROL_PAGE })
@Component
struct MediaControlPage {
private sessionManager: AVSessionManager = AVSessionManager.getInstance()
@State private isInitialized: boolean = false
@State private currentMediaType: MediaType = MediaType.VIDEO
@State private playbackState: PlaybackState = PlaybackState.STOPPED
// 音频元数据
@State private audioMetadata: MediaMetadata = {
title: '晴天',
artist: '周杰伦',
album: '叶惠美',
duration: 300000
}
// 视频元数据
@State private videoMetadata: MediaMetadata = {
title: '演示视频',
artist: '创作者',
album: '示例合集',
duration: 600000
}
}
2. 初始化 Session
private async initializeSession(): Promise<void> {
if (this.isInitialized) {
this.basePage.showToast('Session 已初始化')
return
}
try {
const context = this.getUIContext().getHostContext() as common.UIAbilityContext
// 初始化 Session(使用 video 类型,兼容性更好)
await this.sessionManager.initialize(context, MediaType.VIDEO)
this.isInitialized = true
this.currentMediaType = MediaType.VIDEO
this.totalDuration = this.videoMetadata.duration || 0
this.basePage.showToast('Session 初始化成功')
} catch (error) {
this.basePage.showToast(`初始化失败: ${error}`)
}
}
3. 切换到音频模式
private async switchToAudio(): Promise<void> {
if (!this.isInitialized) {
this.basePage.showToast('请先初始化 Session')
return
}
try {
// 切换到音频模式
await this.sessionManager.switchToAudioMode(this.audioMetadata)
this.currentMediaType = MediaType.AUDIO
this.totalDuration = this.audioMetadata.duration || 0
this.currentPosition = 0
this.basePage.showToast('已切换到音频模式')
} catch (error) {
this.basePage.showToast(`切换失败: ${error}`)
}
}
4. 切换到视频模式
private async switchToVideo(): Promise<void> {
if (!this.isInitialized) {
this.basePage.showToast('请先初始化 Session')
return
}
try {
// 切换到视频模式
await this.sessionManager.switchToVideoMode(this.videoMetadata)
this.currentMediaType = MediaType.VIDEO
this.totalDuration = this.videoMetadata.duration || 0
this.currentPosition = 0
this.basePage.showToast('已切换到视频模式')
} catch (error) {
this.basePage.showToast(`切换失败: ${error}`)
}
}
5. 播放控制
// 播放
private async play(): Promise<void> {
if (!this.isInitialized) return
await this.sessionManager.setPlaybackState(PlaybackState.PLAYING)
this.playbackState = PlaybackState.PLAYING
this.basePage.showToast('开始播放')
}
// 暂停
private async pause(): Promise<void> {
if (!this.isInitialized) return
await this.sessionManager.setPlaybackState(PlaybackState.PAUSED)
this.playbackState = PlaybackState.PAUSED
this.basePage.showToast('已暂停')
}
// 停止
private async stop(): Promise<void> {
if (!this.isInitialized) return
await this.sessionManager.setPlaybackState(PlaybackState.STOPPED)
this.playbackState = PlaybackState.STOPPED
this.currentPosition = 0
this.basePage.showToast('已停止')
}
6. 销毁 Session
private async destroySession(): Promise<void> {
if (!this.isInitialized) return
try {
await this.sessionManager.destroy()
this.isInitialized = false
this.playbackState = PlaybackState.STOPPED
this.currentPosition = 0
this.basePage.showToast('Session 已销毁')
} catch (error) {
this.basePage.showToast(`销毁失败: ${error}`)
}
}
7. UI 布局结构
build() {
Column() {
// 状态栏占位
Blank().height(this.statusBarHeight).width('100%')
// 标题栏
StandardTitleBar({ title: 'AVSession 播控演示', ... })
// 内容区域
Scroll() {
Column({ space: 16 }) {
this.SessionStatusCard() // Session 状态卡片
this.MediaInfoCard() // 媒体信息卡片
this.PlaybackControlCard() // 播放控制卡片
this.ModeSwitchCard() // 模式切换卡片
this.ActionButtonsCard() // 操作按钮卡片
this.InfoCard() // 说明信息卡片
}
.width('100%')
.padding(16)
}
.layoutWeight(1)
.width('100%')
}
.width('100%')
.height('100%')
.backgroundColor('#F5F5F5')
}
8. 页面生命周期管理
aboutToAppear() {
// 设置沉浸式状态栏
BasePageHelper.setImmersiveStatusBar({
statusBarColor: '#00428E',
statusBarContentColor: '#ffffff',
isStatusBarLightIcon: true
})
}
aboutToDisappear() {
// 页面销毁时不销毁 Session,由应用统一管理
this.basePage.destroy()
}
⚙️ 权限配置
在 module.json5 中添加(已配置):
{
"requestPermissions": [
{
"name": "ohos.permission.MEDIA_LOCATION",
"reason": "$string:media_location_permission",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
},
{
"name": "ohos.permission.READ_MEDIA",
"reason": "$string:read_media_permission",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "inuse"
}
}
]
}
运行测试
- 编译项目
- DevEco Studio 中点击 Run
- 访问演示页面
#直接运行应用,打开 pages/MediaControlPage 页面
- 测试流程
#点击「初始化 Session」→ 等待成功提示

#点击「🎵 切换到音频」→ 观察通知栏显示音频播控

#点击「🎬 切换到视频」→ 观察通知栏显示视频播控

#点击播放/暂停/停止按钮 → 观察播放状态变化

#查看日志输出(hilog)
日志输出示例
AVSessionManager: Creating AVSession with type: video
AVSessionManager: AVSession created and activated successfully, type: video
AVSessionManager: Switching to audio mode
AVSessionManager: Successfully switched to audio mode
AVSessionManager: Setting playback state: playing
AVSessionManager: Playback state set to: playing
注意事项
1. Session 生命周期管理
// 推荐:在应用级别管理 Session
class AppManager {
private sessionManager = AVSessionManager.getInstance();
onAbilityCreate() {
// 初始化 Session
}
onAbilityDestroy() {
// 销毁 Session
await this.sessionManager.destroy();
}
}
//避免:在页面级别频繁创建销毁
aboutToAppear() {
await sessionManager.initialize(); // 不要这样做
}
aboutToDisappear() {
await sessionManager.destroy(); // 不要这样做
}
2. 异步操作等待
// 确保前一个操作完成后再执行下一个
async switchMode() {
await sessionManager.switchToAudioMode(metadata);
// 确认切换成功后再执行其他操作
console.info('Switch completed');
}
// 避免并发操作
sessionManager.switchToAudioMode(metadata1);
sessionManager.switchToVideoMode(metadata2); // 可能导致冲突
3. 元数据完整性
// 提供完整的元数据
const metadata: MediaMetadata = {
title: '标题', // 必填
artist: '艺术家', // 必填
album: '专辑', // 可选
artwork: '图片URL', // 可选
duration: 300000 // 可选
};
// 缺少必要字段可能导致通知栏显示异常
const badMetadata = {
title: '' // 空标题
};
常见问题排查
Q1: 通知栏不显示
可能原因:
- Session 未激活(忘记调用 activate())
- 元数据不完整
- 权限未配置
解决方法:
// 1. 检查是否激活
await session.activate();
// 2. 设置完整元数据
await session.setAVMetadata({
title: '标题',
artist: '艺术家',
mediaType: avSession.MediaType.TYPE_AUDIO
});
// 3. 检查权限
// module.json5 中已添加 MEDIA_LOCATION 和 READ_MEDIA
Q2: 切换模式时报错 "session is existed"
原因: 尝试在已有 Session 的情况下再次创建
解决方法:
// 使用单例,检查是否已初始化
if (!sessionManager.isSessionInitialized()) {
await sessionManager.initialize(context);
}
// 不要重复创建
await sessionManager.initialize(context); // 第一次
await sessionManager.initialize(context); // 第二次会报错
Q3: 通知栏状态不同步
原因: 播放状态未更新
解决方法:
// 播放时同步更新状态
async play() {
await player.start(); // 启动播放器
await sessionManager.setPlaybackState(PlaybackState.PLAYING); // 更新 Session 状态
}
async pause() {
await player.pause(); // 暂停播放器
await sessionManager.setPlaybackState(PlaybackState.PAUSED); // 更新 Session 状态
}
📚 相关文档
总结
| 要点 | 说明 |
| 核心原则 | 单一 Session + 动态更新 metadata |
| Session 类型 | 使用 video 类型,兼容性更好 |
| 生命周期 | 应用级别管理,非页面级别 |
| 切换方式 | setAVMetadata 而非销毁重建 |
| 通知栏显示 | 确保 Session 已激活且元数据完整 |
| 入口位置 | 直接访问 pages/MediaControlPage |
| 权限配置 | MEDIA_LOCATION + READ_MEDIA(已配置) |
按照以上方案实现,即可解决音频/视频播控切换时的问题,通知栏会正常显示状态。








































苏公安网备 32011402010933号