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) - takeScreenshot:
 
(int) - selectInternalSubtitle:
 
(int) - setExternalSubtitle:
 
(AgoraMediaPlayerState- getPlayerState
 
(int) - mute:
 
(BOOL) - getMute
 
(int) - adjustPlayoutVolume:
 
(int) - getPlayoutVolume
 
(int) - setPlayerOption: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
urlThe 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
sourcesee AgoraMediaSource
Returns
  • 0: Success.
  • < 0: Failure.

◆ openWithAgoraCDNSrc:startPos:

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

Open the Agora CDN media source.

Parameters
srcThe src of the media file that you want to play.
startPosThe 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
indexSpecific 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
enableWhether enable.
Returns
  • 0: Success.
  • < 0: Failure.

◆ renewAgoraCDNSrcToken:ts:

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

Update the CDN source token and timestamp.

Parameters
tokentoken.
tsts.
Returns
  • 0: Success.
  • < 0: Failure.

◆ switchAgoraCDNSrc:syncPts:

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

Switch the CDN source.

Parameters
srcSpecific line.
syncPtsLive 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
positionThe new playback position (ms).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioPitch:

- (int) setAudioPitch: (NSInteger)  pitch

Sets the pitch of the current media file.

Parameters
pitchSets 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
indexThe 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
loopCountthe 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
speedthe enum of playback speed
Returns
  • 0: Success.
  • < 0: Failure.

◆ selectAudioTrack:

- (int) selectAudioTrack: (int)  index

Slect playback audio track of the media file

Parameters
indexthe index of the audio track in meia file
Returns
  • 0: Success.
  • < 0: Failure.

◆ takeScreenshot:

- (int) takeScreenshot: (NSString *)  filename

take screenshot while playing video

Parameters
filenamethe filename of screenshot file
Returns
  • 0: Success.
  • < 0: Failure.

◆ selectInternalSubtitle:

- (int) selectInternalSubtitle: (int)  index

select internal subtitles in video

Parameters
indexthe index of the internal subtitles
Returns
  • 0: Success.
  • < 0: Failure.

◆ setExternalSubtitle:

- (int) setExternalSubtitle: (NSString *)  url

set an external subtitle for video

Parameters
urlThe 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
isMuteWhether 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
volumeThe 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 play,

Parameters
[in]keythe option key name reference AgoraConstants.h
[in]valuethe option value
Returns
int <= 0 On behalf of an error, the value corresponds to one of PLAYER_ERROR

◆ setView:

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

Set video rendering view.

◆ setRenderMode:

- (int) setRenderMode: (AgoraMediaPlayerRenderMode mode

Set video display mode.

Parameters
modeVideo 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
srcSpecific src.
syncPtsLive 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
srcSpecific src.
startPosThe starting position (ms) for playback. Default value is 0.
Returns
  • 0: Success.
  • < 0: Failure.

◆ unloadSrc:

- (int) unloadSrc: (NSString *)  src

unload a media source

Parameters
srcSpecific src.
Returns
  • 0: Success.
  • < 0: Failure.

◆ playPreloadedSrc:

- (int) playPreloadedSrc: (NSString *)  src

Play a pre-loaded media source

Parameters
srcSpecific src.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioDualMonoMode:

- (int) setAudioDualMonoMode: (AgoraAudioDualMonoMode mode

Set dual-mono output mode of the music file.

Parameters
modeThe 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
startPosSet the starting position for playback, in seconds.
onReadDataCallbackThe player requests to read the data callback , see AgoraRtcMediaPlayerOnReadCallback
onSeekCallbackThe 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
delegateobserver object, pass nil to unregister
Returns
  • YES: Success.
  • NO: Failure.

◆ setVideoFrameDelegate:

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

Registers & unregister the player video observer

Parameters
delegateobserver 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