AgoraMediaPlayer Class Reference

Inherits from NSObject
Declared in AgoraMediaPlayerKit.h

Overview

The AgoraMediaPlayer interface.

  mute

Sets whether to mute the media resource:

@property (nonatomic, assign) BOOL mute

Discussion

  • YES: Mute the media resource.
  • NO: Unmute the media resource.

Declared In

AgoraMediaPlayerKit.h

  volume

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

@property (nonatomic, assign) NSInteger volume

Declared In

AgoraMediaPlayerKit.h

  state

The playback state. See AgoraMediaPlayerState

@property (nonatomic, readonly) AgoraMediaPlayerState state

Declared In

AgoraMediaPlayerKit.h

– initWithDelegate:

Creates an AgoraMediaPlayer instance.

- (instancetype)initWithDelegate:(id<AgoraMediaPlayerDelegate>)delegate

Parameters

delegate

AgoraMediaPlayerDelegate

Return Value

The AgoraMediaPlayer instance.

Declared In

AgoraMediaPlayerKit.h

– initWithDelegate:voiceChatMode:

Creates an AgoraMediaPlayer instance.

- (instancetype)initWithDelegate:(id<AgoraMediaPlayerDelegate>)delegate voiceChatMode:(bool)enableVoiceChatMode

Parameters

delegate

AgoraMediaPlayerDelegate
enableVoiceChatMode

Whether to enable the mode for voice chat:

  • YES: Enable the mode for voice chat. The mediaplayer kit uses the call volume and cannot be set to 0.
  • NO: (Default) Disable the mode for voice chat. The mediaplayer kit uses the media volume. Compared with the call volume, the media volume has better sound performance and can be adjusted to 0, which is more suitable for playing the media resources.

Return Value

The AgoraMediaPlayer instance.

Discussion

Note:

  • When you use the Agora RTC Native SDK and MediaPlayer Kit at the same time, if the audio scenario of the Native SDK is GameStreaming(3), Agora recommends that you set the MediaPlayer Kit to use the media volume and integrate the helper at the same time.
  • When you use the Agora RTC Native SDK and MediaPlayer Kit at the same time, if the audio scenario of the Native SDK is not GameStreaming(3), Agora recommends that you set the MediaPlayer Kit to use the call volume.

Declared In

AgoraMediaPlayerKit.h

– setView:

Sets the view.

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

Parameters

view

The view of the mediaplayer kit.

Declared In

AgoraMediaPlayerKit.h

– setRenderMode:

Sets the render mode of the view.

- (void)setRenderMode:(AgoraMediaPlayerRenderMode)mode

Parameters

mode

The render mode of the view. See AgoraMediaPlayerRenderMode.

Declared In

AgoraMediaPlayerKit.h

– open:startPos:

Opens the media resource.

- (void)open:(NSString *)url startPos:(NSInteger)startPos

Parameters

url

The path of the media resource. Both local path and online path are supported.
startPos

The starting position (ms) for playback. Default value is 0.

Declared In

AgoraMediaPlayerKit.h

– play

Plays the media resource.

- (void)play

Discussion

After opening the media resource or seeking to a new playback position or pausing the playback, you can call this method to play the media resource.

Declared In

AgoraMediaPlayerKit.h

– pause

Pauses the playback.

- (void)pause

Discussion

To resume the playback, call the play method.

Declared In

AgoraMediaPlayerKit.h

– stop

Stops the playback.

- (void)stop

Declared In

AgoraMediaPlayerKit.h

– seekToPosition:

Seeks to a new playback position.

- (void)seekToPosition:(NSInteger)position

Parameters

position

The new playback position (millionseconds).

Discussion

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

Declared In

AgoraMediaPlayerKit.h

– mute:

Sets whether to mute the media resource.

- (int)mute:(bool)isMute

Parameters

isMute

Sets whether to mute the media resource:

  • YES: Mute the media resource.
  • NO: (default) Unmute the media resource.

Return Value

Declared In

AgoraMediaPlayerKit.h

– getMute

Confirms whether the media resource is muted.

- (bool)getMute

Return Value

  • If the call succeeds, returns:
    • YES: The media resource is muted.
    • NO: (default) The media resource is not muted.
  • If the call fails, returns NO.

Declared In

AgoraMediaPlayerKit.h

– adjustVolume:

Adjusts the local playback volume.

- (int)adjustVolume:(int)volume

Parameters

volume

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

Return Value

Declared In

AgoraMediaPlayerKit.h

– getPlayPosition

Gets current local playback progress.

- (NSInteger)getPlayPosition

Return Value

  • < 0: Failure. See AgoraMediaPlayerError.
  • Others: The call succeeds and returns current playback progress (ms).

Declared In

AgoraMediaPlayerKit.h

– getDuration

Gets the duration of the media resource.

- (NSInteger)getDuration

Return Value

  • < 0: Failure. See AgoraMediaPlayerError.
  • Others: The call succeeds and returns the total duration (ms) of the media resource.

Declared In

AgoraMediaPlayerKit.h

– getPlayerState

Gets current playback state.

- (AgoraMediaPlayerState)getPlayerState

Return Value

Declared In

AgoraMediaPlayerKit.h

– getStreamCount

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

- (NSInteger)getStreamCount

Return Value

  • < 0: Failure. See AgoraMediaPlayerError.
  • Others: The call succeeds and returns the number of the media streams in the media resource.

Declared In

AgoraMediaPlayerKit.h

– getStreamByIndex:

Gets the detailed information of the media stream.

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

Parameters

index

The index of the media stream.

Return Value

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

Declared In

AgoraMediaPlayerKit.h

– setLogFile:

Specifies the output log files of the mediaplayer kit.

- (void)setLogFile:(NSString *)filePath

Parameters

filePath

The absolute path of log files. Ensure that the directory for the log files exists and is writable.

Discussion

Note:

  • The default log file path is App Sandbox/Library/caches/agoraplayer.log.
  • Ensure that you call this method immediately after creating AgoraMediaPlayer, otherwise the output logs may not be complete.

Declared In

AgoraMediaPlayerKit.h

– setLogFilter:

Sets the output log level of the mediaplayer kit.

- (void)setLogFilter:(NSInteger)filter

Parameters

filter

Log filter level:

  • AgoraLogFilterDebug(0x080f): Output all log information. Set your log filter as debug if you want to get the most complete log file.
  • AgoraLogFilterInfo(0x000f): Output CRITICAL, ERROR, WARNING, and INFO level log information. We recommend setting your log filter as this level.
  • AgoraLogFilterWarning(0x000e): Outputs CRITICAL, ERROR, and WARNING level log information.
  • AgoraLogFilterError(0x000c): Outputs CRITICAL and ERROR level log information.
  • AgoraLogFilterCritical(0x0008): Outputs CRITICAL level log information.
  • AgoraLogFilterOff(0): Do not output any log information.

Discussion

You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level. For example, if you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Declared In

AgoraMediaPlayerKit.h

– setPlayerOptionInt:value:

Sets the private options for the MediaPlayer Kit.

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

Parameters

key

key.
value

value.

Discussion

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

Note: Calling this method before the open method.

Declared In

AgoraMediaPlayerKit.h

– setPlayerOptionString:value:

Sets the private options for the MediaPlayer Kit.

- (void)setPlayerOptionString:(NSString *)key value:(NSString *)value

Parameters

key

key.
value

value.

Discussion

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

Note: Calling this method before the open method.

Declared In

AgoraMediaPlayerKit.h

– changePlaybackSpeed:

Changes the playback speed.

- (void)changePlaybackSpeed:(AgoraMediaPlayerSpeed)speed

Parameters

speed

The playback speed. See AgoraMediaPlayerSpeed.

Discussion

After opening the media file, you can call this method to change the playback speed.

Declared In

AgoraMediaPlayerKit.h

– selectAudioTrack:

Selects the audio track used during playback.

- (void)selectAudioTrack:(NSInteger)index

Parameters

index

The index of the audio track.

Discussion

After opening the media file, you can call this method to select the audio track used during playback.

Before calling this method, call the getStreamByIndex method to get the audio track information of the current media stream. The streamIndex value of the audio track information is the index value of this method.

Declared In

AgoraMediaPlayerKit.h

– getPlayerSdkVersion

Gets the version number of the MediaPlayer Kit.

- (NSString *)getPlayerSdkVersion

Return Value

The version number of the MediaPlayer Kit, such as "1.2.1".

Declared In

AgoraMediaPlayerKit.h

– setLoopCount:

Sets the loop playback.

- (void)setLoopCount:(NSInteger)loopCount

Parameters

loopCount

The number of the loops.

Discussion

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

When the loop playback ends, the mediaplayer kit returns AgoraMediaPlayerStatePlayBackAllLoopsCompleted(6).

Declared In

AgoraMediaPlayerKit.h

– destroy

Destroys AgoraMediaPlayer.

- (void)destroy

Discussion

This method releases all resources used by the MediaPlayer Kit. After calling this method, you will no longer be able to use other APIs provided by the kit. To reuse the kit, call the initWithDelegate method to re-create an AgoraMediaPlayer instance.

Note:

  • This method is called synchronously. To avoid deadlock, Agora recommends that you do not call this method in the callback.
  • To create a new AgoraMediaPlayer instance after releasing the current one, ensure that you wait until the destroy completes executing.

Declared In

AgoraMediaPlayerKit.h

– setExternalSubtitle:

Sets the external subtitle.(Only for macOS)

- (void)setExternalSubtitle:(NSString *)url

Parameters

url

The URL address of the external subtitle. Both local address and online address are supported.

Discussion

After opening the media file, you can call this method for setting the mediaplayer kit to display the external subtitle.

Note:

Please make sure it is set to software decoding before calling this method:

[_mediaPlayerKit setPlayerOptionInt:@"video_decoder_type" value:1];

or [_mediaPlayerKit setPlayerOptionString:@"media_format" value:@"mp4"];.

Declared In

AgoraMediaPlayerKit.h

– switchSrc:syncPts:

Switches the media resource being played.

- (void)switchSrc:(NSString *)src syncPts:(BOOL)syncPts

Parameters

src

The URL address of the media resource to be switched. HTTP, RTMP, and RTSP protocols are supported for local and online media streams.
syncPts

Whether to synchronize the playback position(millionseconds) before and after the switch:

  • true: (Default) Synchronize the playback position before and after the switch. After the MediaPlayer Kit switches the media resource, it starts playing the media resource from the playback position at the time of the switch.

Note: Agora only supports setting syncPts to true when playing on-demand streams.

  • false: The playback position before and after the switch is not synchronized. Instead, the playback position after the is switched is determined as follows:

  • If the media resource is an on-demand stream, the MediaPlayer Kit starts playing the media resource from the beginning.

  • If the media resource is a live stream, the MediaPlayer Kit starts playing the media resource from the playback position when the code rate is switched.

Discussion

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 switchSrc, if you receive the didOccurEvent callback event AgoraMediaPlayerEventSwitchComplete, the switch is successful; if you receive the didOccurEvent callback event AgoraMediaPlayerEventSwitchError, the switch fails.

Note:

  • Make sure to call this method after open.
  • To ensure normal playback, pay attention to the following when calling switchSrc(src, true):
  • Do not call this method when playback is paused.
  • Do not call seekToPosition during switching.
  • Before switching the media resource, ensure that the playback position does not exceed the total duration of the media resource to be switched.

Declared In

AgoraMediaPlayerKit.h

– addPreloadSrc:startPos:

Preloads media resources.

- (void)addPreloadSrc:(NSString *)src startPos:(NSInteger)startPos

Parameters

src

The URL address of the preloaded media resource. HTTP, RTMP, and RTSP protocols are supported for local and online media streams.
startPos

The starting position (milliseconds) when starting to play after preloading to the playlist. When preloading a live stream, set startPos to 0.

Discussion

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 addPreloadSrc, if you receive the didPreloadEvent callback event AgoraMediaPlayerPreloadEventComplete, the preload is successful; if you receive the didPreloadEvent callback event AgoraMediaPlayerPreloadEventError, the preload fails.

After the preload is successful, if you want to play the media resource, call playPreload; if you want to clear the playlist, call stop.

Note:

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.

Declared In

AgoraMediaPlayerKit.h

– playPreload:

Plays preloaded media resources.

- (void)playPreload:(NSString *)src

Parameters

src

The URL address of the media resource in the playlist. This address must be consistent with the src set by the addPreloadSrc method; otherwise, the media resource cannot be played.

Discussion

This method only supports playing media resources that have been preloaded into the playlist. After calling this method, if you receive the didChangedToState callback to report the state AgoraMediaPlayerStatePlaying, the playback is successful.

If you want to change the preloaded media resource to be played, you can call this method again and specify a new media resource path. If you want to replay the media resource, you need to call addPreloadSrc to preload the media resource to the playlist again before playing. If you want to clear the playlist, call stop.

Note:

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

Declared In

AgoraMediaPlayerKit.h