IMediaPlayer

addListener

addListener?<EventType extends keyof IMediaPlayerEvent>(
      eventType: EventType,
      listener: IMediaPlayerEvent[EventType]
    ): void;

After successfully calling this method, you can use IMediaPlayerEvent to listen to events from the corresponding IMediaPlayer object and retrieve data. You can add multiple listeners for the same event depending on your business needs.

Parameters

eventType

The name of the target event to listen for. See IMediaPlayerEvent.

listener

The callback function corresponding to eventType. For example, to add onPlayerSourceStateChanged:

const onPlayerSourceStateChanged = (connection: RtcConnection, elapsed: number) => {};
engine.addListener('onPlayerSourceStateChanged', onPlayerSourceStateChanged);

adjustPlayoutVolume

Adjusts the local playback volume.

abstract adjustPlayoutVolume(volume: number): number;

Timing

Can be called before or after joining a channel.

Parameters

volume

Local playback volume, ranging from 0 to 100:

0: Mute.
100: (Default) Original playback volume of the media file.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

adjustPublishSignalVolume

Adjusts the volume heard by remote users.

abstract adjustPublishSignalVolume(volume: number): number;

After connecting to the Agora server, you can call this method to adjust the volume of the media file heard by remote users.

Timing

Can be called before or after joining a channel.

Parameters

volume

Signal volume, ranging from 0 to 400:

0: Mute.
100: (Default) Original volume of the media file.
400: Four times the original volume (with built-in overflow protection).

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

getAudioBufferDelay

Gets the audio buffer delay when playing a media file.

abstract getAudioBufferDelay(): number;

Parameters

delayMs: Output parameter. Indicates the audio buffer delay in milliseconds when playing a media file.

Return Values

0: Success.
< 0: Failure.

getDuration

Gets the total duration of the media file.

abstract getDuration(): number;

Return Values

The total duration of the media file in milliseconds.

getMediaPlayerId

Gets the media player ID.

abstract getMediaPlayerId(): number;

Return Values

On success, returns the media player ID.
< 0: Failure. See Error Codes for details and resolution suggestions.

getMute

Gets whether the currently playing media file is muted.

abstract getMute(): boolean;

Return Values

true: The currently playing media file is muted.
false: The currently playing media file is not muted.

getPlayPosition

Gets the current playback position.

abstract getPlayPosition(): number;

Return Values

On success, returns the current playback position in milliseconds.
< 0: Failure. See MediaPlayerReason.

getPlaySrc

Gets the path of the media resource being played.

abstract getPlaySrc(): string;

Return Values

The path of the media resource being played.

getPlayoutVolume

Gets the current local playback volume.

abstract getPlayoutVolume(): number;

Return Values

Returns the current local playback volume, ranging from 0 to 100:

0: Silent.
100: (Default) Original playback volume of the media file.

getPublishSignalVolume

Gets the volume heard by remote users.

abstract getPublishSignalVolume(): number;

Return Values

≥ 0: The remote playback volume of the media file.
< 0: Failure. See Error Codes for details and resolution suggestions.

getState

Gets the current state of the media player.

abstract getState(): MediaPlayerState;

Return Values

The current state of the media player. See MediaPlayerState.

getStreamCount

Gets the number of media streams in the current media file.

abstract getStreamCount(): number;

Note: Call this method after open and after receiving the onPlayerSourceStateChanged callback reporting the playback state as PlayerStateOpenCompleted.

Return Values

On success, returns the number of media streams in the media file.
< 0: Failure. See MediaPlayerReason.

getStreamInfo

Gets media stream information by the index of the media stream.

abstract getStreamInfo(index: number): PlayerStreamInfo;

Timing

You need to call this method after getStreamCount.

Parameters

index: The index of the media stream. The value must be less than the return value of getStreamCount.

Return Values

If the method call succeeds, returns the media stream information. See PlayerStreamInfo.
If the method call fails, returns null.

mute

Sets whether to mute.

abstract mute(muted: boolean): number;

Timing

This method can be called before or after joining a channel.

Parameters

muted

Mute option.

true: Mute.
false: (Default) Do not mute.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

open

Opens a media resource.

abstract open(url: string, startPos: number): number;

Note: This method is asynchronous.

Timing

Can be called before or after joining a channel.

Related Callbacks

Calling this method triggers the onPlayerSourceStateChanged callback. After receiving the playback state report PlayerStateOpenCompleted, you can call the play method to play the media file.

Parameters

url: The path to the media file, supporting both local and online files.
startPos: The starting playback position in milliseconds. The default value is 0.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

openWithMediaSource

Opens a media resource and configures playback.

abstract openWithMediaSource(source: MediaSource): number;

This method allows you to open different types of media resources, including custom media files, and configure playback.

Note: This method is asynchronous. To play the media file, call the play method after receiving the onPlayerSourceStateChanged callback with status PlayerStateOpenCompleted.

Timing

This method can be called before or after joining a channel.

Parameters

source: The media resource. See MediaSource.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

pause

Pauses playback.

abstract pause(): number;

Timing

This method can be called before or after joining a channel.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

play

Plays the media file.

abstract play(): number;

Timing

Call this method after calling open or openWithMediaSource to open the media file and receiving the onPlayerSourceStateChanged callback reporting the status as PlayerStateOpenCompleted.
Call this method after calling seek.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

playPreloadedSrc

Plays a preloaded media resource.

abstract playPreloadedSrc(src: string): number;

After calling the preloadSrc method to preload a media resource into the playlist, you can call this method to play the preloaded media resource. If you receive the onPlayerSourceStateChanged callback reporting the status PlayerStatePlaying, it indicates that playback was successful. If you want to switch to another preloaded media resource, you can call this method again and specify a new media resource path. If you want to replay a media resource, you need to call preloadSrc again to preload it into the playlist before playback. To clear the playlist, call stop.

Note: If you call this method while playback is paused, it will take effect only after playback resumes.

Parameters

src: The URL of the media resource in the playlist. It must match the src set by the preloadSrc method, otherwise playback will fail.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

preloadSrc

Preloads a media resource.

abstract preloadSrc(src: string, startPos: number): number;

You can call this method to preload a media resource into the playlist. To preload multiple media resources, call this method multiple times. After calling this method, if you receive the onPreloadEvent callback with event PlayerPreloadEventComplete, the preload is successful; if you receive the onPreloadEvent callback with event PlayerPreloadEventError, the preload has failed. After successful preload, call playPreloadedSrc to play the media resource, or call stop to clear the playlist.

Note:

Before calling this method, make sure you have successfully opened the media resource using open or openWithMediaSource.
The SDK does not support preloading duplicate media resources into the playlist, but it does support preloading the currently playing media resource again into the playlist.

Parameters

src: The network path of the media resource.
startPos: The starting position (in milliseconds) when playback begins after preloading into the playlist. For live streams, set this parameter to 0.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

registerAudioFrameObserver

Registers an audio frame observer.

abstract registerAudioFrameObserver(
    observer: IAudioPcmFrameSink,
    mode?: RawAudioFrameOpModeType
  ): number;

Parameters

observer: The audio frame observer that monitors the reception of each audio frame. See IAudioPcmFrameSink.
mode: The usage mode of the audio frame. See RawAudioFrameOpModeType.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

registerPlayerSourceObserver

Registers a player source observer.

abstract registerPlayerSourceObserver(
    observer: IMediaPlayerSourceObserver
  ): number;

Timing

Can be called both before and after joining a channel.

Parameters

observer: The player source observer that reports events during playback. See IMediaPlayerSourceObserver.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

registerVideoFrameObserver

Registers a video frame observer.

abstract registerVideoFrameObserver(
    observer: IMediaPlayerVideoFrameObserver
  ): number;

You need to implement a IMediaPlayerVideoFrameObserver class in this method and register the callbacks of that class as needed. After successful registration, the SDK triggers the registered callbacks when each video frame is captured.

Parameters

observer: The video frame observer that monitors the reception of each video frame. See IMediaPlayerVideoFrameObserver.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

removeAllListeners

Removes all listeners for the specified event.

removeAllListeners?<EventType extends keyof IMediaPlayerEvent>(
      eventType?: EventType
    ): void;

Parameters

eventType: The name of the target event to listen for. See IMediaPlayerEvent.

removeListener

Removes the specified IMediaPlayerEvent listener.

removeListener?<EventType extends keyof IMediaPlayerEvent>(
      eventType: EventType,
      listener: IMediaPlayerEvent[EventType]
    ): void;

Parameters

eventType

The name of the target event to listen for. See IMediaPlayerEvent.

listener

The callback function corresponding to eventType. You must pass the same function object that was passed to addListener. For example, to remove the listener for onPlayerSourceStateChanged:

const onPlayerSourceStateChanged = (state: MediaPlayerState, ec: MediaPlayerError) => {};
engine.addListener('onPlayerSourceStateChanged', onPlayerSourceStateChanged);
engine.removeListener('onPlayerSourceStateChanged', onPlayerSourceStateChanged);

resume

Resumes playback after pause.

abstract resume(): number;

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

seek

Seeks to the specified playback position in the media file.

abstract seek(newPos: number): number;

If you call seek after playback has completed (when the onPlayerSourceStateChanged callback reports the playback state as PlayerStatePlaybackCompleted or PlayerStatePlaybackAllLoopsCompleted), and the call succeeds, the SDK automatically starts playback from the specified position. In this case, you receive the onPlayerSourceStateChanged callback reporting the playback state as PlayerStatePlaying.
If you call seek while playback is paused, upon successful call, the SDK seeks to the specified position. To resume playback, call resume or play.

Timing

This method can be called before or after joining a channel.

Related Callbacks

After this method is successfully called, you receive the onPlayerEvent callback reporting events such as seek start, success, or failure.

Parameters

newPos: The target position in milliseconds.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

selectAudioTrack

Specifies the audio track to play in the current audio file.

abstract selectAudioTrack(index: number): number;

After obtaining the audio track index of the audio file, you can call this method to specify any track for playback. If different tracks in a multi-track file contain songs in different languages, you can call this method to set the playback language.

Note: You need to call this method after calling getStreamInfo to obtain the audio stream index.

Parameters

index: The index of the audio track.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

selectMultiAudioTrack

Selects the audio tracks for local playback and remote transmission.

abstract selectMultiAudioTrack(
    playoutTrackIndex: number,
    publishTrackIndex: number
  ): number;

You can call this method to separately set the audio tracks for local playback and remote transmission. Before calling this method, you need to open the media file using openWithMediaSource and set enableMultiAudioTrack to true via MediaSource.

Scenario

In karaoke scenarios, the host can choose to play one track locally (e.g., instrumental) and send another track (e.g., vocals) to the remote audience to enhance their experience.

Parameters

playoutTrackIndex: The index of the audio track used for local playback. You can get the index via getStreamInfo.
publishTrackIndex: The index of the audio track used for remote transmission. You can get the index via getStreamInfo.

Return Values

0: Success.
< 0: Failure.

setAudioDualMonoMode

Sets the channel mode of the current audio file.

abstract setAudioDualMonoMode(mode: AudioDualMonoMode): number;

In stereo audio files, the left and right channels can store different audio data. Depending on your needs, you can set the channel mode to original, left channel, right channel, or mixed mode. For example, in a KTV scenario, the left channel of the audio file stores the accompaniment, and the right channel stores the original vocals. If you only want to hear the accompaniment, call this method to set the channel mode to left channel; if you want to hear both accompaniment and vocals, set the mode to mixed.

Note:

You need to call this method after calling open.
This method only applies to stereo audio files.

Parameters

mode: Channel mode. See AudioDualMonoMode.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setAudioPitch

Adjusts the pitch of the currently playing media resource.

abstract setAudioPitch(pitch: number): number;

Note: You need to call this method after calling open.

Parameters

pitch: Adjusts the pitch of the locally played music file in semitone scale. Default is 0, meaning no pitch adjustment. Value range is [-12,12], where each adjacent value differs by a semitone. The greater the absolute value, the more the pitch is raised or lowered.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setLoopCount

Sets loop playback.

abstract setLoopCount(loopCount: number): number;

If you want to enable loop playback, call this method and set the number of loops. When loop playback ends, the SDK triggers the onPlayerSourceStateChanged callback to report the playback state as PlayerStatePlaybackAllLoopsCompleted.

Parameters

loopCount

Number of times to loop playback.

≥0: Number of loops. For example, 0 means no loop, play once; 1 means loop once, play twice in total.
-1: Loop infinitely.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setPlaybackSpeed

Sets the playback speed of the current audio file.

abstract setPlaybackSpeed(speed: number): number;

You need to call this method after open.

Parameters

speed

Playback speed. Recommended range is [30,400], where:

30: 0.3x speed.
100: Original speed.
400: 4x speed.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setPlayerOptionInInt

Sets media player options.

abstract setPlayerOptionInInt(key: string, value: number): number;

The media player supports setting options via key and value. The difference between this method and setPlayerOptionInString is that the value in this method is of type Int, while in setPlayerOptionInString it is of type String. The two cannot be used interchangeably.

Scenario

Scenarios that require technical preview or special customization features. In general, you do not need to call this method; use the default media player option settings.

Timing

This method must be called before open or openWithMediaSource.

Parameters

key: The key value.
value: The value.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setPlayerOptionInString

Sets media player options.

abstract setPlayerOptionInString(key: string, value: string): number;

The media player allows you to set options using key and value. The difference between this method and setPlayerOptionInInt is that the value in this method is of type String, while in setPlayerOptionInInt, the value is of type Int. These two methods cannot be used interchangeably.

Scenario

Scenarios where technical preview or customized features are needed. In general, you don't need to call this method; the default media player option settings are sufficient.

Timing

This method must be called before open or openWithMediaSource.

Parameters

key: The key value.
value: The value.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setRenderMode

Sets the rendering mode of the player view.

abstract setRenderMode(renderMode: RenderModeType): number;

Parameters

renderMode: Rendering mode of the player view. See RenderModeType.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setSpatialAudioParams

Enables or disables spatial audio for the media player.

abstract setSpatialAudioParams(params: SpatialAudioParams): number;

After successfully setting the spatial audio parameters for the media player, the SDK enables spatial audio for the media player, allowing the local user to hear the media content with a sense of spatiality. To disable spatial audio for the media player, set the params parameter to null.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

setView

Sets the rendering view of the player.

abstract setView(view: any): number;

Timing

This method can be called before or after joining a channel.

Parameters

view: The rendering view. On Windows, it is a window handle (HWND).

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

stop

Stops playback.

abstract stop(): number;

After calling this method to stop playback, you need to call open or openWithMediaSource again to reopen the media resource if you want to play again.

Timing

This method must be called after play.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

switchSrc

Switches the media source.

abstract switchSrc(src: string, syncPts?: boolean): number;

You can call this method to switch the bitrate of the media source being played based on the current network condition. For example:

When the network is poor, switch to a lower bitrate media source URL.
When the network is good, switch to a higher bitrate media source URL.

After calling this method, if you receive the onPlayerEvent callback reporting the PlayerEventSwitchComplete event, the media source has been switched successfully. If the switch fails, the SDK automatically retries 3 times. If it still fails, you will receive the onPlayerEvent callback reporting the PlayerEventSwitchError event, indicating an error occurred during the media source switch.

Note:

Make sure to call this method after open.
To ensure normal playback, pay attention to the following when calling this method:
- Do not call this method while playback is paused.
- Do not call seek during bitrate switching.
- Ensure the playback position before switching is not greater than the total duration of the target media source.

Parameters

src

The network path of the media source.

syncPts

Whether to synchronize the starting playback position before and after the switch:

true: Synchronize.
false: (Default) Do not synchronize.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

unloadSrc

Releases the preloaded media source.

abstract unloadSrc(src: string): number;

Parameters

src: The network path of the media source.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

unregisterAudioFrameObserver

Unregisters the audio frame observer.

abstract unregisterAudioFrameObserver(observer: IAudioPcmFrameSink): number;

Parameters

observer: The audio frame observer. See IAudioPcmFrameSink.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

unregisterPlayerSourceObserver

Unregisters the player source observer.

abstract unregisterPlayerSourceObserver(
    observer: IMediaPlayerSourceObserver
  ): number;

Parameters

observer: The player source observer that reports events during playback. See IMediaPlayerSourceObserver.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.

unregisterVideoFrameObserver

Unregisters the video frame observer.

abstract unregisterVideoFrameObserver(
    observer: IMediaPlayerVideoFrameObserver
  ): number;

Parameters

observer: The video frame observer that monitors the reception of each video frame. See IMediaPlayerVideoFrameObserver.

Return Values

0: Success.
< 0: Failure. See Error Codes for details and resolution suggestions.