getMediaPlayerHandle
Get a media player handle
getMediaPlayerHandle is used to obtain, by instance ID, the control handle of a specific audio/video player inside the mini game. Unlike the global audio session, this method lets the app precisely control one particular audio context (InnerAudioContext) or video component.
Method Declaration
objectivec
/**
* Get the media player handle for a specific instance.
* @param instanceID The unique identifier of the player instance, usually obtained from the SUDRuntimeMediaPlayerListener callback.
* @return An object conforming to the SUDRTGameMediaPlayerHandle protocol.
*/
- (id<SUDRTGameMediaPlayerHandle>)getMediaPlayerHandle:(UInt64)instanceID;Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| instanceID | UInt64 | Yes | Unique identifier. When the game creates a new audio or video object, this ID is dispatched through the listener. |
Runtime Behavior
- Precise targeting: Locates the corresponding playback entity inside the game engine via
instanceID. - Instance control: The returned handle supports atomic operations on that specific instance, such as
play,pause,stop,setVolume, andsetMute. - State sync: If the game layer has already destroyed the corresponding JS object, this method may return
nilor an invalid handle.
Example
Usually used together with setMediaPlayerListener: to reduce or mute the volume of a specific background music track:
objectivec
#pragma mark - SUDRuntimeMediaPlayerListener
- (void)onMediaPlayerCreated:(UInt64)instanceID {
// 1. Get the handle of the newly created player
id<SUDRTGameMediaPlayerHandle> player = [self.gameHandle getMediaPlayerHandle:instanceID];
if (player) {
// 2. Business logic: for a specific sound effect, force-adjust its initial volume in the native layer
[player setVolume:0.8f];
NSLog(@"Successfully took over the player with instance ID %llu", instanceID);
}
}Notes
- Source:
instanceIDshould not be blindly guessed by the app layer; it must be obtained through theonMediaPlayerCreated:callback ofSUDRuntimeMediaPlayerListener. - Resource type: This handle can point to either an audio instance or a video instance.
- Lifecycle constraint: When the
onMediaPlayerDestroyed:callback is received, the app layer should immediately clean up its reference to the handle for thatinstanceID. - Conflict with global settings: If
SUDRTGameAudioSessionis already set to global mute, callingsetMute:NOon this handle usually still cannot produce sound.
