文档开发者中心
我的

日常开发—AVSession 音频视频播控切换实现指南

浏览71发布于2026-04-19 08:11重庆
本文章最后由 阿迪那达斯 于 2026-04-21 01:10 编辑

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"

      }

    }

  ]

}

 运行测试

  1. 编译项目
  • DevEco Studio 中点击 Run
  1. 访问演示页面

#直接运行应用,打开 pages/MediaControlPage 页面

  1. 测试流程

#点击「初始化 Session」→ 等待成功提示

cke_71723.png

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

cke_167189.png

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

cke_262800.png

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

cke_358494.png

#查看日志输出(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(已配置)

按照以上方案实现,即可解决音频/视频播控切换时的问题,通知栏会正常显示状态。

收藏
0
回复
0
分享
全部评论
暂无评论
暂无评论
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
了解社区公约,与您携手共创和谐专业的开发者社区。