Captura 命令行 `--source` 参数完全指南：六种视频源（desktop / region / screen / none / win / webcam）的用法与底层解析

Captura 命令行--source参数完全指南六种视频源desktop / region / screen / none / win / webcam的用法与底层解析【免费下载链接】CapturaCapture Screen, Audio, Cursor, Mouse Clicks and Keystrokes项目地址: https://gitcode.com/gh_mirrors/ca/CapturaCaptura 的独立命令行程序captura-cli通过--source参数指定「从哪里采集视频」是start录屏与shot截图两个核心动词共用的关键选项。本文以 Arg-Source.md 为骨架逐条讲解desktop、region、screen:index、none、win:hWnd、webcam六种取值格式与适用场景并结合 ConsoleManager.cs 与 Screna 视频源提供器的ParseCli实现说明每个取值在源码中的校验规则与行为细节帮助你写出准确、可复现的命令行脚本。--source参数的作用范围--source定义在 CommonCmdOptions.cs是start与shot共用的基础选项[Option(source, Default , HelpText Video source)] public string Source { get; set; }两种动词的可选值几乎完全一致动词用途支持的 sourcecaptura-cli start录制视频desktop、region、screen:index、none、win:hWnd、webcamcaptura-cli shot截取屏幕desktop、region、screen:index、win:hWnd唯一的差别是none纯音频录制与webcam仅摄像头只能用于start详见下文各节。shot的完整参数见 Verb-Shot.mdstart的完整参数见 Verb-Start.md。从源码看start与shot都把--source的字符串交给同一个分发函数处理。ConsoleManager.cs 中的HandleVideoSource会遍历所有已注册的IVideoSourceProvider把原始字符串依次传给各自的ParseCli方法第一个返回true的提供器即被选中IVideoSourceProvider HandleVideoSource(CommonCmdOptions CommonOptions) { var provider _videoSourceProviders.FirstOrDefault(M M.ParseCli(CommonOptions.Source)); return provider; }如果没有任何提供器能解析该字符串start会输出Video source not set or invalid并直接退出。各提供器的ParseCli实现集中在 src/Screna/VideoSourceProviders 下抽象基类声明见 VideoSourceProviderBase.cs。desktop整块桌面默认值desktop用于捕获整块桌面是start与shot的默认取值因此显式写出与否效果相同captura-cli start --source desktop captura-cli shot --source desktop文档明确说明这是默认选项「写上它和不写一样」。在源码中FullScreenSourceProvider.cs 的ParseCli负责匹配该字符串未显式指定--source时字符串为空同样会落入默认的全屏捕获路径。适合快速录全屏、截全屏或作为脚本的兜底参数。regionLeft,Top,Width,Height四值矩形区域用逗号分隔的四个整数依次表示Left左、Top上、Width宽、Height高指定一个矩形区域进行采集。start与shot均支持captura-cli shot --source 100,100,300,400上例表示从坐标(100, 100)开始截取宽度300、高度400的区域。命令的解析与矩形构造逻辑在 RegionSourceProvider.cspublic override bool ParseCli(string Arg) { if (!(Arg.ConvertToRectangle() is Rectangle rect)) return false; _regionProvider.SelectedRegion rect.Even(); return true; }其中ConvertToRectangle()负责把L,T,W,H字符串解析为Rectangle对象解析失败即返回false该提供器不认领此参数随后调用的Even()扩展方法对应文档中的关键约束The dimensions of the region must be even. If not, they are decreased by 1 as required.即区域的宽、高必须是偶数这是底层编码/采集对齐的硬性要求。若传入奇数系统不会报错而是自动减 1调整为偶数后再用于采集。例如--source 0,0,301,401实际生效区域为0,0,300,400。实际截取时RegionSourceProvider.Capture 直接调用ScreenShot.Capture(SelectedRegion, IncludeCursor)与全屏截图共用同一套底层实现因此 region 截图与 desktop 截图在输出质量上是一致的。screen:index指定某块显示器当机器连接多块显示器时可用screen:index选择其中一块index为从 0 开始的屏幕索引captura-cli start --source screen:1 captura-cli shot --source screen:1start与shot均支持。索引的获取方式在文档中有明确提示运行captura-cli list查看屏幕列表及其索引list的输出内容详见 Verb-List.md注意只有多于 1 块屏幕时list才会列出 Screens。ScreenSourceProvider.cs 的校验逻辑非常严格public override bool ParseCli(string Arg) { if (!Regex.IsMatch(Arg, ^screen:\d$)) return false; var index int.Parse(Arg.Substring(7)); var screens _platformServices.EnumerateScreens().ToArray(); if (index screens.Length) return false; Set(screens[index]); return true; }两处值得注意参数必须严格匹配screen:加纯数字的格式正则^screen:\d$多余的空格或字符都会导致解析失败索引越界index screens.Length同样返回false最终表现为「Video source not set or invalid」。有趣的是shot的默认--source在无参数时会被设置为screen:1见 ShotCmdOptions.cs 附近的代码结合上述越界保护可知当机器只有一块屏幕且未显式指定 source 时截图会因索引越界而走其他分支——这提醒我们使用shot时最好显式指定--source避免依赖隐式默认值。none纯音频录制仅startnone表示不采集任何视频画面仅适用于captura-cli start用于纯音频录制场景captura-cli start --source none --speaker 0上例即「只录制第一个扬声器输出」--speaker的索引同样从 0 开始-1表示不使用默认即-1。这种模式常被用来录制系统内部声音或配合--mic录制麦克风产物是纯音频文件。none的解析由 NoVideoSourceProvider.cs 完成其配套的 NoVideoItem.cs 提供了「无视频轨道」的采集项。需要提醒的是既然是纯音频录制--source none一般要配合--speaker/--mic使用否则录出来是无声的空文件。win:hWnd按窗口句柄捕获仅shot支持透明窗口win:hWnd以窗口句柄hWnd为参数捕获指定窗口的内容captura-cli start --source win:123456 captura-cli shot --source win:123456用于captura-cli start时文档特别强调该窗口句柄必须出现在captura-cli list的输出中list会列出所有可见窗口及其hWnd见 Verb-List.md 中的「Visible Windows with hWnd」hWnd是 Windows 原生窗口句柄十进制整数可用captura-cli list查询当前可见窗口也可用 Spy 等工具获取。在源码层面窗口捕获对shot有专门的处理路径。ConsoleManager.cs 在截图前先用正则win:\d判断参数格式命中后通过_platformServices.GetWindow拿到窗口对象再调用ScreenShotModel.ScreenShotWindow截取——这条路径支持带透明度的窗口截图如无边框半透明窗口。WindowSourceProviderWindowSourceProvider.cs则负责在start录制模式下认领并解析该参数。webcam仅摄像头画面仅startwebcam表示只捕获摄像头画面只能与captura-cli start搭配不能用于shotcaptura-cli start --source webcam --webcam 0配合参数说明--webcam指定使用哪一路摄像头索引从 0 开始-1表示不使用默认值即-1。该参数定义在 StartCmdOptions.cs可用captura-cli list查看可用摄像头列表输出逻辑见 ConsoleLister.cs列表项从索引 0 开始编号。底层解析在 WebcamSourceProvider.cs匹配规则非常简单直接Arg webcam即参数必须是精确的字符串webcam不支持任何变体。选中后ConsoleManager.HandleWebcamConsoleManager.cs会把对应摄像头设置进WebcamModel源码中甚至保留了一段注释HACK: Sleep to prevent AccessViolationException——切换摄像头后程序会强制休眠 500ms 再继续以避免访问冲突异常这说明在脚本中连续切换摄像头时应留出缓冲时间。选择正确的 source场景对照与验证手段综合以上六种取值可按下表快速决策需求场景source 取值示例适用动词全屏录制/截图desktop--source desktopstart / shot指定屏幕录制/截图screen:index--source screen:0start / shot矩形区域截图/录制L,T,W,H--source 100,100,300,400start / shot指定窗口录制/截图win:hWnd--source win:123456start / shot纯音频录制none--source none --speaker 0仅 start仅摄像头录制webcam--source webcam --webcam 0仅 start无论选择哪种取值都有两条通用的验证与调试手段先list再执行captura-cli list用法见 Verb-List.md会一次性输出版本号、FFmpeg/SharpAvi 可用性、可见窗口及hWnd、多屏幕时的屏幕列表、麦克风、扬声器与摄像头清单。screen:index的索引、win:hWnd的句柄、--mic/--speaker/--webcam的索引都应先从这里确认避免越界导致的Video source not set or invalid留意奇偶与格式约束region 的宽高会被强制修正为偶数screen:必须紧跟纯数字webcam必须原样拼写。任何格式偏差都会让解析器静默拒绝该参数。另外需要注意命令行程序使用独立的 Captura.Console.csproj 工程构建产物为captura-cli.exe与 GUI 版captura.exe见 docs/Cmdline/README.md 的对照表是两套入口。官方文档同时提示命令行支持目前「不是非常稳定」not very stable发现问题时可在仓库提交 issue 反馈。小结--source是 Captura 命令行采集入口最核心的参数之一desktop、region、screen:index、none、win:hWnd、webcam六种取值分别覆盖全屏、区域、多屏、纯音频、单窗口与摄像头六类典型需求。理解每个取值背后对应的ParseCli校验规则region 的偶数修正、screen 的严格正则、webcam 的精确匹配、win 的 list 白名单约束能让你在编写自动化录制脚本时一次性写对参数避免静默失败。更完整的动词用法可继续阅读 Verb-Start.md、Verb-Shot.md 与 Verb-List.md。【免费下载链接】CapturaCapture Screen, Audio, Cursor, Mouse Clicks and Keystrokes项目地址: https://gitcode.com/gh_mirrors/ca/Captura创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考