knowledge-work-plugins 之 Zoom Video SDK for Windows 官方示例应用完全指南20 个 Sample 选型、代码模式与构建实战【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins本篇技术指南以 knowledge-work-plugins 仓库中 partner-built/zoom-plugin/skills/video-sdk/windows 技能库的官方示例参考文档为核心系统讲解 Zoom Video SDK Windows 端C官方示例工程的完整清单、推荐学习路径、关键代码模式与构建配置。读完本文你将能够根据业务需求原始音视频采集、自定义音视频注入、云录制、信令、转写等快速选定对应示例工程作为起点理解贯穿所有示例的单例获取 → 委托实现 → 订阅使用通用架构并掌握在 Visual Studio 中编译运行这些示例所需的全部前提与配置细节。一、示例总览20 个官方 Sample 一览Zoom Video SDK Windows 官方示例仓库videosdk-windows-rawdata-sample提供了覆盖 SDK 主要能力的示例工程。下表汇总了全部示例的名称、功能定位与核心特性是选型时的首要参考示例描述关键特性VSDK_SkeletonDemo最小化会话加入最简单的入门起点VSDK_getRawVideo采集原始视频YUV420 帧提取VSDK_getRawAudio采集原始音频PCM 音频提取VSDK_getRawShare采集屏幕共享共享内容捕获VSDK_sendRawVideo发送自定义视频虚拟摄像头注入VSDK_sendRawAudio发送自定义音频虚拟麦克风注入VSDK_sendRawShare发送自定义共享自定义屏幕共享源VSDK_CloudRecording云录制启停云端录制VSDK_CommandChannel自定义消息收发自定义命令VSDK_CallInPSTN 呼入电话拨入支持VSDK_CalloutPSTN 呼出电话拨出支持VSDK_ServiceQuality网络统计质量监控VSDK_TranscriptionAndTranslation实时转写实时字幕VSDK_MultiStreamVideo多路视频流多摄像头支持VSDK_PreviewCameraAndMicrophone设备预览入会前设备测试VSDK_Share2ndCameraAsMultiCam第二摄像头多摄像头共享VSDK_Share2ndCameraAsShareScreenDemo摄像头作为共享摄像头内容共享VSDK_ShareScreenPreprocessorDemo共享预处理自定义共享处理VSDK_RTMSDemo实时消息RTMS 集成VSDK_DuilibDemo2完整 UI 演示完整 GUI 应用官方示例仓库与文档的链接信息可在技能库的 SKILL.md 与 windows.md 中查阅本文聚焦于这些示例的本地化解读与代码模式。从示例清单可以看出官方示例覆盖了 SDK 的四大能力域原始数据采集Raw Data Capture、原始数据注入Raw Data Injection、通信Communication与录制/流媒体/高级特性下文第三节将按类别展开。二、推荐学习路径五个阶段吃透核心示例官方建议的学习路径遵循先跑通最小闭环再逐项深入的原则与技能库中 concepts/sdk-architecture-pattern.md 所总结的单例 → 委托 → 订阅三段式架构一脉相承。阶段 1从 VSDK_SkeletonDemo 起步这是代码量最小、最纯粹的会话加入示例演示了以下 SDK 基础能力SDK 初始化CreateZoomVideoSDKObjinitializeJWT 鉴权token字段会话加入/离开joinSession/leaveSessionWindows 消息循环回调驱动的关键前提基础委托实现IZoomVideoSDKDelegate需要掌握的核心模式// 1. 创建 SDK IZoomVideoSDK* sdk CreateZoomVideoSDKObj(); // 2. 初始化 ZoomVideoSDKInitParams params; params.domain Lhttps://zoom.us; sdk-initialize(params); // 3. 添加委托 sdk-addListener(myDelegate); // 4. 加入会话 ZoomVideoSDKSessionContext ctx; ctx.sessionName Lsession; ctx.token Ljwt; ctx.audioOption.connect false; sdk-joinSession(ctx); // 5. 消息循环关键 while (running) { MSG msg; while (PeekMessage(msg, NULL, 0, 0, PM_REMOVE)) { TranslateMessage(msg); DispatchMessage(msg); } Sleep(10); }为什么消息循环关键技能库中的 troubleshooting/windows-message-loop.md 明确指出Zoom Video SDK 依赖 Windows 消息机制派发回调。事件发生时SDK 将消息投递到调用joinSession()所在线程的消息队列若没有PeekMessage/GetMessage驱动的消息循环onSessionJoin()、onError()等回调永远不会触发——表现为joinSession()返回成功但无任何回调。因此消息循环必须与调用 SDK 方法的线程同一线程回调内禁止阻塞不要sleep或忙等GUI 应用WinMain 标准消息循环天然满足控制台/自定义主循环必须显式补充。阶段 2视频采集 VSDK_getRawVideo该示例演示如何捕获远端用户的原始 YUV420 视频帧包含IZoomVideoSDKRawDataPipeDelegate接口实现onRawDataFrameReceived()回调YUV 缓冲区提取Y、U、V 三平面分辨率与旋转角处理核心模式class VideoCapture : public IZoomVideoSDKRawDataPipeDelegate { void onRawDataFrameReceived(YUVRawDataI420* data) override { int width >void onMixedAudioRawDataReceived(AudioRawData* data) override { char* buffer >// 初始化 SDK IZoomVideoSDK* sdk CreateZoomVideoSDKObj(); ZoomVideoSDKInitParams params; params.domain Lhttps://zoom.us; params.videoRawDataMemoryMode ZoomVideoSDKRawDataMemoryModeHeap; sdk-initialize(params);内存模式注意事项技能库 SKILL.md 特别强调原始数据的内存模式应始终使用堆模式ZoomVideoSDKRawDataMemoryModeHeap并同时为视频、共享、音频三路分别设置params.videoRawDataMemoryMode ZoomVideoSDKRawDataMemoryModeHeap; params.shareRawDataMemoryMode ZoomVideoSDKRawDataMemoryModeHeap; params.audioRawDataMemoryMode ZoomVideoSDKRawDataMemoryModeHeap;堆模式而非栈模式可避免大尺寸视频帧导致的内存问题此外还可通过params.enableLog true与params.logFilePrefix开启日志以辅助排查。2. 委托注册必须始终在加入会话之前注册委托sdk-addListener(new MyDelegate()); sdk-joinSession(context);若在joinSession()之后才调用addListener()将错过早期事件examples/session-join-pattern.md 中明确标注此为错误用法。同时注意IZoomVideoSDKDelegate拥有 7080 个纯虚方法全部必须实现哪怕为空实现否则会产生抽象类编译错误。3. 音频连接策略官方推荐先入会、后连音频的两段式入会时设置audioOption.connect false在onSessionJoin()回调中再调用startAudio()context.audioOption.connect false; // 入会配置 void onSessionJoin() override { sdk-getAudioHelper()-startAudio(); // 在此连接 }该策略分离了会话加入与音频初始化可提高可靠性并便于错误处理。同理自己的摄像头应在onSessionJoin中通过videoHelper-startVideo()开启。4. 消息循环所有示例都包含消息循环这是回调触发的必要前提前文已详述while (!g_exit) { MSG msg; while (PeekMessage(msg, NULL, 0, 0, PM_REMOVE)) { TranslateMessage(msg); DispatchMessage(msg); } Sleep(10); }五、构建与配置前置条件Visual Studio 2019 或 2022安装使用 C 的桌面开发工作负载含 MSVC v142/v143 编译器与 Windows 10/11 SDKWindows SDK 10.0.19041.0 及以上Zoom Video SDK从 Zoom Marketplace 下载构建步骤打开解决方案文件.sln将平台设置为x64将配置设置为Release生成解决方案CtrlShiftB将 SDK DLL 拷贝到输出目录技能库 SKILL.md 补充了运行时环境的基线Windows 101903 或更高或 Windows 11支持 x64推荐、x86 与 ARM64 架构若使用 C#/.NET 应用还需 .NET Framework 4.8 及以上与 C/CLI 支持。配置文件每个示例通过config.json提供运行参数{ jwt: your-jwt-token, session_name: test-session, password: , user_name: Bot }在 examples/session-join-pattern.md 的完整实现中LoadConfig()会读取该 JSON使用 jsoncpp将jwt、session_name、password、user_name默认Bot映射为全局宽字符串再填入ZoomVideoSDKSessionContext完成入会。若文件无法打开或 SDK 初始化失败程序会立即退出并返回错误码。六、进阶深化示例背后的 SDK 实现细节理解示例代码后可进一步结合技能库参考文档深入底层实现。6.1 五层 API 层级与导航式访问references/windows-reference.md 将 SDK 建模为五层深的单例对象树所有功能都通过导航而非构造获取Level 1 入口CreateZoomVideoSDKObj() → IZoomVideoSDK*提供initialize、joinSession、addListener、getVideoHelper、getAudioHelper、getShareHelper、getChatHelper、getCmdChannel、getRecordingHelper等入口Level 2 核心 Helper 与会话IZoomVideoSDKSessiongetMyself、getRemoteUsers、IZoomVideoSDKVideoHelper仅控制自己的摄像头、IZoomVideoSDKAudioHelper、IZoomVideoSDKShareHelperLevel 3 用户与渲染对象IZoomVideoSDKUserGetVideoCanvas、GetVideoPipe、getVideoStatus、IZoomVideoSDKCanvasSDK 渲染、IZoomVideoSDKRawDataPipe原始 YUV、IZoomVideoSDKShareAction共享控制Level 4 设备/聊天/回调IZoomVideoSDKCameraDevice、IZoomVideoSDKChatHelper、IZoomVideoSDKRawDataPipeDelegateLevel 5 原始数据与工具YUVRawDataI420、AudioRawData、IZoomVideoSDKUserHelper、IZoomVideoSDKCmdChannel等。关键区分VideoHelper/AudioHelper只控制自己的音视频流startVideo()开启自己的摄像头观看远端参会人的视频必须通过其user-GetVideoCanvas()-subscribeWithView(hwnd, aspect, resolution)或user-GetVideoPipe()-subscribe(resolution, delegate)订阅。屏幕共享则更特殊远端共享必须使用onUserShareStatusChanged回调中的IZoomVideoSDKShareAction而非user-GetShareCanvas()因为一个用户可能同时存在多个共享流。6.2 两种渲染/处理路线Canvas API 与 Raw Data Pipe路线接口适用场景Canvas APIIZoomVideoSDKCanvas::subscribeWithView(HWND)标准应用、画质最佳、实现最简单Raw Data PipeIZoomVideoSDKRawDataPipe::subscribe(delegate)自定义处理、特效、录制、计算机视觉Canvas API 由 SDK 直接渲染到窗口句柄无需 YUV 转换支持ZoomVideoSDKVideoAspect_Original / FullFilled / PanAndScan / LetterBox等纵横比与ZoomVideoSDKResolution_90P / 180P / 360P / 720P / 1080P / Auto等分辨率选项Raw Data Pipe 则向委托回调交付YUVRawDataI420帧交由应用自行转换渲染GDI/DirectX/OpenGL 均可。6.3 原始视频处理的进阶要点对应 VSDK_getRawVideoexamples/raw-video-capture.md 给出了 YUV420I420 平面的内存布局Y 平面为全分辨率width × height字节U/V 平面各为四分之一分辨率(width/2) × (height/2)字节单帧总大小为width × height × 1.5字节分辨率Y 缓冲区U 缓冲区V 缓冲区总计720p1280×720921,600230,400230,4001,382,4001080p1920×10802,073,600518,400518,4003,110,400360p640×360230,40057,60057,600345,600YUVRawDataI420的主要方法包括GetYBuffer/GetUBuffer/GetVBuffer三平面指针、GetStreamWidth/GetStreamHeight帧尺寸、GetRotation0/90/180/270、GetTimeStamp时间戳以及CanAddRef/AddRef/Release引用计数用于跨回调异步处理。采集到的.yuv文件可用 FFplay 回放或 FFmpeg 转码ffplay -video_size 1280x720 -pixel_format yuv420p -f rawvideo video.yuv ffmpeg -video_size 1280x720 -pixel_format yuv420p -framerate 30 -f rawvideo -i video.yuv -c:v libx264 output.mp4性能优化建议预分配 RGB 缓冲区仅尺寸变化时重分配回调内使用AddRef()将帧投递到独立处理线程处理完Release()AI 处理订阅低分辨率ZoomVideoSDKResolution_360P显示则用高分辨率 Canvas。6.4 原始音频采集格式对应 VSDK_getRawAudioexamples/raw-audio-capture.md 明确音频格式为PCM 未压缩、32000 Hz、16-bit 有符号、单声道或双声道、小端序每次回调约 6401280 字节2040ms 音频。三种回调分别对应onMixedAudioRawDataReceived全体参会人混合音频适合整场录制onOneWayAudioRawDataReceived逐用户音频需特殊配置适合按发言人转写onSharedAudioRawDataReceived屏幕共享内容音频与参会人音频分离。AudioRawData提供GetBuffer()PCM 缓冲区、GetBufferLen()字节数、GetSampleRate()通常 32000与GetChannelNum()1单声道2双声道。采集到的.pcm可用 FFplay 回放或转为 WAVffplay -f s16le -ar 32000 -ac 1 audio.pcm ffmpeg -f s16le -ar 32000 -ac 1 -i audio.pcm output.wav常见坑位音频回调不触发未在onSessionJoin连接音频、FFmpeg 中错误使用 44100 Hz、静音无人发言或全员静音需检查onUserAudioStatusChanged。6.5 订阅时机与错误码调试示例的关键依据references/windows-reference.md 强调两条时序铁律不要在onUserJoin中订阅视频——此时视频可能尚未就绪会触发 Error 2Internal_Error。正确做法是在onUserVideoStatusChanged中检查pipe-getVideoStatus().isOn为真后再订阅并跳过自己if (user myself) continue;订阅过快会触发ZoomVideoSDKSubscribeFailReason_TooFrequentCall6处理方式是在相邻订阅调用之间插入Sleep(200)。常用错误码速查0 Success、1 Wrong_Usage错误状态调用、2 Internal_Error视频未就绪/过早订阅、7 Invalid_ParameterNULL 指针、非法 HWND、8 Call_Too_Frequently调用过于频繁。6.6 线程安全与生命周期SDK 回调运行在 SDK 线程而非主线程不要在回调中执行重操作、不要在回调中调用cleanup()、跨线程传递数据使用线程安全队列如YUVRawDataI420的引用计数配合生产者-消费者队列并加锁保护共享状态。退会时统一在onUserLeave/onSessionLeave中解除订阅并清理最后按leaveSession(false)→cleanup()→DestroyZoomVideoSDKObj()的顺序释放。七、相关文档导航本文对应的示例参考文档位于 references/samples.md技能库中与之配套的深度资料还包括SDK 架构模式贯穿所有功能的单例 → 委托 → 订阅万能三段式会话加入模式完整的 JWT 鉴权 入会代码含main.cpp与config.json原始视频采集YUV 捕获完整实现与 FFmpeg 处理原始音频采集PCM 捕获完整实现与 FFplay 处理发送原始视频 / 发送原始音频虚拟摄像头/虚拟麦克风注入实现API 参考五层 API 层级、方法签名、错误码与时序规则委托方法全部回调方法Windows 消息循环回调不触发的第一排查项常见问题快速诊断清单行动建议以VSDK_SkeletonDemo打通初始化 → 委托 → 入会 → 消息循环的最小闭环再根据业务诉求选择VSDK_getRawVideo或VSDK_getRawAudio切入原始数据采集若需要向会话注入内容则对应研读VSDK_sendRawVideo虚拟摄像头与VSDK_sendRawAudio虚拟麦克风。任何示例运行异常优先检查消息循环是否存在、委托是否在入会前注册、订阅是否发生在视频就绪之后。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考