文档中心

getMediaPlayerHandle ​

获取多媒体播放器控制句柄 ​

getMediaPlayerHandle 用于获取小游戏内部音频/视频播放的控制接口。

小游戏在运行过程中可能会调用背景音乐、音效或视频播放功能。通过这个句柄，宿主 App 可以从原生层监控、干预或直接控制游戏内的多媒体行为（例如：在 App 收到来电时强制静音游戏，或者同步 App 的全局音量设置）。

方法声明 ​

java
/**
 * 获取多媒体播放器句柄。
 * @return 返回多媒体控制句柄实例。
 */
SUDRTGameHandle.MediaPlayerHandle getMediaPlayerHandle();

MediaPlayerHandle 接口定义 ​

java
public interface MediaPlayerHandle {
    /** * 设置全剧静音
     * @param isMute 是否静音
     */
    void setMute(boolean isMute);

    /**
     * 设置全局音量
     * @param volume 音量值，范围通常为 0.0 到 1.0
     */
    void setVolume(float volume);

    /**
     * 停止所有正在播放的多媒体（音频和视频）
     */
    void stopAll();
}

核心运行行为 ​

1. 全局控制 ​

该句柄提供的控制是全局性的。调用 setMute(true) 会同时静默游戏内的背景音乐（BGM）和所有的交互音效。

2. 与系统音量区分 ​

此处的 setVolume 调节的是游戏引擎内部的增益系数，而非 Android 系统的多媒体音量（Stream Volume）。

3. 资源清理 ​

当调用 stopAll() 时，引擎会立即释放当前所有活跃的音频解码器和视频缓冲区。

代码示例：处理来电静音逻辑 ​

java
// 模拟电话状态监听
public void onPhoneCallStateChanged(boolean isCalling) {
    SUDRTGameHandle.MediaPlayerHandle player = gameHandle.getMediaPlayerHandle();
    if (player != null) {
        if (isCalling) {
            // 1. 电话进来时，强制静音游戏，避免干扰通话
            player.setMute(true);
        } else {
            // 2. 通话结束后，恢复声音
            player.setMute(false);
        }
    }
}

注意事项 ​

  • 初始化时机：建议在 create() 成功后获取此句柄。在环境销毁（destroy）后，该句柄将失效。
  • 默认状态：游戏启动时默认是不静音的。如果你的 App 有“全局静音启动”的需求，可以在 start() 之前先通过此句柄设置 setMute(true)。
  • 视频支持：该句柄同样影响游戏内嵌入的视频组件（如 video 标签或同层渲染组件）的伴音。