# 无延迟接入

## 简要说明

接入无延迟播放前确保账号开通无延迟直播并且频道是无延迟频道，SDK中使用无延迟与常规播放无异，只需加入若干配置就可以快速接入

## DEMO 下载

[无延迟播放demo](https://git.polyv.net/help-center/document-center/-/blob/master/third_res/POLYV-Low-Latency-Demo.zip)

* 该demo也可支持普通场景连麦

## 快速开始

```javascript
// 初始化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; }`: 无延迟播放设置

```javascript
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;

* 切换失败会继续使用无延迟模式观看

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

### 设置只允许无延迟播放且设备不支持时的回调

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

### 监听无延迟网络状态\`

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

### 无延迟下视频区域人数更新, 如本地流被切换到第一画面该人数也会包含本地流

在当前频道主讲、嘉宾以及其他连麦者总人数变化时触发，这时可根据人做做一下样式调整以便有更好的显示效果

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

#### 连麦实例初始化完成

```javascript
// 连麦实例初始化完成，可以进行连麦相关代码调用，无延迟，普通直播并支持连麦的情况下会回调
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播放
