像素流SDK权威指南

像素流SDK

SDK地址：https://gitee.com/pqo/PixelStreamer/

我们的虚幻引擎像素流SDK经过1年的开发，和大规模的生产检验，已经非常稳定，代码和业务耦合，许多功能是根据前端的需求而开发的。

下面是开发过程中的一些核心理念

组成

像素流SDK由3个端组成，分别是：

·前端：浏览器

·中间件：信令服务器，nodejs

·后端：UE4

其中后端是UE官方开发的C++插件，前端和中间件则是由我们开发，改编自UE官方开发的库。将这3个端一一启动（顺序无所谓），就能在浏览器中看到画面了。

动机

UE官方的SDK代码臃肿，使用不便，扩展麻烦，无法满足我们的业务需求（例如我们需要整合进Vue），于是我们决定自己开发一套前端库以及信令服务器。

Pixel Streamer

Pixel Streamer就是我们开发的产品，它是一套轻量级的像素流SDK，包括前端和信令服务器，其中前端库基于WebComponents API，信令服务器基于Node.js。Pixel Streamer是单一的文件，没有依赖，和官方SDK相比轻量了许多。和官方相比，PixelStreamer提供了海量的功能，下面一一介绍。

信令服务器

启动信令服务器：首先要安装WebSocket依赖ws，然后启动signal.js文件，此时可以输入若干启动参数。启动后开始交换offer、answer、candidate。

npm install ws
node signal.js {key}={value}

目前提供了下面4个选项，可以很好的满足我们的业务需求

key	default	usage
player	88	面向浏览器的端口
unreal	8888	面向UE的端口
token	insigma	密码（填写在url后面）
limit	4	最大连接数（连多了UE会挂）

 

密码认证

通过在ws的url后面加上一段token，可以很好地认证，否则默认任何人都可以连接进来，这里的token是明文传输，因为我们有wss协议保证了安全性，wss是通过nginx代理转发实现的。密码默认是insigma，可以通过信令服务器的启动参数token修改。

nginx的wss代理

为了统一部署ssl证书，我们将http和ws统一由nginx代理成https和wss，用户访问wss后，由代理服务器转译成ws。

WebComponnets：Web组件API

WebComponnets API是目前浏览器上非常流行的组件化接口，它可以让我们自定义html元素，以及元素的生命周期，我们将WebRTC的生命周期与元素的生命周期绑定，让前端更好地控制视频流。这里我们定义了 <video>元素的子类，用来呈现视频流，前端要做的就是定义一个video元素，然后指定信令服务器地址，然后就可以访问像素流了。所以可以通过html或者JavaScript两种方式定义：

使用JavaScript:

import "PixelStream.js";
const ps = document.createElement("video", { is: "pixel-stream" });
ps.setAttribute("signal", "ws://127.0.0.1:88");
document.body.appendChild(ps);

 或者使用HTML:

<script src="PixelStream.js"></script>
<video is="pixel-stream" signal="ws://127.0.0.1:88"></video>

生命周期控制

web RTC视频流与html元素的绑定大大降低了维护成本：当元素插入DOM时，视频开始播放，元素删除时，视频停止播放。同时在window（以及父级window）下会自动挂一个元素的引用，让前端调试更加方便。 <video>元素的signal属性被时刻监听，若发生改变则立即重连。除此之外，还可以对生命周期绑定事件，比如下面3个阶段：

video.addEventListener("open", e => {});
video.addEventListener("message", e => {});
video.addEventListener("close", e => {});

启动UE

因为后端库使用了UE官方提供的插件，启动方式因此也和官方一致：首先要开启插件，然后输入启动参数，最后启动。

Plugins > Built-In > Graphics > Pixel Streaming > Enabled
Editor Preferences > Level Editor > Play > Additional Launch Parameters
start packaged.exe -{key}={value}

这里列举常见的启动参数：

• -ForceRes
• -ResX=1920
• -ResY=1080
• -AudioMixer
• -RenderOffScreen
• -graphicsadapter=1
• -PixelStreamingHudStats
• -AllowPixelStreamingCommands
• -PixelStreamingEncoderRateControl=VBR
• -PixelStreamingURL="ws://localhost:8888"

限制连接人数

UE像素流也有一些不可避免的局限性，比如WebRTC的连接数过多容易崩溃，因此在信令服务器中可以通过limit参数设置最大连接人数。超过limit的用户会在http升级阶段就被打回，每个前端会3s一次轮询，直到有信令服务器连接成功。

可变码率VBR

VBR是相对于恒定码率CBR，编码器会根据视频画面的复杂程度在一定范围内调整码流。对于静止的画面（大部分情况）非常节省性能。Pixel Streamer不仅重写了前端库和信令服务器，还记录了后端常见的启动参数和注意事项，其中开启VBR的方法在最新版中更新了。

后端模拟器

为了开发方便，PixelStreamer中内置了后端模拟器，可以在UE不可用的时候模拟一个UE来欺骗前端，测试连通性。

 

WebRTC监控

在test目录下，有个完整的demo用来展示像素流的前端使用方法，可以直接双击index.html文件或者通过http访问来打开，其中最重要的一个功能是WebRTC的监控，监控的内容包括视频、音频、dataChannel相关的属性，用来监测当前像素流的质量。

版本的更新

无论是前端库还是信令服务器都没有使用版本号，取而代之的是最后更新日期，在PixelStreamer官网下载最新的PixelStream.js或signal.js覆盖原始文件即可，非常方便。

Data Channel接口

Data Channel是WebRTC提供的，除音视频以外的数据接口，可以自定义任意的数据格式，这里我们所有的业务接口都依赖于Data Channel，前端通过ps.emitDescriptor函数发送，通过ps.addEventlistener('message')来监听返回事件。

信令服务器的调试

通过ps.debug()函数可以调试信令服务器，通过传入Node.js代码至服务器执行，可以在前端调用信令的所有隐藏功能，下面是一些常见的调试代码：

ps.debug('PLAYER.clients.size')   // 显示玩家数量
ps.debug('PLAYER.clients.forEach(p=>p.id!==playerId&&p.close(1011,"Infinity"));limit=1;')  // 踢掉其他玩家，并阻止以后的任何连接
ps.debug('[...PLAYER.clients].map(x=>x.req.socket.remoteAddress)')  // 打印每个玩家的IP地址
ps.debug('playerId')  // 打印我的ID
ps.pc.getReceivers().find(x=>x.track.kind==='video').transport.iceTransport.getSelectedCandidatePair().remote    // 展示当前选中的ICE candidate
ps.addEventListener('mouseenter',_=>ps.focus()||ps.requestPointerLock())    // 鼠标锁，用来做沉浸式体验
ps.style.pointerEvents='none'   // 禁用鼠标事件，防止干扰

鼠标、键盘、触屏事件

Pixelstream.js中将 <video>上发生的所有输入事件都通过data channel转发至UE，让后端接收到用户的输入，其中鼠标事件分为悬浮鼠标和沉浸式鼠标，触屏分为普通触屏和“触屏模拟鼠标”，这些事件发送服务都是可选的，默认开启了键盘、悬浮鼠标、普通触屏。

video.registerTouchEvents()
video.registerKeyboardEvents()
video.registerFakeMouseEvents()
video.registerMouseHoverEvents()
video.registerPointerlockEvents()

自动播放

SDK自动检测UE的运行情况，一旦建立连接，立即播放，无须手动触发，因为暴露给前端的有且只有一个html元素，只要熟悉HTMLVideoElement这个H5接口的前端开发者就能很轻松的熟悉PixelStreamer。

资源

• ·GitHub镜像：https://github.com/xosg/PixelStreamer/
• ·Gitee镜像：https://gitee.com/pqo/PixelStreamer/
• ·PixelStream.js（前端库）: https://xosg.github.io/PixelStreamer/PixelStream.js
• ·signal.js（信令服务器）: https://xosg.github.io/PixelStreamer/signal.js
• ·Node.js上的WebSocket库: https://www.npmjs.com/package/ws
• ·UE官方的前端库（及信令服务器）: https://github.com/EpicGames/UnrealEngine/tree/release/Samples/PixelStreaming/WebServers/SignallingWebServer
• ·像素流协议（UE官方的后端插件）: https://github.com/EpicGames/UnrealEngine/tree/release/Engine/Plugins/Media/PixelStreaming
• ·兼容IOS端的WebRTC依赖: https://webrtc.github.io/adapter/adapter-latest.js