Agora RTC Objective-C API Reference Refactor

Instance Methods
<AgoraRtcMediaPlayerProtocol> Protocol Reference

Inherits <NSObject>.

## Instance Methods
(int) | - getMediaPlayerId
(int) | - open:startPos:
(int) | - openWithMediaSource:
(int) | - openWithAgoraCDNSrc:startPos:
(int) | - getAgoraCDNLineCount
(int) | - switchAgoraCDNLineByIndex:
(int) | - getCurrentAgoraCDNIndex
(int) | - enableAutoSwitchAgoraCDN:
(int) | - renewAgoraCDNSrcToken:ts:
(int) | - switchAgoraCDNSrc:syncPts:
(int) | - play
(int) | - pause
(int) | - stop
(int) | - resume
(int) | - seekToPosition:
(int) | - setAudioPitch:
(NSInteger) | - getDuration
(NSInteger) | - getAudioBufferDelay
(NSInteger) | - getPosition
(NSInteger) | - getStreamCount
(AgoraRtcMediaStreamInfo *_Nullable) | - getStreamByIndex:
(int) | - setLoopCount:
(int) | - setPlaybackSpeed:
(int) | - selectAudioTrack:
(int) | - selectMultiAudioTrack:publishTrackIndex:
(int) | - takeScreenshot:
(int) | - selectInternalSubtitle:
(int) | - setExternalSubtitle:
(AgoraMediaPlayerState) | - getPlayerState
(int) | - mute:
(BOOL) | - getMute
(int) | - adjustPlayoutVolume:
(int) | - getPlayoutVolume
(int) | - adjustPublishSignalVolume:
(int) | - getPublishSignalVolume
(int) | - setPlayerOption:value:
(int) | - setPlayerOptionString:value:
(int) | - setView:
(int) | - setRenderMode:
(NSString *) | - getPlaySrc
(int) | - switchSrc:syncPts:
(int) | - preloadSrc:startPos:
(int) | - unloadSrc:
(int) | - playPreloadedSrc:
(int) | - setAudioDualMonoMode:
(BOOL) | - setAudioFrameDelegate:
(BOOL) | - setVideoFrameDelegate:

## Method Documentation

## ◆ getMediaPlayerId

- (int) getMediaPlayerId |  |  |

Gets the ID of the media player.

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

## ◆ open:startPos:

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

Opens the media resource.

Call timing: This method can be called either before or after joining the channel. Related callbacks: After calling this method, the SDK triggers the `AgoraRtcMediaPlayer:didChangedToState:reason:` callback. After receiving the report of the playback status as `AgoraMediaPlayerStateOpenCompleted`, you can call the `play` method to play the media file.

Note
  This method is called asynchronously.

Parameters

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

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ openWithMediaSource:

- (int) openWithMediaSource: |  | (AgoraMediaSource *) | source |

Opens a media file and configures the playback scenarios.

This method supports opening different types of media files, including files starting with `ipod-library://`, and setting the playback options. Call timing: You can call this method either before or after joining a channel.

Note
  This method is called asynchronously. If you need to play a media file, make sure you receive the `AgoraRtcMediaPlayer:didChangedToState:reason:` callback reporting `AgoraMediaPlayerStateOpenCompleted` before calling the `play` method to play the file.

Parameters

  source | Media resources. See `AgoraMediaSource`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ openWithAgoraCDNSrc:startPos:

- (int) openWithAgoraCDNSrc: |  | (NSString *) | src
startPos: |  | (NSInteger) | startPos

Open the Agora CDN media source.

Deprecated:
  4.6.0

Parameters

  src | The src of the media file that you want to play.
  startPos | The playback position (ms).

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getAgoraCDNLineCount

- (int) getAgoraCDNLineCount |  |  |

Gets the number of Agora CDN lines.

Deprecated:
  4.6.0

Returns
  - > 0: number of CDN.
  - <= 0: Failure.

## ◆ switchAgoraCDNLineByIndex:

- (int) switchAgoraCDNLineByIndex: |  | (int) | index |

Switch Agora CDN lines.

Deprecated:
  4.6.0

Parameters

  index | Specific line.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getCurrentAgoraCDNIndex

- (int) getCurrentAgoraCDNIndex |  |  |

Gets the line of the current CDN.

Deprecated:
  4.6.0

Returns
  - >= 0: Specific line.
  - < 0: Failure.

## ◆ enableAutoSwitchAgoraCDN:

- (int) enableAutoSwitchAgoraCDN: |  | (BOOL) | enable |

Enable automatic CDN line switching.

Deprecated:
  4.6.0

Parameters

  enable | Whether enable.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ renewAgoraCDNSrcToken:ts:

- (int) renewAgoraCDNSrcToken: |  | (NSString *) | token
ts: |  | (NSInteger) | ts

Update the CDN source token and timestamp.

Deprecated:
  4.6.0

Parameters

  token | token.
  ts | ts.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ switchAgoraCDNSrc:syncPts:

- (int) switchAgoraCDNSrc: |  | (NSString *) | src
syncPts: |  | (BOOL) | syncPts

Switch the CDN source.

Deprecated:
  4.6.0

Parameters

  src | Specific line.
  syncPts | Live streaming must be set to false.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ play

- (int) play |  |  |

Plays the media file.

Call timing: - Call this method after calling `open:startPos:` or `openWithMediaSource:` opening a media file and receiving a `AgoraRtcMediaPlayer:didChangedToState:reason:` callback reporting the status as AgoraMediaPlayerStateOpenCompleted.

- Call the method after calling `seekToPosition:`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ pause

- (int) pause |  |  |

Pauses the playback.

Call timing: You can call this method either before or after joining a channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ stop

- (int) stop |  |  |

Stops playing the media track.

After calling this method to stop playback, if you want to play again, you need to call `open:startPos:` or `openWithMediaSource:` to open the media resource. Call timing: Call this method after play.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ resume

- (int) resume |  |  |

Resumes playing the media file.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ seekToPosition:

- (int) seekToPosition: |  | (NSInteger) | position |

Seeks to a new playback position.

- If you call `seekToPosition:` after the playback has completed (upon receiving callback `AgoraRtcMediaPlayer:didChangedToState:reason:` reporting playback status as AgoraMediaPlayerStatePlayBackCompleted or AgoraMediaPlayerStatePlayBackAllLoopsCompleted ), the SDK will play the media file from the specified position. At this point, you will receive callback `AgoraRtcMediaPlayer:didChangedToState:reason:` reporting playback status as AgoraMediaPlayerStatePlaying.
- If you call `seekToPosition:` while the playback is paused, upon successful call of this method, the SDK will seek to the specified position. To resume playback, call `resume` or `play`

Call timing: You can call this method either before or after joining a channel. Related callbacks: After successfully calling this method, you will receive the `AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message:` callback, reporting the result of the seek operation to the new playback position.

Parameters

  position | The new playback position (ms).

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioPitch:

- (int) setAudioPitch: |  | (NSInteger) | pitch |

Sets the pitch of the current media resource.

Note
  Call this method after calling `open:startPos:`.

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.

## ◆ getDuration

- (NSInteger) getDuration |  |  |

Gets the duration of the media resource.

Returns
  - If the method call succeeds, the SDK returns the total duration(ms) of the media file.
  - < 0: Failure.

## ◆ getAudioBufferDelay

- (NSInteger) getAudioBufferDelay |  |  |

Gets the audio buffer delay when playing the media file.

Returns
  The audio buffer delay (ms), if the method call succeeds. < 0: An error occurs. You can use MediaPlayerReason to check the reason.

## ◆ getPosition

- (NSInteger) getPosition |  |  |

Gets current local playback progress.

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

## ◆ getStreamCount

- (NSInteger) getStreamCount |  |  |

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

Note
  Call this method after you call `open:startPos:` and receive the `AgoraRtcMediaPlayer:didChangedToState:reason:` callback reporting the state `AgoraMediaPlayerStateOpenCompleted`.

Returns
  - The number of the media streams in the media resource if the method call succeeds.
  - < 0: Failure. See `AgoraMediaPlayerReason`.

## ◆ getStreamByIndex:

- (AgoraRtcMediaStreamInfo *_Nullable) getStreamByIndex: |  | (int) | index |

Gets the detailed information of the media stream.

Call timing: Call this method after calling `getStreamCount`.

Parameters

  index | The index of the media stream. This parameter must be less than the return value of `getStreamCount`.

Returns
  - If the call succeeds, returns the detailed information of the media stream. See `AgoraRtcMediaStreamInfo`.
  - `nil` is returned, if the method call fails.

## ◆ setLoopCount:

- (int) setLoopCount: |  | (int) | loopCount |

Sets the loop playback.

If you want to loop, call this method and set the number of the loops. When the loop finishes, the SDK triggers `AgoraRtcMediaPlayer:didChangedToState:reason:` and reports the playback state as AgoraMediaPlayerStatePlayBackAllLoopsCompleted.

Parameters

  loopCount | The number of times the audio effect loops: ≥0: Number of times for playing. For example, setting it to 0 means no loop playback, playing only once; setting it to 1 means loop playback once, playing a total of twice. -1: Play the audio file in an infinite loop.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlaybackSpeed:

- (int) setPlaybackSpeed: |  | (int) | speed |

Sets the channel mode of the current audio file.

Call this method after calling `open:startPos:`.

Parameters

  speed | The playback speed. Agora recommends that you set this to a value between 30 and 400, defined as follows: 30: 0.3 times the original speed. 100: The original speed. 400: 4 times the original speed.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectAudioTrack:

- (int) selectAudioTrack: |  | (int) | index |

Selects the audio track used during playback.

After getting the track index of the audio file, you can call this method to specify any track to play. For example, if different tracks of 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 `getStreamByIndex:` to get the audio stream index value.

Parameters

  index | The index of the audio track.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectMultiAudioTrack:publishTrackIndex:

- (int) selectMultiAudioTrack: |  | (NSInteger) | playoutTrackIndex
publishTrackIndex: |  | (NSInteger) | publishTrackIndex

Selects the audio tracks that you want to play on your local device and publish to the channel respectively.

You can call this method to determine the audio track to be played on your local device and published to the channel. Before calling this method, you need to open the media file with the `openWithMediaSource:` method and set `enableMultiAudioTrack` in `AgoraMediaSource` as `YES`. Applicable scenarios: For example, in KTV scenarios, the host can choose to play the original sound locally and publish the accompaniment track to the channel.

Parameters

  playoutTrackIndex | The index of audio tracks for local playback. You can obtain the index through `getStreamByIndex:`.
  publishTrackIndex | The index of audio tracks to be published in the channel. You can obtain the index through `getStreamByIndex:`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ takeScreenshot:

- (int) takeScreenshot: |  | (NSString *) | filename |

take screenshot while playing video

Parameters

  filename | the filename of screenshot file

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ selectInternalSubtitle:

- (int) selectInternalSubtitle: |  | (int) | index |

select internal subtitles in video

Parameters

  index | the index of the internal subtitles

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setExternalSubtitle:

- (int) setExternalSubtitle: |  | (NSString *) | url |

set an external subtitle for video

Parameters

  url | The URL of the subtitle file that you want to load.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getPlayerState

- (AgoraMediaPlayerState) getPlayerState |  |  |

Gets current playback state.

Returns
  The current playback state. See `AgoraMediaPlayerState`.

## ◆ mute:

- (int) mute: |  | (BOOL) | isMute |

Sets whether to mute the media file.

Call timing: You can call this method either before or after joining a channel.

Parameters

  isMute | Whether to mute the media file: `YES`: Mute the media file. `NO`: (Default) Unmute the media file.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getMute

- (BOOL) getMute |  |  |

Reports whether the media resource is muted.

Returns
  - `YES`: Reports whether the media resource is muted.
  - `NO`: Reports whether the media resource is muted.

## ◆ adjustPlayoutVolume:

- (int) adjustPlayoutVolume: |  | (int) | volume |

Adjusts the local playback volume.

Call timing: This method can be called either before or after joining the channel.

Parameters

  volume | The local playback volume, which ranges from 0 to 100: 0: Mute. 100: (Default) The original volume.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getPlayoutVolume

- (int) getPlayoutVolume |  |  |

Gets the local playback volume.

Returns
  The local playback volume, which ranges from 0 to 100.
  - 0: Mute.
  - 100: (Default) The original volume.

## ◆ adjustPublishSignalVolume:

- (int) adjustPublishSignalVolume: |  | (int) | volume |

Adjusts the volume of the media file for publishing.

After connected to the Agora server, you can call this method to adjust the volume of the media file heard by the remote user. Call timing: This method can be called either before or after joining the channel.

Parameters

  volume | The 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.

## ◆ getPublishSignalVolume

- (int) getPublishSignalVolume |  |  |

Gets the volume of the media file for publishing.

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

## ◆ setPlayerOption:value:

- (int) setPlayerOption: |  | (NSString *) | key
value: |  | (NSInteger) | value

Sets media player options.

The media player supports setting options through `key` and `value`. The difference between this method and `setPlayerOptionString:value:` is that the `value` parameter of this method is of type Int, while the `value` of `setPlayerOptionString:value:` is of type String. These two methods cannot be used together. Applicable scenarios: Scenarios that require technical previews or special customization features. In general, you do not need to call this method; you can simply use the default options provided by the media player. Call timing: Call this method before the `open:startPos:` or `openWithMediaSource:` method.

Parameters

  key | The key of the option.
  value | The value of the key.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlayerOptionString:value:

- (int) setPlayerOptionString: |  | (NSString *) | key
value: |  | (NSString *) | value

Sets media player options.

The media player supports setting options through `key` and `value`. The difference between this method and `setPlayerOption:value:` is that the `value` parameter of this method is of type String, while the `value` of `setPlayerOption:value:` is of type String. These two methods cannot be used together. Applicable scenarios: Scenarios that require technical previews or special customization features. In general, you do not need to call this method; you can simply use the default options provided by the media player. Call timing: Call this method before the `open:startPos:` or `openWithMediaSource:` method.

Parameters

  key | The key of the option.
  value | The value of the key.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setView:

- (int) setView: |  | (View *_Nullable) | view |

Sets the view.

Call timing: You can call this method either before or after joining a channel.

Parameters

  view | The render view.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRenderMode:

- (int) setRenderMode: |  | (AgoraMediaPlayerRenderMode) | mode |

Sets the render mode of the media player.

Parameters

  mode | Sets the render mode of the view. See `AgoraVideoRenderMode`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ getPlaySrc

- (NSString *) getPlaySrc |  |  |

Gets the path of the media resource being played.

Returns
  The path of the media resource being played.

## ◆ switchSrc:syncPts:

- (int) switchSrc: |  | (NSString *) | src
syncPts: |  | (BOOL) | syncPts

Switches the media resource being played.

You can call this method to switch the media resource to be played according to the current network status. For example:

- When the network is poor, the media resource to be played is switched to a media resource address with a lower bitrate.
- When the network is good, the media resource to be played is switched to a media resource address with a higher bitrate. After calling this method, if you receive the `AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message:` callback report the `AgoraMediaPlayerEventSwitchComplete` event, the switching is successful. If the switching fails, the SDK will automatically retry 3 times. If it still fails, you will receive the `AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message:` callback reporting the `AgoraMediaPlayerEventSwitchError` event indicating an error occurred during media resource switching.

Note
  - Ensure that you call this method after `open:startPos:`.
  - To ensure normal playback, pay attention to the following when calling this method:
    - Do not call this method when playback is paused.
    - Do not call the `seekToPosition:` method during switching.
    - Before switching the media resource, make sure that the playback position does not exceed the total duration of the media resource to be switched.

Parameters

  src | The URL of the media resource.
  syncPts | Whether to synchronize the playback position (ms) before and after the switch: `YES`: Synchronize the playback position before and after the switch. `NO`: (Default) Do not synchronize the playback position before and after the switch.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ preloadSrc:startPos:

- (int) preloadSrc: |  | (NSString *) | src
startPos: |  | (int) | startPos

Preloads a media resource.

You can call this method to preload a media resource into the playlist. If you need to preload multiple media resources, you can call this method multiple times. After calling this method, if you receive the `AgoraMediaPlayerPreloadEventComplete` event in the `AgoraRtcMediaPlayer:didPreloadEvent:` callback, the preload is successful; If you receive the `AgoraMediaPlayerPreloadEventError` event in the `AgoraRtcMediaPlayer:didPreloadEvent:` callback, the preload fails. If the preload is successful and you want to play the media resource, call `playPreloadedSrc:`; if you want to clear the playlist, call `stop`.

Note
  - Before calling this method, ensure that you have called `open:startPos:` or `openWithMediaSource:` to open the media resource successfully.
  - Agora does not support preloading duplicate media resources to the playlist. However, you can preload the media resources that are being played to the playlist again.

Parameters

  src | The URL of the media resource.
  startPos | The starting position (ms) for playing after the media resource is preloaded to the playlist. When preloading a live stream, set this parameter to 0.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ unloadSrc:

- (int) unloadSrc: |  | (NSString *) | src |

Unloads media resources that are preloaded.

Note
  This method cannot release the media resource being played.

Parameters

  src | The URL of the media resource.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ playPreloadedSrc:

- (int) playPreloadedSrc: |  | (NSString *) | src |

Plays preloaded media resources.

After calling the `preloadSrc:startPos:` method to preload the media resource into the playlist, you can call this method to play the preloaded media resource. After calling this method, if you receive the `AgoraRtcMediaPlayer:didChangedToState:reason:` callback which reports the `AgoraMediaPlayerStatePlaying` state, the playback is successful. If you want to change the preloaded media resource to be played, you can call this method again and specify the URL of the new media resource that you want to preload. If you want to replay the media resource, you need to call `preloadSrc:startPos:` to preload the media resource to the playlist again before playing. If you want to clear the playlist, call the `stop` method.

Note
  If you call this method when playback is paused, this method does not take effect until playback is resumed.

Parameters

  src | The URL of the media resource in the playlist must be consistent with the `src` set by the `preloadSrc:startPos:` method; otherwise, the media resource cannot be played.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioDualMonoMode:

- (int) setAudioDualMonoMode: |  | (AgoraAudioDualMonoMode) | mode |

Sets the channel mode of the current audio file.

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.

Note
  - Call this method after calling `open:startPos:`.
  - This method only applies to stereo audio files.

Parameters

  mode | The channel mode. See `AgoraAudioDualMonoMode`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioFrameDelegate:

- (BOOL) setAudioFrameDelegate: |  | (id< AgoraRtcMediaPlayerAudioFrameDelegate > _Nullable) | delegate |

Registers & unregister the player audio observer

Parameters

  delegate | observer object, pass nil to unregister

Returns
  - YES: Success.
  - NO: Failure.

## ◆ setVideoFrameDelegate:

- (BOOL) setVideoFrameDelegate: |  | (id< AgoraRtcMediaPlayerVideoFrameDelegate > _Nullable) | delegate |

Registers the video observer object of the media player.

When calling this method to register a video observer, you can register callbacks in the `AgoraRtcMediaPlayerVideoFrameDelegate` class as needed. After you successfully register the video frame observer, the SDK triggers the registered callbacks each time a video frame is received.

Parameters

  delegate | The delegate instance. See `AgoraRtcMediaPlayerVideoFrameDelegate`. Set the value as nil to release the instance.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ registerMediaPlayerAudioSpectrumDelegate:intervalInMS:

- (int) registerMediaPlayerAudioSpectrumDelegate: |  | (id< AgoraAudioSpectrumDelegate > _Nullable) | delegate
intervalInMS: |  | (NSUInteger) | intervalInMS

## ◆ unregisterMediaPlayerAudioSpectrumDelegate:

- (int) unregisterMediaPlayerAudioSpectrumDelegate: |  | (id< AgoraAudioSpectrumDelegate > _Nullable) | delegate |