简介面向 Java 开发者的海康威视摄像头二次开发源码包完整演示通过海康威视软件开发工具包实现设备连接、通道选取、预览句柄申请、参数设置、视频流显示与资源释放的闭环流程。压缩包共 302 个文件以 Java 源码、编译后的类文件、动态链接库、依赖包和项目配置为主整体体积 7.74MB。已有 9497 人学习下载适合需要对接监控设备、快速落地预览功能的中级 Java 工程师。除基础业务逻辑外工程还封装了海康设备接口映射、播放控制面板和本地视频渲染组件并附带跨语言调用所需的动态库便于直接导入工程对照调试省去环境搭建和协议对接成本。目录组织清晰对后续扩展录像、云台控制等功能也有较好参考价值。1. Java调海康威视SDK做摄像头预览先弄明白这份资源能解决什么接到“Java调用海康威视SDK实现摄像头预览”这个需求很多人的第一反应是把官方Demo跑起来把预览窗口弹出来就算完事。实际上手之后才发现SDK是C写的Java侧要走JNA登录、预览、回调、解码每一环都有自己的脾气。这篇文章就是按我拆过的一个模拟项目XJava端对接某品牌摄像头的预览模块的路径来写的把SDK包的结构、登录和预览的参数、码流回调的数据类型、常见报错和重连机制一次讲透。适合两类人一是刚接手设备接入、需要尽快跑通预览的Java开发二是已经能预览但遇到黑屏、卡顿、录像文件打不开这类问题的熟手。读完你能知道每个接口为什么这么调、参数怎么设、出了问题先查哪里。2. 环境准备SDK包结构、JNA库加载与HCNetSDK接口文件2.1 SDK包里到底有哪些东西哪些是Java必须的海康威视设备网络SDK解压之后目录看起来不少真正Java工程用到的核心就三块一是HCNetSDK.java这个接口文件它是官方用JNA把C的HCNetSDK.dll导出函数封装成Java接口的成果几百个接口定义都在里面二是lib目录下的dll/so文件Windows下是HCNetSDK.dll、HCCore.dll、PlayCtrl.dll等一票动态库Linux下是对应的so三是examples下的JavaDemo里面有现成的登录和预览调用顺序建议当参考而非直接抄因为Demo里很多地方为了兼容C的写法Java侧直接搬会踩坑。这里有个容易忽略的依赖关系HCNetSDK.dll不是单文件就能跑的它依赖hccore.dll、HCCore.dll这些兄弟库。所以JNA加载的时候jna.library.path必须指向包含全部依赖库的目录而不是只指到HCNetSDK.dll一个文件。我遇到过一次只拷了主dll结果Native.load直接抛UnsatisfiedLinkError排查了半天才发现是依赖库缺失。2.2 JNA库加载的正确姿势在工程里引入JNA依赖后加载SDK有两种常见做法。第一种是直接用Native.load加载接口类第二种是让HCNetSDK接口自己持有INSTANCE实例。官方HCNetSDK.java里已经写好了INSTANCE的加载逻辑所以正常使用只需要在程序入口设置好库路径然后通过HCNetSDK.INSTANCE调用所有方法。// 程序入口处设置JNA库搜索路径必须在第一次加载HCNetSDK之前执行 System.setProperty(jna.library.path, D:/workspace/sdk/lib); // 触发类加载HCNetSDK.java内部会执行 Native.loadLibrary(HCNetSDK, HCNetSDK.class) // 返回的INSTANCE是单例后续所有调用都走它 HCNetSDK hik HCNetSDK.INSTANCE; // 初始化SDK返回false说明加载有问题直接看异常栈 boolean initOk hik.NET_DVR_Init(); if (!initOk) { throw new RuntimeException(SDK初始化失败); }这段代码的逻辑很直白第一步设置JNA查找dll的路径第二步通过单例拿到SDK接口第三步调用NET_DVR_Init完成全局初始化。这里要特别说明jna.library.path这个系统属性必须在HCNetSDK类被首次加载前设置因为JNA在类加载时就去找动态库了你放到登录之前再设就晚了。另外NET_DVR_Init只需要调用一次不要在每次登录时重复调用否则可能造成内存重复分配。有个参数容易忽视jna.library.path指向的目录在Windows下最好把dll、exe同级的整个lib目录都放进去因为HCNetSDK.dll运行时还会再去同目录找它的兄弟库。Linux下还要注意so的位数要和JVM位数一致32位JDK配32位库64位配64位这个不匹配也是启动即翻车的重灾区。2.3 工程依赖与最小骨架Maven工程里JNA依赖用4.x版本即可jetbrains的jna或者sun的jna都行我一般用net.java.dev.jna。注意HCNetSDK.java文件不要自己去网上找旧的必须和dll版本配套否则会出现某个接口方法找不到的NoSuchMethodError这是版本不匹配的典型症状。dependency groupIdnet.java.dev.jna/groupId artifactIdjna/artifactId version5.13.0/version /dependency代码结构上我习惯把HCNetSDK.java原封不动放在com.hikvision.sdk包下不要改动它内部任何字段定义因为海康的结构体都是用JNA的Structure实现的字段顺序、类型注解一点都不能动。业务代码单独写一个CameraService类封装登录、预览、注销、重连这些操作。这样后续SDK升级只需要替换HCNetSDK.java和dll目录业务层基本不用动。3. 登录与实时预览V40接口参数和完整调用顺序3.1 NET_DVR_Login_V40的登录参数设置海康登录接口有两个版本V30和V40。V40新增了NET_DVR_USER_LOGIN_INFO结构体把登录信息和解码库信息拆开了推荐直接用V40。登录信息结构体里最关键的是IP地址、端口、用户名、密码四个字段端口默认8000。注意Java里给这个结构体的byte数组赋值不能用String直接set必须手动拷贝字节。// 登录参数组装核心字段说明见下文 HCNetSDK.NET_DVR_USER_LOGIN_INFO loginInfo new HCNetSDK.NET_DVR_USER_LOGIN_INFO(); byte[] ipBytes 192.168.1.64.getBytes(GBK); System.arraycopy(ipBytes, 0, loginInfo.sDeviceAddress, 0, ipBytes.length); byte[] userBytes admin.getBytes(GBK); System.arraycopy(userBytes, 0, loginInfo.sUserName, 0, userBytes.length); byte[] pwdBytes 12345.getBytes(GBK); System.arraycopy(pwdBytes, 0, loginInfo.sPassword, 0, pwdBytes.length); loginInfo.wPort 8000; loginInfo.write(); // JNA Structure参数必须write到native内存 HCNetSDK.NET_DVR_DEVICEINFO_V40 deviceInfo new HCNetSDK.NET_DVR_DEVICEINFO_V40(); int userId HCNetSDK.INSTANCE.NET_DVR_Login_V40(loginInfo, deviceInfo); if (userId -1) { int errorCode HCNetSDK.INSTANCE.NET_DVR_GetLastError(); throw new RuntimeException(登录失败错误码 errorCode); }这段代码的难点在于JNA的Structure在调用native方法前必须调用write()把Java侧字段同步到内存中否则native层读到的全是空值表现为登录直接返回-1。sDeviceAddress、sUserName、sPassword都是定长byte数组长度不足的部分保持默认0。字符编码建议用GBK因为设备端很多老固件的用户名密码是按GBK解析的用UTF-8在某些设备上会登录失败这是血泪经验。登录成功返回的userId就是后续所有操作的句柄很多新手把userId当成设备ID来用其实它只是本次会话的标识。deviceInfo里能拿到设备能力集比如是否支持抓图、是否有云台如果后面要做抓图功能先看这个结构体里的byDVRType和byAbility字段。3.2 NET_DVR_PREVIEWINFO参数与预览句柄预览接口用NET_DVR_RealPlay_V40它接收一个NET_DVR_PREVIEWINFO参数。这个结构体的字段非常多但Java接入时真正需要关心的就几个lChannel是通道号从1开始dwStreamType是码流类型0主码流、1子码流dwLinkMode是取流协议0代表TCP1代表UDP2代表多播bBlocked是取流是否阻塞1阻塞、0非阻塞。字段取值说明lChannel1~n通道号从1开始不是0dwStreamType0/10主码流1子码流dwLinkMode0/1/20 TCP1 UDP2 多播bBlocked0/11表示阻塞式取流0非阻塞hPlayWnd窗口句柄非0时SDK内部解码显示0时走回调这里有个关键选择hPlayWnd传窗口句柄SDK会在内部解码并把画面直接渲染到那个窗口上Java侧不需要碰码流数据hPlayWnd传0同时传回调函数SDK把码流数据回调给Java层由你自行处理。Java项目里要显示到Swing面板我一般用hPlayWnd方式因为SDK内部解码渲染的效率远高于Java层自己解码。// 组装预览参数并启动预览 HCNetSDK.NET_DVR_PREVIEWINFO previewInfo new HCNetSDK.NET_DVR_PREVIEWINFO(); previewInfo.lChannel 1; // 通道1从1开始数 previewInfo.dwStreamType 0; // 主码流分辨率更高 previewInfo.dwLinkMode 0; // TCP方式稳定优先 previewInfo.bBlocked 1; // 阻塞式取流 previewInfo.byPreviewMode 0; // 0常规预览1延迟预览 previewInfo.hPlayWnd hwnd; // 窗口句柄非0时SDK解码渲染 previewInfo.write(); int realPlayHandle HCNetSDK.INSTANCE.NET_DVR_RealPlay_V40(userId, previewInfo, null, null); if (realPlayHandle -1) { int errorCode HCNetSDK.INSTANCE.NET_DVR_GetLastError(); throw new RuntimeException(预览失败错误码 errorCode); }预览成功返回的realPlayHandle之后停止预览、抓图都要用到。这里有个容易被坑的地方hwnd必须是一个真实存在的原生窗口句柄而不是Swing组件的Java对象引用。在Windows下获取Swing组件的原生句柄常见做法是通过内部API反射拿WComponentPeer的hwnd字段具体代码下面章节会展开。dwLinkMode建议优先TCPUDP虽然省带宽但在弱网环境下丢包严重画面会出现花屏和撕裂。3.3 停止预览与注销的顺序停止预览必须按照NET_DVR_StopRealPlay、NET_DVR_Logout、NET_DVR_Cleanup的顺序来顺序反了轻则句柄泄漏重则直接崩溃。特别是NET_DVR_Cleanup会把全局资源都释放掉你如果还开着预览就去调用它进程直接宕掉。// 按顺序释放资源 if (realPlayHandle ! -1) { HCNetSDK.INSTANCE.NET_DVR_StopRealPlay(realPlayHandle); } if (userId ! -1) { HCNetSDK.INSTANCE.NET_DVR_Logout(userId); } HCNetSDK.INSTANCE.NET_DVR_Cleanup();这段代码看起来简单实际上很多崩溃都发生在这个阶段。JNA回调线程还在跑的时候你直接把SDK反初始化了回调里再访问SDK内存就会出现非法访问。所以严谨的做法是先等回调线程退出再执行上面的释放顺序。我在项目里习惯用一个CountDownLatch来等回调线程安全退出避免野指针。4. 码流回调与画面显示从H.264数据到能看的画面4.1 码流回调里拿到的数据类型如果选择hPlayWnd方式预览Java业务层不需要关心码流细节但如果你要做抓帧、录像或自定义渲染就必须把回调函数用起来。海康SDK的回调类型是REALDATACALLBACK回调方法的dwDataType参数区分数据类型0是NET_DVR_SYSHEAD系统头包含SPS/PPS信息1是NET_DVR_STREAMDATA标准码流数据2是音频数据。// 码流回调dwDataType区分数据类型0系统头1码流数据 HCNetSDK.REALDATACALLBACK callback new HCNetSDK.REALDATACALLBACK() { Override public void invoke(int lRealHandle, int dwDataType, byte[] pBuffer, int dwBufSize, Pointer pUser) { if (dwDataType HCNetSDK.NET_DVR_SYSHEAD) { // 系统头里面是SPS/PPS保存录像文件时先写这个 byte[] header new byte[dwBufSize]; System.arraycopy(pBuffer, 0, header, 0, dwBufSize); // 丢给持久化线程处理 } else if (dwDataType HCNetSDK.NET_DVR_STREAMDATA) { // 普通码流帧可能是H.264或H.265的裸流 byte[] frame new byte[dwBufSize]; System.arraycopy(pBuffer, 0, frame, 0, dwBufSize); // 丢给解码器或写入文件 } } };这里有个关键认知回调里的pBuffer是编码后的码流数据不是可以直接显示的YV12或RGB图像。很多人误以为回调解码就能拿到图像帧实则不然。hPlayWnd方式下SDK内部先解码再渲染到窗口回调方式下SDK把原始编码流交给你你要么自己解要么把这个流转发给解码器。Java侧要显示画面常见路线是把H.264裸流喂给FFmpeg通过JavaCV封装解码成BufferedImage后再画到Swing面板上。回调里的数据不能被长时间占用因为SDK的回调线程是共享的你在回调里做了耗时操作比如写磁盘、转码会把其他通道的回调也阻塞住。正确做法是回调里只做浅拷贝把byte[]数据扔给后台线程池或阻塞队列立刻返回。4.2 从回调码流保存可播放的录像文件把回调拿到的H.264裸流保存成文件是录像功能的基础。关键是SYSHEAD必须写在文件最前面否则播放器解析不到SPS/PPS视频打不开。回调里首次收到SYSHEAD时置一个标志位后续STREAMDATA都往后追加。// 录像文件保存器先写系统头再写码流数据 class H264Recorder { private FileOutputStream fos; private boolean headerSaved; void start(String filePath) throws Exception { fos new FileOutputStream(filePath); headerSaved false; } void onData(int dataType, byte[] data) throws Exception { if (dataType HCNetSDK.NET_DVR_SYSHEAD) { fos.write(data); // SPS/PPS写在文件头 headerSaved true; } else if (dataType HCNetSDK.NET_DVR_STREAMDATA) { if (!headerSaved) return; // 头没写之前丢弃数据 fos.write(data); } } void stop() throws Exception { if (fos ! null) { fos.flush(); fos.close(); } } }这段代码的逻辑就是保证文件结构正确SPS/PPS在前帧数据在后。很多新手录出来的文件拖进播放器提示“无法解析”90%是因为没等SYSHEAD就开始写数据或者SYSHEAD被覆盖了。另外要注意不同设备的SYSHEAD数据大小不一样不能假设固定长度必须以dwBufSize为准。保存出来的.h264文件是裸流格式VLC能直接播但想转成mp4或avi需要经过一次转封装。这个阶段可以用FFmpeg命令行也可以用JavaCV的FFmpegFrameRecorder。转封装不涉及重编码速度很快适合把裸流整理成通用格式。4.3 Java Swing里获取原生窗口句柄hPlayWnd方式需要传原生窗口句柄给SDKJava Swing组件没有直接暴露这个值得通过内部API反射拿。在Windows平台Swing组件的peer实现是WComponentPeer它里面有个hwnd字段。// 获取Swing Canvas的原生窗口句柄Windows平台 java.awt.Canvas canvas new java.awt.Canvas(); canvas.setPreferredSize(new java.awt.Dimension(640, 480)); frame.add(canvas, java.awt.BorderLayout.CENTER); frame.pack(); frame.setVisible(true); // 等窗口显示后再取句柄未显示时hwnd为0 sun.awt.windows.WComponentPeer peer (sun.awt.windows.WComponentPeer) canvas.getPeer(); java.lang.reflect.Field f sun.awt.windows.WComponentPeer.class.getDeclaredField(hwnd); f.setAccessible(true); long hwnd f.getLong(peer);这段代码用了JDK内部API在不同JDK版本上字段名可能变化升级JDK时要注意兼容性。一个更稳妥的替代方案是直接用JNA调用User32.dll的API去创建或查找窗口句柄但那样写起来更繁琐。实际项目里如果只是给SDK一个渲染目标我一般直接用CanvasAWT窗口而不是JFrameSwing因为AWT的peer机制更稳定。拿到hwnd后把它设置到previewInfo.hPlayWnd里再调用NET_DVR_RealPlay_V40SDK就会把视频画到这个Canvas上。这种方式下画面显示是SDK内部线程完成的Java侧完全不用管解码渲染CPU占用极低。5. 避坑手册登录失败、黑屏与卡顿的排查顺序5.1 登录返回-1错误码各不相同现象NET_DVR_Login_V40返回-1调用NET_DVR_GetLastError拿到各种错误码。原因网络不通、端口不对、账号密码错、设备连接数满都会导致登录失败。解决先用海康的SADP工具扫描设备确认IP和端口再单独用浏览器或客户端尝试登录设备排除设备本身的问题。错误码这东西只能定位到方向不能直接告诉你具体原因所以排查时先把网络层问题排除。我见过的最多的场景是设备在局域网里IP是192.168.1.64但开发机的网段是192.168.2.x中间没有路由设备自然登录不上。还有一种是设备端口被改过不一定是默认的8000SADP扫描结果里能看到实际端口。5.2 预览黑屏但登录成功现象登录成功NET_DVR_RealPlay_V40也返回了句柄但窗口里一片黑。原因hPlayWnd句柄无效或者Canvas还没显示出来就设置了句柄SDK渲染到一个不存在的窗口上。解决确保先调用frame.setVisible(true)再取句柄再启动预览。如果用了回调方式检查previewInfo.hPlayWnd是否为0以及回调是否每帧都触发。还有一个隐藏原因通道号lChannel越界。设备只有4个通道你填了5预览接口可能不报错但画面黑屏。这个可以通过deviceInfo.byChanNum字段确认设备实际通道数。5.3 画面卡顿CPU占用飙升现象预览画面明显掉帧任务管理器里Java进程CPU占用到100%。原因回调里做了耗时操作比如在回调里写文件、做图像转换、甚至打日志。解决回调里只拷贝数据所有重活扔给独立线程池。另外dwLinkMode如果是UDP网络丢包也会导致解码器反复等待关键帧画面卡顿建议改回TCP。日志打印这个坑特别隐蔽回调里加了System.out.println看着只是打印几行实际上IO操作把回调线程卡死了。把日志去掉画面立刻流畅这是我在某跨平台系统项目里实际踩过的坑。5.4 注销时程序崩溃现象调用NET_DVR_Cleanup时JVM直接崩掉或者注销后再次登录失败。原因释放顺序错了先Cleanup再StopRealPlay或者回调线程还在执行中就释放了SDK资源。解决严格按照StopRealPlay - Logout - Cleanup的顺序并且确保没有回调线程在运行。我一般用AtomicBoolean标记回调状态注销前先把标记置false等回调线程退出。5.5 32位和64位库不匹配现象加载dll时提示Invalid ELF headerLinux或找不到入口点Windows。原因JVM位数和SDK动态库位数不一致比如64位JDK加载了32位dll。解决确认JDK版本用java -version看是64位还是32位然后下载对应位数的SDK包。这问题在政府采购的老机器上特别常见预装的32位JDK配64位SDK启动必挂。6. 进阶用法断线重连与录像验证预览功能跑通之后设备离线、网络抖动、摄像头重启这些异常场景才是真正考验工程能力的地方。海康SDK提供了自动重连机制通过NET_DVR_SetConnectTime和NET_DVR_SetReconnect两个接口配置。// 设置连接超时时间为2秒重试1次 HCNetSDK.INSTANCE.NET_DVR_SetConnectTime(2000, 1); // 启用自动重连10秒后开始重试无限重试 HCNetSDK.INSTANCE.NET_DVR_SetReconnect(10000, true);第一个参数是重连间隔毫秒数第二个参数是是否无限重试。注意这个机制只负责重新建立连接登录状态需要自己维护。我一般会在预览线程里加一个定时任务每5秒调用NET_DVR_GetDVRWorkState查询工作状态如果发现掉线就主动做一次完整注销再重新登录。录像验证这块我录完文件后不会直接用VLC看那样不够严谨。我的习惯是先看文件大小是否持续增长再用FFmpeg做一次转封装验证ffmpeg -i record.h264 -c:v copy record.mp4如果转封装成功且文件大小正常说明裸流结构完整SPS/PPS都在。如果FFmpeg报错“no start code found”说明SYSHEAD没写进去或者数据顺序乱了。从那以后我每次做预览模块都把取句柄时机、回调数据拷贝、释放顺序这三件事固定成模板回回少折腾。希望帮到你。本文还有配套的精品资源点击获取