简介：Delphi 12.3 环境下可直接集成的视频处理控件包，来自 Datastead 的 TVideoGrabber SDK v15.2.5.3，支持 Windows、macOS、iOS、Android 等多平台，主要面向需要快速实现视频采集、摄像头预览、录制与流媒体推流的 Delphi 开发者。压缩包共含 942 个文件，约 101.14MB，主体包括 Delphi 编译安装所需的 bpl、dcu、dcp 单元与包文件，pas 源码、hpp/lib/a 等跨平台链接库，以及 dll/ocx 运行时组件；同时附带 .NET 项目的 cs/resx、VB 示例、表单 frm/dfm 和资源文件，便于参考不同语言下的调用方式。SDK 覆盖桌面与移动端全平台，集成了部署文件、示例工程和文档说明，并包含对应破解文件，安装后即可在 Delphi 12.3 的 IDE 中拖拽使用，省去自行封装底层视频 API 的时间。目前已有 85 人学习下载，适合从事音视频开发、需要为 Delphi 项目快速加入视频能力的开发者参考。
1. Delphi 12.3 下的 TVideoGrabber SDK：这套视频控件到底在解决什么问题
在 Delphi 12.3 里做桌面视频采集，TVideoGrabber SDK v15.x 是我用过封装最完整的一套方案。它把摄像头预览、录像、RTSP 拉流、格式转换、帧回调全部收进一个控件，你不需要去拼 DirectShow 的 COM 接口，也不用为 MediaFoundation 的初始化顺序头疼，拖一个组件就能把画面跑起来。这篇文章写给两类人：一类是刚接触视频采集，想知道它和普通 TImage + 摄像头驱动方案差在哪；另一类是已经用上这控件，但被分辨率切换、内存上涨、断线重连这些实际问题卡住的人。我会从安装集成开始，一路讲到参数调优、录像封装和避坑清单，最后给一套不阻塞 UI 的帧处理管线，你可以直接照着落地。
2. 安装集成与最小采集链路：从组件面板到第一帧画面
2.1 把 SDK 装进 Delphi 12.3 的组件面板
常见做法是先把 SDK 压缩包解压到固定目录，比如D:\Components\TVideoGrabber。目录里会按 Delphi 版本放好运行时包和设计期包，你需要找的是带d12或对应 IDE 版本标识的 dpk 文件。打开 Delphi 12.3，选择 File > Open Project，定位到那个 dpk，右键项目管理器里的包节点选择 Compile，编译通过后再选择 Install，组件就会出现在控件面板的 VideoGrabber 分类下。这里有个细节：如果之前装过旧版本，先卸载旧包再装新的，不然 IDE 会报“Package already installed”的冲突。
设计期包安装完成后，还要确认运行时包路径。Delphi 12.3 默认把 bpl 输出到$(BDSCOMMONDIR)\Bpl，但控件厂商的脚本有时候会把 bpl 放到 SDK 自己的目录。如果编译完代码后，运行时报“找不到 TVideoGrabber 相关的 bpl”，就去 Tools > Options > Library 里把 SDK 的Lib和Bpl目录加进 Search path，或者把 bpl 文件复制到系统搜索路径。这一步不做，后面每建一个新项目都要重新配一遍，很烦。
安装完建议立刻做一个最小空窗体验证：只放一个 TVideoGrabber，写一行StartPreview，先确认画面能出，再继续往下做功能。官方示例代码量不小，直接拿来做基底反而容易看不清楚哪些代码是必需的。我用一个干净项目起手，通常十分钟内能确认控件工作正常。
// 新建 VCL 项目，Form 上放一个 TVideoGrabber 和一个按钮 procedure TForm1.Button1Click(Sender: TObject); begin VideoGrabber1.VideoSource := vs_Device; // 从本地采集设备取流 VideoGrabber1.VideoDevice := 0; // 默认第一个视频设备 VideoGrabber1.Display_Active := True; // 开启预览显示 VideoGrabber1.StartPreview; // 启动采集预览 end;这段代码是 TVideoGrabber 的最小启动序列，逻辑很清楚：VideoSource决定数据从哪来，vs_Device表示本地摄像头；VideoDevice是设备索引，从 0 开始；Display_Active控制控件是否把帧画到自己的显示区，设为 False 后完全由OnFrameBitmap回调接管数据。StartPreview是异步启动，画面需要几百毫秒才会出现。如果长时间黑屏，优先检查设备索引对不对，以及摄像头是否被其他程序占用。
2.2 枚举设备：别让用户手输索引
把设备索引写死成 0，在开发机上没问题，到客户现场就可能翻车。客户的机器可能有多个摄像头、采集卡、虚拟摄像头，顺序也不按常理出牌。我一般会在窗体启动时把设备列表刷到下拉框里，让用户自己选。
procedure TForm1.FormCreate(Sender: TObject); var i: Integer; begin // VideoGrabber 会自动枚举系统里可用的视频源 for i := 0 to VideoGrabber1.VideoDevices.Count - 1 do ComboBox1.Items.Add( Format('%d - %s', [i, VideoGrabber1.VideoDevices[i].Name]) ); end; procedure TForm1.ComboBox1Change(Sender: TObject); begin VideoGrabber1.StopPreview; // 切换前先停掉 VideoGrabber1.VideoSource := vs_Device; VideoGrabber1.VideoDevice := ComboBox1.ItemIndex; VideoGrabber1.StartPreview; end;VideoDevices是 TVideoGrabber 暴露的设备列表对象，每个元素有Name和索引信息。注意切换设备前必须先StopPreview，直接改VideoDevice虽然有时候也能生效，但容易把底层的 DirectShow 状态机搞乱，出现“画面卡在最后一帧”的假死情况。设备名里带Virtual或OBS字样的，通常是虚拟摄像头，客户环境里要留意，别让用户误选。
2.3 选 DirectShow 还是 MediaFoundation：这不是二选一，是场景问题
TVideoGrabber 在 Windows 下支持两套底层框架，由VideoDevice相关属性或全局的 FrameGrabber 属性控制。DirectShow 兼容性好，老 USB 摄像头、采集卡基本都能认；MediaFoundation 在 64 位进程里更稳，但设备驱动支持不如 DirectShow 普遍。我的做法是优先 DirectShow，因为不少工业相机和视频采集卡只写了 DirectShow 驱动，MediaFoundation 枚举出来是空的。只有在系统只有 UVC 标准摄像头、且客户明确要求 Win10 以上纯 64 位环境时，我才会切 MediaFoundation。
选型上还有一个容易被忽略的点：多路采集。DirectShow 的 Filter Graph 在跨线程调用时容易死锁，MediaFoundation 的多实例并发反而好一些。你要是做四路以上同时采集，建议先拿两路做压力测试，半小时不崩再往上加。
3. 分辨率、帧率和录像参数：画面卡不卡其实就那么几个旋钮
3.1 拿到设备真正支持的分辨率，而不是猜
很多人在代码里直接给VideoGrabber1.VideoResolution := cv_1920x1080;，结果在某些摄像头上怎么都没反应，或者画面变形。原因很简单：这个枚举值是控件层推荐的视频尺寸，但底层设备不一定支持这个输出尺寸。正确做法是先枚举设备能力，再挑一个交集来设置。
var i: Integer; begin // 先选定设备再枚举，避免拿到不匹配的能力列表 VideoGrabber1.VideoDevice := ComboBox1.ItemIndex; ListBox1.Clear; for i := 0 to VideoGrabber1.VideoResolutions.Count - 1 do ListBox1.Items.Add(VideoGrabber1.VideoResolutions[i].ToString); end;VideoResolutions列出来的是控件从设备驱动那里读到的实际输出分辨率集合，每项通常包含宽度、高度、帧率组合。这一步很关键，很多“明明设备支持 1080p，但控件里选不到”的问题，真实原因是设备当前输出的颜色格式或帧率组合不被控件默认编码器接收。要是列表里只有 640x480 和 320x240，多半是驱动装成了系统自带 UVC 驱动，去装厂商原厂驱动会多出一大批分辨率。
3.2 帧率、码率和关键帧间隔：录像流畅度的三个旋钮
帧率直接设VideoGrabber1.FrameRate := 25，这是标准 PAL 帧率，国内用这个值准没错。但要注意，如果设备端输出只有 15fps，你设 25 只会让部分帧重复，不会真的让画面更流畅。码率和关键帧间隔属于编码器参数，TVideoGrabber 的录像接口在开始录像前要设置好压缩类型和质量。
// 录像开始前的参数准备 VideoGrabber1.FrameRate := 25; // 采集帧率 VideoGrabber1.VideoCompression := 'Microsoft Video 1'; VideoGrabber1.VideoQuality := 75; // 0-100，越大越清晰 VideoGrabber1.RecordingFormat := rf_AVI; // 封装格式 VideoGrabber1.FileName := 'D:\Capture\record.avi'; VideoGrabber1.StartRecording;VideoCompression字符串要写系统里已安装的压缩器名称，不同系统有所差异，Windows 10 上常见的还有Microsoft H.264 Video Decoder的编码器变体。这个属性是最好发玄学问题的地方，系统缺编码器时，录像文件会特别大或者干脆是 0 字节。VideoQuality在部分编码器下不生效，比如 H.264 系列更认码率参数，而 Video 1 这种老编码器只在质量滑块上做文章。所以我通常先录一分钟测试文件，看文件大小和播放流畅度，再回头微调这两个值。录像文件写不进目标目录时会触发 OnError 事件，错误码一般指向磁盘满或路径不存在。
3.3 封装格式与录像中断：别等到验收时才被发现
AVI 兼容性最好，但文件超过 2GB 时老播放器会出问题，现在用rf_MP4更省心。TVideoGrabber 的 MP4 封装依赖系统里可用的 MP4 写入器，Windows 10 自带的情况居多；但如果客户机器是精简版系统，可能缺少对应组件，录出来的文件拖进播放器里只有声音没画面。所以在交付前，我习惯把录像封装成一个抽检工具：录完立刻回放一遍，校验时间长度和关键帧。录像文件头损坏的另一个常见来源是断电或程序强杀，它发生在录像过程中，文件没有写完成。TVideoGrabber 的 OnLog 事件里会输出录制结束状态，排错时优先看它。
4. 把 RTSP 拉流接进来：从内网摄像头取流到稳定重连
4.1 设置 RTSP 地址与传输协议
TVideoGrabber 自带 RTSP 客户端，把VideoSource切到vs_IPCamera就可以拉摄像头的 RTSP 流。它还可以只用来做播放器，看回放文件或网络流。这里常见做法是配一个带用户名密码的 URL，同时把传输协议固定成 TCP，避免 UDP 在跨网段时丢包花屏。
with VideoGrabber1 do begin VideoSource := vs_IPCamera; // rtsp 地址带认证信息，参数顺序不要写反 IPCameraURL := 'rtsp://admin:password@192.168.1.64:554/Streaming/Channels/101'; IPCameraTransport := ipt_TCP; // 固定 TCP，不用 UDP IPCameraTimeout := 5000; // 单位毫秒，连接超时 Display_Active := True; OpenPlayer(IPCameraURL); // 拉流并播放 end;IPCameraTransport默认用的 UDP 在局域网偶尔会省带宽，但跨路由、Wi-Fi 场景下丢包会让画面出现马赛克甚至黑屏，所以我都改成 TCP。IPCameraTimeout控制连接失败判定的等待时间，设太短在海康大华这些对端响应慢的时候容易反复重连，设太长用户会觉得“卡死了”。5 秒是个平衡点。拉流地址末尾的路径每家摄像头厂商都不同，海康是/Streaming/Channels/101这类风格，大华又有自己的规则，这个必须对着设备说明书抄，不是通用的。
4.2 断线重连：用一个状态机，而不是无脑循环重连
RTSP 拉流的稳定性是项目的生命线。我用过最糙的做法是定时器每 3 秒检查一次画面有没有更新，没更新就重新 OpenPlayer。这个做法能跑，但会在设备重启、网络波动时造成大量重复连接，把摄像头连接数打满。后来换成了基于事件的状态机方案：用 TVideoGrabber 的 OnLog 事件和 OnStreamingError 事件来判断异常，重连动作只允许在“已断开”状态触发。
private FConnected: Boolean; FReconnectTick: Integer; procedure TForm1.VideoGrabber1StreamingError(Sender: TObject; const ErrorCode: Integer); begin FConnected := False; // 错误码非 0 代表流中断，统一走重连逻辑 TThread.ForceQueue(nil, procedure begin if not FConnected then begin VideoGrabber1.ClosePlayer; Sleep(2000); // 等 2 秒再连，给设备留恢复时间 VideoGrabber1.OpenPlayer(VideoGrabber1.IPCameraURL); end; end ); end;这个做法有三个要点。第一，把重连动作通过TThread.ForceQueue丢回主线程执行，避免在控件回调线程里直接操作界面和控件实例，很多“偶尔崩一下”的 RTSP 问题就出在这里。第二，重连前强制ClosePlayer，把上一次的流状态彻底清掉，不然某些设备会一直保持半开连接占用通道。第三，重连间隔用Sleep(2000)或一个递增退避，不要在错误事件里做无间隔循环，否则设备恢复过程中你的循环会把连接请求打满，反而拖慢恢复。
4.3 多路 RTSP 并行：每个实例独立，千万别共享
同时拉四路摄像头时，有人会图省事：一个窗体放四个 TVideoGrabber 控件做多画面。这能跑通，但内存占用偏高，而且某一路网络波动时会牵连其他路的 UI 刷新。更好的做法是做一个 Frame 子类，每个 Frame 里放一个 TVideoGrabber，动态创建多个 Frame 实例。这样每路采集有独立的底层层、独立的事件回调、独立的生命周期。
创建多路时最需要留意的是重连逻辑里不能用全局布尔量，要给每路自己的状态变量。我在这里翻过车：四个实例共用了一个FConnected，结果一台摄像头掉线，其他三路全部被误触发重连，造成短暂集体花屏。后面我把状态拆进每个 Frame 的私有字段，问题就消失了。
5. 常见问题避坑与排查：现场最容易踩的五个坑
5.1 现象：VideoDevice 切到第二路摄像头后画面黑屏
原因：直接修改VideoDevice而没有先停止当前设备。DirectShow 的图在设备间切换时没有正确释放，底层 Filter 仍占着前一个设备的流。解决：切换前显式调用StopPreview并等待一两帧时间，或直接ClosePlayer清空图状态。这个坑在采集卡多路输入时很常见，我第一次接四路采集卡时就是黑屏加程序假死，折腾了半天才发现是切换顺序的问题。
5.2 现象：长时间运行内存稳定上涨，几小时后程序变卡
原因：最常见的是在OnFrameBitmap回调里创建 Tbitmap 又不释放，或者调用了控件内部带缓存的函数但没有清缓存。回调是高频路径，25fps 下一帧漏一个 Tbitmap，半小时就是几万次泄漏。解决：回调里绝不做资源密集型操作，必须持有的临时对象用 try/finally 确保释放。如果确认释放了还涨，检查是否开启了 Log 输出但没有清理日志缓冲，把LogFile设为空或打印级别调低。
5.3 现象：64 位目标编译通过，运行到 StartPreview 报访问违规
原因：系统里装的视频编码器或采集驱动是 32 位 DLL，在 64 位进程里加载失败。TVideoGrabber 本身同时提供 32 位和 64 位版本的运行时，但底层第三方编码器不一定。解决：要么整个程序改用 32 位目标编译，要么找到对应的 64 位编码器 DLL 并重新注册。排查时打开 Windows 事件查看器，看应用程序日志里挂掉的模块名，如果是AVIFIL32.dll或某个厂商编码器，直接换编码器或换位数就能定位。
5.4 现象：录像文件播放时时间轴不对，跳秒或者总时长偏短
原因：录像过程中系统时间被修改，或采集帧率与编码器实际写入帧率不一致。TVideoGrabber 默认按系统时钟打时间戳，跨线程采集时时间戳出现乱序。解决：不要用系统时间做时间基准，可以改成帧计数方式，或同步网络时间协议，并保证录像期间不手工改系统时间。这个问题在客户现场被发现时，往往已经是连续录了几个小时的大文件，得靠回放抽检提前拦截。
5.5 现象：授权文件在开发机上好好的，部署到客户机提示 license invalid
原因：该控件的授权机制绑定机器指纹，换机器必须重新申请授权。很多团队在这上面吃过亏，打包时把开发机的授权文件带过去了。解决：正式部署前，在客户机器上先跑一次授权诊断，拿到机器特征码去申请正式授权。不要试网上流传的盗版替换文件，那会越弄越糟。正版授权的路径是厂商统一的，使用中记住授权单位、产品名和机器绑定三条信息一致才能正常加载。
6. 进阶技巧：把帧数据接入自己的图像处理管线
录像是基本功，真正让 TVideoGrabber 发挥价值的是OnFrameBitmap回调。它会把每帧画面以 Bitmap 形式交到你手上，你就有了无限可能：做运动检测、车牌识别、OCR、画面比对。但这里有个非常关键的原则：回调线程不是你随便造对象的地方。
procedure TForm1.VideoGrabber1FrameBitmap(Sender: TObject; Bitmap: TBitmap); var bmp: TBitmap; pData: TByteArray; begin // 只做拷贝，把数据交给后台线程 bmp := TBitmap.Create; try bmp.Assign(Bitmap); // 深拷贝一次 FFrameQueue.Add(bmp); // 放队列，处理线程取走 except bmp.Free; raise; end; end;队列要带锁，处理线程循环取帧做算法，处理完释放 Bitmap。这样 UI 线程、采集线程、算法线程三者解耦。深度学习的检测模型速度慢，一帧 200ms，如果直接在回调里跑，采集线程会被拖死。让采集线程只负责投递，算法线程按自己的节奏消费，掉帧是必然的，但至少 UI 不卡，录像不丢。内存方面，队列要有上限，处理不过来就丢弃新帧而不是无限堆积。
我早期犯过一个错：在 OnFrameBitmap 里直接做了缩放和格式转换，一帧处理 60ms，结果录像中每隔一秒就掉好几帧，录出来的文件一顿一顿的。后来把所有图像处理挪到独立线程里，采集回调只做指针级拷贝，15 分钟的视频文件再也没有丢帧。另一个惯性要改的是缓冲区复用，把固定尺寸的 Bitmap 池化，能极大降低长时间运行的 GC 压力。那一次调优之后我养成了一个习惯：凡是控件回调，第一件事永远只做数据交接，不做业务逻辑。这个习惯帮我避开了很多奇怪的低概率崩溃。希望帮到你。
本文还有配套的精品资源，点击获取
