# 音视频观测器 (/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-observer)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## AgoraRtcMediaPlayerGetVideoPixelFormat [#agorartcmediaplayergetvideopixelformat]
设置原始视频数据的格式。
```objc
- (AgoraVideoFormat)AgoraRtcMediaPlayerGetVideoPixelFormat NS_SWIFT_NAME(AgoraRtcMediaPlayerGetVideoPixelFormat());
```
你需要在调用 [setVideoFrameDelegate:](/zh-CN/api-reference/rtc/macos/video/video-raw#api_irtcengine_registervideoframeobserver) 方法时注册回调。当媒体播放器接收到每一帧视频时,会触发该回调。你可以在该回调的返回值中设置期望的视频数据格式。
### 返回值 [#返回值]
你为原始视频数据设置的期望格式,详见 [AgoraVideoFormat](/zh-CN/api-reference/rtc/macos/enum-videopixelformat)。默认情况下,原始视频像素格式(`AgoraVideoFormatDefault`)可能是 `I420` 或 `CVPixelBufferRef`。
### 所属接口类 [#所属接口类]
- [AgoraRtcMediaPlayerVideoFrameDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_agorartcmediaplayervideoframedelegate)
## AgoraRtcMediaPlayer\:didReceivePixelBuffer: [#agorartcmediaplayerdidreceivepixelbuffer]
媒体播放器接收到视频源的像素缓冲区时触发的回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didReceivePixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didReceivePixelBuffer:));
```
触发该回调以报告类型为 `CVPixelBufferRef` 的像素缓冲区的详细信息。你可以使用这些信息进行图像处理与分析、自定义渲染等。
### 调用时机 [#调用时机]
该回调在媒体播放器接收到视频源的像素缓冲区时被触发。
### 参数 [#参数]
媒体播放器对象,详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
包含像素缓冲区详细信息的 `CVPixelBufferRef` 对象。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcMediaPlayerVideoFrameDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_agorartcmediaplayervideoframedelegate)
## AgoraRtcMediaPlayer\:didReceiveVideoFrame: [#agorartcmediaplayerdidreceivevideoframe]
每次播放器接收到视频帧时触发的回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didReceiveVideoFrame:(AgoraOutputVideoFrame * _Nonnull)videoFrame NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didReceiveVideoFrame:));
```
### 调用时机 [#调用时机-1]
该回调在播放器每次接收到视频帧时被触发。
### 参数 [#参数-1]
播放器对象。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
视频帧信息。详见 [AgoraOutputVideoFrame](/zh-CN/api-reference/rtc/macos/class-videoframe)。
### 所属接口类 [#所属接口类-2]
- [AgoraRtcMediaPlayerVideoFrameDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_agorartcmediaplayervideoframedelegate)
## AgoraRtcMediaPlayer\:volumeIndicationDidReceive: [#agorartcmediaplayervolumeindicationdidreceive]
报告媒体播放器的音量。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
volumeIndicationDidReceive:(NSInteger)volume NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:volumeIndicationDidReceive:));
```
该回调每 200 毫秒触发一次,用于报告当前媒体播放器的音量。
### 触发时机 [#触发时机]
该回调每 200 毫秒触发一次。
### 参数 [#参数-2]
[AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer) 实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
媒体播放器的音量,取值范围为 0 到 255。
### 所属接口类 [#所属接口类-3]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:didReceiveAudioFrame: [#agorartcmediaplayerdidreceiveaudioframe]
每次播放器接收到音频帧时触发的回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didReceiveAudioFrame:(AgoraAudioFrame* _Nonnull)audioFrame NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didReceiveAudioFrame:));
```
注册音频帧观察器后,每次播放器接收到音频帧时,都会触发该回调,报告音频帧的详细信息。
### 触发时机 [#触发时机-1]
每次播放器接收到音频帧时触发。
### 参数 [#参数-3]
播放器实例,详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
音频帧信息,详见 [AgoraAudioFrame](/zh-CN/api-reference/rtc/macos/class-audioframe)。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcMediaPlayerAudioFrameDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_iaudiopcmframesink)
## AgoraRtcMediaPlayer\:didReceiveData\:length: [#agorartcmediaplayerdidreceivedatalength]
接收到媒体元数据时触发的回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didReceiveData:(NSString *_Nullable)data
length:(NSInteger)length NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didReceiveData:length:));
```
播放器接收到媒体元数据时,会触发该回调并上报媒体元数据的详细信息。
### 触发时机 [#触发时机-2]
该回调在播放器接收到媒体元数据时触发。
### 参数 [#参数-4]
播放器实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
媒体元数据的详细数据。
数据长度(字节)。
### 所属接口类 [#所属接口类-5]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:didPlayBufferUpdated: [#agorartcmediaplayerdidplaybufferupdated]
报告缓冲数据可支持的播放时长。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didPlayBufferUpdated:(NSInteger)playCachedBuffer NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didPlayBufferUpdated:));
```
- 当缓冲数据可支持的播放时长小于阈值(默认值为 0)时,SDK 返回 `AgoraMediaPlayerEventBufferLow`(6)。
- 当缓冲数据可支持的播放时长大于阈值(默认值为 0)时,SDK 返回 `AgoraMediaPlayerEventBufferRecover`(7)。
### 触发时机 [#触发时机-3]
播放在线媒体资源时,SDK 每两秒触发一次该回调。
### 参数 [#参数-5]
播放器实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
缓冲数据可支持的播放时长(毫秒)。
### 所属接口类 [#所属接口类-6]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:didOccurEvent\:elapsedTime\:message: [#agorartcmediaplayerdidoccureventelapsedtimemessage]
上报播放器事件。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didOccurEvent:(AgoraMediaPlayerEvent)eventCode
elapsedTime:(NSInteger)elapsedTime
message:(NSString *_Nullable)message NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didOccur:elapsedTime:message:));
```
调用 [seekToPosition:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 方法后,SDK 会触发该回调,上报跳转播放位置操作的结果。
### 触发时机 [#触发时机-4]
该回调在你调用 [seekToPosition:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 方法后触发,用于上报跳转播放位置操作的结果。
### 参数 [#参数-6]
播放器实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
播放器事件类型。详见 [AgoraMediaPlayerEvent](/zh-CN/api-reference/rtc/macos/enum-mediaplayerevent)。
事件发生的时间,单位为毫秒。
事件的相关信息。
### 所属接口类 [#所属接口类-7]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:infoUpdated: [#agorartcmediaplayerinfoupdated]
媒体播放器相关信息发生变化时的回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit infoUpdated:(AgoraMediaPlayerUpdatedInfo *_Nonnull)info NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:infoUpdated:));
```
你可以通过该回调获取媒体播放器的最新信息,用于故障排查。
### 触发时机 [#触发时机-5]
该回调在媒体播放器相关信息发生变化时被触发。
### 参数 [#参数-7]
媒体播放器对象。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
媒体播放器相关的信息。详见 [AgoraMediaPlayerUpdatedInfo](/zh-CN/api-reference/rtc/macos/class-playerupdatedinfo)。
### 所属接口类 [#所属接口类-8]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:didChangedToState\:reason: [#agorartcmediaplayerdidchangedtostatereason]
播放状态发生变化时触发的回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didChangedToState:(AgoraMediaPlayerState)state
reason:(AgoraMediaPlayerReason)reason NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didChangedTo:reason:));
```
播放状态发生变化时触发的回调。
### 触发时机 [#触发时机-6]
该回调在媒体播放器播放状态发生变化时被触发。
### 参数 [#参数-8]
媒体播放器实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
播放状态。详见 [AgoraMediaPlayerState](/zh-CN/api-reference/rtc/macos/enum-mediaplayerstate)。
播放状态变化的原因。详见 [AgoraMediaPlayerReason](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason)。
### 所属接口类 [#所属接口类-9]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:playerSrcInfoDidChange\:from: [#agorartcmediaplayerplayersrcinfodidchangefrom]
媒体文件播放源信息变化回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit playerSrcInfoDidChange:(AgoraMediaPlayerSrcInfo *_Nonnull)to from:(AgoraMediaPlayerSrcInfo *_Nonnull)from NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:playerSrcInfoDidChange:from:));
```
该回调在播放媒体文件过程中每两秒触发一次,用于报告播放源信息的变化。
### 触发时机 [#触发时机-7]
该回调在播放媒体文件过程中每两秒触发一次。
### 参数 [#参数-9]
播放器实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
变更后的媒体播放器源信息。详见 [AgoraMediaPlayerSrcInfo](/zh-CN/api-reference/rtc/macos/class-srcinfo)。
变更前的媒体播放器源信息。详见 [AgoraMediaPlayerSrcInfo](/zh-CN/api-reference/rtc/macos/class-srcinfo)。
### 所属接口类 [#所属接口类-10]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:didChangedToPosition\:atTimestamp: [#agorartcmediaplayerdidchangedtopositionattimestamp]
播放进度回调。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didChangedToPosition:(NSInteger)positionMs
atTimestamp:(NSTimeInterval)timestampMs NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didChangedTo:atTimestamp:));
```
该回调在播放过程中每秒触发一次,用于报告当前播放进度。
### 触发时机 [#触发时机-8]
该回调在播放过程中每秒触发一次。
### 参数 [#参数-10]
播放器实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
当前播放进度,单位为毫秒。
发送 `positionMs` 时的 NTP 时间戳,单位为毫秒。
:::note
注: 该参数仅在频道内生效。
:::
### 所属接口类 [#所属接口类-11]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)
## AgoraRtcMediaPlayer\:didPreloadEvent: [#agorartcmediaplayerdidpreloadevent]
上报预加载媒体资源的事件。
```objc
- (void)AgoraRtcMediaPlayer:(id _Nonnull)playerKit
didPreloadEvent:(AgoraMediaPlayerPreloadEvent)event NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:didPreloadEvent:));
```
### 触发时机 [#触发时机-9]
该回调在媒体资源预加载过程中发生事件时被触发。
### 参数 [#参数-11]
播放器实例,详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。
预加载媒体资源时发生的事件,详见 [AgoraMediaPlayerPreloadEvent](/zh-CN/api-reference/rtc/macos/enum-playerpreloadevent)。
### 所属接口类 [#所属接口类-12]
- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)