AgoraRtcMediaPlayerProtocol
This class provides media player functions and supports multiple instances.
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 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;
Returns
- If the method call succeeds, the SDK returns the total duration(ms) of the media file.
- ≤ 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;
Returns
- 0: Mute.
- 100: (Default) The original volume.
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
- The remote playback volume, if the method call succeeds.
- < 0: Failure.
getPlayerState
Gets current playback state.
- (AgoraMediaPlayerState)getPlayerState;
Returns
The current playback state. See AgoraMediaPlayerState.
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;
Returns
YES
: Reports whether the media resource is muted.NO
: Reports whether the media resource is muted.
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.
didReceiveAudioFrame
Occurs each time the player receives an audio frame.
- (void)AgoraRtcMediaPlayer:(id<AgoraRtcMediaPlayerProtocol> _Nonnull)playerKit didReceiveAudioFrame:(CMSampleBufferRef _Nonnull)audioFrame;
After registering the audio frame observer, the callback occurs every time the player receives an audio frame, reporting the detailed information of the audio frame.
Parameters
- audioFrame
- Audio frame information (CMSampleBufferRef).
- playerKit
- See AgoraRtcMediaPlayerProtocol.
didReceiveVideoFrame
Occurs each time the player receives a video frame.
- (void)AgoraRtcMediaPlayer:(id<AgoraRtcMediaPlayerProtocol> _Nonnull)playerKit didReceiveVideoFrame:(CVPixelBufferRef _Nonnull)pixelBuffer;public virtual bool OnFrame(VideoFrame audioFrame, VideoFrameBufferConfig config) { return true; }
After registering the video frame observer, the callback occurs every time the player receives a video frame, reporting the detailed information of the video frame.
Parameters
- playerKit
- See AgoraRtcMediaPlayerProtocol.
- pixelBuffer
- The texture's Buffer (CVPixelBufferRef).
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 openWithMediaSource 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. See AgoraRtcMediaPlayerProtocol.
- buffer
- An input parameter. Data buffer (bytes). Write the bufferSize data reported by the SDK into this parameter.
- 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 openWithMediaSource 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. 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;
This method is called asynchronously.
If you need to play a media file, make sure you receive the didChangedToState callback reporting AgoraMediaPlayerStateOpenCompleted before calling the play method to play the file.
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.
openWithCustomSourceAtStartPos
Opens the custom media resource file.
- (int)openWithCustomSourceAtStartPos:(NSInteger)startPos withPlayerOnReadData:(AgoraRtcMediaPlayerCustomSourceOnReadCallback)onReadDataCallback andPlayerOnSeek:(AgoraRtcMediaPlayerCustomSourceOnSeekCallback)onSeekCallback;
- Deprecated:
- This method is deprecated. Use openWithMediaSource instead.
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. The default value is 0.
- onReadDataCallBack
- Occurs when the SDK reads the media resource data. See AgoraRtcMediaPlayerCustomSourceOnReadCallback.
- onSeekCallBack
- Occurs when the SDK seeks the media resource data. See AgoraRtcMediaPlayerCustomSourceOnSeekCallback.
Returns
- 0: Success.
- < 0: Failure.
openWithMediaSource
Opens a media file and configures the playback scenarios.
- (int)openWithMediaSource:(AgoraMediaSource *)source;
This method supports opening media files of different sources, including a custom media source, and allows you to configure the playback scenarios.
Parameters
- source
- Media resources. See AgoraMediaSource.
Returns
- 0: Success.
- < 0: Failure.
pause
Pauses the playback.
- (int)pause;
Returns
- 0: Success.
- < 0: Failure.
play
Plays the media file.
- (int)play;
After calling open or seekToPosition, you can call this method to play the media file.
Returns
- 0: Success.
- < 0: Failure.
playPreloadedSrc
Plays preloaded media resources.
- (int)playPreloadedSrc:(NSString *)src;
After calling the preloadSrc 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 didChangedToState 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 to preload the media resource to the playlist again before playing. If you want to clear the playlist, call the stop method.
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 method; otherwise, the media resource cannot be played.
Returns
- 0: Success.
- < 0: Failure.
preloadSrc
Preloads a media resource.
- (int)preloadSrc:(NSString *)src startPos:(int)startPos;
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 didPreloadEvent callback, the preload is successful; If you receive the AgoraMediaPlayerPreloadEventError event in the 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.
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.
resume
Resumes playing the media file.
- (int)resume;
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.
- 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.
selectAudioTrack
Selects the audio track used during playback.
- (int)selectAudioTrack:(NSInteger)index;
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.
- For the supported formats of audio files, see https://docs.agora.io/en/faq/audio_format.
- You need to call this method after calling startAudioMixing [2/2] and receiving the
audioMixingStateChanged(AgoraAudioMixingStateTypePlaying)
callback.
Parameters
- index
- The audio track you want to specify. The value range is [0, getAudioTrackCount()].
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.
- Call this method after calling open.
- This method only applies to stereo audio files.
Parameters
- mode
- The channel mode. See AgoraAudioDualMonoMode.
Returns
- 0: Success.
- < 0: Failure.
setAudioPitch
Sets the pitch of the current media resource.
- (int)setAudioPitch:(NSInteger)pitch;
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.
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.
- Ensure that you call this method before open.
- If you need to push streams with SEI into the CDN, callsetPlayerOption
("sei_data_with_uuid", 1)
; otherwise, the loss of SEI might occurs.
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 AgoraVideoRenderMode.
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.
switchSrc
Switches the media resource being played.
- (int)switchSrc:(NSString *)src syncPts:(BOOL)sync;
- 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 didOccurEvent event in the AgoraMediaPlayerEventSwitchComplete callback, the switch is successful; If you receive the didOccurEvent event in the AgoraMediaPlayerEventSwitchError callback, the switch fails.
- Ensure that you call this method after open.
- 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.
Make sure to set this parameter as
NO
if you need to play live streams, or the switch fails. If you need to play on-demand streams, you can set the value of this parameter according to your scenarios.
Returns
- 0: Success.
- < 0: Failure.
unloadSrc
Unloads media resources that are preloaded.
- (int)unloadSrc:(NSString *)src;
This method cannot release the media resource being played.
Parameters
- src
- The URL of the media resource.
Returns
- 0: Success.
- < 0: Failure.