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) | - 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) | - setPlayerOption:value:
(int) | - setPlayerOptionString:value:
(int) | - setRenderMode:
(NSString *) | - getPlaySrc
(int) | - switchSrc:syncPts:
(int) | - preloadSrc:startPos:
(int) | - unloadSrc:
(int) | - playPreloadedSrc:
(int) | - setAudioDualMonoMode:
(int) | - openWithCustomSourceAtStartPos:withPlayerOnReadData:andPlayerOnSeek:
(BOOL) | - setAudioFrameDelegate:
(BOOL) | - setVideoFrameDelegate:

## Method Documentation

## ◆ getMediaPlayerId

- (int) getMediaPlayerId |  |  |

Get unique media player id of the media player entity.

Returns
  - >= 0: The mediaPlayerId of this media player entity.
  - < 0: Failure.

## ◆ open:startPos:

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

Opens a media file with a specified URL.

Parameters

  url | The URL of the media file that you want to play.

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

## ◆ openWithMediaSource:

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

Opens a media file with MediaSource

Parameters

  source | see `AgoraMediaSource`

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

## ◆ openWithAgoraCDNSrc:startPos:

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

Open the Agora CDN media source.

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.

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

## ◆ switchAgoraCDNLineByIndex:

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

Switch Agora CDN lines.

Parameters

  index | Specific line.

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

## ◆ getCurrentAgoraCDNIndex

- (int) getCurrentAgoraCDNIndex |  |  |

Gets the line of the current CDN.

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

## ◆ enableAutoSwitchAgoraCDN:

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

Enable automatic CDN line switching.

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.

Parameters

  token | token.
  ts | ts.

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

## ◆ switchAgoraCDNSrc:syncPts:

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

Switch the CDN source.

Parameters

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

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

## ◆ play

- (int) play |  |  |

Plays the media file.

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

## ◆ pause

- (int) pause |  |  |

Pauses playing the media file.

## ◆ stop

- (int) stop |  |  |

Stops playing the current media file.

## ◆ resume

- (int) resume |  |  |

Resumes playing the media file.

## ◆ seekToPosition:

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

Sets the current playback position of the media file.

Parameters

  position | The new playback position (ms).

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

## ◆ setAudioPitch:

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

Sets the pitch of the current media file.

Parameters

  pitch | Sets the pitch of the local music file by 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 file.

## ◆ getPosition

- (NSInteger) getPosition |  |  |

Gets the current playback position of the media file.(ms).

## ◆ getStreamCount

- (NSInteger) getStreamCount |  |  |

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

## ◆ getStreamByIndex:

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

Gets the detailed information of the media stream.

Parameters

  index | The index of the media stream.

Returns
  * If the call succeeds, returns the detailed information of the media stream. See AgoraMediaStreamInfo. If the call fails and returns nil.

## ◆ setLoopCount:

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

Sets whether to loop the media file for playback.

Parameters

  loopCount | the number of times looping the media file. 0: Play the audio effect once. 1: Play the audio effect twice. -1: Play the audio effect in a loop indefinitely, until stopEffect() or stop is called.

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

## ◆ setPlaybackSpeed:

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

Change playback speed

Parameters

  speed | the enum of playback speed

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

## ◆ selectAudioTrack:

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

Select playback audio track of the media file

Parameters

  index | the index of the audio track in media file

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

## ◆ selectMultiAudioTrack:publishTrackIndex:

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

Selects multi audio track of the media file for playback or publish to channel.

Parameters

  playoutTrackIndex | The index of the audio track in media file for local playback.
  publishTrackIndex | The index of the audio track in the media file published to the remote.

Note
  You can obtain the streamIndex of the audio track by calling getStreamInfo.. If you want to use selectMultiAudioTrack, you need to open the media file with openWithMediaSource and set enableMultiAudioTrack to true.

Returns
  - 0: Success.
  - < 0: Failure. See MEDIA_PLAYER_ERROR.
  - -2: Invalid argument. Argument must be greater than or equal to zero.
  - -8: Invalid State.You must open the media file with openWithMediaSource and set enableMultiAudioTrack to true

## ◆ 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 call succeeds and returns current playback state. See AgoraMediaPlayerState. The call fails and returns nil.

## ◆ mute:

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

Turn mute on or off.

Parameters

  isMute | Whether the media source is mute. YES: Yes. NO: No.

Returns
  mute Whether to mute on

## ◆ getMute

- (BOOL) getMute |  |  |

Get mute state.

Returns
  mute Whether is mute on

## ◆ adjustPlayoutVolume:

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

Adjust playback volume.

Parameters

  volume | The volume value to be adjusted The volume can be adjusted from 0 to 400: 0: mute; 100: original volume; 400: Up to 4 times the original volume (with built-in overflow protection).

Returns
  int < 0 on behalf of an error, the value corresponds to one of MEDIA_PLAYER_ERROR

## ◆ getPlayoutVolume

- (int) getPlayoutVolume |  |  |

Get the current playback volume.

Returns
  volume

## ◆ adjustPublishSignalVolume:

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

adjust publish signal volume

## ◆ getPublishSignalVolume

- (int) getPublishSignalVolume |  |  |

get publish signal volume

## ◆ setPlayerOption:value:

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

Modify player option before opening file or url,.

Parameters

  [in] | key | the option key name
  [in] | value | the option value

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

## ◆ setPlayerOptionString:value:

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

Modify player option before opening file or url,.

Parameters

  [in] | key | the option key name
  [in] | value | the option value

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

## ◆ setView:

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

Set video rendering view.

## ◆ setRenderMode:

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

Set video display mode.

Parameters

  mode | Video display mode

Returns
  int < 0 on behalf of an error, the value corresponds to one of MEDIA_PLAYER_ERROR

## ◆ getPlaySrc

- (NSString *) getPlaySrc |  |  |

Get the current play src.

Returns
  - current play src of raw bytes.

## ◆ switchSrc:syncPts:

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

Switch the media source when open a media through "open" API

Parameters

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

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

## ◆ preloadSrc:startPos:

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

Preload a media source

Parameters

  src | Specific src.
  startPos | The starting position (ms) for playback. Default value is 0.

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

## ◆ unloadSrc:

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

unload a media source

Parameters

  src | Specific src.

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

## ◆ playPreloadedSrc:

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

Play a pre-loaded media source

Parameters

  src | Specific src.

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

## ◆ setAudioDualMonoMode:

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

Set dual-mono output mode of the music file.

Parameters

  mode | The audio dual mono mode. See AgoraAudioDualMonoMode.

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

## ◆ openWithCustomSourceAtStartPos:withPlayerOnReadData:andPlayerOnSeek:

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

Deprecated:
  Open media file or stream with custom soucrce. The custom data source provides a data stream input callback, and the player will continue to call back this interface, requesting the user to fill in the data that needs to be played.

Parameters

  startPos | Set the starting position for playback, in seconds.
  onReadDataCallback | The player requests to read the data callback , see `AgoraRtcMediaPlayerOnReadCallback`
  onSeekCallback | The Player seek event callback, see `AgoraRtcMediaPlayerOnSeekCallback`

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 & unregister the player video observer

Parameters

  delegate | observer object, pass nil to unregister.

Returns
  - YES: Success.
  - NO: Failure.

## ◆ registerMediaPlayerAudioSpectrumDelegate:intervalInMS:

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

## ◆ unregisterMediaPlayerAudioSpectrumDelegate:

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