IMediaPlayer

AdjustPlayoutVolume

Adjusts the local playback volume.

public abstract int AdjustPlayoutVolume(int volume);

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.

public abstract int AdjustPublishSignalVolume(int volume);

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.

Dispose

Releases all resources used by the media player.

public abstract void Dispose();

GetAudioBufferDelay

Gets the audio buffer delay when playing a media file.

public virtual int GetAudioBufferDelay()

Parameters

delayMs: Output parameter that 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.

public abstract int GetDuration(ref Int64 duration);

Parameters

duration: Output parameter. Total duration of the media file (in milliseconds).

Return Values

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

GetId

Gets the player ID.

public abstract int GetId();

Return Values

If the method call succeeds, returns the player ID.
< 0: Failure. See Error Codes for details and resolution suggestions.

GetMute

Checks whether the currently playing media file is muted.

public abstract int GetMute(ref bool muted);

Parameters

muted

Output parameter. Mute state:

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

Return Values

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

GetPlayPosition

Gets the current playback position.

public abstract int GetPlayPosition(ref Int64 pos);

Parameters

pos: Current playback position of the media resource file, in milliseconds.

Return Values

If the method call succeeds, returns the current playback position (in milliseconds).
< 0: Failure. See MEDIA_PLAYER_REASON.

GetPlaySrc

Gets the path of the media resource being played.

public abstract string GetPlaySrc();

Return Values

The path of the media resource being played.

GetPlayoutVolume

Gets the current local playback volume.

public abstract int GetPlayoutVolume(ref int volume);

Parameters

volume

Output parameter. Local playback volume, ranging from 0 to 100:

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

Return Values

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

GetPublishSignalVolume

Gets the volume heard by remote users.

public abstract int GetPublishSignalVolume(ref int volume);

Parameters

volume: Output parameter. Remote playback volume of the playing file.

Return Values

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

GetState

Gets the current state of the player.

public abstract MEDIA_PLAYER_STATE GetState();

Return Values

The current state of the player. See MEDIA_PLAYER_STATE.

GetStreamCount

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

public abstract int GetStreamCount(ref Int64 count);

Note: Call this method after Open and after receiving the OnPlayerSourceStateChanged callback reporting the playback state as PLAYER_STATE_OPEN_COMPLETED.

Parameters

count: Output parameter. Number of media streams in the current media file.

Return Values

0: Success.
< 0: Failure. See MEDIA_PLAYER_REASON.

GetStreamInfo

Gets media stream information by index.

public abstract int GetStreamInfo(Int64 index, ref PlayerStreamInfo info);

Timing

You need to call this method after GetStreamCount.

Parameters

index: Media stream index. This parameter must be less than the count parameter returned by GetStreamCount.
info: Output parameter. All information of the media stream. See PlayerStreamInfo.

Return Values

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

InitEventHandler

Adds callback events for the media player.

public abstract int InitEventHandler(IMediaPlayerSourceObserver engineEventHandler);

Parameters

engineEventHandler: The callback event to add. See IMediaPlayerSourceObserver.

Return Values

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

Mute

Sets whether to mute.

public abstract int Mute(bool muted);

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.

public abstract int Open(string url, Int64 startPos);

Note: This method is asynchronous.

Timing

Can be called before or after joining a channel.

Related Callbacks

After calling this method, the OnPlayerSourceStateChanged callback is triggered. Once the playback state PLAYER_STATE_OPEN_COMPLETED is reported, 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 start position (in milliseconds) for playback. 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.

public abstract int OpenWithMediaSource(MediaSource source);

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, you need to call the Play method after receiving the OnPlayerSourceStateChanged callback reporting the PLAYER_STATE_OPEN_COMPLETED state.

Timing

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.

public abstract int Pause();

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.

public abstract int Play();

Timing

Call this method after calling Open or OpenWithMediaSource to open the media file and receiving the OnPlayerSourceStateChanged callback reporting the status as PLAYER_STATE_OPEN_COMPLETED.
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.

public abstract int PlayPreloadedSrc(string src);

After calling the PreloadSrc method to preload the 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 as PLAYER_STATE_PLAYING, the playback has succeeded. If you want to switch the preloaded media resource to play, you can call this method again and specify the new media resource path. If you want to replay the media resource, you need to call PreloadSrc again to preload the resource into the playlist before playing. 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.

public abstract int PreloadSrc(string src, Int64 startPos);

You can call this method to preload a media resource into the playlist. To preload multiple media resources, call this method multiple times. After successful preloading, 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 start position (in milliseconds) for playback 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 [1/2]

Registers a PCM audio frame observer.

public abstract int RegisterAudioFrameObserver(IAudioPcmFrameSink observer);

You need to implement an IAudioPcmFrameSink class in this method and register its callback based on your scenario. After successfully registering the audio frame observer, the SDK triggers the registered callback whenever it captures an audio frame.

Parameters

observer: Audio frame observer that monitors the reception of each audio frame. See IAudioPcmFrameSink.

Return Values

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

RegisterAudioFrameObserver [2/2]

Registers an audio frame observer.

public abstract int RegisterAudioFrameObserver(IAudioPcmFrameSink observer, RAW_AUDIO_FRAME_OP_MODE_TYPE mode);

Parameters

observer: Audio frame observer that monitors the reception of each audio frame. See IAudioPcmFrameSink.
mode: Usage mode of the audio frame. See RAW_AUDIO_FRAME_OP_MODE_TYPE.

Return Values

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

Resume

Resumes playback after pause.

public abstract int Resume();

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.

public abstract int Seek(Int64 newPos);

If you call Seek after playback has completed (as indicated by the OnPlayerSourceStateChanged callback reporting the status as PLAYER_STATE_PLAYBACK_COMPLETED or PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED), the SDK will automatically start playback from the specified position upon successful call. You will receive an OnPlayerSourceStateChanged callback reporting the status as PLAYER_STATE_PLAYING.
If you call Seek while playback is paused, the SDK will seek to the specified position upon success. To play, call Resume or Play.

Timing

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

Related Callbacks

After successfully calling this method, you will receive an OnPlayerEvent callback reporting events such as seek start, seek success, or seek failure.

Parameters

newPos: The specified position (in milliseconds).

Return Values

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

SelectAudioTrack [2/2]

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

public abstract int SelectAudioTrack(int index);

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

Note: You need to call this method after calling GetStreamInfo to get 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 sending.

public abstract int SelectMultiAudioTrack(int playoutTrackIndex, int publishTrackIndex);

You can call this method to separately set the audio tracks for local playback and for sending to the remote end. 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 sent to the remote end. You can get the index via GetStreamInfo.

Return Values

0: Success.
< 0: Failure.

SetAudioDualMonoMode

Sets the channel mode of the current audio file.

public abstract int SetAudioDualMonoMode(AUDIO_DUAL_MONO_MODE mode);

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, right, or mixed. For example, in a karaoke (KTV) scenario, the left channel of the audio file stores the accompaniment, while 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. If you want to hear both the accompaniment and the original vocals, set the channel mode to mixed.

Note:

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

Parameters

mode: Channel mode. See AUDIO_DUAL_MONO_MODE.

Return Values

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

SetAudioPitch

Adjusts the pitch of the currently playing media resource.

public abstract int SetAudioPitch(int pitch);

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

Parameters

pitch: Adjusts the pitch of the locally played music file in semitone steps. The default value is 0, meaning no pitch adjustment. The valid range is [-12,12], where the pitch difference between two adjacent values is one semitone. The greater the absolute value, the more the pitch increases or decreases.

Return Values

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

SetLoopCount

Sets loop playback.

public abstract int SetLoopCount(int loopCount);

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 PLAYER_STATE_PLAYBACK_ALL_LOOPS_COMPLETED.

Parameters

loopCount

Number of playback loops.

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

Return Values

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

SetPlaybackSpeed

Sets the playback speed of the current audio file.

public abstract int SetPlaybackSpeed(int speed);

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.

SetPlayerOption [1/2]

Sets media player options.

public abstract int SetPlayerOption(string key, int value);

The media player supports setting options via key and value. The difference between this method and setPlayerOption [2/2] is that the value in this method is of type Int, while in setPlayerOption [2/2] 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: Key value.
value: Value.

Return Values

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

setPlayerOption [2/2]

Sets media player options.

public abstract int SetPlayerOption(string key, string value);

The media player supports setting options via key and value. The difference between this method and SetPlayerOption [1/2] is that the value in this method is of type String, while in SetPlayerOption [1/2] it is of type Int. The two are not interchangeable.

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.

public abstract int SetRenderMode(RENDER_MODE_TYPE renderMode);

Parameters

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

Return Values

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

SetSpatialAudioParams

Enables or disables spatial audio for the media player.

public abstract int SetSpatialAudioParams(SpatialAudioParams spatial_audio_params);

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 perceive spatial effects from the media source. To disable spatial audio for the media player, you need to set the params parameter to null.

Parameters

spatial_audio_params: Spatial audio parameters for the media player. See SpatialAudioParams.

Return Values

0: Method call succeeds.
< 0: Method call fails. See Error Codes for details and resolution suggestions.

SetView

Sets the player rendering view.

public abstract int SetView();

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.

Stop

Stops playback.

public abstract int Stop();

After calling this method to stop playback, to play again you need to call Open or OpenWithMediaSource to reopen the media resource.

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.

public abstract int SwitchSrc(string src, bool syncPts = true);

You can call this method to switch the bitrate of the currently playing media resource based on the 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 reporting the event PLAYER_EVENT_SWITCH_COMPLETE, the switch was successful. If the switch fails, the SDK retries 3 times. If it still fails, you receive the OnPlayerEvent callback reporting the PLAYER_EVENT_SWITCH_ERROR event, indicating an error occurred during the 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 media resource being switched to.

Parameters

src

The network path of the media resource.

syncPts

Whether to synchronize the start playback position before and after switching:

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

public abstract int UnloadSrc(string src);

Parameters

src: The network path of the media resource.

Return Values

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

UnregisterAudioFrameObserver

Unregisters the audio frame observer.

public abstract int UnregisterAudioFrameObserver();

Return Values

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