本章节介绍了拉流 SDK 进阶功能的接入方式，支持的进阶功能包括但不限于 RTM 协议拉流、QUIC 协议拉流、使用 IP 地址拉流、使用主备流、多档位切换、自适应码率（ABR）拉流、SEI。您可以根据实际业务需求，借助拉流 SDK 实现更复杂的功能。

前提条件 #

• 已完成基础功能接入。详见基础功能。
• 如需使用以下功能，确保使用高级版或试用版 License。
  • 拉流超分
  • H.265 硬解和软解

  注意

  试用版 License 仅用于项目测试，不支持续签。过期的试用版 License 会导致鉴权失败，进而中断服务。请在项目上线前升级为正式版 License。详见升级试用版 License 为基础版或高级版 License。

注意事项 #

真机调试：由于 SDK 使用了大量音视频接口，这些接口在模拟器下可能会出现异常，推荐您使用真机进行代码调试。

RTM 协议拉流 #

视频直播拉流 SDK 支持 RTM 协议拉流，该功能需要配合火山引擎视频直播服务使用。详细信息可参考超低延时直播介绍。

接入准备 #

使用视频直播控制台的地址生成器，生成 RTM 和 FLV 拉流地址，其中，FLV 地址可作为 RTM 拉流失败时的自动降级地址。

接入说明 #

配置 RTM 拉流地址和 FLV 拉流地址进行播放。代码示例如下所示。

// 配置 RTM 地址
const playStreamRTM = new VeLivePlayerStream();
playStreamRTM.url = 'https://pull.example.com/live/stream.sdp';
playStreamRTM.format = VeLivePlayerFormat.VeLivePlayerFormatRTM;
playStreamRTM.resolution = VeLivePlayerResolution.VeLivePlayerResolutionOrigin;
playStreamRTM.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

// 配置 FLV 地址
const playStreamFLV = new VeLivePlayerStream();
playStreamFLV.url = 'https://pull.example.com/live/stream.flv';
playStreamFLV.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamFLV.resolution = VeLivePlayerResolution.VeLivePlayerResolutionOrigin;
playStreamFLV.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

// 创建 VeLivePlayerStreamData
const streamData = new VeLivePlayerStreamData();
const mainStreamList = [];

// 添加 RTM 流地址
mainStreamList.push(playStreamRTM);

// 添加 FLV 流地址
mainStreamList.push(playStreamFLV);

// 配置默认 format 和 protocol
streamData.defaultFormat = VeLivePlayerFormat.VeLivePlayerFormatRTM;
streamData.defaultProtocol = VeLivePlayerProtocol.VeLivePlayerProtocolTLS;

// 配置播放源
mLivePlayer.setPlayStreamData(streamData);

// 开始播放
mLivePlayer.play();

QUIC 协议拉流 #

视频直播拉流 SDK 支持 QUIC 协议拉流，该功能需要配合火山引擎视频直播服务使用。

接入准备 #

使用视频直播控制台的地址生成器，生成 FLV 拉流地址。

接入说明 #

配置 QUIC 拉流地址进行播放。代码示例如下所示。

// 配置 FLV 流地址
const playStreamFLV = new VeLivePlayerStream();
playStreamFLV.url = 'https://pull.example.com/live/stream.flv';
playStreamFLV.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamFLV.resolution = VeLivePlayerResolution.VeLivePlayerResolutionOrigin;
playStreamFLV.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

// 创建播放源
const streamData = new VeLivePlayerStreamData();
const mainStreamList = [];

// 添加 FLV 流
mainStreamList.push(playStreamFLV);

// 配置默认 format 和 protocol
streamData.defaultFormat = VeLivePlayerFormat.VeLivePlayerFormatFLV;
streamData.defaultProtocol = VeLivePlayerProtocol.VeLivePlayerProtocolQUIC; // 协议为 QUIC

// 配置播放源
mLivePlayer.setPlayStreamData(streamData);

// 开始播放
mLivePlayer.play();

使用 IP 地址拉流 #

播放器支持通过设置播放域名的 IP 地址进行拉流，以降低播放首帧时间。

接入准备 #

请先获取直播播放地址并解析出 IP 地址。

接入说明 #

使用播放器的 setUrlHostIP 接口将 IP 地址与域名关联起来，播放器将直接根据 IP 地址进行拉流播放。代码示例如下所示。

// 配置播放 URL
mLivePlayer.setPlayUrl('https://pull.example.com/live/stream.flv');
// 添加 IP 地址和域名关联
const valueList = [];
valueList.push('xxx.xxx.xxx.xxx'); // IP 地址
const map = {};
map['pull.example.com'] = valueList;

// 配置 IP 地址
mLivePlayer.setUrlHostIP(map);

// 开始播放
mLivePlayer.play();

使用主备流 #

主备流主要用于直播间容灾，通过配置主备两路直播流地址，在推流和分发环节使用主备流进行直播。播放器在接入时配置主备两路拉流地址，当主流地址拉流失败或者播放出错时，播放器会自动切换到备流地址进行播放。同样地，当备流地址播放出错时，播放器会切换回主流地址进行播放。主备地址可以来自同一直播服务商，也可以来自不同的直播服务商。

接入准备 #

获取主流地址和备流地址，如果使用火山引擎视频直播服务，您可通过视频直播控制台的地址生成器，生成主备拉流地址。

接入说明 #

1. 配置主备流地址进行播放。代码示例如下所示。

// 配置主流地址
const playStreamMain = new VeLivePlayerStream();
playStreamMain.url = 'https://pull.example.com/live/主.flv';
playStreamMain.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamMain.resolution = VeLivePlayerResolution.VeLivePlayerResolutionOrigin;
playStreamMain.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain; // 流类型配置为主流

// 配置备流地址
const playStreamBackup = new VeLivePlayerStream();
playStreamBackup.url = 'https://pull.example.com/live/备.flv';
playStreamBackup.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamBackup.resolution =
  VeLivePlayerResolution.VeLivePlayerResolutionOrigin;
playStreamBackup.streamType =
  VeLivePlayerStreamType.VeLivePlayerStreamTypeBackup; // 流类型配置为备流

// 创建播放源
const streamData = new VeLivePlayerStreamData();

// 开启主备切换
streamData.enableMainBackupSwitch = true;

// 添加主流
const mainStreamList = [];
mainStreamList.push(playStreamMain);

// 添加备流
const backupStreamList = [];
backupStreamList.push(playStreamBackup);

// 配置播放源
mLivePlayer.setPlayStreamData(streamData);

// 开始播放
mLivePlayer.play();

2. 当播放器内部发生主备切换时，会通过回调接口 onMainBackupSwitch 进行通知。代码示例如下所示。

mLivePlayer.setObserver({ onMainBackupSwitch: (player, streamType) =>{}, });

多档位切换 #

播放器支持配置多档位的直播拉流地址，通过接口可以实现多档位直播流的切换。

接入准备 #

获取源流和各档位转码流拉流地址。如您使用了火山引擎视频直播服务，请先登录控制台完成转码配置，再获取拉流地址，地址方法如下所示。

• 功能调试阶段：可使用地址生成器获取拉流地址；
• 功能正式上线：需通过生成拉流地址的 API 或使用服务端 SDK 获取拉流地址。

本文的接入说明以下列拉流地址为例。

接入说明 #

1. 配置多档位地址进行播放。代码示例如下所示。

// 配置多档位流地址
const playStreamOrgin = new VeLivePlayerStream();
playStreamOrgin.url = "https://pull.example.com/live/123456.flv";
playStreamOrgin.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamOrgin.resolution = VeLivePlayerResolution.VeLivePlayerResolutionOrigin; // 原始档位
playStreamOrgin.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

const playStreamUHD = new VeLivePlayerStream();
playStreamUHD.url = "https://pull.example.com/live/123456_uhd.flv";
playStreamUHD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamUHD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionUHD; // UHD 档位
playStreamUHD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

VeLivePlayerStreamData.VeLivePlayerStream playStreamHD = new VeLivePlayerStreamData.VeLivePlayerStream();
playStreamHD.url = "https://pull.example.com/live/123456_hd.flv";
playStreamHD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamHD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionHD; // HD 档位
playStreamHD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

VeLivePlayerStreamData.VeLivePlayerStream playStreamSD = new VeLivePlayerStreamData.VeLivePlayerStream();
playStreamSD.url = "https://pull.example.com/live/123456_sd.flv";
playStreamSD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamSD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionSD; // SD 档位
playStreamSD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

VeLivePlayerStreamData.VeLivePlayerStream playStreamLD = new VeLivePlayerStreamData.VeLivePlayerStream();
playStreamLD.url = "https://pull.example.com/live/123456_ld.flv";
playStreamLD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamLD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionLD; // LD 档位
playStreamLD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;

// 创建播放源
VeLivePlayerStreamData streamData = new VeLivePlayerStreamData();

// 添加多档位流
const mainStreamList = [];
mainStreamList.push(playStreamOrgin);
mainStreamList.push(playStreamUHD);
mainStreamList.push(playStreamHD);
mainStreamList.push(playStreamSD);
mainStreamList.push(playStreamLD);

// 配置默认启播档位
streamData.defaultResolution = VeLivePlayerResolution.VeLivePlayerResolutionOrigin;

// 配置播放源
mLivePlayer.setPlayStreamData(streamData);

// 开始播放
mLivePlayer.play();

2. 通过调用播放器的 switchResolution 接口可以实现多个档位之间的手动切换。代码示例如下所示。

mLivePlayer.switchResolution(VeLivePlayerResolution.VeLivePlayerResolutionUHD); // 切换到 UHD 档位

3. 当档位切换成功时，会通过回调接口 onResolutionSwitch 进行回调。代码示例如下所示。

mLivePlayer.setObserver({ onResolutionSwitch(_player, resolution),{} ,});

自适应码率（ABR）拉流 #

自适应码率（Adaptive Bit-Rate，简称 ABR）是一种流媒体传输技术，通过一系列算法策略，动态切换不同档位媒体流，以达到适应网络带宽变化，防止观众在观看直播过程产生卡顿，提升播放质量和观看体验。

接入准备 #

获取源流和各档位转码流拉流地址。如您使用了火山引擎视频直播服务，请先登录控制台完成转码配置，再获取拉流地址，地址方法如下所示。

• 功能调试阶段：可使用地址生成器获取拉流地址；
• 功能正式上线：需通过生成拉流地址的 API 或使用服务端 SDK 获取拉流地址。

本文的接入说明以下列拉流地址为例。

接入说明 #

1. 配置多档位地址进行播放。代码示例如下所示。

// 配置多档位流地址
const playStreamOrgin = new VeLivePlayerStream();
playStreamOrgin.url = 'https://pull.example.com/live/123456.flv';
playStreamOrgin.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamOrgin.resolution =
  VeLivePlayerResolution.VeLivePlayerResolutionOrigin; // 原始档位
playStreamOrgin.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;
playStreamOrgin.bitrate = 2500;

const playStreamUHD = new VeLivePlayerStream();
playStreamUHD.url = 'https://pull.example.com/live/123456_uhd.flv';
playStreamUHD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamUHD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionUHD; // UHD 档位
playStreamUHD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;
playStreamUHD.bitrate = 2500;

const playStreamHD = new VeLivePlayerStream();
playStreamHD.url = 'https://pull.example.com/live/123456_hd.flv';
playStreamHD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamHD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionHD; // HD 档位
playStreamHD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;
playStreamHD.bitrate = 1000;

const playStreamSD = new VeLivePlayerStream();
playStreamSD.url = 'https://pull.example.com/live/123456_sd.flv';
playStreamSD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamSD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionSD; // SD 档位
playStreamSD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;
playStreamSD.bitrate = 800;

const playStreamLD = new VeLivePlayerStream();
playStreamLD.url = 'https://pull.example.com/live/123456_ld.flv';
playStreamLD.format = VeLivePlayerFormat.VeLivePlayerFormatFLV;
playStreamLD.resolution = VeLivePlayerResolution.VeLivePlayerResolutionLD; // LD 档位
playStreamLD.streamType = VeLivePlayerStreamType.VeLivePlayerStreamTypeMain;
playStreamLD.bitrate = 500;

// 创建播放源
const streamData = new VeLivePlayerStreamData();

// 添加多档位流
const mainStreamList = [];
mainStreamList.push(playStreamOrgin);
mainStreamList.push(playStreamUHD);
mainStreamList.push(playStreamHD);
mainStreamList.push(playStreamSD);
mainStreamList.push(playStreamLD);

// 配置默认启播档位
streamData.defaultResolution =
  VeLivePlayerResolution.VeLivePlayerResolutionOrigin;

// 开启 ABR
streamData.enableABR = true;

// 配置播放源
mLivePlayer.setPlayStreamData(streamData);

// 开始播放
mLivePlayer.play();

2. ABR 档位自动切换时，会通过接口 onResolutionSwitch 进行回调。代码示例如下所示。

mLivePlayer.setObserver({ onResolutionSwitch(_player, resolution) {}, });

SEI #

SEI（Supplemental Enhancement Information）是直播流中的附加信息，它可以用于传递自定义的数据或元数据。

接入说明 #

1. 在调用初始化播放器时，您可以通过配置播放器的 enableSei 属性来开启 SEI 信息的接收功能。代码示例如下所示。

// 创建播放器初始化配置
initPlayer({
  enableSei: true, // 开启 SEI 信息的接收功能
  ...
})

2. 当直播流中有 SEI 信息时，播放器会通过回调接口 onReceiveSeiMessage 进行回调，并将接收到的 SEI 信息传递给回调方法。代码示例如下所示。

mLivePlayer.setObserver({ onReceiveSeiMessage(seiMessage) {},});
  // 处理接收到的 SEI 信息
});

拉流超分 #

超分，即超分辨率技术（Super-Resolution, SR）是指从观测到的低分辨率图像重建出相应的高分辨率图像的过程，移动端实时超分，是指利用算法技术在端上对低分辨率的帧进行实时重建，产生高分辨率的帧显示在屏幕上，从而改善视频内容的细节与对比度，全面提升视频的播放清晰度和观看体验的优化手段。

接入说明 #

1. 联系技术支持开通拉流超分功能。

2. 调用播放器的 setEnableSuperResolution(boolean enable) 方法开启或者关闭拉流超分功能，默认状态为关闭。

   参数	类型	说明
   enable	boolean	是否开启超分功能。

3. 开启失败后，会通过 onStreamFailedOpenSuperResolution 进行回调。代理方法签名如下所示。

   mLivePlayer.setObserver({ onStreamFailedOpenSuperResolution: (errorCode, errorMsg) => {},});
   

   如果开启超分失败，可能有以下几种原因。

   • 流的实际分辨率大于超分支持的最高分辨率。
   • 流的帧率大于超分支持的最高帧率。
   • 当前机型不支持超分。

画中画 #

画中画（Picture-in-Picture，简称 PiP）功能允许用户在播放视频的同时，将播放器缩放为悬浮窗口，以实现多任务操作。该功能适用于 Android 和 iOS 支持画中画的系统版本。

接入说明 #

1. 配置 iOS 权限

若在 iOS 上启用画中画功能，需先完成原生权限配置：

1. 在 Xcode 打开项目，选中目标 Target。
2. 进入 Signing & Capabilities 页签，点击 + Capability，添加 Background Modes。
3. 勾选 Audio, AirPlay, and Picture in Picture。

2. 启动画中画模式

在视频播放状态下调用 startPictureInPicture 方法可启用画中画模式：

startPictureInPicture(aspectRatio?: number, x?: number, y?: number): Promise<void>

• 在 Android 上，可传入参数设置画中画窗口的宽高比和初始位置。
• 在 iOS 上，无需传入参数，窗口尺寸和位置由系统控制。

3. 管理 iOS 后台行为

iOS 系统中，若希望在应用进入后台时开启画中画功能，需在播放器播放状态下，先调用 enablePictureInPicture 开启画中画能力，再调用 startPictureInPicture 进入画中画模式。

4. 监听画中画状态

通过 setPictureInPictureListener 方法监听画中画的相关事件，如进入、退出、点击小窗等。代理方法签名如下所示。

playerRef.current?.setPictureInPictureListener({
  onStartPictureInPicture: () => {
    addLog('onStartPictureInPicture');
  },
  onStopPictureInPicture: () => {
    addLog('onStopPictureInPicture');
    if (AppState.currentState !== 'active') {
      playerRef.current?.stop();
    }
    manualPip.current = false;
  },
  onClickPictureInPicture: () => {
    addLog('onClickPictureInPicture');
  },
  onError: errorCode => {
    addLog('onError' + errorCode);
  },
});