IMediaPlayer

addListener

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

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

Parameters

eventType

The name of the target event to listen to. 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. The range is from 0 to 100:

0: Mute.
100: (Default) Original 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. The range is 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 media files.

abstract getAudioBufferDelay(): number;

Parameters

delayMs: Output parameter indicating the audio buffer delay in milliseconds when playing media files.

Return Values

0: The method call succeeds.
< 0: The method call fails.

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

Checks 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: Mute.
100: (Default) Original playback volume of the media file.

getPublishSignalVolume

Gets the volume heard by remote users.

abstract getPublishSignalVolume(): number;

Return Values

≥ 0: 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 calling open and 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

Retrieves media stream information by stream index.

abstract getStreamInfo(index: number): PlayerStreamInfo;

Timing

You need to call this method after getStreamCount.

Parameters

index: The media stream index. 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;

Timing

Can be called before or after joining a channel.

Related Callbacks

After calling this method, the onPlayerSourceStateChanged callback is triggered. Once you receive the playback state PlayerStateOpenCompleted, you can call the play method to play the media file.

Parameters

url: The path to the media file. Supports both local and online files.
startPos: The starting playback position in milliseconds. Default is 0.

Return Values

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

openWithMediaSource

Opens a media resource and configures playback settings.

abstract openWithMediaSource(source: MediaSource): number;

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

Note: This method is asynchronous. To play the media file, call the play method after receiving the onPlayerSourceStateChanged callback with the state 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 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 PlayerStatePlaying, it indicates successful playback. If you want to switch to another preloaded media resource, you can call this method again with 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 PlayerPreloadEventComplete, the preload is successful. If you receive PlayerPreloadEventError, the preload has failed. After a successful preload, call playPreloadedSrc to play the media resource, or 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 a media resource that is currently playing.

Parameters

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

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 before or after joining the 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 an IMediaPlayerVideoFrameObserver class in this method and register the callbacks of this class as needed. After successfully registering the video frame observer, the SDK triggers the registered callback each time a 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 to. 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 to. See IMediaPlayerEvent.

listener

The callback function corresponding to eventType. You must pass in 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 (as indicated by the onPlayerSourceStateChanged callback reporting the playback state as PlayerStatePlaybackCompleted or PlayerStatePlaybackAllLoopsCompleted), the SDK automatically starts playback from the specified position upon a successful call. You will receive an onPlayerSourceStateChanged callback reporting the playback state as PlayerStatePlaying.
If you call seek while playback is paused, the SDK seeks to the specified position upon success. To resume playback, call resume or play.

Timing

This method can be called both before and after joining a channel.

Related Callbacks

After a successful call to this method, you will receive an onPlayerEvent callback reporting events such as seeking started, seeking succeeded, or seeking failed.

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 for 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. For example, if different tracks in a multi-track file store 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 Code 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 must 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 for local playback. You can obtain the index value using getStreamInfo.
publishTrackIndex: The index of the audio track to send to the remote end. You can obtain the index value using getStreamInfo.

Return Values

0: Success.
< 0: Failure.

setAudioDualMonoMode

Sets the channel mode for 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 may store the accompaniment and the right channel 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, set it to mixed mode.

Note:

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

Parameters

mode: Channel mode. See AudioDualMonoMode.

Return Values

0: Success.
< 0: Failure. See Error Code 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 local music file in semitone steps. The default value is 0, meaning no pitch adjustment. The value range is [-12, 12], where each adjacent value represents a semitone difference. The greater the absolute value, the more the pitch is raised or lowered.

Return Values

0: Success.
< 0: Failure. See Error Code 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

The number of times to loop playback.

≥0: Number of loops. For example, 0 means no looping and plays once; 1 means loops once and plays twice in total.
-1: Loop playback indefinitely.

Return Values

0: Success.
< 0: Failure. See Error Code 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. The recommended range is [30, 400], where:

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

Return Values

0: Success.
< 0: Failure. See Error Code 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 are not interchangeable.

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 Code 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 this method uses a String type for value, while setPlayerOptionInInt uses an Int type. The two 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: Key value.
value: 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: The 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 spatial audio effects from the media resource. 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 for the player.

abstract setView(view: any): number;

Timing

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

Parameters

view: Rendering view.

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 it 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 resource.

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

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

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

After calling this method, if you receive the onPlayerEvent callback with the event PlayerEventSwitchComplete, the switch is successful. If the switch fails, the SDK automatically retries 3 times. If it still fails, you will receive the onPlayerEvent callback with the event PlayerEventSwitchError, indicating an error occurred during the switch.

Note:

Make sure to call this method after open.
To ensure normal playback, note 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 resource.

Parameters

src

The network path of the media resource.

syncPts

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

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

unloadSrc

Releases preloaded media resources.

abstract unloadSrc(src: string): number;

Parameters

src: The network path of the media resource.

Return Values

0: Success.
< 0: Failure. See Error Code 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.