Skip to content

About

用软件切换显示器输入源:一台显示器共用 Windows 与 macOS 双主机时,碰哪台的键鼠显示器就跳到哪台(DDC/CI + 局域网委托)

Topics

Resources

Stars

12 stars

Watchers

0 watching

Forks

Repository files navigation

display-kvm

用软件切换显示器的输入源(软 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)。

双端各装好后,必做两步:

  1. 让两端 token 一致——二选一:
    • 懒人法(推荐):托盘菜单点「配对两端 …」,两端会自动在局域网里协商出同一个 token 并各自写盘,全程不用手动复制。
    • 手工法:两端 token 改成完全一致的随机串(Windows 端首次生成的是随机值, 复制到 Mac 端即可)。
  2. 识别当前屏幕的输入源:托盘菜单点「自动探测本机输入口」让它自己试出来 (它会先问你「现在这个口是不是本机」,一次问答通常就够)。

配对安全性:协商出的 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

三、具体功能

1. 自动切换(核心)

你碰哪台的键鼠,画面就跳到哪台。判据分两段,这是它能"不误触、也不漏触"的原因:

阶段 条件 作用
待命(arm) 画面在对端,且本机键鼠已空闲超过 arm_after_idle_seconds 过滤"我人不在电脑前"的状态,避免走过碰一下就抢屏
触发(fire) 待命之后,检测到空闲计时器被重置(这一拍明显小于上一拍) 只要这期间发生过任何一次输入就一定能抓到,不依赖采样刚好落在动作瞬间
冷却(cooldown) 刚切完画面的 cooldown_seconds 内 不响应自动触发,防止来回弹

键鼠空闲是独立高频采样的(200ms 一次):macOS 走 Quartz,Windows 走 GetLastInputInfo,都是一次 API 调用、不碰显示器。所以动一下鼠标就能被看到, 不用等下一轮 2 秒的角色轮询。

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 + 消息循环目前只做了逻辑验证,还没在真机上跑过。 如果快捷键没反应,先用托盘菜单或命令行,别怀疑自动切换。

3. 两端配对

token 一致才算"同一对"。两条路:

  • 自动配对:任一端点「配对两端 …」,发起端生成 token 连同一个一次性 nonce 广播 出去(255.255.255.255 + 已知候选 IP,3.2 秒内 4 轮),对端抄下 token 写盘并回 pairing_accept,发起端收到 accept 才置为已配对。两端同时点也不会打结:会按 名字定胜负,最后只留一个结果。
  • 手工配对:两端 token 写成同一串随机字符,重启生效。

配套细节都是踩出来的:

  • 发起配对的端会先发一个 pairing_reset 清掉对端可能残留的旧配对状态 —— 否则对端卡在「已配对」会一直拒绝新请求,这就是 v1.0.7 那个死局。
  • 「解除配对」会顺带请对端一起解除,不用跑到另一台机器上再点一次。
  • 两端 token 不一致时,菜单里会直接写「token 不一致,正在自动解除以便重新配对」, 不会只在日志里刷屏。

4. 自动切换开关两端同步

「自动切换」是两端联动的总开关:任一端改(菜单勾选 / 设置窗口保存 / kvmctl auto on|off),都会通过 config_sync 报文推给对端,对端镜像并写回自己的 kvm.json。所以"Windows 关了、Mac 没关"这种各管各的情况不会再出现。

防回声是硬要求:接收端只镜像、不回播,且值相同直接跳过 —— 两边同时改也只会收敛到 同一个值。只有 token 一致的对端报文才会被接受。

5. 输入口自动探测

「自动探测本机输入口」用来回答一个问题:这台机器接在显示器的哪个口上。

它不能纯靠软件推断:DDC 里显示器只知道自己哪个口有信号,不知道那个信号属于哪台机器, 没有反向通道可问。实测过"切到空口看会不会自动跳回"这条路 —— 空口要 12 秒才跳回, 等 3 秒去读会把空口全判成有信号,等够 14 秒虽然准但一轮要一分多钟。

所以改成问一句:先问当前正在显示的那个口(多数人是在用本机时点的探测,一次问答 就完事,连画面都不用切);答"不是本机"就切到下一个候选口再问,直到确认。候选口默认 0x0F 0x10 0x11 0x12 0x1B(DP-1 / DP-2 / HDMI-1 / HDMI-2 / USB-C), 可用配置里的 input_candidates 改。

dry_run: true 时探测会直接拒绝 —— 它依赖真的把画面切过去看反应。

6. 参数设置窗口

菜单 →「参数设置 …」:一个窗口填完,保存即时生效,不用重启。macOS 上是原生窗口, Windows 上是系统表单;万一两边都弹不出来,会自动退化成逐项输入框。

填进去的值会自动做范围钳制(比如保护时间最长 120 秒),填了非法值就忽略该项。 也可以直接改 kvm.json 里的同名字段,但改完要退出再重开才生效 —— 走设置窗口则不用。

各字段含义见下一节。

7. 演练模式

dry_run: true 时只写日志、不真的切,用来在第一次部署时确认"它想干什么"。 托盘菜单状态、kvmctl status 都会标出来,日志里每条决策前会带 DRY-RUN。

8. 开机自启与单实例

  • 开机自启:Windows 走注册表 Run 键,macOS 走 ~/Library/LaunchAgents/cn.displaykvm.agent.plist,菜单里一个勾选框。 安装包里也可以选。
  • 单实例:控制口(默认 127.0.0.1:47822)已被占用时,第二次启动只会提示"已在运行", 不会起第二个实例抢着发 DDC 命令。

9. 状态、日志与排障

托盘 / 菜单栏菜单顶部三行是实时的:

  • 角色:🟢 本机在显示 / 🔴 画面在对端
  • 对端: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)。

About

用软件切换显示器输入源:一台显示器共用 Windows 与 macOS 双主机时,碰哪台的键鼠显示器就跳到哪台(DDC/CI + 局域网委托)

Topics

Resources

Stars

12 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages