基础功能

本文介绍 Android 观播 SDK 的基础功能接入方法，包括如何接入完整直播间、独立播放器以及完整播放器。

前提条件

您已完成集成 Android 观播 SDK 的前 5 步。

功能列表

本文介绍以下功能的接入方法。

• 完整直播间
• 独立播放器
• 完整播放器

完整直播间

完整直播间包含企业直播直播间的所有功能模块，相较于模块化接入，更为简单、便捷。如无特殊需求，推荐接入完整直播间。

有关完整直播间支持的具体功能，详见 SaaS 与 aPaaS 功能差异。

进入直播间

调用 joinLiveRoom 方法，让观众进入完整直播间并在 App 内显示完整直播间页面。
示例代码如下所示：

long activityId = ACTIVITY_ID; // 将 ACTIVITY_ID 替换为直播间的活动 ID。
String token = "TOKEN"; // 将 TOKEN 替换为进入该直播间所需的授权 Token。
TVULiveRoom.TVURoomAuthMode roomAuthMode = TVULiveRoom.TVURoomAuthMode.PUBLIC; // 直播间鉴权模式。此处以公开模式进入直播间为例。观众无需登录即可观看直播、查看评论等。
boolean isPortrait = true;// 是否为竖屏直播间。此处以竖屏直播间为例。
// 进入直播间。
TVULiveRoom.joinLiveRoom(context, activityId, token, roomAuthMode, isPortrait);

定制直播间

在进入直播间前，您可以调用 CustomSettings.Holder.mSettings.set 方法定制直播间以下各项的显示效果：

• 字体：通过 TypeFace 设置字体。
• 字号：通过 Integer 类型的值设置字号。单位：sp。
• 图片：通过 Drawable 对象设置图片。支持 PNG 和 JPG 格式的图片。
• 颜色：通过 Integer 类型的值设置颜色，例如白色为 0xFFFFFFFF。
• 其他。

以下示例代码将直播间的关闭按钮自定义为文件名为 tvu_nav_icon_back_melon 的图片。

CustomSettings settings = CustomSettings.Holder.mSettings;
settings.setExitRoomIcon(ContextCompat.getDrawable(this, R.drawable.tvu_nav_icon_back_melon));

更多定制直播间的方法，详见 mSettings 类的相关方法。

离开直播间

当需要让观众离开直播间页面时，例如观众观看权限不足时，可以调用 leaveLiveRoom 方法。如需让观众重新进入直播间，需再次调用 joinLiveRoom 方法。
示例代码如下所示。

TVULiveRoom.leaveLiveRoom(context);

销毁悬浮窗

如开启悬浮窗权限，退出直播间页面时会显示悬浮窗。如果不需要显示悬浮窗，可以销毁悬浮窗。销毁悬浮窗会同时销毁悬浮窗中相应的播放器。

示例代码如下所示。

TVULiveRoom.destroyFloatWindow();

完整示例代码

以下示例以直播间的活动 ID（activityId）为 1721010849258****、token 为 pg****、鉴权模式（roomAuthMode）为公开模式的竖屏直播间为例。您可以按需修改相关参数值。

long activityId = 1721010849258****;
String token = "pg****";
TVULiveRoom.TVURoomAuthMode roomAuthMode = TVULiveRoom.TVURoomAuthMode.PUBLIC;
boolean isPortrait = true;
//（可选）定制直播间。此处以定制直播间的关闭按钮为例。
CustomSettings settings = CustomSettings.Holder.mSettings;
settings.setExitRoomIcon(ContextCompat.getDrawable(this, R.drawable.tvu_nav_icon_back_melon));
// 进入直播间。
TVULiveRoom.joinLiveRoom(context, activityId, token, roomAuthMode, isPortrait);
// 离开直播间。
TVULiveRoom.leaveLiveRoom(context);

独立播放器

独立播放器不包含控制界面，即播放器内无播放按钮等互动按钮。
独立播放器 TVUSinglePlayerView 实例包含 TextureView 和视频封面图两个元素，并暴露了部分接口和事件供调用和监听，方便将独立播放器嵌入您自己的页面并实现以下功能：

• 在您的自有观看页面，自行在独立播放器添加自定义的控制界面。
• 在您的自有页面展示多个独立播放器，不同独立播放器对应着不同的直播间。观众点击页面中展示的独立播放器时，即可进入对应的完整直播间。
  您必须在观众点击自有页面中的独立播放器时，调用进入完整直播间的代码。
  
• 自行实现悬浮窗并将独立播放器播放的内容展示在悬浮窗 View 上，即可先展示悬浮窗，再展示完整直播间，例如观众先进入您的商品详情页查看商品，再点击悬浮窗进入完整直播间。
  您必须将进入直播间示例代码中的 videoView 添加到悬浮窗 View 中。在观众点击悬浮窗 View 时，调用进入完整直播间的代码。
  

进入直播间

您可以通过以下示例代码，进入直播间并创建独立播放器。

// 在调用 Activity.setContentView 方法前，创建 TVULiveRoomServer 实例。此处以仅接入独立播放器为例。如需在接入独立播放器的基础上，绑定聊天互动菜单、人气等直播间组件，请将 SERVER_TYPE_SINGLE 替换为 SERVER_TYPE_LIVEROOM。
TVULiveRoomServer roomServer = new TVULiveRoomServer(this, activityId, token, TVULiveRoomServer.SERVER_TYPE_SINGLE);
// 将直播间鉴权模式设置为公开，观众无需登录即可观看直播、查看评论等。
roomServer.setRoomAuthMode(TVULiveRoom.TVURoomAuthMode.PUBLIC);
// 初始化 TVUSinglePlayerView 实例。  
InitConfig initConfig = new InitConfig();
TVUSinglePlayerView videoView = findViewById(R.id.video_view);
videoView.init(initConfig);
// 绑定 TVUSinglePlayerView 实例和 TVULiveRoomServer 实例。
roomServer.setPlayerView(videoView.getInnerPlayerView());
// 启动 TVULiveRoomServer 实例。实例启动后，播放器会自动播放视频。
roomServer.start();   

自定义控制界面

为独立播放器添加自定义的控制界面后，您可以设置按钮的点击行为。
以下示例代码设置了播放按钮和暂停按钮的点击行为。

// 通过 findViewById 方法找到 videoView。
TVUSinglePlayerView videoView = findViewById(R.id.video_view);
// 通过 findViewById 方法找到播放按钮。
Button btnPlay = findViewById(R.id.btn_play);
// 通过 findViewById 方法找到暂停按钮。
Button btnPause = findViewById(R.id.btn_pause);
// 设置播放按钮的点击行为：当点击播放按钮时，播放视频。
btnPlay.setOnClickListener(v -> {
    videoView.play();
});
// 设置暂停按钮的点击行为：当点击暂停按钮时，暂停播放视频。
btnPause.setOnClickListener(v -> {
    videoView.pause();
});

实现独立播放器控制

在 TVULiveRoomServer 实例启动成功后，您可以调用相关方法实现独立播放器控制，详见 TVUSinglePlayerView。
以下示例代码实现了独立播放器中的视频暂停和播放。

// 通过 findViewById 方法找到 videoView。
TVUSinglePlayerView videoView = findViewById(R.id.video_view);
videoView.pause();   // 暂停播放视频。
videoView.play();    // 播放视频。

监听独立播放器事件

您可以监听独立播放器事件。详见 SinglePlayerListener。
示例代码如下所示：

// 设置监听独立播放器事件。
initConfig.singlePlayerListener = new SinglePlayerListener() {
    /**
     * 直播状态变化回调。
     * @param status 当前直播状态。
     *               1：直播中。
     *               2：预告。
     *               3：回放。
     *               4：已结束。
     */
    @Override
    public void liveRoomStatusChanged(int status) {
    }

    /**
     * 资源可播放状态变化回调。
     * @param playableStatus 当前资源可播放状态。
     *                       0：当前无任何资源可播放，无法调用 play 方法。
     *                       1：当前有点播视频（预告和回放视频）可播放，可调用 play 方法播放视频。
     *                       2：当前有直播可播放，可调用 play 方法播放视频。
     */
    @Override
    public void playableStatusChanged(int playableStatus) {
    }

    /**
     * 播放状态变化回调。
     * @param playStatus 当前播放状态。
     *                   0：暂停。
     *                   1：播放。
     */
    @Override
    public void playStatusChanged(int playStatus) {

    }

    /**
     * 视频画面尺寸变化回调。
     * @param width 视频宽度。
     * @param height 视频高度。
     */
    @Override
    public void sizeChanged(int width, int height) {
    }

    /**
     * 卡顿状态变化回调。您可以自行配置是否显示自定义加载动画。
     * @param isStalling 当前视频是否卡顿。
     *                   true：卡顿。
     *                   false：不卡顿。
     */
    @Override
    public void stallingStatusChanged(boolean isStalling) {
    }

    /**
     * 点播发生错误回调。
     * @param error 错误详情。
     */
    @Override
    public void vodErrorOccurred(Error error) {
    }

    /**
     * 直播发生错误回调。
     * @param error 错误详情。
     */
    @Override
    public void liveErrorOccurred(LiveError error) {
    }

    /**
     * 视频播放发生错误回调，包括点播发生错误和直播发生错误。此时播放处于暂停状态，您可以自行配置重试画面，引导观众点击重试播放。
     * @param isPlayError 当前是否发生播放错误。
     *                    true：发生播放错误。
     *                    false：未发生播放错误。
     */
    @Override
    public void playErrorStatusChanged(boolean isPlayError) {
    }

    /**
     * 点播视频已准备完毕回调。您可以调用 seekVodTime 方法。
     */
    @Override
    public void vodPrepared() {
    }

    /**
     * 点播视频画面渲染开始回调。
     */
    @Override
    public void vodRenderStarted() {
    }

    /**
     * 点播视频自动断点续播回调。
     * @param seekTimeInMills 自动断点续播后跳转到的视频播放位置。单位：ms。
     */
    @Override
    public void vodAutoSeekPreviousTime(int seekTimeInMills) {
    }


    /**
     * 点播视频当前播放进度变化回调。每秒更新一次。
     * @param curTimeInMills 当前播放进度。单位：ms。
     */
    @Override
    public void vodCurPlayTimeChanged(int curTimeInMills) {
    }

    /**
     * 点播视频总时长变化回调。此回调通常在视频切换时触发。
     * @param durationInMills 当前视频的总时长。单位：ms。
     */
    @Override
    public void vodDurationChanged(int durationInMills) {
    }

    /**
     * 点播视频播放完成回调。
     */
    @Override
    public void vodCompletion() {
    }

    /**
     * 直播已准备完毕回调。
     */
    @Override
    public void livePrepared() {
    }

    /**
     * 直播渲染开始回调。
     * @param isFirstFrame 是否为真正渲染的第一帧。直播过程中可能会发生重试导致多次触发此回调。
     *                     true：当前是调用 play 方法后的第一帧。
     *                     flase：当前不是调用 play 方法后的第一帧。
     */
    @Override
    public void liveFirstFrameRendered(boolean isFirstFrame) {
    }

    /**
     * 直播结束回调。
     */
    @Override
    public void liveCompletion() {
    }

    /**
     * 封面可见状态变化回调。视频播放时封面不可见，无视频播放时封面可见。
     * @param isVisible 封面是否可见。
     *                  true：可见。
     *                  false：不可见。
     */
    @Override
    public void coverImageVisibleChanged(boolean isVisible) {
    }

    /**
     * 视频分辨率信息变化回调。此回调通常在视频切换时触发。
     * @param resolutions 当前支持的分辨率列表。
     * @param defaultResolution 当前默认选中的分辨率。
     */
    @Override
    public void resolutionInfoChanged(String[] resolutions, String defaultResolution) {
    }

    /**
     * 当前正在播放的点播视频 Vid 变化回调。在观看页播放的点播视频变更时或者直播状态发生变化时会触发该回调。
     * @param vid 当前正在播放的点播视频 Vid。如果当前未播放点播视频，则返回空字符串。
     */
    @Override
    public void onCurVodVidChanged(String vid) {
    }

    /**
     * 当前直播间的回放列表变化回调。在上下架回放时或者直播状态发生变化时会触发该回调。
     * @param replayList 直播间的回放列表。如果当前直播间没有回放视频，则返回空数组。
     */
    @Override
    public void onCurReplayListChanged(List<Replay> replayList) {
    }

    /**
     * 当前直播频道 ID 变化回调。
     * @param lineId 当前直播频道 ID。如果当前直播间并非直播中状态，则返回 0。
     */
    @Override
    public void onCurLiveLineIdChanged(long lineId) {
    }

    /**
     * 当前直播频道列表变化回调。
     * @param liveLineList 当前直播频道列表。如果当前直播间并非直播中状态，则返回空数组。
     */
    @Override
    public void onCurLiveLineListChanged(List<PullStreamUrl> liveLineList) {
    }
};

离开直播间

在销毁自有页面等场景下，您可以通过以下示例代码，离开直播间并销毁独立播放器。

roomServer.closeRoom();

完整示例代码

以下示例以直播间的活动 ID（activityId）为 1721010849258****、token 为 pg****、鉴权模式（roomAuthMode）为公开模式的直播间为例。您可以按需修改相关参数值。

long activityId = 1721010849258****;
String token = "pg****";
TVULiveRoomServer roomServer = new TVULiveRoomServer(this, activityId, token, TVULiveRoomServer.SERVER_TYPE_SINGLE);
roomServer.setRoomAuthMode(TVULiveRoom.TVURoomAuthMode.PUBLIC);
InitConfig initConfig = new InitConfig();
TVUSinglePlayerView videoView = findViewById(R.id.video_view);
videoView.init(initConfig);
// 绑定 TVUSinglePlayerView 实例和 TVULiveRoomServer 实例。 
roomServer.setPlayerView(videoView.getInnerPlayerView());
// 启动 TVULiveRoomServer 实例。
roomServer.start();
// 为自定义的播放按钮和暂停按钮设置点击行为。
Button btnPlay = findViewById(R.id.btn_play);
Button btnPause = findViewById(R.id.btn_pause);
btnPlay.setOnClickListener(v -> {
    videoView.play();
});
btnPause.setOnClickListener(v -> {
    videoView.pause();
});
// 离开直播间并销毁独立播放器。
roomServer.closeRoom();

完整播放器

如果您具备自有的观看页面，并且对播放器的控制界面无自定义需求，可以选择只接入完整播放器。

进入直播间

您可以通过以下示例代码，进入直播间并创建完整播放器。

// 创建竖屏直播间 TVULiveRoomServer 实例。如需创建横屏直播间 TVULiveRoomServer 实例，请将 TVULiveRoomServer.SERVER_TYPE_PORTRAIT_LIVEROOM 替换为 TVULiveRoomServer.SERVER_TYPE_LIVEROOM。
TVULiveRoomServer mServer = new TVULiveRoomServer(this, activityId, token, TVULiveRoomServer.SERVER_TYPE_PORTRAIT_LIVEROOM);
// 引入播放器模块 PlayerView 实例。
PlayerView playerView = (PlayerView) LayoutInflater.from(this).inflate(com.bytedance.live.sdk.R.layout.tvu_player_layout, null, false);
// 将直播间鉴权模式设置为公开，观众无需登录即可观看直播、查看评论等。
mServer.setRoomAuthMode(TVULiveRoom.TVURoomAuthMode.PUBLIC);
// 绑定 PlayerView 实例和 TVULiveRoomServer 实例。
mServer.setPlayerView(playerView);
// 引入您的播放器容器。
FrameLayout playerViewContainer = findViewById(R.id.player_view_container);
// 将 PlayerView 实例放入容器中。
playerViewContainer.addView(playerView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
// 启动 TVULiveRoomServer 实例。实例启动后，播放器会自动播放视频。
mServer.start();

实现完整播放器控制

在 TVULiveRoomServer 实例启动成功后，您可以调用相关方法实现完整播放器控制，详见 PlayerView。
以下示例代码实现了完整播放器中的视频暂停和播放。

// 引入播放器模块 PlayerView 实例。
PlayerView playerView = (PlayerView) LayoutInflater.from(this).inflate(com.bytedance.live.sdk.R.layout.tvu_player_layout, null, false);
playerView.pause(); // 暂停播放视频。
playerView.play();  // 播放视频。

监听完整播放器事件

您可以监听完整播放器事件。详见 ITVULiveRoomServerListener。
示例代码如下所示：

// 设置监听完整播放器事件。
mServer.setListener(new ITVULiveRoomServerListener() {

    /**
     * 获取直播间信息成功回调。
     * @param activityResult 返回的服务端直播间数据。
     */
    @Override
    public void onGetRoomDataSuccess(ActivityResult activityResult) {
    }

    /**
     * 获取直播间信息失败回调。
     *
     * @param errCode 错误码。0：服务端数据解析错误。1：该直播间禁止手机观看。
     * @param errMsg 失败原因。
     */
    @Override
    public void onGetRoomDataFailed(int errCode, String errMsg) {
    }

    /**
     * 播放器全屏、退出全屏图标点击回调。您可以在该回调中切换横竖屏播放、显示或隐藏状态栏等。
     */
    @Override
    public void onFullScreenChange() {
        // 如果当前为竖屏播放，则切换为横屏播放。
        if (ActivityInfo.SCREEN_ORIENTATION_PORTRAIT == getRequestedOrientation()) {
            setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE);
            Toast.makeText(getBaseContext(), "点击全屏，切换至横屏观看", Toast.LENGTH_LONG).show();
            BarUtils.setStatusBarVisibility(ModularizationActivity.this, false); // 进入全屏模式，隐藏状态栏。
            ViewHelper.removeViewParent(playerView);
            playerView.setIsLandScape(true);
            landPlayerViewContainer.setVisibility(View.VISIBLE);
            landPlayerViewContainer.addView(playerView, 0, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
                    ViewGroup.LayoutParams.MATCH_PARENT));
        } else {
            setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT); // 如果当前为横屏播放，则切换为竖屏播放。
            BarUtils.setStatusBarVisibility(ModularizationActivity.this, true); // 退出全屏模式，显示状态栏。
            ViewHelper.removeViewParent(playerView);
            playerView.setIsLandScape(false);
            landPlayerViewContainer.setVisibility(View.GONE);
            playerViewContainer.addView(playerView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
                    ViewGroup.LayoutParams.MATCH_PARENT));
        }
    }

    /**
     * 直播状态变化回调。
     * @param value 当前直播状态。1：直播中。2：预告。3：回放。4：已结束。
     */
    @Override
    public void liveRoomStatusChange(int value) {
    }

    /**
     * 播放状态变化回调。
     * @param playerStatus 当前播放状态。0：暂停。1：播放。
     */
    @Override
    public void playerStatusChange(int playerStatus) {
    }

    /**
     * 播放器倍速按钮点击回调。
     */
    @Override
    public void onSpeedButtonDidTouch() {
    }

    /**
     * 播放器重放按钮点击回调。
     */
    @Override
    public void onReplayButtonDidTouch() {
    }
});

离开直播间

在观众退出您的观看页面时，您可以通过以下示例代码，离开直播间并销毁完整播放器。

mServer.closeRoom();

完整示例代码

以下示例以直播间的活动 ID（activityId）为 1721010849258****、token 为 pg****、鉴权模式（roomAuthMode）为公开模式的竖屏直播间为例。您可以按需修改相关参数值。

long activityId = 1721010849258****;
String token = "pg****";

TVULiveRoomServer mServer = new TVULiveRoomServer(this, activityId, token, TVULiveRoomServer.SERVER_TYPE_PORTRAIT_LIVEROOM);
PlayerView playerView = (PlayerView) LayoutInflater.from(this).inflate(com.bytedance.live.sdk.R.layout.tvu_player_layout, null, false);
mServer.setRoomAuthMode(TVULiveRoom.TVURoomAuthMode.PUBLIC);
mServer.setPlayerView(playerView);
FrameLayout playerViewContainer = findViewById(R.id.player_view_container);
playerViewContainer.addView(playerView, new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
// 启动 TVULiveRoomServer 实例。
mServer.start();
// 离开直播间并销毁完整播放器。
mServer.closeRoom();