android-frame/frame/media/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

媒体模块架构概述

此模块是 WeNext Android 框架的媒体处理核心模块，提供音视频通信、音乐播放和音效处理功能。基于多厂商 RTC SDK 支持（声网、腾讯云、即构、火山引擎）的统一抽象层。

核心架构模式

统一服务接口

• IMediaService: 顶层服务接口，聚合了RTC通信、音乐播放和音效功能
• MediaService: 具体实现类，通过配置注入支持不同RTC厂商

工厂模式与依赖注入

@Synchronized
fun createMediaService(config: IMediaConfig): IMediaService {
    return MediaService(config)
}

多厂商 RTC 抽象

• IRtcEngine: RTC引擎抽象接口，支持不同厂商SDK
• IRtcCallback: 统一的RTC事件回调接口
• RtcType: 支持的RTC厂商类型枚举（AGORA_RTC, T_RTC, ZEGO_RTC, VOLC_RTC）

主要功能模块

1. RTC 实时通信服务 (IMediaRtcService)

• 频道管理: 加入/离开音视频频道，支持异步操作和回调
• 音频控制: 本地/远程音频流的开关控制
• 设备管理: 扬声器/听筒切换，音量调节
• 网络监控: 连接状态、网络质量、Token续期

核心方法：

• joinChannel(): 异步加入频道，支持超时处理
• leaveChannel(): 离开频道，清理资源
• muteLocalAudioStream(): 控制本地音频流发布

2. 音乐播放服务 (IMusicService)

• 本地/远程播放: 支持仅本地播放或推流到远端
• 播放控制: 播放/暂停/停止/进度控制
• 音量管理: 分别控制本地和远程播放音量
• 系统音频分享: 分享设备系统声音到频道

核心方法：

• playMusic(): 播放音乐文件，支持循环次数配置
• setMusicVolume(): 设置音乐整体音量
• shareSystemMusic(): 开启/关闭系统音频分享

3. 音效服务 (ISoundEffectService)

• 多音效并发: 支持多个音效同时播放
• 音效参数: 音量、播放速率动态调节
• 远端发布: 可选择是否将音效推送到远端

核心方法：

• playSoundEffect(): 播放音效，返回音效ID用于后续控制
• setSoundEffectVolume(): 设置特定音效音量

关键设计特点

1. 多厂商RTC支持

• 通过 IRtcEngine 接口抽象不同厂商SDK
• currRtcType 运行时切换RTC厂商
• 配置驱动的RTC引擎创建

2. 异步架构

• 基于 Kotlin 协程的异步操作
• CoroutineScope 管理异步任务生命周期
• SerialHandler 保证关键操作的串行执行

3. 事件驱动模式

• IMediaRtcListener: RTC事件监听
• IMediaMusicListener: 音乐播放事件监听
• 观察者模式支持多个监听器

4. 状态管理

• MediaMusicPlayState: 音乐播放状态枚举
• MediaShareSystemAudioState: 系统音频分享状态
• 原子操作保证状态一致性

5. 线程安全

• ReentrantReadWriteLock 保护RTC类型切换
• ConcurrentList 管理监听器集合
• AtomicBoolean/AtomicInteger 原子状态更新

关键数据类型

• RtcChannelInfo: RTC频道信息，包含频道名、RTC类型、用户ID
• WeNextAudioVolumeInfo: 音频音量信息
• MediaConflictConfig: 媒体冲突配置
• AudioRouter: 音频路由类型（耳机、扬声器、蓝牙等）

开发注意事项

1. RTC厂商兼容性

• 不同厂商SDK在接口行为和回调时机上可能存在差异
• isRtcChannelChanged() 方法用于处理异步回调的有效性验证

2. 资源管理

• 必须调用 leaveChannel() 结束通话
• destroy() 方法释放RTC引擎资源

3. 配置依赖

• 通过 IMediaConfig 注入必要的配置
• 支持低码率模式和Token获取回调

4. 错误处理

• RTC错误通过 RtcError 枚举定义
• 媒体相关错误继承自 MediaChannelNameNull, MediaTokenNull 等

测试命令

该模块遵循标准Android Library测试结构：

• 单元测试：./gradlew :frame:media:test
• 集成测试：./gradlew :frame:media:connectedAndroidTest