实时音视频 TRTCLiveRoom API (Android) - 场景实践

TRTCLiveRoom 是基于腾讯云实时音视频（TRTC）和即时通信 IM 服务组合而成的，支持以下功能：

• 主播创建新的直播间开播，观众进入直播间观看。
• 主播和观众进行视频连麦互动。
• 两个不同房间的主播 PK 互动。
• 支持发送各种文本消息和自定义消息，自定义消息可用于实现弹幕、点赞和礼物。

TRTCLiveRoom 是一个开源的 Class，依赖腾讯云的两个闭源 SDK，具体的实现过程请参见 视频连麦直播（Android）。

• TRTC SDK：使用 TRTC SDK 作为低延时直播组件。
• IM SDK：使用 IM SDK 的 AVChatroom 实现直播聊天室的功能，同时，通过 IM 消息串联主播间的连麦流程。

TRTCLiveRoom API 概览

SDK 基础函数

房间相关接口函数

推拉流相关接口函数

主播和观众连麦

主播跨房间 PK

音视频控制相关接口函数

背景音乐音效相关接口函数

美颜滤镜相关接口函数

消息发送相关接口函数

调试相关接口函数

TRTCLiveRoomDelegate API 概览

通用事件回调

房间事件回调

主播和观众进出事件回调

主播和观众连麦事件回调

主播 PK 事件回调

消息事件回调

SDK 基础函数

sharedInstance

获取 TRTCLiveRoom 单例对象。

public static synchronized TRTCLiveRoom sharedInstance(Context context);

参数如下表所示：

destroySharedInstance

销毁 TRTCLiveRoom 单例对象。

说明：

销毁实例后，外部缓存的 TRTCLiveRoom 实例无法再使用，需要重新调用 sharedInstance 获取新实例。

public static void destroySharedInstance();

setDelegate

TRTCLiveRoom 事件回调，您可以通过 TRTCLiveRoomDelegate 获得 TRTCLiveRoom 的各种状态通知。

public abstract void setDelegate(TRTCLiveRoomDelegate delegate);

说明：

setDelegate 是 TRTCLiveRoom 的代理回调。

setDelegateHandler

设置事件回调所在的线程。

public abstract void setDelegateHandler(Handler handler);

参数如下表所示：

login

登录。

public abstract void login(int sdkAppId,
 String userId, String userSig,
 TRTCLiveRoomDef.TRTCLiveRoomConfig config, 
 TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

logout

登出。

public abstract void logout(TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

setSelfProfile

修改个人信息。

public abstract void setSelfProfile(String userName, String avatarURL, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

房间相关接口函数

createRoom

创建房间（主播调用）。

public abstract void createRoom(int roomId, TRTCLiveRoomDef.TRTCCreateRoomParam roomParam, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

主播开播的正常调用流程如下：

1. 【主播】调用 startCameraPreview() 打开摄像头预览，此时可以调整美颜参数。
2. 【主播】调用 createRoom() 创建直播间，房间创建成功与否会通过 ActionCallback 通知给主播。
3. 【主播】调用 starPublish() 开始推流。

destroyRoom

销毁房间（主播调用）。主播在创建房间后，可以调用该函数来销毁房间。

public abstract void destroyRoom(TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

enterRoom

进入房间（观众调用）。

public abstract void enterRoom(int roomId, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

观众观看直播的正常调用流程如下：

1. 【观众】向您的服务端获取最新的直播间列表，可能包含多个直播间的 roomID 和房间信息。
2. 【观众】观众选择一个直播间，并调用 enterRoom() 进入该房间。
3. 【观众】调用startPlay(userId)并传入主播的 userId 开始播放。
   • 若直播间列表已包含主播端的 userId 信息，观众端可直接调用 startPlay(userId) 即可开始播放。
   • 若在进房前暂未获取主播的 userId，观众端在进房后会收到 TRTCLiveRoomDelegate 中的 onAnchorEnter(userId) 的事件回调，该回调中携带主播的 userId 信息，再调用startPlay(userId)即可播放。

exitRoom

离开房间。

public abstract void exitRoom(TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

getRoomInfos

获取房间列表的详细信息，房间信息是主播在创建 createRoom() 时通过 roomInfo 设置的。

说明：

如果房间列表和房间信息都由您自行管理，可忽略该函数。

public abstract void getRoomInfos(List<Integer> roomIdList, TRTCLiveRoomCallback.RoomInfoCallback callback);

参数如下表所示：

getAnchorList

获取房间内所有的主播列表，enterRoom() 成功后调用才有效。

public abstract void getAnchorList(TRTCLiveRoomCallback.UserListCallback callback);

参数如下表所示：

getAudienceList

获取房间内所有的观众信息，enterRoom() 成功后调用才有效。

public abstract void getAudienceList(TRTCLiveRoomCallback.UserListCallback callback);

参数如下表所示：

推拉流相关接口函数

startCameraPreview

开启本地视频的预览画面。

public abstract void startCameraPreview(boolean isFront, TXCloudVideoView view, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

stopCameraPreview

停止本地视频采集及预览。

public abstract void stopCameraPreview();

startPublish

开始直播（推流），适用于以下场景：

• 主播开播的时候调用
• 观众开始连麦时调用

public abstract void startPublish(String streamId, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

stopPublish

停止直播（推流），适用于以下场景：

• 主播结束直播时调用
• 观众结束连麦时调用

public abstract void stopPublish(TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

startPlay

播放远端视频画面，可以在普通观看和连麦场景中调用。

public abstract void startPlay(String userId, TXCloudVideoView view, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

普通观看场景

• 若直播间列表已包含主播端的 userId 信息，观众端可以直接在 enterRoom() 成功后调用 startPlay(userId) 播放主播的画面。
• 若在进房前暂未获取主播的 userId，观众端在进房后会收到 TRTCLiveRoomDelegate 中的 onAnchorEnter(userId) 的事件回调，该回调中携带主播的 userId 信息，再调用startPlay(userId)即可播放主播的画面。

直播连麦场景
发起连麦后，主播会收到来自 TRTCLiveRoomDelegate 中的 onAnchorEnter(userId) 回调，此时使用回调中的 userId 调用 startPlay(userId) 即可播放连麦画面。

stopPlay

停止渲染远端视频画面。需在 onAnchorExit() 回调时，调用该接口。

public abstract void stopPlay(String userId, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

主播和观众连麦

requestJoinAnchor

观众请求连麦。

public abstract void requestJoinAnchor(String reason, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

主播和观众的连麦流程如下：

1. 【观众】调用 requestJoinAnchor() 向主播发起连麦请求。
2. 【主播】会收到 TRTCLiveRoomDelegate 的 onRequestJoinAnchor() 回调通知。
3. 【主播】调用 responseJoinAnchor() 决定是否接受来自观众的连麦请求。
4. 【观众】会收到 responseCallback 回调通知，该通知会携带主播的处理结果。
5. 【观众】如果请求被同意，则调用 startCameraPreview() 开启本地摄像头。
6. 【观众】然后调用 startPublish() 正式进入推流状态。
7. 【主播】一旦观众进入连麦状态，主播会收到 TRTCLiveRoomDelegate 的 onAnchorEnter() 通知。
8. 【主播】主播调用 startPlay() 即可看到连麦观众的视频画面。
9. 【观众】如果直播间里已有其他观众正在跟主播连麦，新加入的连麦观众会收到 onAnchorEnter() 通知，调用 startPlay() 播放其他连麦者的视频画面。

responseJoinAnchor

主播处理连麦请求。主播在收到 TRTCLiveRoomDelegate 的 onRequestJoinAnchor() 回调后需要调用此接口来处理观众的连麦请求。

public abstract void responseJoinAnchor(String userId, boolean agree, String reason);

参数如下表所示：

kickoutJoinAnchor

主播踢除连麦观众。主播调用此接口踢除连麦观众后，被踢连麦观众会收到 TRTCLiveRoomDelegate 的 onKickoutJoinAnchor() 回调通知。

public abstract void kickoutJoinAnchor(String userId, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

主播跨房间 PK

requestRoomPK

主播请求跨房 PK。

public abstract void requestRoomPK(int roomId, String userId, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

主播和主播之间可以跨房间 PK，两个正在直播中的主播 A 和 B 之间的跨房 PK 流程如下：

1. 【主播 A】调用 requestRoomPK() 向主播 B 发起连麦请求。
2. 【主播 B】会收到 TRTCLiveRoomDelegate 的 onRequestRoomPK() 回调通知。
3. 【主播 B】调用 responseRoomPK() 决定是否接受主播 A 的 PK 请求。
4. 【主播 B】如果接受主播 A 的要求，等待 TRTCLiveRoomDelegate 的 onAnchorEnter() 通知，然后调用 startPlay() 来显示主播 A 的视频画面。
5. 【主播 A】会收到 responseCallback 回调通知，该通知会携带来自主播 B 的处理结果。
6. 【主播 A】如果请求被同意，等待 TRTCLiveRoomDelegate 的 onAnchorEnter() 通知，然后调用 startPlay() 显示主播 B 的视频画面。

responseRoomPK

主播响应跨房 PK 请求。主播响应后，对方主播会收到 requestRoomPK 传入的 responseCallback 回调。

public abstract void responseRoomPK(String userId, boolean agree, String reason);

参数如下表所示：

quitRoomPK

退出跨房 PK。PK 中的任何一个主播退出跨房 PK 状态后，另一个主播会收到 TRTCLiveRoomDelegate 的 onQuitRoomPk() 回调通知。

public abstract void quitRoomPK(TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

音视频控制相关接口函数

switchCamera

切换前后摄像头。

public abstract void switchCamera();

setMirror

设置是否镜像展示。

public abstract void setMirror(boolean isMirror);

参数如下表所示：

muteLocalAudio

静音本地音频。

public abstract void muteLocalAudio(boolean mute);

参数如下表所示：

muteRemoteAudio

静音远端音频。

public abstract void muteRemoteAudio(String userId, boolean mute);

参数如下表所示：

muteAllRemoteAudio

静音所有远端音频。

public abstract void muteAllRemoteAudio(boolean mute);

参数如下表所示：

背景音乐音效相关接口函数

getAudioEffectManager

获取背景音乐音效管理对象 TXAudioEffectManager。

public abstract TXAudioEffectManager getAudioEffectManager();

美颜滤镜相关接口函数

getBeautyManager

获取美颜管理对象 TXBeautyManager。

public abstract TXBeautyManager getBeautyManager();

通过美颜管理，您可以使用以下功能：

• 设置“美颜风格”、“美白”、“红润”、“大眼”、“瘦脸”、“V脸”、“下巴”、“短脸”、“小鼻”、“亮眼”、“白牙”、“祛眼袋”、“祛皱纹”、“祛法令纹”等美容效果。
• 调整“发际线”、“眼间距”、“眼角”、“嘴形”、“鼻翼”、“鼻子位置”、“嘴唇厚度”、“脸型”。
• 设置人脸挂件（素材）等动态效果。
• 添加美妆。
• 进行手势识别。

消息发送相关接口函数

sendRoomTextMsg

在房间中广播文本消息，一般用于弹幕聊天。

public abstract void sendRoomTextMsg(String message, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

sendRoomCustomMsg

发送自定义文本消息。

public abstract void sendRoomCustomMsg(String cmd, String message, TRTCLiveRoomCallback.ActionCallback callback);

参数如下表所示：

调试相关接口函数

showVideoDebugLog

是否在界面中展示debug信息。

public abstract void showVideoDebugLog(boolean isShow);

参数如下表所示：

TRTCLiveRoomDelegate事件回调

通用事件回调

onError

错误回调。

说明：

SDK 不可恢复的错误，一定要监听，并分情况给用户适当的界面提示。

void onError(int code, String message);

参数如下表所示：

onWarning

警告回调。

void onWarning(int code, String message);

参数如下表所示：

onDebugLog

Log 回调。

void onDebugLog(String message);

参数如下表所示：

房间事件回调

onRoomDestroy

房间被销毁的回调。主播退房时，房间内的所有用户都会收到此通知。

void onRoomDestroy(String roomId);

参数如下表所示：

onRoomInfoChange

直播房间信息变更回调。多用于直播连麦、PK下房间状态变化通知场景。

void onRoomInfoChange(TRTCLiveRoomDef.TRTCLiveRoomInfo roomInfo);

参数如下表所示：

主播和观众进出事件回调

onAnchorEnter

收到新主播进房通知。连麦观众和跨房 PK 主播进房后观众会收到新主播的进房事件，您可以调用 TRTCLiveRoom 的 startPlay() 显示该主播的视频画面。

void onAnchorEnter(String userId);

参数如下表所示：

onAnchorExit

收到主播退房通知。房间内的主播（和连麦中的观众）会收到新主播的退房事件，您可以调用 TRTCLiveRoom 的 stopPlay() 关闭该主播的视频画面。

void onAnchorExit(String userId);

参数如下表所示：

onAudienceEnter

收到观众进房通知。

void onAudienceEnter(TRTCLiveRoomDef.TRTCLiveUserInfo userInfo);

参数如下表所示：

onAudienceExit

收到观众退房通知。

void onAudienceExit(TRTCLiveRoomDef.TRTCLiveUserInfo userInfo);

参数如下表所示：

主播和观众连麦事件回调

onRequestJoinAnchor

主播收到观众连麦请求时的回调。

void onRequestJoinAnchor(TRTCLiveRoomDef.TRTCLiveUserInfo userInfo, String reason, int timeOut);

参数如下表所示：

onKickoutJoinAnchor

连麦观众收到被踢出连麦的通知。连麦观众收到被主播踢除连麦的消息，您需要调用 TRTCLiveRoom 的 stopPublish() 退出连麦。

void onKickoutJoinAnchor();

主播 PK 事件回调

onRequestRoomPK

收到请求跨房 PK 通知。主播收到其他房间主播的 PK 请求，如果同意 PK ，您需要等待 TRTCLiveRoomDelegate 的 onAnchorEnter() 通知，然后调用 startPlay() 来播放邀约主播的流。

void onRequestRoomPK(TRTCLiveRoomDef.TRTCLiveUserInfo userInfo, int timeout);

参数如下表所示：

onQuitRoomPK

收到断开跨房 PK 通知。

void onQuitRoomPK();

消息事件回调

onRecvRoomTextMsg

收到文本消息。

void onRecvRoomTextMsg(String message, TRTCLiveRoomDef.TRTCLiveUserInfo userInfo);

参数如下表所示：

onRecvRoomCustomMsg

收到自定义消息。

void onRecvRoomCustomMsg(String cmd, String message, TRTCLiveRoomDef.TRTCLiveUserInfo userInfo);

参数如下表所示：

TRTCAudioEffectManager

playBGM

播放背景音乐。

void playBGM(String url, int loopTimes, int bgmVol, int micVol, TRTCCloud.BGMNotify notify);

参数如下表所示：

stopBGM

停止播放背景音乐。

void stopBGM();

pauseBGM

暂停播放背景音乐。

void pauseBGM();

resumeBGM

继续播放背景音乐。

void resumeBGM();

setBGMVolume

设置背景音乐的音量大小，播放背景音乐混音时使用，用来控制背景音的音量大小。

void setBGMVolume(int volume);

参数如下表所示：

setBGMPosition

设置背景音乐播放进度。

int setBGMPosition(int position);

参数如下表所示：

返回

0：成功。

setMicVolume

设置麦克风的音量大小，播放背景音乐混音时使用，用来控制麦克风音量大小。

void setMicVolume(int volume);

参数如下表所示：

setReverbType

设置混响效果。

void setReverbType(int reverbType);

参数如下表所示：

setVoiceChangerType

设置变声类型。

void setVoiceChangerType(int type);

参数如下表所示：

playAudioEffect

播放音效，每个音效都需要您指定具体的 ID，您可以通过该 ID 对音效的开始、停止、音量等进行设置。支持 aac、mp3 以及 m4a 格式。

void playAudioEffect(int effectId, String path, int count, boolean publish, int volume);

参数如下表所示：

pauseAudioEffect

暂停音效播放。

void pauseAudioEffect(int effectId);

参数如下表所示：

resumeAudioEffect

恢复音效播放。

void resumeAudioEffect(int effectId);

参数如下表所示：

stopAudioEffect

停止音效播放。

void stopAudioEffect(int effectId);

参数如下表所示：

stopAllAudioEffects

停止全部音效播放。

void stopAllAudioEffects();

setAudioEffectVolume

设置音效音量。

void setAudioEffectVolume(int effectId, int volume);

参数如下表所示：

setAllAudioEffectsVolume

设置所有音效的音量。

void setAllAudioEffectsVolume(int volume);

参数如下表所示：