Skip to content

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 ​

ParameterTypeRequiredDescription
instanceIDUInt64YesUnique identifier. When the game creates a new audio or video object, this ID is dispatched through the listener.

Runtime Behavior ​

  1. Precise targeting: Locates the corresponding playback entity inside the game engine via instanceID.
  2. Instance control: The returned handle supports atomic operations on that specific instance, such as play, pause, stop, setVolume, and setMute.
  3. State sync: If the game layer has already destroyed the corresponding JS object, this method may return nil or 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: instanceID should not be blindly guessed by the app layer; it must be obtained through the onMediaPlayerCreated: callback of SUDRuntimeMediaPlayerListener.
  • 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 that instanceID.
  • Conflict with global settings: If SUDRTGameAudioSession is already set to global mute, calling setMute:NO on this handle usually still cannot produce sound.