1. 项目概述与核心价值最近在做一个智慧安防类的项目客户要求在Web端主要是内网大屏和移动端浏览器实时查看监控视频流和直播。技术栈是Unity最终要发布成WebGL。需求很明确在Unity WebGL里流畅播放m3u8格式的在线视频流。这听起来像是把“播放器”和“网页游戏”两个领域硬凑到一起但实际做下来发现Unity的WebGL能力比想象中强大只是坑也不少。这个项目不仅适用于监控、直播看板对于任何需要在3D/2D Web交互应用中嵌入实时视频流的场景比如虚拟展厅的直播窗口、在线教育的视频课件、甚至游戏内的直播互动都是一个非常实用的技术方案。网上关于Unity播放视频的资料很多但针对WebGL环境下处理m3u8这种流媒体协议的资料却比较零散特别是结合最新的Unity版本和浏览器限制时会遇到很多“此路不通”的情况。我花了相当一段时间踩坑、测试和优化才把流程跑通并稳定下来。这篇文章我就把自己从技术选型、核心实现到避坑优化的完整过程以及一个可运行的Demo关键代码系统地分享出来。无论你是想实现一个监控后台还是想在WebGL游戏里加个直播功能相信都能从这里找到直接可用的思路和代码。2. 整体方案设计与技术选型考量2.1 为什么是m3u8流媒体协议简析在监控和直播领域m3u8HTTP Live Streaming, HLS几乎是事实上的标准。它不是一个视频文件而是一个文本格式的播放列表Playlist。一个典型的m3u8文件内容是这样的#EXTM3U #EXT-X-VERSION:3 #EXT-X-TARGETDURATION:10 #EXT-X-MEDIA-SEQUENCE:0 #EXTINF:10.0, http://example.com/live/segment0.ts #EXTINF:10.0, http://example.com/live/segment1.ts #EXTINF:10.0, http://example.com/live/segment2.ts它的工作原理是将整个视频流切割成一系列小的.tsTransport Stream文件片段并通过一个不断更新的.m3u8索引文件来告知播放器下一个该播放哪个片段。这种设计带来了几个关键优势也是我们选择它的核心原因出色的兼容性与穿透性基于标准的HTTP协议传输几乎不会被防火墙或代理拦截非常适合在复杂的网络环境如企业内网、公共Wi-Fi下分发。这也是它能在各种浏览器、移动设备上无障碍播放的基础。自适应码率ABRm3u8可以包含多套不同码率分辨率、带宽的流媒体索引播放器可以根据用户当前的网络速度自动切换保证流畅度。这对于网络状况不一的WebGL用户来说至关重要。天然支持直播与回放通过#EXT-X-ENDLIST标签来区分直播无该标签列表持续更新和点播有该标签列表固定。一套方案可以覆盖监控实时直播和录像回放两种场景。在Unity WebGL环境中我们无法直接使用操作系统级别的媒体解码器因此不能像在PC或移动端原生平台那样用VideoPlayer组件直接喂给它一个m3u8链接就了事。我们必须寻找一个能在浏览器JavaScript环境中解码并播放HLS流的方案然后让Unity去与之通信。2.2 Unity WebGL播放m3u8的三种技术路径对比基于上述限制我们主要有三条路可以走每条路都有其明显的优缺点。路径一使用Unity VideoPlayer 透明视频纹理RenderTexture这是最“Unity原生”的思路。我们可以在场景中创建一个RawImage或使用Mesh Renderer将VideoPlayer的输出指向一个RenderTexture再将该纹理赋给UI或物体。优点与Unity渲染管线集成度高可以方便地应用Shader特效、进行3D空间投影等。致命缺点如前所述Unity WebGL的VideoPlayer仅支持直接播放.mp4,.webm,.ogg等单个媒体文件不支持流媒体协议如http://.../live.m3u8。你需要一个后端服务将m3u8流实时转封装成MP4例如使用FFmpeg这增加了架构复杂度和延迟。对于实时性要求高的监控场景此方案基本不可行。路径二使用HTML5video标签与Unity交互这是目前最主流、最推荐的方案。核心思想是在承载Unity WebGL的HTML页面中创建一个原生的HTML5video元素。利用浏览器自身或通过JavaScript库如hls.js对HLS的强大支持来播放m3u8流。然后通过Unity的WebGL插件与JavaScript互操作jslib将video元素的当前帧每一帧都“拷贝”到Unity内部的一个纹理中。优点直接利用浏览器成熟、高效的HLS播放能力兼容性好性能高。可以享受hls.js带来的自动质量切换、错误恢复等高级特性。Unity端只需负责接收纹理并显示逻辑相对清晰。缺点需要编写JavaScript桥接代码有一定上手门槛。涉及到跨语言C#/JS的频繁数据通信每帧传输图像数据对性能有一定要求需要优化。浏览器的自动播放策略Autoplay Policy可能会造成干扰需要妥善处理用户交互。路径三使用第三方WebGL流媒体插件如AVPro WebGL有一些商业插件如RenderHeads的AVPro Video提供了对WebGL平台流媒体播放的封装。优点开箱即用封装完善可能提供更多高级功能和更好的性能优化。缺点需要付费购买增加了项目成本。并且插件的更新节奏可能与Unity版本或浏览器标准的变化不同步存在一定的绑定风险。我们的选择对于绝大多数项目尤其是考虑成本、灵活性和对最新Web标准的跟进速度路径二HTML5 Video jslib桥接是最佳选择。它构建在开放标准之上可控性强也是本文接下来重点详解的方案。我们将创建一个隐藏的video标签用hls.js库来加载和播放m3u8然后通过Canvas和WebGL上下文将视频帧数据“喂”给Unity。2.3 核心工具与库准备在开始编码前我们需要准备好以下“武器”Unity版本建议使用2021 LTS或2022 LTS等较新版本。它们对WebGL的编译工具链Emscripten更新生成代码的效率和对现代JavaScript API的支持更好。我使用的是Unity 2022.3 LTS。hls.js库这是一个纯JavaScript实现的HLS客户端。我们将把它引入到我们的HTML模板中。可以从 GitHub release 下载hls.min.js或者直接使用CDN链接。一个可用的m3u8测试流地址这是开发和调试的基石。你可以使用一些公开的测试流注意可用性或者在本地使用FFmpegnginx-rtmp-module搭建一个简单的HLS推流服务器。一个公开的测试地址示例请务必遵守使用条款https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8。3. 核心实现构建JavaScript桥接层这是整个方案的技术中枢负责在浏览器环境和Unity之间建立通信和数据传输通道。3.1 创建与初始化视频播放器首先我们需要修改Unity WebGL生成的默认HTML模板。找到你的项目的WebGLTemplates文件夹如果没有则创建复制一份默认模板我们将其命名为MyTemplate。在其下的index.html中我们需要添加关键代码。关键步骤一在HTML中引入hls.js并创建视频元素我们通常将视频元素创建为隐藏的因为我们的目的是获取其帧数据而不是显示它本身。!DOCTYPE html html langen-us head !-- ... 其他head内容 ... -- !-- 引入hls.js库 -- script srchttps://cdn.jsdelivr.net/npm/hls.jslatest/script /head body !-- Unity的Canvas容器 -- div idunity-container classunity-desktop canvas idunity-canvas/canvas !-- ... 加载条等 ... -- /div !-- 我们创建的隐藏视频播放器 -- video idhiddenVideoPlayer styledisplay: none; crossoriginanonymous playsinline/video canvas idvideoFrameCanvas styledisplay: none;/canvas script // 全局变量用于管理HLS实例和状态 var hlsPlayer null; var videoElement null; var frameCanvas null; var frameCtx null; var isVideoReady false; // 此函数将由Unity在初始化后调用 function initVideoPlayer(m3u8Url) { console.log(Initializing video player with URL: m3u8Url); videoElement document.getElementById(hiddenVideoPlayer); frameCanvas document.getElementById(videoFrameCanvas); frameCtx frameCanvas.getContext(2d); if (!videoElement) { console.error(Video element not found!); return; } // 检查浏览器是否原生支持HLS if (videoElement.canPlayType(application/vnd.apple.mpegurl)) { // Safari等原生支持 videoElement.src m3u8Url; console.log(Using native HLS playback.); } else if (Hls.isSupported()) { // 使用hls.js hlsPlayer new Hls({ enableWorker: true, // 使用Web Worker提升性能 lowLatencyMode: true, // 低延迟模式对直播有益 backBufferLength: 90, // 设置回看缓冲区长度秒 // 更多配置项可根据需要调整 }); hlsPlayer.loadSource(m3u8Url); hlsPlayer.attachMedia(videoElement); hlsPlayer.on(Hls.Events.MANIFEST_PARSED, function() { console.log(HLS manifest parsed, ready to play.); // 通知Unity视频已准备就绪 if (typeof unityInstance ! undefined) { unityInstance.SendMessage(VideoManager, OnJsVideoReady); } isVideoReady true; }); // 监听错误事件 hlsPlayer.on(Hls.Events.ERROR, function(event, data) { console.error(HLS Error:, data); // 可以将错误信息传回Unity if (data.fatal) { switch(data.type) { case Hls.ErrorTypes.NETWORK_ERROR: console.error(Fatal network error, trying to recover...); hlsPlayer.startLoad(); break; case Hls.ErrorTypes.MEDIA_ERROR: console.error(Fatal media error, recovering...); hlsPlayer.recoverMediaError(); break; default: console.error(Unrecoverable error, destroying HLS instance.); hlsPlayer.destroy(); break; } } }); } else { console.error(This browser does not support HLS playback.); return; } // 监听视频元数据加载完成以获取正确的宽高 videoElement.addEventListener(loadedmetadata, function() { console.log(Video dimensions: ${videoElement.videoWidth}x${videoElement.videoHeight}); // 设置Canvas尺寸与视频一致 frameCanvas.width videoElement.videoWidth; frameCanvas.height videoElement.videoHeight; // 通知Unity视频尺寸信息 if (typeof unityInstance ! undefined) { unityInstance.SendMessage(VideoManager, OnJsVideoMetadata, videoElement.videoWidth , videoElement.videoHeight); } }); // 处理自动播放策略需要用户手势后播放 videoElement.addEventListener(play, function() { console.log(Video playback started.); }); } /script !-- 后续是Unity的加载脚本... -- /body /html注意crossoriginanonymous属性非常重要。如果你的m3u8流来自不同于网页部署的域名即存在跨域这个属性允许浏览器进行跨域请求同时需要流服务器正确设置CORS头。没有它你可能会遇到“跨源请求被阻止”的错误。3.2 实现帧数据抓取与传输到Unity视频在video标签里播放起来了但Unity还看不到。我们需要将每一帧的画面数据从video元素提取出来并通过Unity WebGL提供的特殊接口传进去。原理我们使用一个离屏的canvas元素上面代码中的videoFrameCanvas通过它的2D上下文ctx将当前视频帧绘制到canvas上。然后从canvas中获取图像数据一个Uint8ClampedArray表示的RGBA像素数组最后将这个庞大的像素数组传递给Unity。直接在每一帧requestAnimationFrame中都进行完整的“绘制-获取数据-传递”操作性能开销是巨大的。我们需要优化按需传输Unity端控制请求频率例如每秒30次30fps而不是浏览器的每秒60次。使用ImageData和Uint8Array视图避免不必要的内存分配。利用UnityWebGL的HEAP8内存这是Unity在JavaScript中暴露的WebAssembly内存堆。我们可以直接将像素数据写入这块内存然后通知Unity去读取这比通过SendMessage传递大数组高效得多。下面是优化后的JavaScript函数// 在之前的script标签内继续添加 var unityTexturePtr 0; // Unity端纹理数据在HEAP中的指针 var textureWidth 0; var textureHeight 0; var isTransferring false; var lastTransferTime 0; var targetFPS 30; var frameInterval 1000 / targetFPS; // Unity调用此函数告知纹理数据在内存中的位置和尺寸 function registerTextureForVideo(ptr, width, height) { unityTexturePtr ptr; textureWidth width; textureHeight height; console.log(Texture registered at ptr ${ptr}, size: ${width}x${height}); // 开始传输循环 requestAnimationFrame(transferVideoFrame); } // 核心函数将视频帧传输到Unity纹理 function transferVideoFrame() { requestAnimationFrame(transferVideoFrame); // 保持循环 if (!videoElement || !isVideoReady || !unityTexturePtr || textureWidth 0 || textureHeight 0) { return; // 条件不满足跳过 } var now performance.now(); if (now - lastTransferTime frameInterval) { return; // 未达到目标帧间隔跳过 } lastTransferTime now; // 确保视频尺寸有效且与注册的纹理尺寸匹配或进行缩放 if (videoElement.videoWidth 0 videoElement.videoHeight 0) { // 绘制视频当前帧到Canvas // 注意这里假设Canvas尺寸已通过loadedmetadata事件设置好与视频尺寸一致。 // 如果Unity纹理尺寸与视频尺寸不同这里需要做缩放绘制。 frameCtx.drawImage(videoElement, 0, 0, frameCanvas.width, frameCanvas.height); // 从Canvas获取ImageData var imageData frameCtx.getImageData(0, 0, frameCanvas.width, frameCanvas.height); var data imageData.data; // 这是一个Uint8ClampedArray, RGBA格式 // 将数据拷贝到Unity的WebGL内存中 // unityInstance.Module.HEAP8 是一个Int8Array视图指向WASM内存 var heap new Uint8Array(unityInstance.Module.HEAP8.buffer); // 计算目标内存区域的起始位置 var startIndex unityTexturePtr; // 将RGBA数据拷贝进去 heap.set(data, startIndex); // 通知Unity数据已更新 if (typeof unityInstance ! undefined) { unityInstance.SendMessage(VideoManager, OnJsFrameUpdated); } } } // 提供给Unity调用的控制函数 function jsPlayVideo() { if (videoElement isVideoReady) { var playPromise videoElement.play(); if (playPromise ! undefined) { playPromise.catch(error { console.log(Autoplay prevented:, error); // 通常需要用户手势触发后再次调用play() }); } } } function jsPauseVideo() { if (videoElement) videoElement.pause(); } function jsSetVolume(volume) { if (videoElement) videoElement.volume volume; } function jsSeekTo(time) { if (videoElement !isNaN(time)) videoElement.currentTime time; } function jsLoadNewSource(m3u8Url) { if (hlsPlayer) { hlsPlayer.loadSource(m3u8Url); hlsPlayer.attachMedia(videoElement); } else if (videoElement.canPlayType(application/vnd.apple.mpegurl)) { videoElement.src m3u8Url; } isVideoReady false; } function jsCleanup() { if (hlsPlayer) { hlsPlayer.destroy(); hlsPlayer null; } if (videoElement) { videoElement.pause(); videoElement.src ; videoElement.load(); } isVideoReady false; unityTexturePtr 0; }这段代码是性能的关键。registerTextureForVideo函数由Unity调用传递一个内存指针。transferVideoFrame函数在浏览器的动画循环中运行但受targetFPS限制它将视频帧绘制到Canvas然后直接将像素数据data拷贝到Unity提供的内存地址heap.set(data, startIndex)。这种方式避免了通过SendMessage传递大量数据产生的序列化和反序列化开销。4. Unity C#端的整合与管理现在我们需要在Unity中创建一个C#脚本来管理整个流程初始化通信、创建接收纹理、调用JavaScript函数、从内存中更新纹理。4.1 创建VideoManager与纹理准备在Unity中创建一个C#脚本命名为WebGLVideoManager.cs。using UnityEngine; using UnityEngine.UI; using System; using System.Runtime.InteropServices; using System.Collections; public class WebGLVideoManager : MonoBehaviour { // 公开变量用于在Inspector中设置 public RawImage targetDisplay; // 用于显示视频的UI RawImage public string testM3u8Url https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8; // 测试流地址 private Texture2D _videoTexture; private Color32[] _texturePixelBuffer; private GCHandle _pixelBufferHandle; private IntPtr _pixelBufferPtr; private bool _isTextureRegistered false; private bool _isJsReady false; private int _videoWidth 0; private int _videoHeight 0; // 导入JavaScript函数 [DllImport(__Internal)] private static extern void initVideoPlayer(string url); [DllImport(__Internal)] private static extern void registerTextureForVideo(int ptr, int width, int height); [DllImport(__Internal)] private static extern void jsPlayVideo(); [DllImport(__Internal)] private static extern void jsPauseVideo(); [DllImport(__Internal)] private static extern void jsSetVolume(float volume); [DllImport(__Internal)] private static extern void jsSeekTo(float time); [DllImport(__Internal)] private static extern void jsLoadNewSource(string url); [DllImport(__Internal)] private static extern void jsCleanup(); void Start() { // 检查运行平台 if (Application.platform ! RuntimePlatform.WebGLPlayer) { Debug.LogWarning(This script is designed for WebGL platform. Current platform: Application.platform); // 可以在其他平台使用Unity原生的VideoPlayer作为fallback return; } if (targetDisplay null) { Debug.LogError(Target Display RawImage is not assigned!); return; } // 第一步初始化视频纹理先假设一个默认尺寸后续会被JS通知的尺寸覆盖 CreateVideoTexture(512, 512); // 第二步调用JS初始化播放器 InitPlayer(); } void CreateVideoTexture(int width, int height) { if (_videoTexture ! null) { Destroy(_videoTexture); } _videoWidth width; _videoHeight height; // 创建Texture2D格式为RGBA32用于接收来自JS的RGBA数据 _videoTexture new Texture2D(width, height, TextureFormat.RGBA32, false); _videoTexture.filterMode FilterMode.Bilinear; _videoTexture.wrapMode TextureWrapMode.Clamp; // 获取纹理的原始像素数据数组 _texturePixelBuffer _videoTexture.GetPixels32(); // 固定这个数组在内存中的地址防止GC移动它并获取指针 _pixelBufferHandle GCHandle.Alloc(_texturePixelBuffer, GCHandleType.Pinned); _pixelBufferPtr _pixelBufferHandle.AddrOfPinnedObject(); // 将纹理赋值给UI targetDisplay.texture _videoTexture; targetDisplay.SetNativeSize(); // 可选让RawImage匹配纹理尺寸 Debug.Log($Video texture created: {width}x{height}. Pixel buffer ptr: {_pixelBufferPtr}); } void InitPlayer() { if (Application.platform RuntimePlatform.WebGLPlayer) { // 调用JS函数传递m3u8地址 initVideoPlayer(testM3u8Url); } } // 由JavaScript调用视频元数据尺寸就绪 public void OnJsVideoMetadata(string sizeStr) { Debug.Log(JS Video Metadata: sizeStr); string[] dimensions sizeStr.Split(,); if (dimensions.Length 2 int.TryParse(dimensions[0], out int w) int.TryParse(dimensions[1], out int h)) { if (w ! _videoWidth || h ! _videoHeight) { // 视频尺寸与当前纹理不同需要重新创建纹理 CreateVideoTexture(w, h); } // 纹理已创建或尺寸匹配现在可以注册给JS了 RegisterTextureToJS(); } } // 由JavaScript调用HLS播放器已准备好 public void OnJsVideoReady() { Debug.Log(JS Video Player is ready.); _isJsReady true; // 可以在这里自动开始播放但注意浏览器自动播放策略 // StartPlayback(); } void RegisterTextureToJS() { if (_isTextureRegistered || _pixelBufferPtr IntPtr.Zero) { return; } // 将纹理数据的内存指针和尺寸传递给JavaScript // 注意指针需要转换为int在WebGL的Emscripten中指针通常用int表示 registerTextureForVideo((int)_pixelBufferPtr, _videoWidth, _videoHeight); _isTextureRegistered true; Debug.Log(Texture registered to JS.); } // 由JavaScript调用新的一帧数据已写入内存 public void OnJsFrameUpdated() { if (!_isTextureRegistered || _videoTexture null) return; // 直接应用像素缓冲区的更改到纹理 // 由于JS是直接修改了_texturePixelBuffer对应的内存这里只需调用Apply // 但为了保险可以重新获取一下引用实际上不需要因为数组是引用类型且内存被固定 _videoTexture.SetPixels32(_texturePixelBuffer); _videoTexture.Apply(false); // 不进行mipmap生成 } // 提供给UI按钮调用的控制方法 public void StartPlayback() { if (Application.platform RuntimePlatform.WebGLPlayer _isJsReady) { jsPlayVideo(); } } public void PausePlayback() { if (Application.platform RuntimePlatform.WebGLPlayer) { jsPauseVideo(); } } public void ChangeVolume(float vol) { if (Application.platform RuntimePlatform.WebGLPlayer) { jsSetVolume(Mathf.Clamp01(vol)); } } public void ChangeSource(string newUrl) { if (Application.platform RuntimePlatform.WebGLPlayer) { testM3u8Url newUrl; jsLoadNewSource(newUrl); _isJsReady false; _isTextureRegistered false; } } void OnDestroy() { // 清理释放固定的内存调用JS清理函数 if (Application.platform RuntimePlatform.WebGLPlayer) { jsCleanup(); } if (_pixelBufferHandle.IsAllocated) { _pixelBufferHandle.Free(); _pixelBufferPtr IntPtr.Zero; } if (_videoTexture ! null) { Destroy(_videoTexture); _videoTexture null; } Debug.Log(WebGLVideoManager cleaned up.); } }4.2 构建场景与测试在Unity场景中创建一个UI Canvas。在Canvas下创建一个RawImage将其锚点拉伸至全屏或调整到你想要的大小。将WebGLVideoManager脚本挂载到一个GameObject上例如创建一个空对象叫VideoController。将上一步创建的RawImage拖拽到脚本的Target Display字段。可选创建几个UI Button分别关联到WebGLVideoManager的StartPlayback(),PausePlayback()等方法。在File - Build Settings中选择WebGL平台在Player Settings - Resolution and Presentation中确保使用了我们自定义的MyTemplate。构建并运行。首次加载可能会因为自动播放策略而需要你点击一下画面或按钮来触发播放。5. 性能优化、兼容性处理与深度避坑指南实现基本功能只是第一步要让它在生产环境中稳定可靠还需要解决一系列棘手问题。5.1 性能优化关键点传输频率与分辨率控制如前所述在JavaScript端通过targetFPS和frameInterval控制传输频率。如果视频源是1080p甚至更高每一帧的像素数据量1920x1080x4 ≈ 8MB会非常大。可以考虑在JS端将Canvas绘制尺寸缩小frameCtx.drawImage(videoElement, 0, 0, targetWidth, targetHeight)再传输给Unity。Unity端的纹理也可以相应创建为小尺寸。这是一种用画质换性能的权衡。内存与垃圾回收GC固定内存C#端使用GCHandle.Alloc(..., Pinned)固定像素数组内存是必须的防止GC移动内存导致JS端写入错误位置。避免托管分配在OnJsFrameUpdated中避免在每帧都new Color32[]或调用GetPixels32()如果不固定内存每次调用都会产生新数组。我们的方案在初始化时只分配一次是高效的。JS端优化ctx.getImageData()和new Uint8Array(view)在循环中也会产生GC压力。确保它们只在必要时执行。使用WebGL2与UNITY_WEBGL宏在Unity中确保发布设置启用了WebGL 2.0通常性能更好。使用#if UNITY_WEBGL !UNITY_EDITOR来条件编译只属于WebGL平台的代码避免在其他平台编译错误。5.2 浏览器兼容性与策略应对自动播放策略Autoplay Policy这是最大的“坑”之一。现代浏览器Chrome, Safari, Firefox等严禁未经用户交互就自动播放带声音的视频。我们的视频元素虽然是隐藏的但如果有音频轨道同样受此限制。解决方案设置muted属性在HTML中为video标签添加muted属性。静音视频通常被允许自动播放。用户可以在UI上提供一个取消静音的按钮通过jsSetVolume(1.0)来恢复声音。用户手势触发将“开始播放”绑定到一个UI按钮的点击事件上。这是最合规的方式。我们的StartPlayback()方法就应该由用户点击来调用。监听play()Promise如JS代码所示videoElement.play()返回一个Promise如果播放被阻止Promise会reject。我们需要捕获这个错误并给出友好提示如“请点击画面以开始播放”。iOS/Safari 特殊处理如网络资料所示某些iOS版本对Unity WebGL支持有问题。此外Safari对HLS有原生支持但行为可能与hls.js略有不同。建议在JS初始化时优先检测原生支持 (videoElement.canPlayType(application/vnd.apple.mpegurl))并使用原生播放。这通常能获得更好的能效比。iOS页面全屏在iOS上视频播放可能会自动触发全屏。为video标签添加playsinline属性可以防止此行为让视频在页面内播放。跨域资源共享CORS如果你的m3u8和ts文件来自另一个域名服务器必须返回正确的CORS头例如Access-Control-Allow-Origin: *或你的网页域名。否则浏览器会阻止JS读取视频数据导致黑屏或错误。这是服务端必须配置的。5.3 错误处理与健壮性HLS.js错误监听我们的JS代码中已经监听了Hls.Events.ERROR。需要根据错误类型data.fatal,data.type,data.details进行不同的恢复尝试如网络错误时重新加载媒体错误时尝试切换码流或重建实例。网络状态监测可以监听视频元素的waiting缓冲和playing事件在Unity端显示“缓冲中...”或“正在播放”的提示。Unity与JS连接状态在Unity的Update中可以定期检查_isJsReady标志如果长时间未就绪可以提示用户刷新或检查网络。内存泄漏务必在OnDestroy中调用JS的jsCleanup()来销毁Hls实例、清空视频源并释放C#端固定的内存句柄GCHandle.Free()。5.4 针对监控/直播场景的增强低延迟模式HLS的默认延迟通常在10-30秒。对于实时监控这是不可接受的。需要在Hls.js配置中启用lowLatencyMode并调整相关参数如maxMaxBufferLength,liveSyncDurationCount等。同时流服务器也需要配置为生成更短的TS片段如2秒。多路视频一个页面播放多个监控画面。你需要为每个视频流创建独立的video元素、Canvas和Hls实例并在Unity端管理多张纹理。注意浏览器对同时解码视频数量的限制通常6个左右。控制信令除了视频流监控往往需要云台控制PTZ。这需要额外的WebSocket或HTTP API与流媒体服务器通信与视频播放逻辑分离。6. 项目构建、部署与Demo使用说明6.1 构建与部署步骤准备自定义模板将修改好的index.html包含所有JS代码和hls.min.js如果本地引用放入Assets/WebGLTemplates/MyTemplate文件夹。Unity设置在Player Settings - Resolution and Presentation下选择MyTemplate作为WebGL模板。发布设置建议在Player Settings - Publishing Settings中启用Compression Format为Brotli获得更小的包体。根据需求调整Data Caching等选项。构建执行Build。构建完成后会生成一个包含index.html,.data,.framework.js,.wasm等文件的文件夹。部署将这个文件夹内的所有文件上传到你的Web服务器如Nginx, Apache, Tomcat或云存储。关键点确保服务器对.wasm文件配置正确的MIME类型application/wasm否则可能无法加载。6.2 Demo运行与测试我将提供一个简化版的Demo项目包。解压后用Unity打开项目。打开MainScene。检查VideoController物体上的WebGLVideoManager脚本Target Display已关联好。你可以修改Test M3U8 Url为你的流地址。点击播放按钮需要先点击一下Canvas触发用户手势。观察Console日志查看初始化、尺寸获取、帧更新的流程。常见问题速查表问题现象可能原因排查步骤黑屏Console无报错1. 自动播放被阻止2. 视频尺寸为03. 纹理注册失败1. 点击页面上的“播放”按钮。2. 检查JS控制台看loadedmetadata事件是否触发视频宽高是否正确。3. 检查Unity Console看Texture registered to JS日志是否打印。黑屏Console有CORS错误视频流服务器未配置CORS1. 在浏览器开发者工具Network面板查看m3u8或ts请求确认响应头是否有Access-Control-Allow-Origin。2. 联系服务端管理员配置CORS。画面卡顿帧率低1. 传输帧率过高或分辨率太大2. 浏览器性能不足3. 网络缓冲1. 在JS中降低targetFPS如15。2. 在JS绘制Canvas时缩小尺寸如缩小到原图50%。3. 检查网络速度降低视频流码率。有声音无画面Unity端纹理更新失败1. 检查OnJsFrameUpdated是否被调用。2. 检查_videoTexture.SetPixels32和Apply是否执行。3. 检查GCHandle是否已释放。iOS上无法播放1. iOS版本兼容性问题2. 使用了不支持的Codec1. 尝试升级测试设备iOS版本。2. 确保视频流编码为H.264 AAC这是iOS Safari最广泛支持的格式。切换视频源后黑屏JS状态未重置确保在jsLoadNewSource后将_isJsReady和_isTextureRegistered设为false等待新的OnJsVideoReady事件。这个方案将浏览器强大的媒体播放能力与Unity的渲染交互能力结合实现了在WebGL中播放m3u8流媒体的目标。虽然涉及到底层的跨语言交互和性能调优但一旦打通它就成为一个非常强大且灵活的基础模块。你可以在此基础上添加UI控件、实现VR/AR中的视频贴图、或者结合AI进行视频分析开拓出更多的应用场景。 Unity WebGL播放m3u8视频流：HTML5桥接方案与性能优化实践
1. 项目概述与核心价值最近在做一个智慧安防类的项目客户要求在Web端主要是内网大屏和移动端浏览器实时查看监控视频流和直播。技术栈是Unity最终要发布成WebGL。需求很明确在Unity WebGL里流畅播放m3u8格式的在线视频流。这听起来像是把“播放器”和“网页游戏”两个领域硬凑到一起但实际做下来发现Unity的WebGL能力比想象中强大只是坑也不少。这个项目不仅适用于监控、直播看板对于任何需要在3D/2D Web交互应用中嵌入实时视频流的场景比如虚拟展厅的直播窗口、在线教育的视频课件、甚至游戏内的直播互动都是一个非常实用的技术方案。网上关于Unity播放视频的资料很多但针对WebGL环境下处理m3u8这种流媒体协议的资料却比较零散特别是结合最新的Unity版本和浏览器限制时会遇到很多“此路不通”的情况。我花了相当一段时间踩坑、测试和优化才把流程跑通并稳定下来。这篇文章我就把自己从技术选型、核心实现到避坑优化的完整过程以及一个可运行的Demo关键代码系统地分享出来。无论你是想实现一个监控后台还是想在WebGL游戏里加个直播功能相信都能从这里找到直接可用的思路和代码。2. 整体方案设计与技术选型考量2.1 为什么是m3u8流媒体协议简析在监控和直播领域m3u8HTTP Live Streaming, HLS几乎是事实上的标准。它不是一个视频文件而是一个文本格式的播放列表Playlist。一个典型的m3u8文件内容是这样的#EXTM3U #EXT-X-VERSION:3 #EXT-X-TARGETDURATION:10 #EXT-X-MEDIA-SEQUENCE:0 #EXTINF:10.0, http://example.com/live/segment0.ts #EXTINF:10.0, http://example.com/live/segment1.ts #EXTINF:10.0, http://example.com/live/segment2.ts它的工作原理是将整个视频流切割成一系列小的.tsTransport Stream文件片段并通过一个不断更新的.m3u8索引文件来告知播放器下一个该播放哪个片段。这种设计带来了几个关键优势也是我们选择它的核心原因出色的兼容性与穿透性基于标准的HTTP协议传输几乎不会被防火墙或代理拦截非常适合在复杂的网络环境如企业内网、公共Wi-Fi下分发。这也是它能在各种浏览器、移动设备上无障碍播放的基础。自适应码率ABRm3u8可以包含多套不同码率分辨率、带宽的流媒体索引播放器可以根据用户当前的网络速度自动切换保证流畅度。这对于网络状况不一的WebGL用户来说至关重要。天然支持直播与回放通过#EXT-X-ENDLIST标签来区分直播无该标签列表持续更新和点播有该标签列表固定。一套方案可以覆盖监控实时直播和录像回放两种场景。在Unity WebGL环境中我们无法直接使用操作系统级别的媒体解码器因此不能像在PC或移动端原生平台那样用VideoPlayer组件直接喂给它一个m3u8链接就了事。我们必须寻找一个能在浏览器JavaScript环境中解码并播放HLS流的方案然后让Unity去与之通信。2.2 Unity WebGL播放m3u8的三种技术路径对比基于上述限制我们主要有三条路可以走每条路都有其明显的优缺点。路径一使用Unity VideoPlayer 透明视频纹理RenderTexture这是最“Unity原生”的思路。我们可以在场景中创建一个RawImage或使用Mesh Renderer将VideoPlayer的输出指向一个RenderTexture再将该纹理赋给UI或物体。优点与Unity渲染管线集成度高可以方便地应用Shader特效、进行3D空间投影等。致命缺点如前所述Unity WebGL的VideoPlayer仅支持直接播放.mp4,.webm,.ogg等单个媒体文件不支持流媒体协议如http://.../live.m3u8。你需要一个后端服务将m3u8流实时转封装成MP4例如使用FFmpeg这增加了架构复杂度和延迟。对于实时性要求高的监控场景此方案基本不可行。路径二使用HTML5video标签与Unity交互这是目前最主流、最推荐的方案。核心思想是在承载Unity WebGL的HTML页面中创建一个原生的HTML5video元素。利用浏览器自身或通过JavaScript库如hls.js对HLS的强大支持来播放m3u8流。然后通过Unity的WebGL插件与JavaScript互操作jslib将video元素的当前帧每一帧都“拷贝”到Unity内部的一个纹理中。优点直接利用浏览器成熟、高效的HLS播放能力兼容性好性能高。可以享受hls.js带来的自动质量切换、错误恢复等高级特性。Unity端只需负责接收纹理并显示逻辑相对清晰。缺点需要编写JavaScript桥接代码有一定上手门槛。涉及到跨语言C#/JS的频繁数据通信每帧传输图像数据对性能有一定要求需要优化。浏览器的自动播放策略Autoplay Policy可能会造成干扰需要妥善处理用户交互。路径三使用第三方WebGL流媒体插件如AVPro WebGL有一些商业插件如RenderHeads的AVPro Video提供了对WebGL平台流媒体播放的封装。优点开箱即用封装完善可能提供更多高级功能和更好的性能优化。缺点需要付费购买增加了项目成本。并且插件的更新节奏可能与Unity版本或浏览器标准的变化不同步存在一定的绑定风险。我们的选择对于绝大多数项目尤其是考虑成本、灵活性和对最新Web标准的跟进速度路径二HTML5 Video jslib桥接是最佳选择。它构建在开放标准之上可控性强也是本文接下来重点详解的方案。我们将创建一个隐藏的video标签用hls.js库来加载和播放m3u8然后通过Canvas和WebGL上下文将视频帧数据“喂”给Unity。2.3 核心工具与库准备在开始编码前我们需要准备好以下“武器”Unity版本建议使用2021 LTS或2022 LTS等较新版本。它们对WebGL的编译工具链Emscripten更新生成代码的效率和对现代JavaScript API的支持更好。我使用的是Unity 2022.3 LTS。hls.js库这是一个纯JavaScript实现的HLS客户端。我们将把它引入到我们的HTML模板中。可以从 GitHub release 下载hls.min.js或者直接使用CDN链接。一个可用的m3u8测试流地址这是开发和调试的基石。你可以使用一些公开的测试流注意可用性或者在本地使用FFmpegnginx-rtmp-module搭建一个简单的HLS推流服务器。一个公开的测试地址示例请务必遵守使用条款https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8。3. 核心实现构建JavaScript桥接层这是整个方案的技术中枢负责在浏览器环境和Unity之间建立通信和数据传输通道。3.1 创建与初始化视频播放器首先我们需要修改Unity WebGL生成的默认HTML模板。找到你的项目的WebGLTemplates文件夹如果没有则创建复制一份默认模板我们将其命名为MyTemplate。在其下的index.html中我们需要添加关键代码。关键步骤一在HTML中引入hls.js并创建视频元素我们通常将视频元素创建为隐藏的因为我们的目的是获取其帧数据而不是显示它本身。!DOCTYPE html html langen-us head !-- ... 其他head内容 ... -- !-- 引入hls.js库 -- script srchttps://cdn.jsdelivr.net/npm/hls.jslatest/script /head body !-- Unity的Canvas容器 -- div idunity-container classunity-desktop canvas idunity-canvas/canvas !-- ... 加载条等 ... -- /div !-- 我们创建的隐藏视频播放器 -- video idhiddenVideoPlayer styledisplay: none; crossoriginanonymous playsinline/video canvas idvideoFrameCanvas styledisplay: none;/canvas script // 全局变量用于管理HLS实例和状态 var hlsPlayer null; var videoElement null; var frameCanvas null; var frameCtx null; var isVideoReady false; // 此函数将由Unity在初始化后调用 function initVideoPlayer(m3u8Url) { console.log(Initializing video player with URL: m3u8Url); videoElement document.getElementById(hiddenVideoPlayer); frameCanvas document.getElementById(videoFrameCanvas); frameCtx frameCanvas.getContext(2d); if (!videoElement) { console.error(Video element not found!); return; } // 检查浏览器是否原生支持HLS if (videoElement.canPlayType(application/vnd.apple.mpegurl)) { // Safari等原生支持 videoElement.src m3u8Url; console.log(Using native HLS playback.); } else if (Hls.isSupported()) { // 使用hls.js hlsPlayer new Hls({ enableWorker: true, // 使用Web Worker提升性能 lowLatencyMode: true, // 低延迟模式对直播有益 backBufferLength: 90, // 设置回看缓冲区长度秒 // 更多配置项可根据需要调整 }); hlsPlayer.loadSource(m3u8Url); hlsPlayer.attachMedia(videoElement); hlsPlayer.on(Hls.Events.MANIFEST_PARSED, function() { console.log(HLS manifest parsed, ready to play.); // 通知Unity视频已准备就绪 if (typeof unityInstance ! undefined) { unityInstance.SendMessage(VideoManager, OnJsVideoReady); } isVideoReady true; }); // 监听错误事件 hlsPlayer.on(Hls.Events.ERROR, function(event, data) { console.error(HLS Error:, data); // 可以将错误信息传回Unity if (data.fatal) { switch(data.type) { case Hls.ErrorTypes.NETWORK_ERROR: console.error(Fatal network error, trying to recover...); hlsPlayer.startLoad(); break; case Hls.ErrorTypes.MEDIA_ERROR: console.error(Fatal media error, recovering...); hlsPlayer.recoverMediaError(); break; default: console.error(Unrecoverable error, destroying HLS instance.); hlsPlayer.destroy(); break; } } }); } else { console.error(This browser does not support HLS playback.); return; } // 监听视频元数据加载完成以获取正确的宽高 videoElement.addEventListener(loadedmetadata, function() { console.log(Video dimensions: ${videoElement.videoWidth}x${videoElement.videoHeight}); // 设置Canvas尺寸与视频一致 frameCanvas.width videoElement.videoWidth; frameCanvas.height videoElement.videoHeight; // 通知Unity视频尺寸信息 if (typeof unityInstance ! undefined) { unityInstance.SendMessage(VideoManager, OnJsVideoMetadata, videoElement.videoWidth , videoElement.videoHeight); } }); // 处理自动播放策略需要用户手势后播放 videoElement.addEventListener(play, function() { console.log(Video playback started.); }); } /script !-- 后续是Unity的加载脚本... -- /body /html注意crossoriginanonymous属性非常重要。如果你的m3u8流来自不同于网页部署的域名即存在跨域这个属性允许浏览器进行跨域请求同时需要流服务器正确设置CORS头。没有它你可能会遇到“跨源请求被阻止”的错误。3.2 实现帧数据抓取与传输到Unity视频在video标签里播放起来了但Unity还看不到。我们需要将每一帧的画面数据从video元素提取出来并通过Unity WebGL提供的特殊接口传进去。原理我们使用一个离屏的canvas元素上面代码中的videoFrameCanvas通过它的2D上下文ctx将当前视频帧绘制到canvas上。然后从canvas中获取图像数据一个Uint8ClampedArray表示的RGBA像素数组最后将这个庞大的像素数组传递给Unity。直接在每一帧requestAnimationFrame中都进行完整的“绘制-获取数据-传递”操作性能开销是巨大的。我们需要优化按需传输Unity端控制请求频率例如每秒30次30fps而不是浏览器的每秒60次。使用ImageData和Uint8Array视图避免不必要的内存分配。利用UnityWebGL的HEAP8内存这是Unity在JavaScript中暴露的WebAssembly内存堆。我们可以直接将像素数据写入这块内存然后通知Unity去读取这比通过SendMessage传递大数组高效得多。下面是优化后的JavaScript函数// 在之前的script标签内继续添加 var unityTexturePtr 0; // Unity端纹理数据在HEAP中的指针 var textureWidth 0; var textureHeight 0; var isTransferring false; var lastTransferTime 0; var targetFPS 30; var frameInterval 1000 / targetFPS; // Unity调用此函数告知纹理数据在内存中的位置和尺寸 function registerTextureForVideo(ptr, width, height) { unityTexturePtr ptr; textureWidth width; textureHeight height; console.log(Texture registered at ptr ${ptr}, size: ${width}x${height}); // 开始传输循环 requestAnimationFrame(transferVideoFrame); } // 核心函数将视频帧传输到Unity纹理 function transferVideoFrame() { requestAnimationFrame(transferVideoFrame); // 保持循环 if (!videoElement || !isVideoReady || !unityTexturePtr || textureWidth 0 || textureHeight 0) { return; // 条件不满足跳过 } var now performance.now(); if (now - lastTransferTime frameInterval) { return; // 未达到目标帧间隔跳过 } lastTransferTime now; // 确保视频尺寸有效且与注册的纹理尺寸匹配或进行缩放 if (videoElement.videoWidth 0 videoElement.videoHeight 0) { // 绘制视频当前帧到Canvas // 注意这里假设Canvas尺寸已通过loadedmetadata事件设置好与视频尺寸一致。 // 如果Unity纹理尺寸与视频尺寸不同这里需要做缩放绘制。 frameCtx.drawImage(videoElement, 0, 0, frameCanvas.width, frameCanvas.height); // 从Canvas获取ImageData var imageData frameCtx.getImageData(0, 0, frameCanvas.width, frameCanvas.height); var data imageData.data; // 这是一个Uint8ClampedArray, RGBA格式 // 将数据拷贝到Unity的WebGL内存中 // unityInstance.Module.HEAP8 是一个Int8Array视图指向WASM内存 var heap new Uint8Array(unityInstance.Module.HEAP8.buffer); // 计算目标内存区域的起始位置 var startIndex unityTexturePtr; // 将RGBA数据拷贝进去 heap.set(data, startIndex); // 通知Unity数据已更新 if (typeof unityInstance ! undefined) { unityInstance.SendMessage(VideoManager, OnJsFrameUpdated); } } } // 提供给Unity调用的控制函数 function jsPlayVideo() { if (videoElement isVideoReady) { var playPromise videoElement.play(); if (playPromise ! undefined) { playPromise.catch(error { console.log(Autoplay prevented:, error); // 通常需要用户手势触发后再次调用play() }); } } } function jsPauseVideo() { if (videoElement) videoElement.pause(); } function jsSetVolume(volume) { if (videoElement) videoElement.volume volume; } function jsSeekTo(time) { if (videoElement !isNaN(time)) videoElement.currentTime time; } function jsLoadNewSource(m3u8Url) { if (hlsPlayer) { hlsPlayer.loadSource(m3u8Url); hlsPlayer.attachMedia(videoElement); } else if (videoElement.canPlayType(application/vnd.apple.mpegurl)) { videoElement.src m3u8Url; } isVideoReady false; } function jsCleanup() { if (hlsPlayer) { hlsPlayer.destroy(); hlsPlayer null; } if (videoElement) { videoElement.pause(); videoElement.src ; videoElement.load(); } isVideoReady false; unityTexturePtr 0; }这段代码是性能的关键。registerTextureForVideo函数由Unity调用传递一个内存指针。transferVideoFrame函数在浏览器的动画循环中运行但受targetFPS限制它将视频帧绘制到Canvas然后直接将像素数据data拷贝到Unity提供的内存地址heap.set(data, startIndex)。这种方式避免了通过SendMessage传递大量数据产生的序列化和反序列化开销。4. Unity C#端的整合与管理现在我们需要在Unity中创建一个C#脚本来管理整个流程初始化通信、创建接收纹理、调用JavaScript函数、从内存中更新纹理。4.1 创建VideoManager与纹理准备在Unity中创建一个C#脚本命名为WebGLVideoManager.cs。using UnityEngine; using UnityEngine.UI; using System; using System.Runtime.InteropServices; using System.Collections; public class WebGLVideoManager : MonoBehaviour { // 公开变量用于在Inspector中设置 public RawImage targetDisplay; // 用于显示视频的UI RawImage public string testM3u8Url https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8; // 测试流地址 private Texture2D _videoTexture; private Color32[] _texturePixelBuffer; private GCHandle _pixelBufferHandle; private IntPtr _pixelBufferPtr; private bool _isTextureRegistered false; private bool _isJsReady false; private int _videoWidth 0; private int _videoHeight 0; // 导入JavaScript函数 [DllImport(__Internal)] private static extern void initVideoPlayer(string url); [DllImport(__Internal)] private static extern void registerTextureForVideo(int ptr, int width, int height); [DllImport(__Internal)] private static extern void jsPlayVideo(); [DllImport(__Internal)] private static extern void jsPauseVideo(); [DllImport(__Internal)] private static extern void jsSetVolume(float volume); [DllImport(__Internal)] private static extern void jsSeekTo(float time); [DllImport(__Internal)] private static extern void jsLoadNewSource(string url); [DllImport(__Internal)] private static extern void jsCleanup(); void Start() { // 检查运行平台 if (Application.platform ! RuntimePlatform.WebGLPlayer) { Debug.LogWarning(This script is designed for WebGL platform. Current platform: Application.platform); // 可以在其他平台使用Unity原生的VideoPlayer作为fallback return; } if (targetDisplay null) { Debug.LogError(Target Display RawImage is not assigned!); return; } // 第一步初始化视频纹理先假设一个默认尺寸后续会被JS通知的尺寸覆盖 CreateVideoTexture(512, 512); // 第二步调用JS初始化播放器 InitPlayer(); } void CreateVideoTexture(int width, int height) { if (_videoTexture ! null) { Destroy(_videoTexture); } _videoWidth width; _videoHeight height; // 创建Texture2D格式为RGBA32用于接收来自JS的RGBA数据 _videoTexture new Texture2D(width, height, TextureFormat.RGBA32, false); _videoTexture.filterMode FilterMode.Bilinear; _videoTexture.wrapMode TextureWrapMode.Clamp; // 获取纹理的原始像素数据数组 _texturePixelBuffer _videoTexture.GetPixels32(); // 固定这个数组在内存中的地址防止GC移动它并获取指针 _pixelBufferHandle GCHandle.Alloc(_texturePixelBuffer, GCHandleType.Pinned); _pixelBufferPtr _pixelBufferHandle.AddrOfPinnedObject(); // 将纹理赋值给UI targetDisplay.texture _videoTexture; targetDisplay.SetNativeSize(); // 可选让RawImage匹配纹理尺寸 Debug.Log($Video texture created: {width}x{height}. Pixel buffer ptr: {_pixelBufferPtr}); } void InitPlayer() { if (Application.platform RuntimePlatform.WebGLPlayer) { // 调用JS函数传递m3u8地址 initVideoPlayer(testM3u8Url); } } // 由JavaScript调用视频元数据尺寸就绪 public void OnJsVideoMetadata(string sizeStr) { Debug.Log(JS Video Metadata: sizeStr); string[] dimensions sizeStr.Split(,); if (dimensions.Length 2 int.TryParse(dimensions[0], out int w) int.TryParse(dimensions[1], out int h)) { if (w ! _videoWidth || h ! _videoHeight) { // 视频尺寸与当前纹理不同需要重新创建纹理 CreateVideoTexture(w, h); } // 纹理已创建或尺寸匹配现在可以注册给JS了 RegisterTextureToJS(); } } // 由JavaScript调用HLS播放器已准备好 public void OnJsVideoReady() { Debug.Log(JS Video Player is ready.); _isJsReady true; // 可以在这里自动开始播放但注意浏览器自动播放策略 // StartPlayback(); } void RegisterTextureToJS() { if (_isTextureRegistered || _pixelBufferPtr IntPtr.Zero) { return; } // 将纹理数据的内存指针和尺寸传递给JavaScript // 注意指针需要转换为int在WebGL的Emscripten中指针通常用int表示 registerTextureForVideo((int)_pixelBufferPtr, _videoWidth, _videoHeight); _isTextureRegistered true; Debug.Log(Texture registered to JS.); } // 由JavaScript调用新的一帧数据已写入内存 public void OnJsFrameUpdated() { if (!_isTextureRegistered || _videoTexture null) return; // 直接应用像素缓冲区的更改到纹理 // 由于JS是直接修改了_texturePixelBuffer对应的内存这里只需调用Apply // 但为了保险可以重新获取一下引用实际上不需要因为数组是引用类型且内存被固定 _videoTexture.SetPixels32(_texturePixelBuffer); _videoTexture.Apply(false); // 不进行mipmap生成 } // 提供给UI按钮调用的控制方法 public void StartPlayback() { if (Application.platform RuntimePlatform.WebGLPlayer _isJsReady) { jsPlayVideo(); } } public void PausePlayback() { if (Application.platform RuntimePlatform.WebGLPlayer) { jsPauseVideo(); } } public void ChangeVolume(float vol) { if (Application.platform RuntimePlatform.WebGLPlayer) { jsSetVolume(Mathf.Clamp01(vol)); } } public void ChangeSource(string newUrl) { if (Application.platform RuntimePlatform.WebGLPlayer) { testM3u8Url newUrl; jsLoadNewSource(newUrl); _isJsReady false; _isTextureRegistered false; } } void OnDestroy() { // 清理释放固定的内存调用JS清理函数 if (Application.platform RuntimePlatform.WebGLPlayer) { jsCleanup(); } if (_pixelBufferHandle.IsAllocated) { _pixelBufferHandle.Free(); _pixelBufferPtr IntPtr.Zero; } if (_videoTexture ! null) { Destroy(_videoTexture); _videoTexture null; } Debug.Log(WebGLVideoManager cleaned up.); } }4.2 构建场景与测试在Unity场景中创建一个UI Canvas。在Canvas下创建一个RawImage将其锚点拉伸至全屏或调整到你想要的大小。将WebGLVideoManager脚本挂载到一个GameObject上例如创建一个空对象叫VideoController。将上一步创建的RawImage拖拽到脚本的Target Display字段。可选创建几个UI Button分别关联到WebGLVideoManager的StartPlayback(),PausePlayback()等方法。在File - Build Settings中选择WebGL平台在Player Settings - Resolution and Presentation中确保使用了我们自定义的MyTemplate。构建并运行。首次加载可能会因为自动播放策略而需要你点击一下画面或按钮来触发播放。5. 性能优化、兼容性处理与深度避坑指南实现基本功能只是第一步要让它在生产环境中稳定可靠还需要解决一系列棘手问题。5.1 性能优化关键点传输频率与分辨率控制如前所述在JavaScript端通过targetFPS和frameInterval控制传输频率。如果视频源是1080p甚至更高每一帧的像素数据量1920x1080x4 ≈ 8MB会非常大。可以考虑在JS端将Canvas绘制尺寸缩小frameCtx.drawImage(videoElement, 0, 0, targetWidth, targetHeight)再传输给Unity。Unity端的纹理也可以相应创建为小尺寸。这是一种用画质换性能的权衡。内存与垃圾回收GC固定内存C#端使用GCHandle.Alloc(..., Pinned)固定像素数组内存是必须的防止GC移动内存导致JS端写入错误位置。避免托管分配在OnJsFrameUpdated中避免在每帧都new Color32[]或调用GetPixels32()如果不固定内存每次调用都会产生新数组。我们的方案在初始化时只分配一次是高效的。JS端优化ctx.getImageData()和new Uint8Array(view)在循环中也会产生GC压力。确保它们只在必要时执行。使用WebGL2与UNITY_WEBGL宏在Unity中确保发布设置启用了WebGL 2.0通常性能更好。使用#if UNITY_WEBGL !UNITY_EDITOR来条件编译只属于WebGL平台的代码避免在其他平台编译错误。5.2 浏览器兼容性与策略应对自动播放策略Autoplay Policy这是最大的“坑”之一。现代浏览器Chrome, Safari, Firefox等严禁未经用户交互就自动播放带声音的视频。我们的视频元素虽然是隐藏的但如果有音频轨道同样受此限制。解决方案设置muted属性在HTML中为video标签添加muted属性。静音视频通常被允许自动播放。用户可以在UI上提供一个取消静音的按钮通过jsSetVolume(1.0)来恢复声音。用户手势触发将“开始播放”绑定到一个UI按钮的点击事件上。这是最合规的方式。我们的StartPlayback()方法就应该由用户点击来调用。监听play()Promise如JS代码所示videoElement.play()返回一个Promise如果播放被阻止Promise会reject。我们需要捕获这个错误并给出友好提示如“请点击画面以开始播放”。iOS/Safari 特殊处理如网络资料所示某些iOS版本对Unity WebGL支持有问题。此外Safari对HLS有原生支持但行为可能与hls.js略有不同。建议在JS初始化时优先检测原生支持 (videoElement.canPlayType(application/vnd.apple.mpegurl))并使用原生播放。这通常能获得更好的能效比。iOS页面全屏在iOS上视频播放可能会自动触发全屏。为video标签添加playsinline属性可以防止此行为让视频在页面内播放。跨域资源共享CORS如果你的m3u8和ts文件来自另一个域名服务器必须返回正确的CORS头例如Access-Control-Allow-Origin: *或你的网页域名。否则浏览器会阻止JS读取视频数据导致黑屏或错误。这是服务端必须配置的。5.3 错误处理与健壮性HLS.js错误监听我们的JS代码中已经监听了Hls.Events.ERROR。需要根据错误类型data.fatal,data.type,data.details进行不同的恢复尝试如网络错误时重新加载媒体错误时尝试切换码流或重建实例。网络状态监测可以监听视频元素的waiting缓冲和playing事件在Unity端显示“缓冲中...”或“正在播放”的提示。Unity与JS连接状态在Unity的Update中可以定期检查_isJsReady标志如果长时间未就绪可以提示用户刷新或检查网络。内存泄漏务必在OnDestroy中调用JS的jsCleanup()来销毁Hls实例、清空视频源并释放C#端固定的内存句柄GCHandle.Free()。5.4 针对监控/直播场景的增强低延迟模式HLS的默认延迟通常在10-30秒。对于实时监控这是不可接受的。需要在Hls.js配置中启用lowLatencyMode并调整相关参数如maxMaxBufferLength,liveSyncDurationCount等。同时流服务器也需要配置为生成更短的TS片段如2秒。多路视频一个页面播放多个监控画面。你需要为每个视频流创建独立的video元素、Canvas和Hls实例并在Unity端管理多张纹理。注意浏览器对同时解码视频数量的限制通常6个左右。控制信令除了视频流监控往往需要云台控制PTZ。这需要额外的WebSocket或HTTP API与流媒体服务器通信与视频播放逻辑分离。6. 项目构建、部署与Demo使用说明6.1 构建与部署步骤准备自定义模板将修改好的index.html包含所有JS代码和hls.min.js如果本地引用放入Assets/WebGLTemplates/MyTemplate文件夹。Unity设置在Player Settings - Resolution and Presentation下选择MyTemplate作为WebGL模板。发布设置建议在Player Settings - Publishing Settings中启用Compression Format为Brotli获得更小的包体。根据需求调整Data Caching等选项。构建执行Build。构建完成后会生成一个包含index.html,.data,.framework.js,.wasm等文件的文件夹。部署将这个文件夹内的所有文件上传到你的Web服务器如Nginx, Apache, Tomcat或云存储。关键点确保服务器对.wasm文件配置正确的MIME类型application/wasm否则可能无法加载。6.2 Demo运行与测试我将提供一个简化版的Demo项目包。解压后用Unity打开项目。打开MainScene。检查VideoController物体上的WebGLVideoManager脚本Target Display已关联好。你可以修改Test M3U8 Url为你的流地址。点击播放按钮需要先点击一下Canvas触发用户手势。观察Console日志查看初始化、尺寸获取、帧更新的流程。常见问题速查表问题现象可能原因排查步骤黑屏Console无报错1. 自动播放被阻止2. 视频尺寸为03. 纹理注册失败1. 点击页面上的“播放”按钮。2. 检查JS控制台看loadedmetadata事件是否触发视频宽高是否正确。3. 检查Unity Console看Texture registered to JS日志是否打印。黑屏Console有CORS错误视频流服务器未配置CORS1. 在浏览器开发者工具Network面板查看m3u8或ts请求确认响应头是否有Access-Control-Allow-Origin。2. 联系服务端管理员配置CORS。画面卡顿帧率低1. 传输帧率过高或分辨率太大2. 浏览器性能不足3. 网络缓冲1. 在JS中降低targetFPS如15。2. 在JS绘制Canvas时缩小尺寸如缩小到原图50%。3. 检查网络速度降低视频流码率。有声音无画面Unity端纹理更新失败1. 检查OnJsFrameUpdated是否被调用。2. 检查_videoTexture.SetPixels32和Apply是否执行。3. 检查GCHandle是否已释放。iOS上无法播放1. iOS版本兼容性问题2. 使用了不支持的Codec1. 尝试升级测试设备iOS版本。2. 确保视频流编码为H.264 AAC这是iOS Safari最广泛支持的格式。切换视频源后黑屏JS状态未重置确保在jsLoadNewSource后将_isJsReady和_isTextureRegistered设为false等待新的OnJsVideoReady事件。这个方案将浏览器强大的媒体播放能力与Unity的渲染交互能力结合实现了在WebGL中播放m3u8流媒体的目标。虽然涉及到底层的跨语言交互和性能调优但一旦打通它就成为一个非常强大且灵活的基础模块。你可以在此基础上添加UI控件、实现VR/AR中的视频贴图、或者结合AI进行视频分析开拓出更多的应用场景。