Delphi 12.3 集成 TVideoGrabber SDK：视频采集、录像与推流实战指南

简介本资源为Datastead.TVideoGrabber SDK V15.2.5.6全平台版面向使用Delphi 12.3进行视频捕获与处理开发的工程师。该SDK支持从摄像头、电视卡、网络摄像机等视频源实时采集数据并完成编码、预览、录制等操作适合需要在Windows、macOS及Linux上构建跨平台视频应用的开发者。压缩包共1113个文件约139.54MB包含pas、dpr、dfm等Delphi源码与窗体文件bpl、dcp、dcu等编译组件以及dll、hpp、lib等跨平台库文件另附示例工程、文档与配置文件便于快速集成与调试。目前已有83人学习关注。借助该SDK开发者可调用统一接口实现视频采集、格式设置、回调处理与文件保存并参考示例项目掌握基本与高级用法同时需留意不同平台在硬件接口、驱动及UI适配上的差异从而高效扩展Delphi应用的视频处理能力。1. Delphi 12.3 下 Datastead TVideoGrabber SDK 的定位与适用边界如果你正在用 Delphi 12.3 做 Windows 桌面端的视频采集、录像或推流功能大概率绕不开一个名字Datastead TVideoGrabber SDK。这次标题里的 V15.2.5.6 All Platforms 版本本质上是把一套成熟的视频采集与处理组件打包成覆盖 Delphi、C Builder 以及 .NET 的多平台 SDK。它解决的核心问题很具体让你不用从零去啃 DirectShow、Media Foundation 的底层接口就能在窗体上拖一个控件把摄像头、采集卡、桌面屏幕甚至 RTSP 流拉进来做预览、录像、抓帧、叠加文字和时间戳。我最早接触它是在一个工业检测项目里客户要求把产线摄像头的画面实时显示在 Delphi 界面上同时按班次自动切分录像文件。当时试过直接调 DirectShow光是枚举设备、协商媒体类型、处理格式回退就写了两百多行还时不时在某些 USB 采集卡上翻车。换成 TVideoGrabber 之后核心逻辑压缩到几十行设备兼容性也稳了很多。这就是它存在的意义把视频采集这条链路上最容易出玄学问题的部分封装掉留给你的是属性、事件和方法。这个版本标注 All Platforms需要说清楚边界。它指的是 SDK 本身提供了 Delphi VCL、FireMonkey 以及 C Builder 的接口单元并不是说你的采集程序能直接编译到 Android 或 iOS 上跑摄像头采集。实际落地场景仍然是 Windows 桌面端为主FMX 可以让你在跨平台 UI 框架里调用但底层采集还是走 Windows 的媒体栈。所以如果你的目标是 Delphi 12.3 的 VCL 项目这个包是对口的如果你打算做移动端采集需要先确认目标平台的支持情况别看到 All Platforms 就默认全平台开箱即用。适合谁一是手里有 Delphi 12.3 项目、需要快速加视频功能的开发者二是做安防、工业视觉、医疗影像、教育录播这类桌面软件要求稳定采集和录像的团队三是想用 C Builder 复用同一套 SDK 的跨语言项目。不适合谁只需要静态图片处理、或者想用纯 Web 技术做视频的这套东西偏重没必要上。2. 把 SDK 装进 Delphi 12.3包结构、编译与第一个采集窗体2.1 解压后先看清目录别急着装拿到 Datastead.TVideoGrabber.SDK.V15.2.5.6.All.Platforms.7z 之后第一步是解压到一个路径里没有中文和空格的目录比如D:\SDK\TVideoGrabber。路径带空格或中文在 Delphi 的包编译和运行时 DLL 加载阶段都可能出问题这是血泪经验。解压后典型结构大致是这几类内容Delphi或Delphi VCL目录放的是 VCL 组件包和单元文件CBuilder目录放 C 接口Assemblies或DotNet目录放 .NET 程序集Redist或Runtime目录放运行时需要的 DLLDemos或Samples目录放示例工程。不同小版本目录名可能有差异但逻辑一致。关键动作是找到 Delphi 对应的包文件通常是.dpk或.dproj。用 Delphi 12.3 打开它先别改任何东西直接 Build。如果编译报错大概率是搜索路径没配好或者运行时包和设计期包混在一起了。2.2 安装设计期包并配置搜索路径在 Delphi 12.3 里推荐的做法是打开 SDK 提供的设计期包工程右键 Install。安装成功后工具面板上会出现 TVideoGrabber 组件。如果 Install 灰色说明这个包被标记为运行时包需要先找到对应的设计期包。安装完成后去Tools Options Language Delphi Library在Library Path里把 SDK 的 Delphi 源码目录加进去。这样你自己的工程引用单元时不会找不到文件。同时确认Browsing Path也加上方便调试时跳转。提示Delphi 12.3 的包管理对平台限定比较严格安装时确认目标平台是 Win32 还是 Win64两个平台要分别编译和安装对应的包不能混用。2.3 最小可运行的采集窗体代码下面这段代码是我一般用来验证 SDK 是否正常工作的最小骨架。新建一个 VCL 应用放一个 TVideoGrabber 组件、一个 TButton、一个 TPanel然后写unit Unit1; interface uses Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics, Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls, Vcl.ExtCtrls, VideoGrabber; type TForm1 class(TForm) VideoGrabber1: TVideoGrabber; Panel1: TPanel; Button1: TButton; procedure Button1Click(Sender: TObject); procedure FormCreate(Sender: TObject); procedure VideoGrabber1Log(Sender: TObject; LogType: TLogType; Severity: TLogSeverity; const InfoMsg: string); private { Private declarations } public { Public declarations } end; var Form1: TForm1; implementation {$R *.dfm} procedure TForm1.FormCreate(Sender: TObject); begin // 把预览窗口挂到 Panel1 上避免控件自己弹独立窗口 VideoGrabber1.VideoSource : vs_VideoCaptureDevice; VideoGrabber1.VideoRenderer : vr_VMR9; VideoGrabber1.PreviewWindow : Panel1.Handle; VideoGrabber1.StretchPreview : True; VideoGrabber1.OnLog : VideoGrabber1Log; end; procedure TForm1.Button1Click(Sender: TObject); begin if not VideoGrabber1.IsVideoSourceOpen then begin // 打开默认采集设备设备索引从 0 开始 VideoGrabber1.VideoDevice : 0; VideoGrabber1.OpenVideoSource; VideoGrabber1.StartPreview; end else begin VideoGrabber1.StopPreview; VideoGrabber1.CloseVideoSource; end; end; procedure TForm1.VideoGrabber1Log(Sender: TObject; LogType: TLogType; Severity: TLogSeverity; const InfoMsg: string); begin // 把 SDK 内部日志输出到调试窗口排错时非常有用 OutputDebugString(PChar(Format([TVG][%d] %s, [Ord(Severity), InfoMsg]))); end; end.逻辑说明FormCreate里做三件事——指定视频源类型为采集设备、指定渲染器为 VMR9、把预览窗口句柄交给 Panel1。Button1Click里用IsVideoSourceOpen做状态判断避免重复打开导致异常。OnLog事件是排错入口SDK 内部很多状态变化和错误都会往这里抛。参数说明VideoDevice是设备索引不是设备名多摄像头环境下需要先枚举再赋值VideoRenderer可选 VMR7、VMR9、EVR 等Win10 以上建议 VMR9 或 EVR老系统用 VMR7 兼容性更好StretchPreview控制是否拉伸填满预览窗口做比例保持时应该关掉自己算黑边。2.4 设备枚举与格式选择实际项目里不能假设设备索引 0 就是你要的摄像头。常见做法是先枚举var i: Integer; begin ComboBox1.Items.Clear; for i : 0 to VideoGrabber1.VideoDevicesCount - 1 do ComboBox1.Items.Add(VideoGrabber1.VideoDeviceName[i]); if ComboBox1.Items.Count 0 then ComboBox1.ItemIndex : 0; end;VideoDevicesCount和VideoDeviceName是成对使用的枚举完让用户选再把选中索引赋给VideoDevice。格式选择上VideoGrabber1.VideoWidth和VideoHeight可以指定期望分辨率但最终能不能用取决于设备支持的媒体类型。如果设了一个设备不支持的分辨率SDK 会回退到最接近的可用格式这时候要通过OnVideoDeviceSelected或日志确认实际生效的参数别默认自己设的就一定生效。3. 录像、抓帧与推流参数怎么设才不翻车3.1 录像文件切分与编码器选择录像功能的核心属性是RecordingFileName、RecordingMode和RecordingMethod。我一般这样配VideoGrabber1.RecordingFileName : D:\Rec\cam01_ FormatDateTime(yyyymmdd_hhnnss, Now) .mp4; VideoGrabber1.RecordingMode : rm_MP4; VideoGrabber1.RecordingMethod : rmm_Recompress; VideoGrabber1.VideoCompressor : vc_H264; VideoGrabber1.AudioCompressor : ac_AAC; VideoGrabber1.StartRecording;rm_MP4指定容器格式rmm_Recompress表示重新编码而不是直接存原始流。重新编码的好处是文件小、兼容性好代价是吃 CPU。如果机器性能紧张可以改成rmm_NoRecompress但这样录出来的文件格式取决于采集设备输出后期播放器兼容性要自己验证。自动切分用RecordingSplitMode和RecordingSplitSize或RecordingSplitDuration。比如按 10 分钟切VideoGrabber1.RecordingSplitMode : rsm_Duration; VideoGrabber1.RecordingSplitDuration : 600; // 单位秒注意切分时 SDK 会在后台关闭当前文件并打开新文件这期间如果磁盘 IO 跟不上可能丢帧。建议录像目录单独放一块盘别和系统盘混用。3.2 抓帧保存为图片的两种路径抓帧有两种常见需求一是手动点按钮抓一张二是按固定间隔自动抓。手动抓用VideoGrabber1.BMPSaveToFile : D:\Snap\snap_ FormatDateTime(hhnnsszzz, Now) .bmp; VideoGrabber1.SaveFrameToFile;如果要 JPEG把BMPSaveToFile换成JPGSaveToFile并通过JPGSaveQuality控制质量取值 0 到 100工业检测一般 85 到 95 够用再高文件体积涨得快但肉眼区别不大。自动抓帧用定时器配合SaveFrameToFile但要注意别在预览线程里直接调容易和渲染抢资源。我一般用TTimer在主线程触发间隔不低于 200ms否则某些采集卡会报设备忙。3.3 网络流与 RTSP 的接入要点TVideoGrabber 也支持把网络流当视频源。设置VideoSource : vs_IPCamera或类似枚举然后填 URL。实际项目里 RTSP 接入最常见的坑是延迟和断流重连。延迟方面可以调NetworkLatency或缓冲相关属性但调太小会卡顿调太大延迟高需要根据场景权衡。断流重连我一般自己写一个看门狗定时器检测IsVideoSourceOpen状态发现断了就CloseVideoSource再OpenVideoSource而不是指望 SDK 自动恢复。推流方面SDK 支持把采集内容推到 RTMP 等目标。配置项集中在NetworkStreaming相关属性里需要填目标地址和流密钥。这块我踩过的坑是推流和本地录像同时开CPU 占用会明显上升如果编码器选的是软件 H264低配机器可能扛不住。解决办法是优先用设备硬件编码或者降低推流分辨率别和本地录像用同一路高码率。4. 避坑与排查Delphi 12.3 集成 TVideoGrabber 的五个高频问题4.1 预览黑屏但日志显示设备已打开现象调用OpenVideoSource和StartPreview后Panel 上什么都没有日志里也没有明显报错。原因最常见的是PreviewWindow句柄赋值时机不对。如果在窗体还没创建完、Panel 句柄还没生成时就赋值SDK 拿到的是无效句柄。另一个原因是渲染器和系统不兼容比如在 Win10 上用了过老的 VMR7。解决把PreviewWindow : Panel1.Handle放到FormShow或Panel1的OnResize之后确保句柄有效。渲染器优先试 VMR9不行换 EVR。还可以在赋值后调一次VideoGrabber1.UpdatePreview强制刷新。4.2 编译期报找不到单元或包冲突现象打开示例工程编译提示找不到VideoGrabber.dcu或某个单元或者提示包版本冲突。原因Delphi 12.3 的库路径里可能残留了旧版本 TVideoGrabber 的路径或者 SDK 的源码目录没加到Library Path。另外如果之前装过其他版本的包设计期包可能冲突。解决先在Component Install Packages里把所有 TVideoGrabber 相关的包移除再清理Library Path里的旧路径重新编译安装当前版本的包。确认 Win32 和 Win64 的路径分开配置不要互相污染。4.3 录像文件能生成但播放器打不开现象录像正常停止文件也有体积但用播放器打开提示格式不支持或文件损坏。原因多半是录像没有正常停止就退出了程序文件头没写完。TVideoGrabber 在StopRecording时会做文件收尾如果程序直接被杀进程MP4 的 moov box 写不进去文件就废了。解决在窗体OnClose或OnDestroy里确保调用StopRecording并且给它一点时间完成。如果程序可能被强制结束考虑用rmm_NoRecompress存原始流或者改用对异常结束容忍度更高的容器格式。另外录像过程中别去手动改RecordingFileName容易把文件句柄搞乱。4.4 多摄像头同时采集时某个设备打不开现象单摄像头正常同时开两个就有一个报错或黑屏。原因一是 USB 带宽不够两个高分辨率摄像头挂在同一个 USB 控制器下带宽被占满。二是某些摄像头驱动不支持多实例。三是 SDK 的设备索引在热插拔后变了代码里还按旧索引打开。解决先确认硬件层面把摄像头插到不同的 USB 控制器上或者降低其中一个的分辨率。软件层面每次打开前重新枚举设备用设备名匹配而不是固定索引。如果驱动不支持多实例换摄像头或换采集卡。4.5 程序退出时报内存泄漏或线程未结束现象关闭程序时 Delphi 报内存泄漏或者调试器显示有线程还在运行。原因TVideoGrabber 内部有采集线程和渲染线程如果只调CloseVideoSource而没有先StopPreview和StopRecording线程可能没完全退出。另外事件回调里如果引用了已经释放的窗体对象也会出问题。解决退出顺序固定为StopRecording→StopPreview→CloseVideoSource然后再释放组件。事件回调里尽量只做数据传递不要直接操作可能已经销毁的 UI 对象。如果用了OnLog之类的回调在窗体销毁前把事件置空。5. 进阶技巧用日志和状态机把采集稳定性拉满TVideoGrabber 的OnLog事件是我用得最多的排错工具但很多人只把它当调试输出其实可以做成运行时的状态监控。我的习惯是在OnLog里过滤出Severity为警告和错误的条目写入一个环形缓冲区界面上放一个小指示灯有错误就变红。这样现场部署时不用连调试器也能知道采集链路有没有出问题。更进一步我会给采集流程写一个显式状态机而不是靠一堆布尔标志。状态大致是Idle、Opening、Previewing、Recording、Error。每次调用 SDK 方法前先检查当前状态是否允许该操作操作结果通过OnLog和OnVideoDeviceSelected等事件回写状态。这样做的好处是多线程环境下不会出现“以为已经打开了其实还在打开中”的竞态。下面是一个简化的状态判断片段type TCaptureState (csIdle, csOpening, csPreviewing, csRecording, csError); procedure TForm1.UpdateState(NewState: TCaptureState); begin FState : NewState; case FState of csIdle: StatusLabel.Caption : 空闲; csOpening: StatusLabel.Caption : 打开中; csPreviewing:StatusLabel.Caption : 预览中; csRecording: StatusLabel.Caption : 录像中; csError: StatusLabel.Caption : 异常; end; end; procedure TForm1.ButtonOpenClick(Sender: TObject); begin if FState csIdle then Exit; UpdateState(csOpening); try VideoGrabber1.VideoDevice : GetSelectedDeviceIndex; VideoGrabber1.OpenVideoSource; VideoGrabber1.StartPreview; UpdateState(csPreviewing); except on E: Exception do begin UpdateState(csError); OutputDebugString(PChar(Open failed: E.Message)); end; end; end;参数和逻辑说明FState是窗体私有字段所有对 SDK 的操作都先过状态判断。GetSelectedDeviceIndex是自己封装的函数从下拉框取当前设备索引。异常捕获里不要只弹框一定要写日志因为现场往往没人看弹框。另一个进阶点是录像文件的命名和归档策略。我一般用「设备名 日期 班次 序号」的规则避免纯时间戳在跨天时排序混乱。同时给录像目录设一个容量阈值超过就删最旧的文件这个逻辑放在单独的定时器里别和采集线程耦合。最后说一个我自己的习惯每次升级 SDK 版本先在一个独立的小工程里跑通预览、录像、抓帧三个基本功能再往主工程里合。因为视频采集这条链路版本升级带来的行为变化有时候不会写在更新说明里只有跑一遍才知道。希望帮到你。本文还有配套的精品资源点击获取