setMediaPlayerListener

设置多媒体播放器监听器

setMediaPlayerListener 用于监听小游戏内部音视频播放器实例的生命周期。当游戏引擎创建、播放、暂停、停止或销毁一个具体的音频（AudioContext）或视频（VideoContext）对象时，SDK 会通过该监听器通知宿主 App。

这是原生层接管游戏内部细粒度音效控制的关键入口。

---

方法声明

/**
 * 设置多媒体播放器监听。
 * @param listener 遵循 SUDRuntimeMediaPlayerListener 协议的对象。
 */
- (void)setMediaPlayerListener:(nullable id<SUDRuntimeMediaPlayerListener>)listener;

---

参数说明

参数名	类型	必传	描述
listener	id<SUDRuntimeMediaPlayerListener>	否	监听器实例。传入 nil 则取消监听。

---

运行行为

1. 对象感知：每当游戏代码执行 wx.createInnerAudioContext() 或渲染 <video> 组件时，此监听器会触发 onMediaPlayerCreated。
2. 句柄绑定：通过回调提供的 instanceID，App 可以调用 getMediaPlayerHandle: 获取控制权。
3. 状态同步：监听器会实时反馈每个实例的播放状态（播放中、已暂停、已结束）。
4. 自动清理：当游戏逻辑销毁播放器对象时，触发 onMediaPlayerDestroyed，提示原生层释放相关引用。

---

代码示例

通过监听器，可以实现在用户开启原生语音通话时，自动静音游戏内的所有背景音乐：

// 1. 实现协议
@interface GameViewController () <SUDRuntimeMediaPlayerListener>
@property (nonatomic, strong) NSMutableSet *activePlayerIDs;
@end

@implementation GameViewController

- (void)setupMediaPlayerListener {
    self.activePlayerIDs = [NSMutableSet set];
    // 2. 注册监听
    [self.gameHandle setMediaPlayerListener:self];
}

#pragma mark - SUDRuntimeMediaPlayerListener

- (void)onMediaPlayerCreated:(UInt64)instanceID {
    [self.activePlayerIDs addObject:@(instanceID)];
    NSLog(@"[SUD] 播放器创建: %llu", instanceID);
}

- (void)onMediaPlayerStateChanged:(UInt64)instanceID state:(NSInteger)state {
    // state: 0-Stopped, 1-Playing, 2-Paused...
    NSLog(@"[SUD] 播放器 %llu 状态变更: %ld", instanceID, (long)state);
}

- (void)onMediaPlayerDestroyed:(UInt64)instanceID {
    [self.activePlayerIDs removeObject:@(instanceID)];
    NSLog(@"[SUD] 播放器销毁: %llu", instanceID);
}

@end

---

注意事项

• 实例识别：instanceID 是唯一的。如果需要区分背景音乐（BGM）和普通音效，通常需要配合游戏逻辑通过 setGameEventListener 传递额外的元数据。
• 高频触发：在具有大量短促音效（如射击游戏）的场景下，此监听器触发非常频繁，回调内逻辑应尽量精简。
• 资源管理：务必在 onMediaPlayerDestroyed 中清理本地持有的句柄引用，避免内存泄漏。
• 全局与局部：此监听器负责“点对点”控制。如果需要一键静音所有声音，使用 getGameAudioSession 会更高效。

---