最近在做一个智慧园区大屏项目遇到一个很典型的需求把园区里数十路摄像头的RTSP流直接拉到UE5场景里实时显示而不是先转码成HLS或者缓存下来再播。尝试了UE5原生媒体框架之后发现它并不能直接拉RTSP最后稳定跑通的是基于FFMPEGMedia插件把RTSP流接进UE5的Media Framework链路再通过MediaTexture输出到UMG界面和三维屏体上。这篇文章就把这套打法的完整过程梳理一遍包含插件接入、取流地址、蓝图播放链路、安卓缓存和双指触摸控制以及我在项目里踩过的那些莫名其妙的坑。1. 为什么用FFMPEGMedia这套组合1.1 项目里真正难的地方大屏显示RTSP画面第一反应是找一台解码器或者用VLC窗口嵌入。但在UE5里做智慧园区大屏通常需要把多路视频贴到虚拟楼宇模型的外立面上或者做一个可交互的数字孪生场景这就不能简单弹窗播放了。视频流必须作为一种动态纹理进到UE的渲染管线里贴上Mesh、注入UMG还要和多路UI联动。UE5其实自带Media Framework能处理本地视频、HTTP文件、HLS这类媒体源。但直接往Media Player里填rtsp://开头的地址大多情况下是失败的。因为RTSP不是单纯的下载协议它要经过DESCRIBE、SETUP、PLAY这样的会话协商媒体数据走RTP/RTCP传输UE内置的媒体模块并没有把这些协议完全封装好。这时候就需要一个能解析RTSP、并重新包装成UE Media Framework能识别的源和解码器。FFMPEGMedia就是这个定位。我从一开始就考虑过自己基于FFmpeg拉流再用Render Thread上传纹理。坦白说这条路不是不能走但工程量大得离谱。RTSP的音视频同步、断线重连、不同编码格式的适配、纹理格式转换每一项都要自己处理。FFMPEGMedia的好处是它把FFmpeg的解封装、解码、格式转换能力嫁接到UE的Media Framework上这样视频流一旦打开后续的播放状态、帧上传、音视频同步都交给UE标准链路处理改动可控踩坑也相对集中。1.2 几套主流方案的取舍做方案对比时我把市面上能走的路都试了一圈这里直接给结论方案实现方式优点局限性UE原生Media Framework内置播放器开箱即用稳定RTSP需要额外扩展很多版本不支持FFMPEGMedia插件FFmpeg解码 Media Framework接入直接拉RTSP改动小可定制项目维护一般多路软解CPU压力大自研FFmpeg链路C线程拉流 RHI纹理上传可控性强性能极限高工作量大音视频同步难做C调用摄像头SDK海康/大华SDK直接取流功能全延迟低绑定厂商跨设备适配差服务端转HLS/WebRTC后端统一拉流再分发适合大规模、弱网链路长延迟会增加最终我选了FFMPEGMedia原因很实际项目周期不允许自研设备品牌又不只海康一家RTSP通用的协议反而能让一套代码兼容多类摄像头。FFMPEGMedia基于FFmpeg本身就支持H.264、H.265、MJPEG等常见编码也内置了RTMP、RTSP、HTTP等多种协议的处理。它相当于给UE5补上了“原厂缺失的RTSP支持”代价是插件本身的维护度参差不齐部分代码还要针对UE5版本手动改一改。1.3 这套方案适用的项目形态用了这套方案之后我把它复用到其他项目里总结出它的适用范围。最适合的是中小规模可视化项目比如智慧楼宇、园区数字孪生、巡检可视化视频路数在几路到十几路而且需要把画面融合到三维场景中。如果只是看监控墙直接解码器上墙更好。如果是几十路甚至上百路FFMPEGMedia这种纯CPU软解方案会非常吃紧更建议后端统一转码UE端只拉低码率预览流。2. 插件接入与环境准备2.1 获取FFMPEGMedia源码与目录放置FFMPEGMedia并不是UE官方商店里的付费插件它是开源项目直接在GitHub上搜就能找到。下载时注意分支支持的UE版本有些是UE4时代的老代码UE5工程直接编译会报错。我当时的做法是找一个带UE5兼容拉请求的分支或者自己把uplugin文件里的引擎版本改成当前项目对应版本再逐个修正编译错误。插件源码放哪很关键。不要放在Engine/Plugins下除非你想影响所有项目。推荐放在项目根目录的Plugins/FFMPEGMedia下这样插件跟着工程走换电脑也能通过源码管理同步。目录结构大致是Plugins/ FFMPEGMedia/ FFMPEGMedia.uplugin Source/ FFMPEGMedia/ ... FFMPEGMediaFactory/ ... ThirdParty/ ffmpeg/uplugin是插件的描述文件Source下一般有两个模块一个负责媒体源和播放器接入另一个负责工厂注册。ThirdParty里则是打包好的FFmpeg库。放置完插件后如果工程是C项目直接让UE生成新工程文件即可如果是蓝图项目需要在项目设置里多打开几个编译相关选项因为FFMPEGMedia会有C模块参与构建。2.2 编辑器中启用插件打开工程后从菜单栏进入Edit Plugins搜索FFMPEGMedia找到插件后勾选Enabled。启用成功后通常会自动重启编辑器。这类第三方插件有时会因为没有启用而出现加载失败表现为Log里出现Plugin FFMPEGMedia failed to load这个问题经常被忽略我一开始就卡在这。如果你用的版本比较老还可能出现“类加载不完全”的情况。重启编辑器后在Content Browser里右键新建媒体源资产时能看到FFMPEGMedia相关选项就说明加载成功了。看不到的话优先检查uplugin里的EngineVersion是否与当前UE5版本兼容。版本不匹配时UE会直接禁用插件这在日志里最明显。2.3 FFmpeg动态库与运行环境的坑FFmpeg是以动态库方式接入的插件运行需要对应的dll。有些仓库把dll放在ThirdParty/ffmpeg/bin/Win64下有些则需要自己下载拷贝。务必确认dll的架构和UE构建架构一致Windows下通常是x64。如果dll版本不对启动编辑器就会报Unable to load DLL avcodec这类错误。注意FFmpeg的dll版本改动后最好把Intermediate和Binaries目录清一遍再重新编译。否则编辑器还会缓存旧的DLL路径导致运行时加载仍然失败。这个坑让我无端消耗过一个下午。打包发布时也要确认dll是否被自动收录。很多时候Editor里能正常播放打包后黑屏或直接崩溃就是因为dll没进包。打开项目设置里的Packaging或者手动检查打包目录下的Binaries/Win64缺哪个补哪个。不同分支的插件对FFmpeg库的依赖路径不一样不要想当然。2.4 编译环境与启动前的准备UE5的C插件编译基本依赖Visual Studio 2022和.NET环境。先找一个空的C工程编译通过后再放插件这样出了问题能快速区分是工程问题还是插件问题。编译FFMPEGMedia插件时我也常看到链接错误大多是缺少FFmpeg的lib文件或第三方目录的include路径没生效。不要试图把FFmpeg头文件直接塞进系统目录正确做法是让插件模块的Build.cs里增加第三方库路径或者在ThirdParty目录结构里放置CMake配置。如果你下载的插件版本较完整这些已经配好你要做的只是打开工程编译一次看结果。3. RTSP取流地址与本地测试流3.1 常见摄像头的RTSP地址格式做RTSP播放第一个绕不开的问题就是地址哪来。不同品牌的摄像头RTSP路径并不统一这里把常见的格式列一下方便你对照设备手册排查品牌主码流地址子码流地址海康威视rtsp://user:passip:554/Streaming/Channels/101rtsp://user:passip:554/Streaming/Channels/102大华rtsp://user:passip:554/cam/realmonitor?channel1subtype0rtsp://user:passip:554/cam/realmonitor?channel1subtype1萤石rtsp://user:passip:554/h264/ch1/main/av_streamrtsp://user:passip:554/h264/ch1/sub/av_stream小米摄像头rtsp://user:passip:554/streaming/channels/1rtsp://user:passip:554/streaming/channels/2这些格式我只在常见固件上验证过不代表所有版本。不同时期、不同固件路径可能会变化比如海康新老固件对101和102的支持是一致的但也有人遇到过需要追加?transportmodeunicast的情况。建议以设备的官方取流说明为准。拿不到说明时先用VLC填地址试一遍VLC能拉出来就说明地址和我方网络基本没问题。用户名和密码要嵌在URL里注意冒号和的位置。如果密码里有特殊字符比如或:一定得做URL编码。:编码为%3A编码为%40否则FFmpeg会把密码部分截断导致认证失败。这是RTSP播放最常见的隐藏问题之一。3.2 主码流和子码流到底该怎么选摄像头通常同时输出两路码流主码流分辨率高、码率大适合录像和事后分析子码流分辨率低、码率小适合预览和网络受限场景。在UE5里显示的实时画面选哪一路直接决定画面质量、延迟和CPU占用。调试阶段我都建议先拉子码流。因为FFMPEGMedia默认走CPU软解主码流4K或者5MP的话理解压力非常大一拉起来编辑器就可能卡死。把功能调通后再看实际大屏尺寸决定要不要切主码流。如果大屏只是作为背景或者缩小到某个角标子码流完全够用真没必要跟性能过不去。考虑到多路显示我最终在生产环境里统一用子码流只在选中某一台设备放大查看时才临时切换主码流。这样一个折中设计方案既保障了实时预览的流畅度又保留关键设备的清晰度。切换的时候注意先释放旧流再重新打开新地址不然容易出现“打开的流还没关掉新流又进来”的状态错乱。3.3 本地测试流怎么搭没有摄像头时也别硬等设备。我常用Docker跑一个轻量RTSP服务再用FFmpeg推流模拟这样整套UE5侧的逻辑在开发环境就能调。项目里我用的是mediamtx早期版本叫rtsp-simple-server。# 启动RTSP服务 docker run --rm -p 8554:8554 -p 1935:1935 bluenviron/mediamtx # 推一个本地视频文件作为测试流 ffmpeg -re -stream_loop -1 -i test.mp4 -c copy -f rtsp rtsp://localhost:8554/live推流成功后UE5里要填的地址就是rtsp://localhost:8554/live。这样本地开发不需要摄像头也能验证播放链路、重连逻辑、延迟表现。-stream_loop -1表示循环推流不然文件播完流就结束了。实际推流时如果-c copy失败改成-c:v libx264重新编码即可。如果Linux环境里有GStreamer也可以直接用gst-rtsp-server的测试程序生成一个虚拟视频源./test-launch ( videotestsrc ! x264enc ! rtph264pay namepay0 pt96 )这种测试流的好处是纯虚拟画面不依赖文件适合长期稳定性测试。总之手头有摄像头的用真实RTSP地址没有的用mediamtx ffmpeg自发自拉这两种方式足够覆盖开发期的验证需求。4. 在UE5里把RTSP画面显示出来4.1 创建MediaPlayer与媒体源资产FFMPEGMedia插件启用后播放链路跟UE原生Media Framework很像核心是Media Player它负责控制播放、暂停、打开媒体源Media Texture负责把解码后的视频帧上传到GPUMedia Source则保存具体的媒体源配置比如RTSP地址。操作路径是在Content Browser里右键选择Media Player命名后它通常会弹出提示是否同时创建Media Texture和Media Sound Component这里都勾上。然后创建一个媒体源资产具体名称取决于插件实现常见的是File Media Source但在FFMPEGMedia里也可能是自定义媒体源类。双击打开媒体源在细节面板里找到URL字段填入RTSP地址。这一步要注意区分Media Source和Media Texture。很多人搞混Media Texture不存地址它只是一个GPU纹理容器Media Source才存地址。正确关系是Media Player打开Media Source解码后的纹理输出到Media Texture之后UI和材质再采样这个纹理。顺序错了无论填多少地址都白搭。4.2 蓝图逻辑与自动重连RTSP是实时流网络抖动、摄像头重启都可能让连接断开所以播放逻辑不能只是“Open一次然后播放”必须要考虑重连。我的做法是在关卡蓝图或组件蓝图中维护对Media Player的引用用一个自定义事件循环执行打开逻辑。蓝图节点顺序大致是使Media Texture关联到Media Player调用Media Player的Open Source传入媒体源资产成功后调用Play监听OnMediaOpened和OnMediaOpenFailed事件OnMediaOpenFailed触发时等待数秒后重新执行Open Source。关于重连我加了一个计数器连续失败超过五次就停住不无限循环轰炸摄像头。因为摄像头网络恢复一般需要时间无限重连会导致CPU高占用和日志泛滥。重连间隔可以做成可配置变量弱网环境建议15秒到30秒局域网环境5秒就够了。这个处理在项目交付后避免了很多现场“黑屏没人管”的尴尬。4.3 MediaTexture在UI和三维模型上的显示RTSP画面最终要显示到屏幕常见出口有两个。一是UMG界面二是三维模型材质。UMG里最直接的方式是把Media Texture赋给Image控件的Brush。运行时可以通过Set Brush From Texture动态指定纹理。另一个更灵活的方式新建一个材质在材质图里拉入Media Texture作为Texture Sample连接自发光和BaseColor再将材质赋给UI的Image或三维Mesh。如果使用UI建议材质通道简单一点不要叠加一堆特效。视频纹理本身是动态的再做复杂模糊或半透明混合性能立刻下降。我遇到过3D UI加了半透明模糊效果后视频画面糊成一片原因就是UI的Blend Mode设置为Transparent且采样动态纹理时触发了奇怪的mipmap采样。解决方式是把视频相关的材质改成Unlit或Opaque或者单独提高MediaTexture的mipmap生成质量。简单说视频画面能别走透明混合就别走。三维模型上的显示比如园区楼宇外立面的大屏直接建一个平面网格把含有MediaTexture的材质赋给它就行。需要注意UV方向RTSP流多是横屏平面网格的UV缩放要对上视频宽高比否则画面会拉伸变形。4.4 安卓端缓存与双指触摸交互移动端项目安卓盒子或平板也是一种常见宿主。安卓上拉RTSP有两点要特别留意网络权限和缓存策略。打包前确保INTERNET权限开启否则打开RTSP地址会静默失败。另外安卓Wi-Fi网络波动比有线网络更频繁RTSP走UDP时丢包严重如果插件或底层FFmpeg支持设置传输协议尽量把rtsp_transport设为tcp能减少花屏和卡顿。缓存方面我建议给RTSP播放器设置较小的缓冲重点保证画面流式更新而不是累积延迟。视频流是实时的缓存越多延迟越大现场如果拿来做远程控制或语音对话延迟一高体验就很差。有的场景需要预缓存几帧来减少卡顿那就需要你在“画面稳定”和“低延迟”之间做个取舍我通常把缓存控制在200毫秒以内。交互上移动端最常用的手势是双指缩放和平移。UE5里可以通过两个触摸事件节点获取两个手指的屏幕坐标实时计算两指距离变化量用这个变化量去驱动UIMesh或场景相机的缩放。大致逻辑是触摸开始记录初始距离触摸移动时计算当前距离用两个距离的比值更新视频画面的缩放值。这个思路不只能用在RTSP显示上任何需要双指操作的UI都可以复用。5. 排障实录与性能优化5.1 lowlevelfatalerror渲染层报错这个报错经常伴随类似日志lowlevelfatalerror [File:D:\build\UE5\Sync\Engine\Source\Runtime\RenderCore\...]从路径看是渲染核心层出的致命错误。在实际项目里我遇到这类崩溃主要有三个原因GPU纹理格式不支持、H.265/4K高分辨率解码后无法创建RHI纹理、DX12下的纹理兼容问题。处理建议很直接项目渲染器先切到DX11这类插件大都在DX11下更稳定。如果仍然崩溃检查RTSP流的分辨率把摄像头从主码流切到子码流或者把视频分辨率限制在1080p以下。驱动也记得升级部分旧驱动对动态纹理创建的性能很差。打包环境如果遇到这个错多半和显卡型号相关尽量在目标机型上跑一遍完整流程再交付。5.2 MSB3073编译报错日志里的error MSB3073其实是MSBuild的通用错误常见于Visual Studio构建UE项目时某个构建步骤返回了非零退出码。单独看MSB3073本身没有太大意义关键要看它前面的具体命令和报错输出。我遇到的原因五花八门编辑器开着导致文件被占用、dll被杀毒软件锁定、生成路径过长、权限不足。常规解决办法是关闭UE编辑器和VS删除Intermediate和Binaries目录以管理员身份重新打开VS或执行Build.bat暂时关闭杀毒软件实时监控在Developer Command Prompt中手动运行Engine\Build\BatchFiles\Build.bat查看完整错误。如果是FFMPEGMedia插件相关还要检查插件目录下哪些文件被同步工具设为只读。只读会导致中间文件无法覆盖MSBuild就会莫名失败。5.3 黑屏、卡顿、花屏的排查顺序现场遇到黑屏不要慌按这个顺序排查症状可能原因快速处理黑屏插件未加载或dll缺失检查Plugins面板和打包目录黑屏RTSP地址不可达先用VLC验证地址黑屏密码含特殊字符未编码URL编码特殊字符卡顿主码流分辨率过高切子码流或限制码率卡顿弱网丢包切换RTSP over TCP花屏UDP丢包导致RTP乱序改用TCP传输无声音音频Codec不支持关闭音频输出或转码判断RTSP地址本身能不能用Windows上直接用VLC或ffprobe是最快的。VLC能出画面UE里黑屏问题基本在插件或UE侧VLC也不能出画面那就是地址或网络问题没必要在UE里反复试。卡顿的另一个隐藏因素是防火墙。Windows防火墙默认可能拦截RTP的UDP端口摄像头在跨网段拉流时尤其明显。排查时可以先关闭防火墙看是否恢复再考虑做端口放行规则。5.4 多路视频的性能控制与拓展思路FFMPEGMedia走FFmpeg软解这是最大的性能瓶颈。单路1080p可能还好多路叠加后CPU很快吃满。性能优化我总结了几个有效动作视频路数控制在十路以内超过后考虑后端转码优先使用子码流、低帧率RTSP流不需要显示的画面暂停播放或关闭MediaPlayer用材质做画面切换而不是同时保留多路MediaPlayer避免在UI布局中把所有视频流都设置为全屏清晰度。我项目里有个极端场景同时十二路RTSP直接把编辑器和打包程序的CPU打爆。后来把其中八路切到子码流并做了分页轮播同一时间最多四路全码率播放整体才稳定下来。如果你确实需要几十路同屏建议后端做集中拉流和转码再以低延迟HLS或WebRTC方式推给UE千万别指望一台客户端软解几十路。另外FFMPEGMedia本身的开源链路是可以用C扩展的。比如在FFmpeg解码前设置缓冲区参数、修改rtsp_transport、加自定义重连逻辑。如果插件默认行为不满足需求直接改插件源码可能是唯一出路但改动前一定保留原版备份。最后分享一点个人感受FFMPEGMedia UE5 RTSP这套方案在中小型可视化项目里非常实用能省下自研解码链路的巨额工作量但也不是万能匙。真正交付项目时大多不稳定问题反而不是解码而是网络和地址配置。把RTSP地址先验证明白、把重连和缓存策略写清楚这个项目基本就成功了一大半。后续想扩充时我会优先考虑后端转码加WebRTC的分发架构把UE端的软解压力彻底降下来。