AgoraRtcMediaPlayerProtocol - All

adjustPlayoutVolume

Adjusts the local playback volume.

- (int)adjustPlayoutVolume:(int)volume;

Parameters

volume

The local playback volume, which ranges from 0 to 100.

0: Mute.
100: (Default) The original volume.

Returns

0: Success.
< 0: Failure.

adjustPublishSignalVolume

Adjusts the volume of the media file for publishing.

- (int)adjustPublishSignalVolume:(int)volume;

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

Parameters

volume

The remote playback volume, which ranges from 0 to 400:

0: Mute.
100: (Default) The original volume.
400: Four times the original volume (amplifying the audio signals by four times).

Returns

0: Success.
< 0: Failure.

destroyMediaPlayer

Destroys the media player instance.

- (int)destroyMediaPlayer:(id<AgoraRtcMediaPlayerProtocol>_Nullable)mediaPlayer;

Parameters

mediaPlayer: AgoraRtcMediaPlayerProtocol object.

Returns

≥ 0: Success. Returns the ID of media player source instance.
< 0: Failure.

getDuration

Gets the duration of the media resource.

- (NSInteger)getDuration;

Parameters

duration: Output parameter. The total duration (ms) of the media file.

Returns

0: Success.
< 0: Failure.

getMediaPlayerId

Gets the ID of the media player.

- (int)getMediaPlayerId;

Returns

≥ 0: Success. The ID of the media player.
< 0: Failure.

getPlayoutVolume

Gets the local playback volume.

- (int)getPlayoutVolume;

Parameters

volume

Output parameter. The local playback volume, which ranges from 0 to 100.

0: Mute.
100: (Default) The original volume.

Returns

0: Success.
< 0: Failure.

getPosition

Gets current local playback progress.

- (NSInteger)getPosition;

Returns

Returns the current playback progress (ms) if the call succeeds.
< 0: Failure. See AgoraMediaPlayerError.

getPublishSignalVolume

Gets the volume of the media file for publishing.

- (int)getPublishSignalVolume;

Returns

≥ 0: The remote playback volume.
< 0: Failure.

getPlayerState

Gets current playback state.

- (AgoraMediaPlayerState)getPlayerState;

Returns

The current playback state. See AgoraMediaPlayerState.

0: Success.
< 0: Failure.

getStreamCount

Gets the number of the media streams in the media resource.

- (NSInteger)getStreamCount;

Returns

The number of the media streams in the media resource if the method call succeeds.
< 0: Failure. See AgoraMediaPlayerError.

getStreamByIndex

Gets the detailed information of the media stream.

- (AgoraMediaStreamInfo *_Nullable)getStreamByIndex:(int)index;

Parameters

index: The index of the media stream.

Returns

If the call succeeds, returns the detailed information of the media stream. See AgoraRtcMediaStreamInfo.
If the call fails, returns nil.

getMute

Reports whether the media resource is muted.

- (bool)getMute;

Parameters

mute

Output parameter. Whether the media file is muted:

YES: The media file is muted.
NO: The media file is unmuted.

Returns

0: Success.
< 0: Failure.

mute

Sets whether to mute the media file.

- (int)mute:(bool)isMute;

Parameters

isMute

Whether to mute the media file:

YES: Mute the media file.
NO: (Default) Unmute the media file.

Returns

0: Success.
< 0: Failure.

AgoraRtcMediaPlayerCustomSourceOnReadCallback

Occurs when the SDK reads the media resource data.

typedef int(^AgoraRtcMediaPlayerCustomSourceOnReadCallback)(id<AgoraRtcMediaPlayerProtocol> _Nonnull playerKit, unsigned char * _Nullable buffer, int bufferSize);

When you call the openWithCustomSourceAtStartPos method to open a custom media resource, the SDK triggers this callback, requesting you to transfer the media resource data into the buffer.

Parameters

playerKit: Media player protocol. For details, see AgoraRtcMediaPlayerProtocol.
buffer: An input parameter. Data buffer (bytes). Write the bufferSize data reported by the SDK into buffer.
bufferSize: The length of the data buffer (bytes).

Returns

If the data is read successfully, pass in the length of the data (bytes) you actually read in the return value.
If reading the data fails, pass in 0 in the return value.

AgoraRtcMediaPlayerCustomSourceOnSeekCallback

Occurs when the SDK seeks the media resource data.

typedef long long(^AgoraRtcMediaPlayerCustomSourceOnSeekCallback)(id<AgoraRtcMediaPlayerProtocol> _Nonnull playerKit, long long offset, int whence);

When you call the openWithCustomSourceAtStartPos method to open a custom media resource, the SDK triggers this callback to request the specified location in the media resource.

Parameters

playerKit

Media player protocol. For details, see AgoraRtcMediaPlayerProtocol.

offset

An input parameter. The offset of the target position relative to the starting point, in bytes. The value can be positive or negative.

whence

An input parameter. The starting point. You can set it as one of the following values:

0: The starting point is the head of the data, and the actual data offset after seeking is offset.
1: The starting point is the current position, and the actual data offset after seeking is the current position plus offset.
2: The starting point is the end of the data, and the actual data offset after seeking is the whole data length plus offset.
65536: Do not perform position seeking, return the file size. Agora recommends that you use this parameter value when playing pure audio files such as MP3 and WAV.

Returns

When whence is 65536, the media file size is returned.
When whence is 0, 1, or 2, the actual data offset after the seeking is returned.
-1: Seeking failed.

open

Opens the media resource.

- (int)open:(NSString *)url startPos:(NSInteger)startPos;

Parameters

url: The URL of the media resource. Both local path and online path are supported.
startPos: The starting position (ms) for playback. Default value is 0.

Returns

0: Success.
< 0: Failure.

openWithCustomSourceAtStartPos

Opens the custom media resource file.

- (int)openWithCustomSourceAtStartPos:(NSInteger)startPos
                 withPlayerOnReadData:(AgoraRtcMediaPlayerCustomSourceOnReadCallback)onReadDataCallback
                      andPlayerOnSeek:(AgoraRtcMediaPlayerCustomSourceOnSeekCallback)onSeekCallback;

This method allows you to open custom media resource files. For example, you can call this method to open encrypted media resources.

Parameters

startPos: The starting position (ms) for playback. Default value is 0.
onReadDataCallBack: Occurs when the SDK reads the media resource data. For details, see AgoraRtcMediaPlayerCustomSourceOnReadCallback.

onSeekCallBack: Occurs when the SDK seeks the media resource data. For details, see AgoraRtcMediaPlayerCustomSourceOnSeekCallback.

Returns

0: Success.
< 0: Failure.

play

Plays the media file.

- (int)play;

After calling open or seekToPosition, you can call the method to play the media file.

Returns

0: Success.
< 0: Failure.

seekToPosition

Seeks to a new playback position.

- (void)seekToPosition:(NSInteger)position;

After successfully calling this method, you will receive the didOccurEvent callback, reporting the result of the seek operation to the new playback position.

To play the media file from a specific position, do the following:

Call this method to seek to the position you want to begin playback.
Call the play method to play the media file.

Parameters

position: The new playback position (ms).

Returns

0: Success.
< 0: Failure.

setAudioMixingPitch

Sets the pitch of the local music file.

- (int)setAudioMixingPitch:(NSInteger)pitch;

When a local music file is mixed with a local human voice, call this method to set the pitch of the local music file only.

Attention: You need to call this method after calling startAudioMixing [2/2] and receiving the audioMixingStateChanged(AgoraAudioMixingStateTypePlaying) callback.

Parameters

pitch: Sets the pitch of the local music file by the chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.

Returns

0: Success.
< 0: Failure.

setAudioDualMonoMode

Sets the channel mode of the current audio file.

- (int)setAudioDualMonoMode:(AgoraAudioDualMonoMode)mode;

In a stereo music file, the left and right channels can store different audio data. According to your needs, you can set the channel mode to original mode, left channel mode, right channel mode, or mixed channel mode. For example, in the KTV scenario, the left channel of the music file stores the musical accompaniment, and the right channel stores the singing voice. If you only need to listen to the accompaniment, call this method to set the channel mode of the music file to left channel mode; if you need to listen to the accompaniment and the singing voice at the same time, call this method to set the channel mode to mixed channel mode.

Attention:

Call this method after calling open.
This method only applies to stereo audio files.

Parameters

mode: The channel mode. For details, see AgoraAudioDualMonoMode.

Returns

0: Success.
< 0: Failure.

setLoopCount

Sets the loop playback.

- (void)setLoopCount:(NSInteger)loopCount;

If you want to loop, call this method and set the number of the loops.

When the loop finishes, the SDK triggers didChangedToState and reports the playback state as AgoraMediaPlayerStatePlayBackAllLoopsCompleted.

Parameters

loopCount: The number of times the audio effect loops:

Returns

0: Success.
< 0: Failure.

setPlaybackSpeed

Sets the channel mode of the current audio file.

- (int)setPlaybackSpeed:(int)speed;

Call this method after calling open.

Parameters

speed

The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:

50: Half the original speed.
100: The original speed.
400: 4 times the original speed.

Returns

0: Success.
< 0: Failure.

setPlayerOption

Sets the private options for the media player.

- (void)setPlayerOptionInt:(NSString *)key value:(NSInteger)value;

The media player supports setting private options by key and value. Under normal circumstances, you do not need to know the private option settings, and just use the default option settings.

Attention:

Ensure that you call this method before open.
If you need to push streams with SEI into the CDN, call setPlayerOption("sei_data_with_uuid", 1); otherwise, the loss of SEI might occur.

Parameters

key: The key of the option.
value: The value of the key.

Returns

0: Success.
< 0: Failure.

setRenderMode

Sets the render mode of the media player.

- (void)setRenderMode:(AgoraMediaPlayerRenderMode)mode;

Parameters

mode: Sets the render mode of the view. See AgoraMediaPlayerRenderMode.

Returns

0: Success.
< 0: Failure.

setView

Sets the view.

- (void)setView:(View *_Nullable)view;

Parameters

view: The render view.

Returns

0: Success.
< 0: Failure.

stop

Stops playing the media track.

- (void)stop;

Returns

0: Success.
< 0: Failure.