文档中心

getMediaPlayerHandle ​

获取多媒体播放器句柄 ​

getMediaPlayerHandle 用于根据实例 ID 获取小游戏内部特定音视频播放器的控制句柄。与全局的音频会话不同，该方法允许 App 精确控制某一个具体的音频上下文（InnerAudioContext）或视频组件。

方法声明 ​

objectivec
/**
 * 获取特定实例的多媒体播放器句柄。
 * @param instanceID 播放器实例的唯一标识符，通常从 SUDRuntimeMediaPlayerListener 回调中获取。
 * @return 返回遵循 SUDRTGameMediaPlayerHandle 协议的对象。
 */
- (id<SUDRTGameMediaPlayerHandle>)getMediaPlayerHandle:(UInt64)instanceID;

参数说明 ​

参数名类型必传描述
instanceIDUInt64是唯一标识符。当游戏创建新的 audio 或 video 对象时，通过监听器分发此 ID。

运行行为 ​

  1. 精准定位：通过 instanceID 锁定游戏引擎内部对应的播放实体。
  2. 实例控制：返回的句柄支持对该特定实例进行 play、pause、stop、setVolume 以及 setMute 等原子操作。
  3. 状态同步：如果游戏层已经销毁了对应的 JS 对象，调用此方法可能返回 nil 或返回一个失效的句柄。

代码示例 ​

通常配合 setMediaPlayerListener: 使用，实现对特定背景音乐的降噪或静音：

objectivec
#pragma mark - SUDRuntimeMediaPlayerListener
- (void)onMediaPlayerCreated:(UInt64)instanceID {
    // 1. 获取新创建的播放器句柄
    id<SUDRTGameMediaPlayerHandle> player = [self.gameHandle getMediaPlayerHandle:instanceID];
    
    if (player) {
        // 2. 业务逻辑：如果是特定音效，可以在原生层强制调整其初始音量
        [player setVolume:0.8f];
        NSLog(@"成功接管实例 ID 为 %llu 的播放器", instanceID);
    }
}

注意事项 ​

  • 获取来源：instanceID 不应由 App 层盲目猜测，必须通过 SUDRuntimeMediaPlayerListener 的 onMediaPlayerCreated: 回调获取。
  • 资源类型：该句柄既可以指向音频实例，也可以指向视频实例。
  • 生命周期约束：当监听到 onMediaPlayerDestroyed: 回调时，App 层应立即同步清理对该 instanceID 对应句柄的引用。
  • 与全局冲突：如果 SUDRTGameAudioSession 已设置为全局静音，即使在此句柄调用 setMute:NO，通常也无法发出声音。