jetson-inference WebRTC 网页应用实战:基于 HTML/JavaScript 的 DNN 推理流媒体前端
jetson-inference WebRTC 网页应用实战:基于 HTML/JavaScript 的 DNN 推理流媒体前端
本文是 jetson-inference "WebApp Frameworks" 系列指南的开篇实战文章,聚焦仓库内置的最简 WebRTC 示例 python/www/html:通过一个纯 Python 内建 Web 服务器(app.py)与独立流线程(stream.py),实现浏览器与 Jetson 之间的 WebRTC 双向视频传输,并在服务器端叠加分类、检测、分割、姿态、动作识别与背景移除等 TensorRT DNN 推理。读完本文,你将掌握如何一键启动该示例、如何切换并加载不同 DNN 模型,以及如何复用仓库提供的 webrtc.js 与 index.html 核心代码,把 WebRTC 流式播放与推理能力集成进任意自己偏好的 Web 前端框架。
仓库内 WebRTC 示例全家桶
jetson-inference 仓库在 python/www 目录下提供了一系列基于 WebRTC 的示例 Web 应用,覆盖不同的 Python Web 服务器框架,供你构建自己的 AI 交互式网页应用:
+ python/
+ www/
- dash # Plotly Dashboard
- html # core HTML/JavaScript
- flask # Flask + REST
- recognizer # interactive training
这些示例通常都包含以下相似的核心组件:
app.py— 服务器端 Python 代码,负责运行 Web 服务器stream.py— 服务器端 Python 代码,负责 WebRTC 流传输与推理webrtc.js— 客户端 WebRTC JavaScript 代码index.html— 客户端 HTML 页面代码
其中 python/www/html 是最简单、最基础的示例,它突出展示了播放/发送 WebRTC 流并应用 DNN 推理所需的核心 HTML/JavaScript 代码。如果你已经有自己偏好的前端框架,完全可以将其中的 webrtc.js 代码复制、粘贴到任何项目中启用 WebRTC。
运行示例
启动 app.py 会同时做两件事:
- 启动一个内建的 Python Web 服务器(
http.server.HTTPServer+SimpleHTTPRequestHandler)。文档与源码(python/www/html/app.py)均明确指出:它使用简单、但不适合生产环境,且随时可以替换为其他 Web 框架; - 启动一个独立的流线程(
stream.py中的Stream类,继承自threading.Thread),运行 WebRTC 的采集/传输与推理代码。
启动命令:
$ cd jetson-inference/python/www/html
$ python3 app.py --classification # 其他 DNN 选项见下文
注意:接收浏览器摄像头需要启用 HTTPS/SSL。
启动后,在浏览器中访问 https://<JETSON-IP>:8050 即可开始播放/发送流。8050 是这些 Web 应用示例使用的默认端口,可通过 --port=N 命令行参数修改。示例默认配置为 WebRTC 输入与输出(--input=webrtc://@:8554/input、--output=webrtc://@:8554/output,见 app.py),如果想使用其他视频输入设备,可用 --input 参数指定(例如 --input=/dev/video0 使用直连 Jetson 的 V4L2 摄像头)。
app.py 命令行参数一览
结合 python/www/html/app.py 源码,该示例完整支持以下参数:
| 参数 | 默认值 | 作用 |
|---|---|---|
--host |
0.0.0.0 |
Web 服务器监听接口(默认所有接口) |
--port |
8050 |
Web 服务器端口 |
--ssl-key |
环境变量 SSL_KEY |
PEM 编码的 SSL/TLS 私钥路径,用于启用 HTTPS |
--ssl-cert |
环境变量 SSL_CERT |
PEM 编码的 SSL/TLS 证书路径,用于启用 HTTPS |
--input |
webrtc://@:8554/input |
输入摄像头流或视频文件 |
--output |
webrtc://@:8554/output |
从 --input 提供 WebRTC 输出流 |
--no-stream |
关闭 | 禁用输入/输出流(仅提供网页服务) |
--classification |
关闭 | 加载图像分类模型(imageNet 参数) |
--detection |
关闭 | 加载目标检测模型(detectNet 参数) |
--segmentation |
关闭 | 加载语义分割模型(segNet 参数) |
--background |
关闭 | 加载背景移除模型(backgroundNet 参数) |
--action |
关闭 | 加载动作识别模型(actionNet 参数) |
--pose |
关闭 | 加载姿态估计模型(poseNet 参数) |
从源码可以看到几个值得注意的实现细节:
- HTTPS 的开启方式:当同时提供
--ssl-key与--ssl-cert时,代码通过ssl.wrap_socket(httpd.socket, ...)包装 HTTP 服务器 socket 并打印HTTPS enabled(app.py)。这两个参数也分别默认取环境变量SSL_KEY、SSL_CERT的值,因此设置环境变量后即可免传参数; - JS MIME 类型补丁:由于使用 Python 标准库的
SimpleHTTPRequestHandler提供静态文件,代码特意将.js文件的扩展名映射为text/javascript(app.py),否则旧版服务器默认映射可能导致浏览器以错误 MIME 处理webrtc.js; - 流线程的启动:只要未指定
--no-stream,程序就会创建Stream(args)并调用stream.start()(app.py),Web 服务器与推理流互不阻塞地并行运行。
stream.py:流线程如何工作
python/www/html/stream.py 中的 Stream 类封装了视频输入、输出与推理网络:
- 构造函数中,
videoSource(args.input, argv=sys.argv)与videoOutput(args.output, argv=sys.argv)来自 jetson-utils,负责 WebRTC 的解码与硬件加速编码;随后根据命令行传入的网络类型标志实例化对应的 jetson-inference 网络对象(stream.py); process()主循环每次从输入捕获一帧图像,然后按网络类型分派处理逻辑(stream.py):- 分类 / 动作:调用
self.net.Classify(img),将置信度与类别标签用cudaFont叠加到画面左上角(OverlayText); - 检测:调用
self.net.Detect(img, overlay="box,labels,conf"),直接绘制检测框、标签与置信度,并逐条打印检测结果; - 分割:通过
cudaAllocMapped分配与输入同尺寸的叠加缓冲,调用Process+Overlay(filter_mode='linear')生成彩色分割可视化; - 姿态:调用
self.net.Process(img, overlay="links,keypoints"),绘制骨架连线与关键点; - 背景移除:调用
self.net.Process(img)生成去背结果;
- 分类 / 动作:调用
- 处理完的帧通过
self.output.Render(img)输出到 WebRTC 流,并周期性打印捕获帧数、输入输出地址与分辨率统计。
这套结构意味着:只要你熟悉 jetson-utils 的 videoSource/videoOutput 编程模型(仓库中所有 C++/Python 示例都遵循这一模型),就能轻易理解并改造这条推理流水线。
加载 DNN 模型
该示例一次只支持运行一个 DNN 模型——分类、检测、分割、姿态估计、动作识别或背景移除任选其一(后续的 Flask 等示例才支持同时运行多个模型)。启动应用时可按如下方式切换 DNN:
$ python3 app.py --classification --model=resnet18
$ python3 app.py --detection --model=ssd-mobilenet-v2
$ python3 app.py --segmentation --model=fcn-resnet18-mhp
$ python3 app.py --pose --model=resnet18-body
$ python3 app.py --action --model=resnet18-kinetics
$ python3 app.py --background --model=u2net
省略可选的 --model 参数会加载该网络类型的默认模型;如果你在教程中用 PyTorch 训练了自己的自定义分类或检测模型并导出为 ONNX,则可以使用扩展的命令行参数加载它(分类模型用法见 pytorch-cat-dog.md 的 "Processing Images with TensorRT" 一节,检测模型用法见 pytorch-ssd.md 的对应小节)。
小技巧:
python3 app.py --help会打印所有网络类型的完整参数说明(stream.py 中Stream.usage()拼接了videoSource、videoOutput以及各网络类的帮助文本),你可以从中查看所有可用的内置模型名称,也可以对照仓库的 data/networks/models.json 模型清单。
构建自己的 WebRTC 页面:核心 HTML 元素
查阅 python/www/html/index.html 的源码,下面逐步拆解构建使用 WebRTC 的网页时最重要的步骤。
1. JavaScript 导入
在 <head> 中引入两个脚本:
<script type='text/javascript' src='https://webrtc.github.io/adapter/adapter-latest.js'></script>
<script type='text/javascript' src='/webrtc.js'></script>
adapter-latest.js是 WebRTC 官方适配层,用于抹平不同浏览器之间的 API 差异;/webrtc.js是仓库自带的客户端核心逻辑(由SimpleHTTPRequestHandler从python/www/html目录提供),包含下文用到的全部 WebRTC 辅助函数。
2. HTML 视频播放器
在页面 <body> 中创建视频播放元素:
<video id="video-player" autoplay controls playsinline muted></video>
autoplay 保证流建立后自动播放,playsinline 适配移动端 Safari 内联播放,muted 满足浏览器自动播放策略(示例页面中并未使用音频轨道)。
3. 启动播放
// playStream() 是 webrtc.js 中的辅助函数,将指定 WebRTC 流连接到视频播放器
// getWebSocketURL() 是辅助函数,构造形如 wss://<SERVER-IP>:8554/output 的 URL
playStream(getWebsocketURL('output'), document.getElementById('video-player'));
通常这个 JavaScript 函数会在 window.onload() 中调用,或者像示例页面那样绑定到按钮的 onclick() 事件(index.html 中 play() 读取输入框中的流地址并调用 playStream,send() 则调用 sendStream 后自动开始播放)。示例页面还包含了枚举浏览器摄像头并经由 WebRTC 发送到 Jetson 作为视频输入的代码(window.onload 中通过 navigator.mediaDevices.enumerateDevices() 填充下拉列表,见 index.html)。你可以把这段代码连同 webrtc.js 一起复制粘贴到任何项目中启用 WebRTC。
深入 webrtc.js:客户端协议实现
python/www/html/webrtc.js 是客户端 WebRTC 的全部核心,几个关键函数值得重点理解:
getWebsocketProtocol()/getWebsocketURL(name, port=8554):根据当前页面协议自动选择wss://(HTTPS)或ws://(HTTP),并拼接形如wss://<host>:8554/<stream-name>的 WebSocket 地址。WebSocket 端口默认8554,与服务端 WebRTC 服务器监听端口一致;playStream(url, videoElement)(入站播放):将连接类型标记为'inbound',创建WebSocket并监听服务端消息(webrtc.js)。服务端下发的 SDP/ICE 消息由onServerMessage分派到onIncomingSDP/onIncomingICE:前者setRemoteDescription后调用createAnswer()生成应答并通过 WebSocket 回传;后者把 ICE 候选addIceCandidate加入连接。远端媒体轨道到达时,onAddRemoteStream将流挂到视频元素上并调用play();sendStream(url, deviceId)(出站发送):将连接类型标记为'outbound',在收到 SDP 后通过navigator.mediaDevices.getUserMedia({audio: false, video: {deviceId}})获取指定摄像头,addStream后createAnswer()回传(webrtc.js)。若对同一地址重复调用,则走replaceStream()用replaceTrack无缝替换已建立连接的视频轨道;- STUN 配置:两种连接都使用
{ 'iceServers': <a href="https://link.gitcode.com/i/b12d43aed3a2274b84ada54c1eed6906" target="_blank">{ 'urls': 'stun:stun.l.google.com:19302' }] }作为 ICE 服务器,帮助浏览器穿越 NAT 建立 P2P 通道([webrtc.js)。
值得一提的是,所有连接都以流 URL 为 key 存放在 connections 对象中,因此同一页面可以同时维护多个入站/出站连接——这正是后续 Flask 示例能同时展示多个模型流的基石。
前置条件:启用 HTTPS/SSL
如果计划使用浏览器摄像头作为视频输入(即 WebRTC 出站发送),必须在 Jetson 上启用 HTTPS。参考 webrtc-server.md 的完整流程,核心步骤是生成自签名证书并让应用拾取:
$ cd /jetson-inference/data
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes -subj '/CN=localhost'
$ export SSL_KEY=/jetson-inference/data/key.pem
$ export SSL_CERT=/jetson-inference/data/cert.pem
设置 $SSL_KEY 与 $SSL_CERT 环境变量后,仓库中的应用程序会自动检测并启用 HTTPS(app.py 的 --ssl-key / --ssl-cert 默认值正是取自这两个环境变量)。首次访问使用自签名证书的页面时,浏览器会提示证书警告,选择继续后该提示在证书或主机名/IP 变化前不会再次出现。
与 WebRTC 服务器及后续示例的衔接
本示例构建在仓库集成的 WebRTC 服务器之上:任何使用 videoSource/videoOutput 接口的应用程序(包括仓库中的 C++/Python 示例),只要把流 URL 设置为 webrtc://@:8554/my_stream 即可启用 WebRTC 服务(详见 webrtc-server.md)。本示例在此基础上完成了"浏览器 ↔ Jetson ↔ 浏览器"的全双工闭环(--input=webrtc://@:8554/input、--output=webrtc://@:8554/output),并示范了最小化的客户端 HTML/JavaScript 集成方式。
后续的 Flask + REST 示例 正是以本示例的 webrtc.js 代码为内核,进一步引入 Flask Web 框架、Bootstrap 样式与 REST JSON 查询来实现多模型并行切换和实时参数调节;Plotly Dashboard、交互式训练工具 也均沿用同一套 WebRTC 传输机制。掌握了本示例的 HTML/JavaScript 核心代码后,你可以自由选择任何 Web 框架进行集成,把 Jetson 上的实时 DNN 推理能力搬进自己的网页应用。

