# 媒体播放器 (/zh-CN/realtime-media/rtc/build/audio/media-player)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" />
## 前提条件 [#前提条件]
本文介绍如何调用媒体播放器相关的 API 播放本地或在线媒体资源,或将媒体资源分享给声网频道内的远端用户。在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。有关详细信息,请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法]
参考如下步骤,在你的项目中使用媒体播放器:
1. 初始化 `RtcEngine` 后,创建一个 `IMediaPlayer` 对象,并调用 `registerPlayerObserver` 方法注册播放观测器。
```java
engine = RtcEngine.create(config);
...
// 创建媒体播放器对象
mediaPlayer = engine.createMediaPlayer();
// 注册播放观测器
mediaPlayer.registerPlayerObserver(this);
```
2. 实现媒体播放器观测器的回调。根据你的需求,你可以通过 `onPlayerStateChanged` 回调来观测播放器的状态,通过 `onPositionChanged` 回调来获取当前媒体文件的播放进度,通过 `onPlayerEvent` 来获取播放器事件。
```java
@Override
// 报告播放器的状态
public void onPlayerStateChanged(io.agora.mediaplayer.Constants.MediaPlayerState mediaPlayerState, io.agora.mediaplayer.Constants.MediaPlayerError mediaPlayerError) {
Log.e(TAG, "onPlayerStateChanged mediaPlayerState " + mediaPlayerState);
Log.e(TAG, "onPlayerStateChanged mediaPlayerError " + mediaPlayerError);
if (mediaPlayerState.equals(PLAYER_STATE_OPEN_COMPLETED)) {
setMediaPlayerViewEnable(true);
} else if (mediaPlayerState.equals(PLAYER_STATE_IDLE) || mediaPlayerState.equals(PLAYER_STATE_PLAYBACK_COMPLETED) ) {
setMediaPlayerViewEnable(false);
}
}
@Override
// 报告当前播放进度
public void onPositionChanged(long position) {
Log.e(TAG, "onPositionChanged position " + position);
if (playerDuration > 0) {
final int result = (int) ((float) position / (float) playerDuration * 100);
handler.post(new Runnable() {
@Override
public void run() {
progressBar.setProgress(Long.valueOf(result).intValue());
}
});
}
}
@Override
// 报告播放器事件
public void onPlayerEvent(io.agora.mediaplayer.Constants.MediaPlayerEvent mediaPlayerEvent) {
Log.e(TAG, " onPlayerEvent mediaPlayerEvent " + mediaPlayerEvent);
}
```
3. 调用 `setupLocalVideo` 方法渲染本地媒体播放视图。
```java
VideoCanvas videoCanvas = new VideoCanvas(surfaceView, Constants.RENDER_MODE_HIDDEN, Constants.VIDEO_MIRROR_MODE_AUTO,
Constants.VIDEO_SOURCE_MEDIA_PLAYER, mediaPlayer.getMediaPlayerId(), 0);
engine.setupLocalVideo(videoCanvas);
```
4. 调用 `joinChannel` 加入频道时,通过 `options` 参数设置媒体播放器 ID、发布媒体播放器的音视频、将媒体资源分享给声网频道内的远端用户。
```java
private ChannelMediaOptions options = new ChannelMediaOptions();
...
options.publishMediaPlayerId = mediaPlayer.getMediaPlayerId();
options.publishMediaPlayerAudioTrack = true;
options.publishMediaPlayerVideoTrack = true;
int res = engine.joinChannel(accessToken, channelId, 0, options);
```
5. 调用 `open` 打开本地或在线媒体文件。
```java
mediaPlayer.open(url, 0);
```
6. 调用 `play` 播放媒体文件。
:::warning[注意]
请在收到 `onPlayerStateChanged` 回调报告播放状态为 `PLAYER_STATE_OPEN_COMPLETED` 后再调用 `play` 方法播放媒体文件。
:::
```java
mediaPlayer.play();
```
7. 当用户离开频道时,调用 `stop` 停止播放、调用 `unRegisterPlayerObserver` 取消注册播放观测器、调用 `destroy` 销毁媒体播放器并释放已分配的资源。
```java
mediaPlayer.stop();
mediaPlayer.unRegisterPlayerObserver(this);
mediaPlayer.destroy();
```
## 参考信息 [#参考信息]
### 示例项目 [#示例项目]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### 支持的格式 [#支持的格式]
声网的媒体播放器支持下列格式及协议:
**视频编码格式**
- H.263、H.264、H.265、MPEG4、MPEG2、RMVB、Theora、VP3、VP8、AVS、WMV
**音频编码格式**
- WAV、MP2、MP3、AAC、OPUS、FLAC、Vorbis、AMR-NB、AMR-WB、WMA v1、WMA v2
**容器格式**
- WAV、FLAC、OGG、MOV、ASF、FLV、MP3、MP4、MPEG-TS、Matroska (MKV)、AVI、ASS、CONCAT、DTS、AVS
**支持的协议**
- HTTP、HTTPS、RTMP、HLS、RTP、RTSP
### API 参考 [#api-参考]
- [`createMediaPlayer`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer)
- [`destroy`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-initialize#api_imediaplayer_destroy_imediaplayer)
- [`registerPlayerObserver`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#api_imediaplayer_registerplayersourceobserver)
- [`unRegisterPlayerObserver`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#api_imediaplayer_unregisterplayersourceobserver)
- [`getMediaPlayerId`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid)
- [`open`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-open#api_imediaplayer_open)
- [`play`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-control#api_imediaplayer_play)
- [`pause`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause)
- [`stop`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-control#api_imediaplayer_stop)
- [`onPlayerSourceStateChanged`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged)
- [`onPositionChanged`](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onpositionchanged)
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" />
本文介绍如何调用媒体播放器相关的 API 播放本地或在线媒体资源,或将媒体资源同步分享给声网频道内的远端用户。
## 前提条件 [#前提条件-1]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-1]
参考如下步骤,在你的项目中使用媒体播放器:
1. 初始化 `AgoraRtcEngineKit` 后,调用 `createMediaPlayer` 创建 `AgoraRtcMediaPlayerProtocol` 对象。
```swift
// 初始化 AgoraRtcEngineKit
agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
// 创建 mediaPlayerKit 对象
mediaPlayerKit = agoraKit.createMediaPlayer(with: self)
```
2. 实现媒体播放器回调。根据你的需求,你可以通过 `didChangedToState` 回调来观测播放器的状态,通过 `didChangedToPosition` 回调来获取当前媒体文件的播放进度。
```swift
extension MediaPlayerMain: AgoraRtcMediaPlayerDelegate {
// 报告播放器的状态
func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedTo state: AgoraMediaPlayerState, error: AgoraMediaPlayerError) {
LogUtils.log(message: "player rtc channel publish helper state changed to: \(state.rawValue), error: \(error.rawValue)", level: .info)
DispatchQueue.main.async { [weak self] in
guard let weakself = self else { return }
switch state {
case .failed:
weakself.showAlert(message: "media player error: \(error.rawValue)")
break
case .openCompleted:
let duration = weakself.mediaPlayerKit.getDuration()
weakself.playerControlStack.isHidden = false
weakself.playerDurationLabel.text = "\(String(format: "%02d", duration / 60)) : \(String(format: "%02d", duration % 60))"
weakself.playerProgressSlider.setValue(0, animated: true)
break
case .stopped:
weakself.playerControlStack.isHidden = true
weakself.playerProgressSlider.setValue(0, animated: true)
weakself.playerDurationLabel.text = "00 : 00"
break
default: break
}
}
}
// 报告当前的播放进度
func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedToPosition position: Int) {
let duration = Float(mediaPlayerKit.getDuration() * 1000)
var progress: Float = 0
var left: Int = 0
if duration > 0 {
progress = Float(mediaPlayerKit.getPosition()) / duration
left = Int((mediaPlayerKit.getDuration() * 1000 - mediaPlayerKit.getPosition()) / 1000)
}
DispatchQueue.main.async { [weak self] in
guard let weakself = self else { return }
weakself.playerDurationLabel.text = "\(String(format: "%02d", left / 60)) : \(String(format: "%02d", left % 60))"
if !weakself.playerProgressSlider.isTouchInside {
weakself.playerProgressSlider.setValue(progress, animated: true)
}
}
}
}
```
3. 调用 `setupLocalVideo` 渲染本地媒体播放视图。
```swift
mediaPlayerKit.setView(localVideo.videoView)
let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.view = localVideo.videoView
videoCanvas.renderMode = .hidden
videoCanvas.sourceType = .mediaPlayer
videoCanvas.sourceId = mediaPlayerKit.getMediaPlayerId()
agoraKit.setupLocalVideo(videoCanvas)
```
4. 调用 `joinChannelByToken` 加入频道时,通过 `mediaOptions` 设置媒体播放器 ID,发布媒体播放器的音视频,将媒体资源分享给声网频道内的远端用户。
```swift
let option1 = AgoraRtcChannelMediaOptions()
...
option1.publishMediaPlayerId = .of((Int32)(mediaPlayerKit.getMediaPlayerId()))
```
5. 调用 `open` 打开本地或在线媒体文件。
```swift
mediaPlayerKit.open(url, startPos: 0)
```
6. 调用 `play` 播放媒体文件。
:::warning[注意]
请在收到 `didChangedToState` 回调报告播放状态为 `AgoraMediaPlayerStateOpenCompleted` 后再调用 `play` 方法播放媒体文件。
:::
```swift
mediaPlayerKit.play()
```
7. 当用户离开频道时,调用 `stop` 停止播放、调用 `destroyMediaPlayer` 销毁媒体播放器、取消注册播放观测器,并销毁分配的资源。
```swift
mediaPlayerKit.stop()
agoraKit.destroyMediaPlayer(mediaPlayerKit)
```
## 参考信息 [#参考信息-1]
### 示例项目 [#示例项目-1]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### 支持的格式 [#支持的格式-1]
声网的媒体播放器支持下列格式及协议:
**视频编码格式**
- H.263、H.264、H.265、MPEG4、MPEG2、RMVB、Theora、VP3、VP8、AVS、WMV
**音频编码格式**
- WAV、MP2、MP3、AAC、OPUS、FLAC、Vorbis、AMR-NB、AMR-WB、WMA v1、WMA v2
**容器格式**
- WAV、FLAC、OGG、MOV、ASF、FLV、MP3、MP4、MPEG-TS、Matroska (MKV)、AVI、ASS、CONCAT、DTS、AVS
**支持的协议**
- HTTP、HTTPS、RTMP、HLS、RTP、RTSP
### API 参考 [#api-参考-1]
- [`createMediaPlayerWithDelegate`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer)
- [`destroyMediaPlayer`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer)
- [`getMediaPlayerId`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid)
- [`open`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-open#api_imediaplayer_open)
- [`play`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_play)
- [`pause`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause)
- [`stop`](/zh-CN/api-reference/rtc/ios/play/mediaplayer/mediaplayer-control#api_imediaplayer_stop)
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="macos" />
本文介绍如何调用媒体播放器相关的 API 播放本地或在线媒体资源,或将媒体资源同步分享给声网频道内的远端用户。
## 前提条件 [#前提条件-2]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-2]
参考如下步骤,在你的项目中使用媒体播放器:
1. 初始化 `AgoraRtcEngineKit` 后,调用 `createMediaPlayer` 创建 `AgoraRtcMediaPlayerProtocol` 对象。
```swift
// 初始化 AgoraRtcEngineKit
agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
// 创建 mediaPlayerKit 对象
mediaPlayerKit = agoraKit.createMediaPlayer(with: self)
```
2. 实现媒体播放器回调。根据你的需求,你可以通过 `didChangedToState` 回调来观测播放器的状态,通过 `didChangedToPosition` 回调来获取当前媒体文件的播放进度。
```swift
extension MediaPlayerMain: AgoraRtcMediaPlayerDelegate {
// 报告播放器的状态
func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedTo state: AgoraMediaPlayerState, error: AgoraMediaPlayerError) {
LogUtils.log(message: "player rtc channel publish helper state changed to: \(state.rawValue), error: \(error.rawValue)", level: .info)
DispatchQueue.main.async { [weak self] in
guard let weakself = self else { return }
switch state {
case .failed:
weakself.showAlert(message: "media player error: \(error.rawValue)")
break
case .openCompleted:
let duration = weakself.mediaPlayerKit.getDuration()
weakself.playerControlStack.isHidden = false
weakself.playerDurationLabel.text = "\(String(format: "%02d", duration / 60)) : \(String(format: "%02d", duration % 60))"
weakself.playerProgressSlider.setValue(0, animated: true)
break
case .stopped:
weakself.playerControlStack.isHidden = true
weakself.playerProgressSlider.setValue(0, animated: true)
weakself.playerDurationLabel.text = "00 : 00"
break
default: break
}
}
}
// 报告当前的播放进度
func agoraRtcMediaPlayer(_ playerKit: AgoraRtcMediaPlayerProtocol, didChangedToPosition position: Int) {
let duration = Float(mediaPlayerKit.getDuration() * 1000)
var progress: Float = 0
var left: Int = 0
if duration > 0 {
progress = Float(mediaPlayerKit.getPosition()) / duration
left = Int((mediaPlayerKit.getDuration() * 1000 - mediaPlayerKit.getPosition()) / 1000)
}
DispatchQueue.main.async { [weak self] in
guard let weakself = self else { return }
weakself.playerDurationLabel.text = "\(String(format: "%02d", left / 60)) : \(String(format: "%02d", left % 60))"
if !weakself.playerProgressSlider.isTouchInside {
weakself.playerProgressSlider.setValue(progress, animated: true)
}
}
}
}
```
3. 调用 `setupLocalVideo` 渲染本地媒体播放视图。
```swift
mediaPlayerKit.setView(localVideo.videoView)
let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.view = localVideo.videoView
videoCanvas.renderMode = .hidden
videoCanvas.sourceType = .mediaPlayer
videoCanvas.sourceId = mediaPlayerKit.getMediaPlayerId()
agoraKit.setupLocalVideo(videoCanvas)
```
4. 调用 `joinChannelByToken` 加入频道时,通过 `mediaOptions` 设置媒体播放器 ID,发布媒体播放器的音视频,将媒体资源分享给声网频道内的远端用户。
```swift
let option1 = AgoraRtcChannelMediaOptions()
...
option1.publishMediaPlayerId = .of((Int32)(mediaPlayerKit.getMediaPlayerId()))
```
5. 调用 `open` 打开本地或在线媒体文件。
```swift
mediaPlayerKit.open(url, startPos: 0)
```
6. 调用 `play` 播放媒体文件。
:::warning[注意]
请在收到 `didChangedToState` 回调报告播放状态为 `AgoraMediaPlayerStateOpenCompleted` 后再调用 `play` 方法播放媒体文件。
:::
```swift
mediaPlayerKit.play()
```
7. 当用户离开频道时,调用 `stop` 停止播放、调用 `destroyMediaPlayer` 销毁媒体播放器、取消注册播放观测器,并销毁分配的资源。
```swift
mediaPlayerKit.stop()
agoraKit.destroyMediaPlayer(mediaPlayerKit)
```
## 参考信息 [#参考信息-2]
### 示例项目 [#示例项目-2]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### 支持的格式 [#支持的格式-2]
声网的媒体播放器支持下列格式及协议:
**视频编码格式**
- H.263、H.264、H.265、MPEG4、MPEG2、RMVB、Theora、VP3、VP8、AVS、WMV
**音频编码格式**
- WAV、MP2、MP3、AAC、OPUS、FLAC、Vorbis、AMR-NB、AMR-WB、WMA v1、WMA v2
**容器格式**
- WAV、FLAC、OGG、MOV、ASF、FLV、MP3、MP4、MPEG-TS、Matroska (MKV)、AVI、ASS、CONCAT、DTS、AVS
**支持的协议**
- HTTP、HTTPS、RTMP、HLS、RTP、RTSP
### API 参考 [#api-参考-2]
- [`createMediaPlayerWithDelegate`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer)
- [`destroyMediaPlayer`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer)
- [`getMediaPlayerId`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid)
- [`open`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_open)
- [`play`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_play)
- [`pause`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause)
- [`stop`](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-control#api_imediaplayer_stop)
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="windows" />
本文介绍如何调用媒体播放器相关的 API 播放本地或在线媒体资源,或将媒体资源分享给声网频道内的远端用户。
## 前提条件 [#前提条件-3]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。有关详细信息,请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-3]
参考如下步骤,在你的项目中使用媒体播放器:
1. 初始化 `IRtcEngine` 后,创建一个 `IMediaPlayer` 对象。
```cpp
void CAgoraMediaPlayer::InitMediaPlayerKit() {
// 创建声网媒体播放器
m_mediaPlayer = m_rtcEngine->createMediaPlayer().get();
m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("createAgoraMediaPlayer"));
m_lstInfo.InsertString(m_lstInfo.GetCount(), _T("mediaplayer initialize"));
// 设置播放器渲染视图
RECT rc = {0};
m_localVideoWnd.GetWindowRect(&rc);
int ret = m_mediaPlayer->setView(
(agora::media::base::view_t)m_localVideoWnd.GetSafeHwnd());
// 设置接收播放器事件的窗口
m_mediaPlayerEvent.SetMsgReceiver(m_hWnd);
}
```
2. 调用 `registerPlayerSourceObserver` 方法注册播放观测器。
```cpp
void CAgoraMediaPlayer::OnBnClickedButtonJoinchannel() {
// ...
// 注册播放观测器
ret = m_mediaPlayer->registerPlayerSourceObserver(&m_mediaPlayerEvent);
m_lstInfo.InsertString(m_lstInfo.GetCount(),
_T("registerPlayerSourceObserver"));
if (0 ==
m_rtcEngine->joinChannel(APP_TOKEN, szChannelId.c_str(), 0, options)) {
strInfo.Format(_T("join channel %s, use ChannelMediaOptions"),
getCurrentTime());
}
}
else {
// 取消注册播放观测器
ret = m_mediaPlayer->unregisterPlayerSourceObserver(&m_mediaPlayerEvent);
m_lstInfo.InsertString(m_lstInfo.GetCount(),
_T("registerPlayerSourceObserver"));
// leave channel in the engine.
if (0 == m_rtcEngine->leaveChannel()) {
strInfo.Format(_T("leave channel %s"), getCurrentTime());
}
}
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
```
3. 实现媒体播放器观测器的回调。
```cpp
// 报告播放器状态改变
LRESULT CAgoraMediaPlayer::OnmediaPlayerStateChanged(WPARAM wParam,
LPARAM lParam) {
CString strState;
CString strError;
switch ((agora::media::base::MEDIA_PLAYER_STATE)wParam) {
case agora::media::base::PLAYER_STATE_OPEN_COMPLETED:
strState = _T("PLAYER_STATE_OPEN_COMPLETED");
m_mediaPlayerState = mediaPLAYER_OPEN;
int64_t duration;
m_mediaPlayer->getDuration(duration);
m_sldVideo.SetRangeMax((int)duration);
break;
// ...
}
switch ((agora::media::base::MEDIA_PLAYER_ERROR)lParam) {
case agora::media::base::PLAYER_ERROR_URL_NOT_FOUND:
strError = _T("PLAYER_ERROR_URL_NOT_FOUND");
break;
// ...
}
CString strInfo;
strInfo.Format(_T("sta:%s,\nerr:%s"), strState, strError);
m_lstInfo.InsertString(m_lstInfo.GetCount(), strInfo);
return TRUE;
}
// 报告当前播放进度
LRESULT CAgoraMediaPlayer::OnmediaPlayerPositionChanged(WPARAM wParam,
LPARAM lParam) {
int64_t *p = (int64_t *)wParam;
m_sldVideo.SetPos((int)*p);
delete p;
return TRUE;
}
```
4. 调用 `joinChannel` 加入频道时,通过 `options` 参数设置媒体播放器 ID,发布媒体播放器的音视频,将媒体资源分享给声网频道内的远端用户。
```cpp
void CAgoraMediaPlayer::OnBnClickedButtonPublishVideo() {
if (m_publishMeidaplayer) {
ChannelMediaOptions op;
op.clientRoleType = CLIENT_ROLE_BROADCASTER;
op.publishMediaPlayerVideoTrack = false;
op.publishMediaPlayerAudioTrack = false;
op.publishMediaPlayerId = m_mediaPlayer->getMediaPlayerId();
int ret = m_rtcEngine->updateChannelMediaOptions(op);
ChannelMediaOptions op2;
op2.clientRoleType = CLIENT_ROLE_BROADCASTER;
op2.publishCameraTrack = true;
ret = m_rtcEngine->updateChannelMediaOptions(op2);
m_publishMeidaplayer = false;
} else {
ChannelMediaOptions options;
options.clientRoleType = CLIENT_ROLE_BROADCASTER;
options.publishMediaPlayerVideoTrack = true;
options.publishMediaPlayerAudioTrack = true;
options.publishMediaPlayerId = m_mediaPlayer->getMediaPlayerId();
options.publishCameraTrack = false;
options.publishAudioTrack = false;
options.autoSubscribeAudio = false;
options.autoSubscribeVideo = false;
m_rtcEngine->updateChannelMediaOptions(options);
m_publishMeidaplayer = true;
}
}
```
5. 调用 `open` 打开本地或在线媒体文件。
```cpp
void CAgoraMediaPlayer::OnBnClickedButtonOpen() {
CString strUrl;
CString strInfo;
m_edtVideoSource.GetWindowText(strUrl);
std::string tmp = cs2utf8(strUrl);
switch (m_mediaPlayerState) {
case mediaPLAYER_READY:
case mediaPLAYER_STOP:
if (tmp.empty()) {
AfxMessageBox(_T("you can fill video source."));
return;
}
// 打开媒体文件
m_mediaPlayer->open(tmp.c_str(), 0);
break;
default:
m_lstInfo.InsertString(m_lstInfo.GetCount(),
_T("can not open player."));
break;
}
}
```
6. 调用 `play` 播放媒体文件。如果你需要暂停播放文件,可调用 `pause` 方法。
:::warning[注意]
请在收到 `onPlayerSourceStateChanged` 回调报告播放状态为 `PLAYER_STATE_OPEN_COMPLETED` 后再调用 `play` 方法播放媒体文件。
:::
```cpp
void CAgoraMediaPlayer::OnBnClickedButtonPlay() {
int ret;
switch (m_mediaPlayerState) {
case mediaPLAYER_PAUSE:
case mediaPLAYER_OPEN:
// 播放媒体文件
ret = m_mediaPlayer->play();
if (ret == 0) {
m_mediaPlayerState = mediaPLAYER_PLAYING;
}
break;
case mediaPLAYER_PLAYING:
// 暂停播放
ret = m_mediaPlayer->pause();
if (ret == 0) {
m_mediaPlayerState = mediaPLAYER_PAUSE;
}
break;
default:
break;
}
}
```
7. 当用户离开频道时,停止播放、销毁媒体播放器、取消注册播放观测器,并销毁分配的资源。
```cpp
void CAgoraMediaPlayer::OnBnClickedButtonStop() {
if (m_mediaPlayerState == mediaPLAYER_OPEN ||
m_mediaPlayerState == mediaPLAYER_PLAYING ||
m_mediaPlayerState == mediaPLAYER_PAUSE) {
// 停止播放
m_mediaPlayer->stop();
m_mediaPlayerState = mediaPLAYER_STOP;
}
}
void CAgoraMediaPlayer::OnDestroy() {
// 销毁媒体播放器
CDialogEx::OnDestroy();
UnInitMediaPlayerKit();
}
```
## 参考信息 [#参考信息-3]
### 示例项目 [#示例项目-3]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### 支持的格式 [#支持的格式-3]
声网的媒体播放器支持下列格式及协议:
**视频编码格式**
- H.263、H.264、H.265、MPEG4、MPEG2、RMVB、Theora、VP3、VP8、AVS、WMV
**音频编码格式**
- WAV、MP2、MP3、AAC、OPUS、FLAC、Vorbis、AMR-NB、AMR-WB、WMA v1、WMA v2
**容器格式**
- WAV、FLAC、OGG、MOV、ASF、FLV、MP3、MP4、MPEG-TS、Matroska (MKV)、AVI、ASS、CONCAT、DTS、AVS
**支持的协议**
- HTTP、HTTPS、RTMP、HLS、RTP、RTSP
### API 参考 [#api-参考-3]
- [`createMediaPlayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer)
- [`destroyMediaPlayer`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer)
- [`registerPlayerSourceObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#api_imediaplayer_registerplayersourceobserver)
- [`unregisterPlayerSourceObserver`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#api_imediaplayer_unregisterplayersourceobserver)
- [`getMediaPlayerId`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid)
- [`open`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-open#api_imediaplayer_open)
- [`play`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_play)
- [`pause`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause)
- [`stop`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_stop)
- [`onPlayerSourceStateChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged)
- [`onPositionChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onpositionchanged)
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="electron" />
本文介绍如何调用媒体播放器相关的 API 播放本地或在线媒体资源,或将媒体资源分享给声网频道内的远端用户。
## 前提条件 [#前提条件-4]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。有关详细信息,请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-4]
参考如下步骤,在你的项目中使用媒体播放器:
1. 初始化 `IRtcEngine` 后,创建一个 `IMediaPlayer` 对象。
```typescript
// 创建并初始化引擎
let rtcEngine = createAgoraRtcEngine();
rtcEngine.initialize({
appId,
});
// 创建媒体播放器对象
let mediaPlayer = rtcEngine.createMediaPlayer();
```
2. 调用 `registerPlayerSourceObserver` 方法注册播放观测器。
```typescript
// 注册播放观测器
mediaPlayer.registerPlayerSourceObserver(this);
```
3. 根据你的需求,你可以注册以下媒体播放器观测器的回调:
- `onPlayerSourceStateChanged`:报告播放器状态改变。
- `onPositionChanged`:报告当前媒体文件的播放进度。
- `onPlayerEvent`:报告播放器事件。
```typescript
const EventHandles = {
// 报告播放器状态改变
onPlayerSourceStateChanged: (state, ec) {
console.log(`state:${state}, ec:${ec}`);
};
// 报告当前媒体文件的播放进度
onPositionChanged: (position) {
console.log(`position:${position}`);
};
// 报告播放器事件
onPlayerEvent: (
eventCode,
elapsedTime,
message
) {
console.log(
`eventCode:${eventCode},
elapsedTime:${elapsedTime},
message:${message}`
);
};
};
// 添加主回调事件
rtcEngine.registerEventHandler(EventHandles);
```
4. 调用 `open` 打开本地或在线媒体文件。
```typescript
open = () => {
const url = 'https://example/video.mov';
if (!url) {
this.error("url is invalid");
}
mediaPlayer.open(url, 0);
};
```
5. 调用 `play` 播放媒体文件。
```typescript
// 播放媒体文件
play = () => {
const { position, duration } = this.state;
if (position === duration && duration !== 0) {
mediaPlayer.seek(0);
} else {
mediaPlayer.play();
}
};
// 暂停播放媒体文件
pause = () => {
mediaPlayer.pause();
};
// 恢复播放媒体文件
resume = () => {
mediaPlayer.resume();
};
```
6. 停止播放并释放资源。
```typescript
// 停止播放
mediaPlayer.stop();
// 销毁媒体播放器
rtcEngine.destroyMediaPlayer(this.player);
// 取消注册播放观测器
rtcEngine.unregisterEventHandler(this);
```
## 参考信息 [#参考信息-4]
### 示例项目 [#示例项目-4]
声网提供了开源的实现媒体播放器示例项目供你参考,你可以前往下载或查看其中的源代码。
MediaPlayer} href="https://gitee.com/agoraio-community/Electron-SDK/tree/main/example/src/renderer/examples/advanced/MediaPlayer/MediaPlayer.tsx" />
MediaPlayer} href="https://github.com/AgoraIO-Extensions/Electron-SDK/blob/main/example/src/renderer/examples/advanced/MediaPlayer/MediaPlayer.tsx" />
### API 参考 [#api-参考-4]
- [`createMediaPlayer`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer)
- [`destroy`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer)
- [`registerPlayerObserver`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-observer#api_imediaplayer_registerplayersourceobserver)
- [`unRegisterPlayerObserver`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-observer#api_imediaplayer_unregisterplayersourceobserver)
- [`getMediaPlayerId`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid)
- [`open`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-open#api_imediaplayer_open)
- [`play`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_play)
- [`pause`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause)
- [`stop`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-control#api_imediaplayer_stop)
- [`onPlayerEvent`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent)
- [`onPlayerSourceStateChanged`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged)
- [`onPositionChanged`](/zh-CN/api-reference/rtc/electron/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onpositionchanged)
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="unity" />
媒体播放器是 RTC SDK 内置的一个播放器,支持播放多种格式的媒体资源。本文介绍如何调用媒体播放器相关的 API 播放本地或在线媒体资源,并将媒体资源分享给声网频道内的远端用户观看或收听。
## 前提条件 [#前提条件-5]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。有关详细信息,请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-5]
参考如下步骤,在你的项目中使用媒体播放器:
### 创建媒体播放器对象 [#创建媒体播放器对象]
初始化 `IRtcEngine` 后,调用 `CreateMediaPlayer` 创建一个 `IMediaPlayer` 对象。
:::warning[注意]
如果你需要创建多个媒体播放器对象,可以多次调用 `CreateMediaPlayer`。
:::
```csharp
MediaPlayer = RtcEngine.CreateMediaPlayer();
if (MediaPlayer == null)
{
this.Log.UpdateLog("CreateMediaPlayer failed!");
return;
}
```
### 注册回调事件并实现回调 [#注册回调事件并实现回调]
1. 调用 `IMediaPlayer` 类下的 `InitEventHandler` 方法添加媒体播放器的回调事件。
```csharp
MpkEventHandler handler = new MpkEventHandler(this);
MediaPlayer.InitEventHandler(handler);
this.Log.UpdateLog("playerId id: " + MediaPlayer.GetId());
```
2. 根据你的需求,实现媒体播放器观测器的回调。
```csharp
class MpkEventHandler : IMediaPlayerSourceObserver
{ // 报告播放器状态改变
public override void OnPlayerSourceStateChanged(MEDIA_PLAYER_STATE state, MEDIA_PLAYER_REASON reason)
{
}
// 报告播放器的事件
public override void OnPlayerEvent(MEDIA_PLAYER_EVENT @event, Int64 elapsedTime, string message)
{
Debug.Log(string.Format("OnPlayerEvent state: {0}", @event));
}
// 报告预加载媒体资源的事件
public override void OnPreloadEvent(string src, PLAYER_PRELOAD_EVENT @event)
{
Debug.Log(string.Format("OnPreloadEvent src: {0}, @event: {1}", src, @event));
}
// 报告当前媒体资源的播放进度
public override void OnPositionChanged(long positionMs, long timestampMs)
{
}
}
```
### 设置视频渲染窗口 [#设置视频渲染窗口]
如果你需要播放视频资源,在媒体资源打开后,设置视频渲染。当播放器停止播放时,销毁对应的视频视图。在渲染视图时,你可以通过 `GetId` 获取媒体播放器的 ID,并需要将 `VIDEO_SOURCE_TYPE` 设为 `VIDEO_SOURCE_MEDIA_PLAYER`。
```csharp
// 报告播放器状态改变
public override void OnPlayerSourceStateChanged(MEDIA_PLAYER_STATE state, MEDIA_PLAYER_REASON reason)
{
Debug.Log(string.Format(
"OnPlayerSourceStateChanged state: {0}, ec: {1}, playId: {2}", state, reason, _sample.MediaPlayer.GetId()));
Debug.Log("OnPlayerSourceStateChanged");
if (state == MEDIA_PLAYER_STATE.PLAYER_STATE_OPEN_COMPLETED)
{
// 成功打开媒体资源后,创建一个视图用于显示媒体播放器的视频流
MakeVideoView((uint)_sample.MediaPlayer.GetId(), "", VIDEO_SOURCE_TYPE.VIDEO_SOURCE_MEDIA_PLAYER);
}
else if (state == MEDIA_PLAYER_STATE.PLAYER_STATE_STOPPED)
{
// 播放停止后,销毁视频视图
DestroyVideoView((uint)_sample.MediaPlayer.GetId());
}
}
```
调用 `SetForUser` 设置视频显示,调用 `SetEnable` 开始视频渲染。
```csharp
// 创建一个视频视图
static void MakeVideoView(uint uid, string channelId = "", VIDEO_SOURCE_TYPE videoSourceType = VIDEO_SOURCE_TYPE.VIDEO_SOURCE_CAMERA)
{
var go = GameObject.Find(uid.ToString());
if (!ReferenceEquals(go, null))
{
return;
}
// 创建一个新的 GameObject 用于渲染视频
var videoSurface = MakeImageSurface(uid.ToString());
if (ReferenceEquals(videoSurface, null)) return;
// 设置视频显示
videoSurface.SetForUser(uid, channelId, videoSourceType);
// 开始视频渲染
videoSurface.SetEnable(true);
// Texture 的宽高发生改变回调
videoSurface.OnTextureSizeModify += (int width, int height) =>
{
var transform = videoSurface.GetComponent();
if (transform)
{
// 如果在 RawImage 中渲染,只需设置 RawImage 的大小
transform.sizeDelta = new Vector2(width / 2, height / 2);
transform.localScale = Vector3.one;
}
else
{
// 如果在 MeshRenderer 中渲染,只需设置 MeshRenderer 的本地大小
float scale = (float)height / (float)width;
videoSurface.transform.localScale = new Vector3(-1, 1, scale);
}
Debug.Log("OnTextureSizeModify: " + width + " " + height);
};
}
// 销毁视频视图
static void DestroyVideoView(uint uid)
{
var go = GameObject.Find(uid.ToString());
if (!ReferenceEquals(go, null))
{
Destroy(go);
}
}
// 创建一个新的视频视图,包含一个 RawImage 组件,用于显示视频
private static VideoSurface MakeImageSurface(string goName)
{
// 创建一个新的 GameObject
GameObject go = new GameObject();
go.name = goName;
// 添加 RawImage 组件,用于渲染视频
go.AddComponent();
go.AddComponent();
var canvas = GameObject.Find("VideoCanvas");
if (canvas != null)
{
go.transform.parent = canvas.transform;
Debug.Log("add video view");
}
else
{
Debug.Log("Canvas is null video view");
}
// 设置 GameObject 的变换
go.transform.Rotate(0f, 0.0f, 180.0f);
go.transform.localPosition = Vector3.zero;
go.transform.localScale = new Vector3(4.5f, 3f, 1f);
// 添加 VideoSurface 组件
var videoSurface = go.AddComponent();
return videoSurface;
}
```
### 打开媒体资源 [#打开媒体资源]
调用 `Open` 打开本地或在线媒体文件并设置起始播放位置。支持打开的媒体资源格式见[支持的格式](#支持的格式-4)。
```csharp
public void OnOpenButtonPress()
{
var ret = MediaPlayer.Open("Your File Path", 0);
Debug.Log("Open returns: " + ret);
}
```
声网还提供 `OpenWithMediaSource` 方法打开媒体资源,同时可以进行播放设置,例如设置是否开启自动播放、实时缓存等功能。
### 发布媒体播放器的音视频流 [#发布媒体播放器的音视频流]
调用 `JoinChannel` 加入频道时,在 `ChannelMediaOptions` 中进行如下设置:
- 设置用户角色为主播(`CLIENT_ROLE_BROADCASTER`)。
- 将 `autoSubscribeAudio` 和 `autoSubscribeVideo` 设为 `true`,自动订阅所有音视频流。
- 将 `publishMediaPlayerAudioTrack` 和 `publishMediaPlayerVideoTrack` 设为 `true`,发布媒体播放器的音视频流。
- 将 `publishMediaPlayerId` 设为你的媒体播放器的 ID。
- 将 `enableAudioRecordingOrPlayout` 设为 `true`,开启音频播放。
```csharp
ChannelMediaOptions options = new ChannelMediaOptions();
// 自动订阅远端的音频流
options.autoSubscribeAudio.SetValue(true);
// 自动订阅远端的视频流
options.autoSubscribeVideo.SetValue(true);
options.publishCustomAudioTrack.SetValue(false);
options.publishCameraTrack.SetValue(false);
// 设置发布视频播放器的音频流
options.publishMediaPlayerAudioTrack.SetValue(true);
// 设置发布视频播放器的视频流
options.publishMediaPlayerVideoTrack.SetValue(true);
// 待发布的媒体播放器的 ID
options.publishMediaPlayerId.SetValue(MediaPlayer.GetId());
// 开启音频录制或播放
options.enableAudioRecordingOrPlayout.SetValue(true);
// 设置用户角色为主播
options.clientRoleType.SetValue(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER);
// 加入频道
var ret = RtcEngine.JoinChannel(_token, _channelName, 0, options);
this.Log.UpdateLog("RtcEngineController JoinChannel_MPK returns: " + ret);
```
### 播放控制 [#播放控制]
本节介绍如何实现播放控制,包括暂停、恢复播放、停止播放等功能。
#### 播放 [#播放]
调用 `Play` 方法播放本地或在线媒体资源。
:::warning[注意]
- 如果你通过 `Open` 打开媒体资源,你需要在收到 `OnPlayerSourceStateChanged` 回调报告状态为 `PLAYER_STATE_OPEN_COMPLETED` 后再调用 `Play` 进行播放。
- 如果你通过 `OpenWithMediaSource` 打开媒体资源,且 `autoPlay` 为 `true` 时,媒体资源打开后会自动播放,无需再额外调用 `Play` 方法。
:::
```csharp
public void OnPlayButtonPress()
{
var ret = MediaPlayer.Play();
Debug.Log("Play return" + ret);
}
```
**循环播放**
如果你需要循环播放,可以调用 `SetLoopCount` 方法并通过 `loopCount` 参数设置循环播放的次数,默认为 `0`,表示不循环播放。如需无限循环播放,将该参数设为 `-1`。
```csharp
public void OnPlayButtonPress()
{
if (this.IsLoop())
{
MediaPlayer.SetLoopCount(-1);
}
else
{
MediaPlayer.SetLoopCount(0);
}
var ret = MediaPlayer.Play();
this.Log.UpdateLog("Play return" + ret);
}
```
**定位指定位置播放**
如果你需要定位到媒体资源的指定位置再播放,可以调用 `Seek` 方法定位到指定位置。
:::warning[注意]
- 请确保在成功打开媒体文件后(即收到 `OnPlayerSourceStateChanged` 回调报告状态为 `PLAYER_STATE_OPEN_COMPLETED`)再调用 `Seek`。成功调用后,媒体播放器会自动从指定位置开始播放,并报告状态为 `PLAYER_STATE_PLAYING`。
- 如果你在暂停播放的情况下调用 `Seek`,成功调用后,媒体资源仍然会是暂停播放的状态。如需播放,请调用 `Resume` 或 `Play`。
:::
**设置播放速度**
调用 `SetPlaybackSpeed` 方法来设置当前媒体文件的播放速度。
```csharp
public void OnSetPlaybackSpeedButtonPress()
{
var ret = MediaPlayer.SetPlaybackSpeed(2);
this.Log.UpdateLog("SetPlaybackSpeed return" + ret);
}
```
#### 暂停播放 [#暂停播放]
调用 `Pause` 方法暂停当前播放。
```csharp
public void OnPauseButtonPress()
{
var ret = MediaPlayer.Pause();
this.Log.UpdateLog("Pause return" + ret);
}
```
#### 恢复播放 [#恢复播放]
暂停播放后,如需恢复播放,调用 `Resume` 方法。
```csharp
public void OnResumeButtonPress()
{
var ret = MediaPlayer.Resume()
this.Log.UpdateLog("Resume returns: " + ret);
}
```
#### 停止播放 [#停止播放]
调用 `Stop` 方法停止播放。停止播放后,如果你需要再次播放,需要重新打开该媒体资源。
```csharp
public void OnStopButtonPress()
{
var ret = MediaPlayer.Stop();
this.Log.UpdateLog("Stop return" + ret);
}
```
### 调整音量 [#调整音量]
如果你需要调整媒体播放器本地播放的音量,调用 `AdjustPlayoutVolume`。如果要调整所播放的媒体资源发布到远端的音量,调用 `AdjustPublishSignalVolume`。
```csharp
var ret = MediaPlayer.AdjustPlayoutVolume(30);
this.Log.UpdateLog("AdjustPlayoutVolume return" + ret);
ret = MediaPlayer.AdjustPublishSignalVolume(50);
this.Log.UpdateLog("AdjustPublishSignalVolume return" + ret);
```
### 预加载媒体资源 [#预加载媒体资源]
如果你需要连续播放多个不同的媒体资源,可以预先加载待播放的媒体资源以保证资源切换时的观众体验。
1. 调用 `PreloadSrc` 预加载媒体资源。如需加载多个资源,你可以多次调用该方法。预加载的相关事件可以通过监听 `OnPreloadEvent` 回调得知。
```csharp
public void OnPreloadSrcButtonClick()
{
var nRet = MediaPlayer.PreloadSrc(PRELOAD_URL, 0);
this.Log.UpdateLog("PreloadSrc: " + nRet);
}
```
2. 调用 `PlayPreloadedSrc` 播放预加载的媒体资源。调用该方法后,如果你收到 `OnPlayerSourceStateChanged` 回调报告状态 `PLAYER_STATE_PLAYING`,则表示播放成功。
```csharp
public void OnPlayPreloadButtonClick()
{
var nRet = MediaPlayer.PlayPreloadedSrc(PRELOAD_URL);
this.Log.UpdateLog("PlayPreloadedSrc: " + nRet);
}
```
3. 如果不再需要已加载的媒体资源,可以调用 `UnloadSrc` 释放预加载的资源。
```csharp
var nRet = MediaPlayer.UnloadSrc(PRELOAD_URL);
this.Log.UpdateLog("UnloadSrc: " + nRet);
```
### 离开频道 [#离开频道]
参考下列步骤离开频道:
1. 调用 `DestroyMediaPlayer` 销毁媒体播放器对象。
2. 调用 `InitEventHandler` 取消注册播放器事件观测器。
3. 调用 `LeaveChannel` 离开频道。
4. 调用 `Dispose` 销毁 `IRtcEngine` 对象并释放 SDK 使用的资源。
```csharp
public void OnLeaveChannelButtonPress()
{
if (RtcEngine == null) return;
// 销毁媒体播放器对象
if (MediaPlayer != null) RtcEngine.DestroyMediaPlayer(MediaPlayer);
// 取消注册播放器事件观测器
RtcEngine.InitEventHandler(null);
// 离开频道
RtcEngine.LeaveChannel();
// 销毁引擎并释放资源
RtcEngine.Dispose();
RtcEngine = null;
MediaPlayer = null;
}
```
## 参考信息 [#参考信息-5]
### 示例项目 [#示例项目-5]
声网提供了开源的音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。
MediaPlayer} href="https://gitee.com/agoraio-community/Agora-Unity-Quickstart/blob/main/API-Example-Unity/Assets/API-Example/Examples/Advanced/MediaPlayer/MediaPlayerExample.cs" />
MediaPlayer} href="https://github.com/AgoraIO-Extensions/Agora-Unity-Quickstart/blob/main/API-Example-Unity/Assets/API-Example/Examples/Advanced/MediaPlayer/MediaPlayerExample.cs" />
### 支持的格式 [#支持的格式-4]
声网的媒体播放器支持下列格式及协议:
**视频编码格式**
- H.263、H.264、H.265、MPEG4、MPEG2、RMVB、Theora、VP3、VP8、AVS、WMV
**音频编码格式**
- WAV、MP2、MP3、AAC、OPUS、FLAC、Vorbis、AMR-NB、AMR-WB、WMA v1、WMA v2
**容器格式**
- WAV、FLAC、OGG、MOV、ASF、FLV、MP3、MP4、MPEG-TS、Matroska (MKV)、AVI、ASS、CONCAT、DTS、AVS
**支持的协议**
- HTTP、HTTPS、RTMP、HLS、RTP、RTSP
### API 参考 [#api-参考-5]
- [`IMediaPlayer`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imediaplayer)
- [`IMediaPlayerSourceObserver`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imediaplayersourceobserver)
- [`IMediaPlayerCacheManager`](/zh-CN/api-reference/rtc/unity/rtc-interface-class#class_imediaplayercachemanager)
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="react-native" />
本文介绍如何调用媒体播放器相关的 API 播放本地或在线媒体资源,或将媒体资源分享给声网频道内的远端用户。
## 前提条件 [#前提条件-6]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。有关详细信息,请参考[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-6]
参考如下步骤,在你的项目中使用媒体播放器:
1. 初始化 `IRtcEngine` 后,创建一个 `IMediaPlayer` 对象。
```typescript
// 创建并初始化引擎
let rtcEngine = createAgoraRtcEngine();
rtcEngine.initialize({
appId,
});
// 创建媒体播放器对象
let mediaPlayer = rtcEngine.createMediaPlayer();
```
2. 调用 `registerPlayerSourceObserver` 方法注册播放观测器。
```typescript
// 注册播放观测器
mediaPlayer.registerPlayerSourceObserver(this);
```
3. 根据你的需求,你可以注册以下媒体播放器观测器的回调:
- `onPlayerSourceStateChanged`:报告播放器状态改变。
- `onPositionChanged`:报告当前媒体文件的播放进度。
- `onPlayerEvent`:报告播放器事件。
```typescript
const EventHandles = {
// 报告播放器状态改变
onPlayerSourceStateChanged: (state, ec) {
console.log(`state:${state}, ec:${ec}`);
};
// 报告当前媒体文件的播放进度
onPositionChanged: (position) {
console.log(`position:${position}`);
};
// 报告播放器事件
onPlayerEvent: (
eventCode,
elapsedTime,
message
) {
console.log(
`eventCode:${eventCode},
elapsedTime:${elapsedTime},
message:${message}`
);
};
};
// 添加主回调事件
rtcEngine.registerEventHandler(EventHandles);
```
4. 调用 `open` 打开本地或在线媒体文件。
```typescript
open = () => {
const url = 'https://example/video.mov';
if (!url) {
this.error("url is invalid");
}
mediaPlayer.open(url, 0);
};
```
5. 调用 `play` 播放媒体文件。
```typescript
// 播放媒体文件
play = () => {
const { position, duration } = this.state;
if (position === duration && duration !== 0) {
mediaPlayer.seek(0);
} else {
mediaPlayer.play();
}
};
// 暂停播放媒体文件
pause = () => {
mediaPlayer.pause();
};
// 恢复播放媒体文件
resume = () => {
mediaPlayer.resume();
};
```
6. 停止播放并释放资源。
```typescript
// 停止播放
mediaPlayer.stop();
// 销毁媒体播放器
rtcEngine.destroyMediaPlayer(this.player);
// 取消注册播放观测器
rtcEngine.unregisterEventHandler(this);
```
## 参考信息 [#参考信息-6]
### 示例项目 [#示例项目-6]
声网提供了开源的实现媒体播放器示例项目供你参考,你可以前往下载或查看其中的源代码。
MediaPlayer} href="https://gitee.com/agoraio-community/react-native-agora/tree/main/example/src/examples/advanced/MediaPlayer/MediaPlayer.tsx" />
MediaPlayer} href="https://github.com/AgoraIO-Extensions/react-native-agora/blob/main/examples/legacy/src/examples/advanced/MediaPlayer/MediaPlayer.tsx" />
### API 参考 [#api-参考-6]
- [`createMediaPlayer`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-initialize#api_irtcengine_createmediaplayer)
- [`destroy`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-initialize#api_irtcengine_destroymediaplayer)
- [`registerPlayerObserver`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-observer#api_imediaplayer_registerplayersourceobserver)
- [`unRegisterPlayerObserver`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-observer#api_imediaplayer_unregisterplayersourceobserver)
- [`getMediaPlayerId`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-info#api_imediaplayer_getmediaplayerid)
- [`open`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-open#api_imediaplayer_open)
- [`play`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_play)
- [`pause`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_pause)
- [`stop`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-control#api_imediaplayer_stop)
- [`onPlayerEvent`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayerevent)
- [`onPlayerSourceStateChanged`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged)
- [`onPositionChanged`](/zh-CN/api-reference/rtc/react-native/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onpositionchanged)
<_PlatformProcessedMarker close="true" />