Low-Latency Integration

Updated: 2023-12-01 11:04:54

Overview

Before integrating low-latency playback, ensure your account has low-latency live streaming enabled and the channel is a low-latency channel. Using low-latency in the SDK is similar to regular playback; you only need to add a few configurations for quick integration.

DEMO Download

Low-Latency Playback Demo

This demo also supports standard scene co-hosting.

Quick Start

// 初始化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 // 必须添加该参数
  });
});

`liveSdk.setupPlayer` Method Parameter Addition

lowLatency: boolean: Whether to use low-latency playback. When enabled, if the current channel is a low-latency channel and the device supports low-latency playback, it will be used. lowLatencyConfig?: { controls: boolean; hideNickname: boolean; drag: boolean; }: Low-latency playback settings.

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,
  }
  // ...
});

Check if Co-hosting is Supported

PolyvLiveSdk.checkSystemRequirements(): boolean;

Check if Low-Latency Playback is Active

liveSdk.player.lowLatency: boolean; Indicates whether low-latency playback is currently active.

Check if Low-Latency Viewing is Supported

liveSdk.checkSupportLowLatency(): boolean; Must be called after the PolyvLiveSdk.EVENTS.CHANNEL_DATA_INIT event is triggered.

Switch to Standard CDN Stream Playback

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

If switching fails, low-latency mode will continue to be used.

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

Callback When Only Low-Latency Playback is Allowed but Device Does Not Support It

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

Monitor Low-Latency Network Status

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

Video Area User Count Update in Low-Latency Mode (Includes Local Stream When Switched to Primary View)

Triggered when the total number of speakers, guests, and other co-hosting participants in the current channel changes. You can adjust the UI style accordingly for a better display effect.

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);
});

Co-hosting Instance Initialization Complete

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

In low-latency mode, the SDK automatically subscribes to user streams, so the 'USER_STREAM_ADDED', 'SWITCH_MASTER', and 'USER_PEER_LEAVE' events will not be broadcast.

Notes

After setting the lowLatency parameter, the SDK will determine whether to use low-latency playback based on whether the current channel is a low-latency channel and whether the browser environment supports it. If not supported, regular live streaming will be used.
After playback starts, you can query liveSdk.player.lowLatency: boolean to check if low-latency live streaming is active.
Must use HTTPS or localhost for playback; otherwise, regular live streaming will be used.
For relay channels, simply use the relay target channel's channelId when initializing the SDK.
Due to device limitations, some models or browsers may experience issues with auto-play.
iOS versions below 13 are downgraded to CDN viewing due to poor compatibility and inability to support multi-person playback.
iOS 14.2.x versions are downgraded to CDN playback due to system issues causing audio anomalies.

Live Web SDK