用软件切换显示器的输入源(软 KVM),替代伸手去按显示器上的实体按钮。
针对的场景:一台显示器同时接了 Windows 主机和 Mac 主机,两台各有独立的键鼠。 你碰哪台的键鼠,显示器就自动跳到哪台。
到 Releases 下载对应平台的产物。
| 平台 | 文件 | 是什么 |
|---|---|---|
| Windows | display-kvm.exe |
免安装执行文件(绿色版)。双击直接运行,不用装、不用管理员权限,托盘常驻;配置生成在 %APPDATA%\display-kvm\kvm.json。适合先试一下,或者不想往系统里写东西。 |
| Windows | Display-KVM-Setup-x.x.xx.exe |
安装包。双击安装,会写开始菜单快捷方式、可选桌面图标与开机自启,卸载入口也在开始菜单里。长期用推荐这个。 |
| macOS | Display-KVM-x.x.xx.dmg |
苹果 M 芯片(Apple Silicon:M1/M2/M3/M4)Mac 的安装包。打开后把 Display KVM 拖进 Applications 即可。 |
dmg 只面向 Apple 芯片的 Mac:它内置的 m1ddc 依赖 Apple 的私有 CoreDisplay 接口,
Intel Mac 上拿不到 DDC 通道(需要把配置里的 DDC 命令换成 ddcctl)。
另外 dmg 无法在 Windows/Linux 上交叉构建,如需自己打,在 Mac 上跑
bash packaging/build_mac.sh 即可(自动装依赖、打 .app、做 dmg)。
双端各装好后,必做两步:
- 让两端
token一致——二选一:- 懒人法(推荐):托盘菜单点「配对两端 …」,两端会自动在局域网里协商出同一个
token并各自写盘,全程不用手动复制。 - 手工法:两端
token改成完全一致的随机串(Windows 端首次生成的是随机值, 复制到 Mac 端即可)。
- 懒人法(推荐):托盘菜单点「配对两端 …」,两端会自动在局域网里协商出同一个
- 识别当前屏幕的输入源:托盘菜单点「自动探测本机输入口」让它自己试出来 (它会先问你「现在这个口是不是本机」,一次问答通常就够)。
配对安全性:协商出的
token在局域网里是明文广播的,家用无妨;公司 / 公共网络 请勿用配对,改用手工法并自行保管随机串。已配对的两端会忽略任何新的配对请求, 不会被同网段其他实例劫持。
想从源码直接跑:
python app.py(Windows 需pip install pystray pillow, macOS 还要pyobjc-framework-Cocoa;macOS 侧 DDC 依赖m1ddc,brew install m1ddc)。
显示器内部有颗控制芯片。所有输入口切换、亮度、对比度,都走 VESA 的 MCCS 协议,
通过视频线里的 DDC 通道传命令 —— 具体是 VCP 0x60 (Input Source)。
你按显示器实体按钮,是让显示器的 MCU 执行这条命令;软件做的事,
只是把同一条命令替你说出去。所以本质上不是"绕过硬件",而是"换个手按"。
已在本机实测(Windows 端,2560×1440 主屏):
| 项目 | 结果 |
|---|---|
| DDC/CI 可读可写 | 是 |
| 当前输入源 | 0x10 (DisplayPort-2) |
| 可选输入源 | 0x11 HDMI-1 / 0x12 HDMI-2 / 0x0F DP-1 / 0x10 DP-2 |
| 切换耗时 | 显示器重锁信号 1–3 秒(物理必然,无法消除) |
三个前提,缺一个就白忙:
- 显示器 OSD 里的
DDC/CI必须打开(不少显示器出厂是关的),否则一切无效。 - 视频线要直连,或走雷电 / USB4 扩展坞;廉价转接器、部分 HDMI 分配器会把 DDC 通道吃掉。
- macOS 侧要能跑
m1ddc(dmg 里已内置);Intel Mac 不适用,见上一节。
还有几个躲不开的限制:
- 切换时黑屏 1–3 秒:显示器重锁信号 + 重新协商分辨率 / HDCP 的物理开销,消不掉。
- 切走的那台会掉屏:Windows 上窗口可能重排。要让被切走的一侧保留桌面坐标, 得给它配一块虚拟屏(本项目不处理)。
- 自动切换靠键鼠输入活动判定,所以纯触屏操作、或者你用的是硬件 KVM 切换器, 检测不到输入 —— 这种场景只能用托盘菜单 / 快捷键 / 命令行手动切。
切换命令只能由「当前正被显示器选中」的那台机器发出。
DDC 通道挂在活跃的视频链路上。显示器一旦切走,另一台机器的链路就静默了, 它发不出任何命令。所以:
想切过去的机器,往往正好是发不出命令的那台。
本项目的解法是委托:
- 我检测到本机键鼠有活动,但我当前不在显示器上 → 通过网络请对端(它正被显示)替我说
- 我当前正在显示器上,要切走 → 本地直接发 DDC
因此两台都必须装,且必须能互相通信。
display-kvm/
├─ app.py 打包入口 / 门面(134 行):对齐导入路径与旧名字,实际实现都在 kvm_app/
├─ agent.py 后台 agent 门面(302 行):建 socket、跑主循环、对外 facade
├─ kvmctl.py 本地控制客户端:status / switch / auto on|off / pair …
├─ hotkeys.py 全局快捷键(macOS Carbon / Windows RegisterHotKey)
├─ settings.py 参数设置窗口(原生窗口 / 系统表单 / 输入框降级)
├─ ddc_win.py Windows DDC 读写:纯 ctypes 调 dxva2.dll,零第三方依赖
│
├─ kvm_platform/ 平台层:只跟"硬件怎么说话"有关
│ ├─ constants.py VCP 码表、输入源编号 ↔ 名字(0x0F = DP-1)
│ ├─ base.py PlatformBase:探角色 / 切输入源 / 查键鼠空闲 的接口约定
│ ├─ windows.py GetLastInputInfo + dxva2
│ └─ mac.py Quartz 取空闲时长 + m1ddc 读写 DDC
│
├─ kvm_core/ 逻辑层:协议与状态机,不 import 任何 UI
│ ├─ config.py 默认值、类型归一化(脏配置自愈)
│ ├─ common.py 极小的公共件
│ ├─ transport.py UDP 收发与报文编码
│ ├─ discovery.py 心跳、对端发现、超时判定
│ ├─ pairing.py 局域网自动配对(token 协商)
│ ├─ sync.py 两端配置同步(auto_switch 联动)
│ ├─ probe.py 角色探测:现在画面在谁那儿 / 自动探测输入口
│ ├─ switch.py 切换决策:arm、cooldown、委托对端
│ └─ control.py 本地控制口(127.0.0.1:47822),kvmctl 走这里
│
├─ kvm_app/ 界面层:托盘、窗口、日志、自启
│ ├─ paths.py 配置 / 日志路径,frozen 与开发态的资源定位
│ ├─ logsetup.py 日志落盘
│ ├─ config_store.py 配置读写(含"只改指定字段")
│ ├─ autostart.py 开机自启(注册表 Run 键 / LaunchAgent plist)
│ ├─ dialogs.py 系统对话框与"用默认程序打开"
│ ├─ tray.py 托盘 / 菜单栏:状态行、菜单项、Windows 菜单钩子
│ └─ entry.py 命令行入口与单实例检查
│
├─ selftest/ pytest 用例(30 个):配对、同步、配置、托盘菜单
├─ packaging/ PyInstaller spec、Inno Setup 脚本、构建脚本、图标、m1ddc
├─ tools/dump_mccs.py 排障用:把显示器的 MCCS 能力整表打出来
├─ VERSION 版本号唯一来源(打包脚本从这里取)
├─ kvm.windows.json 配置模板(手动部署 / 命令行方式用)
├─ kvm.mac.json 同上,macOS 版
└─ CHANGELOG.md 更新日志
三层分工是刻意的:kvm_platform 只关心"这台机器怎么读写显示器和键鼠空闲",
kvm_core 只关心"什么时候该切、跟对端说什么",kvm_app 才是壳(托盘、窗口、自启)。
加一个平台只动 kvm_platform/,换一套 UI 只动 kvm_app/,互不牵连。
改完代码跑一遍用例:
pip install pytest pytest-timeout
python -m pytest -q # 30 passed你碰哪台的键鼠,画面就跳到哪台。判据分两段,这是它能"不误触、也不漏触"的原因:
| 阶段 | 条件 | 作用 |
|---|---|---|
| 待命(arm) | 画面在对端,且本机键鼠已空闲超过 arm_after_idle_seconds |
过滤"我人不在电脑前"的状态,避免走过碰一下就抢屏 |
| 触发(fire) | 待命之后,检测到空闲计时器被重置(这一拍明显小于上一拍) | 只要这期间发生过任何一次输入就一定能抓到,不依赖采样刚好落在动作瞬间 |
| 冷却(cooldown) | 刚切完画面的 cooldown_seconds 内 |
不响应自动触发,防止来回弹 |
键鼠空闲是独立高频采样的(200ms 一次):macOS 走 Quartz,Windows 走
GetLastInputInfo,都是一次 API 调用、不碰显示器。所以动一下鼠标就能被看到,
不用等下一轮 2 秒的角色轮询。
| 方式 | 怎么做 | 适合 |
|---|---|---|
| 托盘 / 菜单栏菜单 | 「立即切到本机」/「立即切到对端(对端名字)」 | 随手点一下 |
| 全局快捷键 | 默认 ctrl+alt+1 切到本机、ctrl+alt+2 切到对端 |
键盘党,不打断手头的事 |
| 命令行 | kvmctl status / switch / switch-peer / auto on|off |
脚本、Alfred、AutoHotkey、快捷指令 |
手动切换不受冷却时间限制 —— 你明确要求切,程序不会拦。
快捷键在托盘菜单里直接改(点「快捷键 · 切到本机:⌃⌥1」会弹输入框):
- 写法是
修饰键 + 主键,例如ctrl+alt+1、cmd+shift+m、ctrl+alt+f13 - 修饰键可用
ctrl(Mac 上是 ⌃)、alt(⌥)、shift(⇧)、cmd(⌘);主键可用字母、 数字、f1~f20、方向键、space等 - 至少要带一个修饰键,单独一个字母键会和正常打字打架,程序会直接拒绝
- 留空 = 取消该快捷键;菜单里还有「启用快捷键」总开关
macOS 用的是 Carbon 的 RegisterEventHotKey,不需要「辅助功能」权限。这是特意选的:
CGEventTap 那条路必须授权,而 ad-hoc 签名(--sign -)每次重新打包 cdhash 都会变、
旧授权立刻失配,等于每构建一次就要用户重新勾一次权限。Windows 侧用 RegisterHotKey,
同样不需要管理员权限。
Windows 端的
RegisterHotKey+ 消息循环目前只做了逻辑验证,还没在真机上跑过。 如果快捷键没反应,先用托盘菜单或命令行,别怀疑自动切换。
token 一致才算"同一对"。两条路:
- 自动配对:任一端点「配对两端 …」,发起端生成
token连同一个一次性 nonce 广播 出去(255.255.255.255 + 已知候选 IP,3.2 秒内 4 轮),对端抄下token写盘并回pairing_accept,发起端收到 accept 才置为已配对。两端同时点也不会打结:会按 名字定胜负,最后只留一个结果。 - 手工配对:两端
token写成同一串随机字符,重启生效。
配套细节都是踩出来的:
- 发起配对的端会先发一个
pairing_reset清掉对端可能残留的旧配对状态 —— 否则对端卡在「已配对」会一直拒绝新请求,这就是 v1.0.7 那个死局。 - 「解除配对」会顺带请对端一起解除,不用跑到另一台机器上再点一次。
- 两端
token不一致时,菜单里会直接写「token 不一致,正在自动解除以便重新配对」, 不会只在日志里刷屏。
「自动切换」是两端联动的总开关:任一端改(菜单勾选 / 设置窗口保存 /
kvmctl auto on|off),都会通过 config_sync 报文推给对端,对端镜像并写回自己的
kvm.json。所以"Windows 关了、Mac 没关"这种各管各的情况不会再出现。
防回声是硬要求:接收端只镜像、不回播,且值相同直接跳过 —— 两边同时改也只会收敛到
同一个值。只有 token 一致的对端报文才会被接受。
「自动探测本机输入口」用来回答一个问题:这台机器接在显示器的哪个口上。
它不能纯靠软件推断:DDC 里显示器只知道自己哪个口有信号,不知道那个信号属于哪台机器, 没有反向通道可问。实测过"切到空口看会不会自动跳回"这条路 —— 空口要 12 秒才跳回, 等 3 秒去读会把空口全判成有信号,等够 14 秒虽然准但一轮要一分多钟。
所以改成问一句:先问当前正在显示的那个口(多数人是在用本机时点的探测,一次问答
就完事,连画面都不用切);答"不是本机"就切到下一个候选口再问,直到确认。候选口默认
0x0F 0x10 0x11 0x12 0x1B(DP-1 / DP-2 / HDMI-1 / HDMI-2 / USB-C),
可用配置里的 input_candidates 改。
dry_run: true时探测会直接拒绝 —— 它依赖真的把画面切过去看反应。
菜单 →「参数设置 …」:一个窗口填完,保存即时生效,不用重启。macOS 上是原生窗口, Windows 上是系统表单;万一两边都弹不出来,会自动退化成逐项输入框。
填进去的值会自动做范围钳制(比如保护时间最长 120 秒),填了非法值就忽略该项。
也可以直接改 kvm.json 里的同名字段,但改完要退出再重开才生效 —— 走设置窗口则不用。
各字段含义见下一节。
dry_run: true 时只写日志、不真的切,用来在第一次部署时确认"它想干什么"。
托盘菜单状态、kvmctl status 都会标出来,日志里每条决策前会带 DRY-RUN。
- 开机自启:Windows 走注册表
Run键,macOS 走~/Library/LaunchAgents/cn.displaykvm.agent.plist,菜单里一个勾选框。 安装包里也可以选。 - 单实例:控制口(默认
127.0.0.1:47822)已被占用时,第二次启动只会提示"已在运行", 不会起第二个实例抢着发 DDC 命令。
托盘 / 菜单栏菜单顶部三行是实时的:
- 角色:🟢 本机在显示 / 🔴 画面在对端
- 对端:IP、角色、几秒前的心跳(掉线会写"离线,Xs 前失去心跳")
- 配对状态:未配对 / 已配对 / 发现可配对设备 / token 不一致
更全的用命令行看(display-kvm-ctl.exe 是打包版,kvmctl.py 是源码版):
kvmctl.py status # 身份、角色、显示器、键鼠空闲、自动切换、配对、对端、输入源
kvmctl.py switch # 立即切到本机
kvmctl.py switch-peer # 立即把手上的画面交出去
kvmctl.py autodetect # 自动探测输入口
kvmctl.py auto off # 暂停自动,只留手动
kvmctl.py unpair # 解除配对(并请对端一起解除)日志在两个平台上都叫 display-kvm.log,就在配置文件旁边:
| 平台 | 目录 |
|---|---|
| Windows | %APPDATA%\display-kvm\ |
| macOS | ~/Library/Application Support/display-kvm/ |
菜单里的「打开配置文件」「打开日志」会直接调系统默认程序打开它们。
给想自己接工具的人:两端通信走 UDP 47821(心跳、委托、配对、配置同步), 本地控制口是 127.0.0.1:47822,一行一个纯文本命令、回 JSON。
菜单栏图标 →「参数设置 …」:一个窗口填完,保存即时生效,不用重启。 macOS 上是原生窗口,Windows 上是系统表单;万一两边都弹不出来,会自动退化成逐项输入框。
| 窗口里的名字 | 配置字段 | 默认 | 说明 |
|---|---|---|---|
| 启用自动切换 | auto_switch |
true | 关掉就只剩手动切换 |
| 切换后的保护时间(秒) | cooldown_seconds |
6.0 | 刚切完画面的这段时间内,碰鼠标键盘都不会再触发自动切换。托盘菜单和快捷键的手工切换不受它限制 |
| 离开多久后才允许被唤醒(秒) | arm_after_idle_seconds |
3.0 | 画面在对端时,本机键鼠要空闲超过这么久才进入待命状态。调大可减少误触 |
| 判定为「有操作」的阈值(秒) | fire_below_idle_seconds |
0.45 | 待命状态下,空闲时长低于这个值就认为你碰了键鼠,立刻切过来 |
| 状态检测周期(秒) | role_poll_seconds |
2.0 | 多久探测一次「画面现在在谁那儿」。越小越灵敏,DDC 查询也越频繁 |
| 对端失联判定(秒) | peer_timeout_seconds |
12.0 | 超过这么久收不到对端心跳就认为它下线了 |
| 演练模式 | dry_run |
false | 只写日志,不真的切 |
填进窗口的值会自动做范围钳制(比如保护时间最长 120 秒),填了非法值就忽略该项。
也可以直接改配置 JSON 里的同名字段,但改完要退出再重开才生效——走设置窗口则不用。
两个常见调法:
- 觉得太容易误触(走过碰一下桌子就被切走):把「离开多久后才允许被唤醒」提到 8–10 秒。
- 切完显示器还没亮又被弹回去:把「切换后的保护时间」提到 8–10 秒。
每个版本改了什么、为什么改,见 CHANGELOG.md。
MIT。第三方组件:m1ddc(MIT)、pystray / Pillow(LGPL / MIT-CMU)。