無延遲接入

更新時間：2023-12-01 11:04:54

簡要說明

接入無延遲播放前請確保帳號已開通無延遲直播，且頻道為無延遲頻道。SDK 中使用無延遲與常規播放無異，只需加入若干配置即可快速接入。

DEMO 下載

該 demo 也可支援一般場景的連麥

快速開始

// 初始化SDK
var liveSdk = new PolyvLiveSdk({
  channelId: channelId,
  sign: sign, // 频道验证签名
  timestamp: timestamp, // 毫秒级时间戳
  appId: appId, // polyv 后台的appId
  user: {
    userId: userId,
    userName: 'polyv-test',
    pic: 'https://livestatic.videocc.net/assets/wimages/missing_face.png'
  }
});

// 监听频道信息并初始化播放器，并加入lowLatency参数开启无延迟观看
liveSdk.on(PolyvLiveSdk.EVENTS.CHANNEL_DATA_INIT, (event, data) => {
  liveSdk.setupPlayer({
    pptEl: '#ppt',
    el: '#player',
    type: 'live',
    lowLatency: true // 必须添加该参数
  });
});

相關 API

`liveSdk.setupPlayer` 方法增加參數

lowLatency: boolean: 是否使用無延遲播放，開啟後若當前頻道為無延遲頻道且當前裝置支援無延遲播放，則使用無延遲播放 lowLatencyConfig?: { controls: boolean; hideNickname: boolean; drag: boolean; }: 無延遲播放設定

liveSdk.setupPlayer({
  // ...
  lowLatency: true,
  lowLatencyConfig: {
    // 是否显示频道中每个人(讲师、嘉宾、其他连麦者)的控制栏, 默认显示，如果没有视频流或者关闭摄像头则固定显示
    controls: true,
    //是否隐藏控制栏的昵称, 默认显示
    hideNickname: false,
    /* 
    * 默认按非无延迟直播的主讲模式排版，在人数少于13包含13人时非主讲按播放器 1/6 宽度，16:9的比例显示，大于6人时分行显示
    * 大于13人时非主讲按播放器 1/8 宽度，16:9的比例显示，大于8人时分行显示
    * 设置后非主讲按每个人宽 1/3, 宽高 16/9显示，在一行显示，鼠标或者左右滑切换,建议在小尺寸和移动端使用
    */
    drag: isMobile,
    /**
     * 是否只允许无延迟播放，默认为false。可监听 lowLatencyOnly 事件回调
     * 播放器在遇到不兼容无延迟的设备或者无延迟播放失败会降级为普通延迟播放
     * 若只允许无延迟播放可传该参数，设置后如果不支持播放播放器会做不支持播放的提示
     */
    lowLatencyOnly: false,
  }
  // ...
});

查詢是否支援連麥

PolyvLiveSdk.checkSystemRequirements(): boolean;

查詢是否播放無延遲

liveSdk.player.lowLatency: boolean; 當前是否正在播放無延遲

查詢是否支援無延遲觀看

liveSdk.checkSupportLowLatency(): boolean; 需在 PolyvLiveSdk.EVENTS.CHANNEL_DATA_INIT 事件觸發後呼叫

切換到常規 CDN 拉流播放

liveSdk.player.switchToCDNPlayer(onSuccess?: () => void, onError?: (err: any) => void): Promse;

切換失敗會繼續使用無延遲模式觀看

if (liveSdk.player.lowLatency) {
    liveSdk.player.switchToCDNPlayer(function() {
      console.log('切换成功')
    }, function(err) {
      console.error(err); // 切换失败，可能是cdn播放器加载失败，可能是当前正在播cdn
    });
}

設定只允許無延遲播放且裝置不支援時的回呼

liveSdk.player.on('lowLatencyOnly', function(evt) {
  // 'ERR_NOT_SUPPORTED' - 当前设备或者环境不支持
  // 'ERR_ABORTED' - 播放异常
  console.log(evt.type);
})

監聽無延遲網路狀態

// interface Stats { downlink: 1|2|3 }
// downlink为1时代表网络状态良好，
// 2代表网络状态不佳，可能存在卡顿情况 
// 3代表网络状态糟糕，可提示用户切换网络观看或者尝试降级到cdn播放
// 事件大约20秒触发一次，注意多次调用的情况，只在无延迟状态下回调
liveSdk.player.on('networkQuality', function(Stats) {
    if (Stats.downlink === 3) {
      console.log('当前网络状态较差，建议切换网络观看');
    }
});

無延遲下影片區域人數更新，如本地流被切換到第一畫面，該人數也會包含本地流

在當前頻道主講、嘉賓以及其他連麥者總人數變化時觸發，此時可根據人數進行樣式調整，以獲得更好的顯示效果

liveSdk.player.on('rtcUsersUpdated', function(data) {
  // 可根据人数设置界面样式
  // 比如设置lowLatencyConfig.drag = true 后可在人数大于1时将播放器区域设置为4:3，等于1时设置为16:9
  // data = { users: 3, hasLocalStream: true }
  console.log('当前视频区域人数为', data.users);
  console.log('是否包含本地流', data.hasLocalStream);
});

連麥實例初始化完成

// 连麦实例初始化完成，可以进行连麦相关代码调用，无延迟，普通直播并支持连麦的情况下会回调
liveSdk.player.on('rtcInitialized', function(rtc){
  // 也可以这样获取实例 liveSdk.player.rtcInstance
  console.log('连麦sdk实例', rtc);
  // 连麦sdk加载后调用相关代码
});

在無延遲模式下，SDK 會自行訂閱使用者流，因此不會廣播 'USER_STREAM_ADDED'、'SWITCH_MASTER'、'USER_PEER_LEAVE' 事件

注意事項

lowLatency 參數設定後，SDK 會根據當前頻道是否開啟無延遲頻道，以及當前瀏覽器環境是否支援，來決定是否播放無延遲；若不支援則播放常規直播
播放後可查詢 liveSdk.player.lowLatency: boolean 來確認播放的是否為無延遲直播
必須使用 https 或在本地使用 localhost 播放，否則會播放常規直播
轉播頻道只需在初始化 SDK 時，channelId 使用接受轉播的頻道即可
因裝置限制，部分機型或瀏覽器上可能存在無法自動播放的問題
iOS 13 以下因相容性較差且無法支援多人播放，因此降級為 CDN 觀看
iOS 14.2.x 版本因 iOS 系統存在問題，會導致聲音異常，因此降級為 CDN 播放