# 音视频观测器 (/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## registerAudioFrameObserver [1/2] [#registeraudioframeobserver-12]
注册一个 [IAudioPcmFrameSink](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudiopcmframesink) 音频帧观察者对象。
```cpp
virtual int registerAudioFrameObserver(media::IAudioPcmFrameSink* observer) = 0;
```
你需要实现 [IAudioPcmFrameSink](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudiopcmframesink) 类,并根据业务场景注册回调。注册成功后,每当接收到音频帧时,SDK 会触发对应的回调。
### 参数 [#参数]
音频帧观察者对象,详见 [IAudioPcmFrameSink](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudiopcmframesink)。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)
## registerAudioFrameObserver [2/2] [#registeraudioframeobserver-22]
注册音频帧观测器对象。
```cpp
virtual int registerAudioFrameObserver(media::IAudioPcmFrameSink* observer, RAW_AUDIO_FRAME_OP_MODE_TYPE mode) = 0;
```
### 参数 [#参数-1]
音频帧观测器对象。详见 [IAudioPcmFrameSink](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudiopcmframesink)。
音频帧的使用模式。详见 [RAW_AUDIO_FRAME_OP_MODE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-rawaudioframeopmodetype)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)
## registerPlayerSourceObserver [#registerplayersourceobserver]
注册媒体播放器观察器。
```cpp
virtual int registerPlayerSourceObserver(IMediaPlayerSourceObserver* observer) = 0;
```
用于监听播放过程中的事件。
### 调用时机 [#调用时机]
该方法可以在加入频道前或加入频道后调用。
### 参数 [#参数-2]
用于监听播放过程中的事件。详见 [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)
## registerVideoFrameObserver [#registervideoframeobserver]
注册视频帧观察器对象。
```cpp
virtual int registerVideoFrameObserver(media::base::IVideoFrameObserver* observer) = 0;
```
你需要实现 [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) 类,并根据你的使用场景注册回调。成功注册视频帧观察器后,SDK 每次接收到视频帧时都会触发已注册的回调。
### 参数 [#参数-3]
视频帧观察器。详见 [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)
## unregisterAudioFrameObserver [#unregisteraudioframeobserver]
取消注册音频帧观察器。
```cpp
virtual int unregisterAudioFrameObserver(media::IAudioPcmFrameSink* observer) = 0;
```
### 参数 [#参数-4]
音频帧观察器。详见 [IAudioPcmFrameSink](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudiopcmframesink)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)
## unregisterPlayerSourceObserver [#unregisterplayersourceobserver]
释放媒体播放器观察者。
```cpp
virtual int unregisterPlayerSourceObserver(IMediaPlayerSourceObserver* observer) = 0;
```
### 参数 [#参数-5]
媒体播放器观察者,用于监听播放过程中的事件。详见 [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)
## unregisterVideoFrameObserver [#unregistervideoframeobserver]
取消注册视频帧观察器。
```cpp
virtual int unregisterVideoFrameObserver(agora::media::base::IVideoFrameObserver* observer) = 0;
```
### 参数 [#参数-6]
视频帧观察器。详见 [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver)。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [IMediaPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayer)
## onAudioVolumeIndication [#onaudiovolumeindication]
报告媒体播放器音量的回调。
```cpp
virtual void onAudioVolumeIndication(int volume) = 0;
```
该回调每 200 毫秒触发一次。
### 参数 [#参数-7]
媒体播放器的音量,取值范围为 0 到 255。
### 所属接口类 [#所属接口类-7]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onFrame [#onframe]
[onFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_iaudiopcmframesink_onframe_iaudiopcmframesink) 回调。每次播放器接收到音频帧时触发。
```cpp
virtual void onFrame(agora::media::base::AudioPcmFrame* frame) = 0;
```
注册音频帧观察器后,每次播放器接收到音频帧时,都会触发该回调,并报告该音频帧的详细信息。
### 触发时机 [#触发时机]
每次播放器接收到音频帧时触发。
### 参数 [#参数-8]
音频帧信息,详见 [AudioPcmFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/class-audiopcmframe)。
### 所属接口类 [#所属接口类-8]
- [IAudioPcmFrameSink](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_iaudiopcmframesink)
## onMetaData [1/2] [#onmetadata-12]
接收到媒体元数据时触发的回调。
```cpp
virtual void onMetaData(const void* data, int length) = 0;
```
该回调在播放器接收到媒体元数据时触发。
### 参数 [#参数-9]
媒体元数据的详细数据。
数据长度,单位为字节。
### 所属接口类 [#所属接口类-9]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onPlayBufferUpdated [#onplaybufferupdated]
报告缓冲数据可支持的播放时长。
```cpp
virtual void onPlayBufferUpdated(int64_t playCachedBuffer) = 0;
```
当播放在线媒体资源时,SDK 每两秒触发一次该回调,用于报告当前缓冲数据可支持的播放时长。
- 当缓冲数据可支持的播放时长小于阈值(默认值为 0)时,SDK 返回 `PLAYER_EVENT_BUFFER_LOW`(6)。
- 当缓冲数据可支持的播放时长大于阈值(默认值为 0)时,SDK 返回 `PLAYER_EVENT_BUFFER_RECOVER`(7)。
### 触发时机 [#触发时机-1]
播放在线媒体资源时,SDK 每两秒触发一次该回调。
### 参数 [#参数-10]
缓冲数据可支持的播放时长,单位为毫秒。
### 所属接口类 [#所属接口类-10]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onPlayerEvent [#onplayerevent]
播放器事件回调。
```cpp
virtual void onPlayerEvent(media::base::MEDIA_PLAYER_EVENT eventCode, int64_t elapsedTime, const char* message) = 0;
```
调用 [seek](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 方法后,SDK 会触发该回调报告 [seek](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_seek) 操作的结果。
### 参数 [#参数-11]
播放器事件,详见 [MEDIA_PLAYER_EVENT](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediaplayerevent)。
事件发生的时间,单位为毫秒。
事件的相关信息。
### 所属接口类 [#所属接口类-11]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onPlayerInfoUpdated [1/2] [#onplayerinfoupdated-12]
`onPlayerInfoUpdated` 回调:当媒体播放器信息发生变化时触发。
```cpp
virtual void onPlayerInfoUpdated(const media::base::PlayerUpdatedInfo& info) = 0;
```
你可以通过该回调获取媒体播放器信息的变化,用于故障排查。
### 参数 [#参数-12]
媒体播放器相关信息。详见 [PlayerUpdatedInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-playerupdatedinfo)。
### 所属接口类 [#所属接口类-12]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onPlayerSourceStateChanged [#onplayersourcestatechanged]
播放状态变化回调。
```cpp
virtual void onPlayerSourceStateChanged(media::base::MEDIA_PLAYER_STATE state, media::base::MEDIA_PLAYER_REASON reason) = 0;
```
当媒体播放器状态发生变化时,SDK 会触发该回调报告当前播放状态。
### 参数 [#参数-13]
播放状态。详见 [MEDIA_PLAYER_STATE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediaplayerstate)。
播放状态变化的原因。详见 [MEDIA_PLAYER_REASON](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediaplayerreason)。
### 所属接口类 [#所属接口类-13]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onPlayerSrcInfoChanged [#onplayersrcinfochanged]
媒体资源视频码率发生变化时触发的回调。
```cpp
virtual void onPlayerSrcInfoChanged(const media::base::SrcInfo& from, const media::base::SrcInfo& to) = 0;
```
### 参数 [#参数-14]
正在播放的媒体资源的视频码率信息。详见 [SrcInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-srcinfo)。
变更后的视频码率信息。详见 [SrcInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-srcinfo)。
### 所属接口类 [#所属接口类-14]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onPositionChanged [#onpositionchanged]
播放进度发生变化回调。
```cpp
virtual void onPositionChanged(int64_t positionMs, int64_t timestampMs) = 0;
```
该回调在播放媒体文件时每两秒触发一次,用于报告当前播放进度。
### 参数 [#参数-15]
媒体文件的播放位置,单位为毫秒。
当前播放进度对应的 NTP 时间戳,单位为毫秒。
:::note
注: 该参数仅在频道内生效。
:::
### 所属接口类 [#所属接口类-15]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onPreloadEvent [#onpreloadevent]
预加载媒体资源事件回调。
```cpp
virtual void onPreloadEvent(const char* src, media::base::PLAYER_PRELOAD_EVENT event) = 0;
```
### 参数 [#参数-16]
媒体资源的 URL。
预加载媒体资源时触发的事件,详见 [PLAYER_PRELOAD_EVENT](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-playerpreloadevent)。
### 所属接口类 [#所属接口类-16]
- [IMediaPlayerSourceObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayersourceobserver)
## onReadData [#onreaddata]
SDK 读取媒体资源数据时触发的回调。
```cpp
virtual int onReadData(unsigned char *buffer, int bufferSize) = 0;
```
当你调用 [openWithMediaSource](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 方法打开媒体资源时,SDK 会触发该回调,并请求你传入媒体资源数据的缓冲区。
### 参数 [#参数-17]
输出参数,表示数据缓冲区(字节)。你需要将 SDK 请求的 `bufferSize` 大小的数据写入该缓冲区。
数据缓冲区的长度(字节)。
### 返回值 [#返回值-7]
- 如果数据读取成功,返回实际读取的数据长度(字节)。
- 如果读取失败,返回 0。
### 所属接口类 [#所属接口类-17]
- [IMediaPlayerCustomDataProvider](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaplayercustomdataprovider)