DS5 Vibe Controller for macOS

把 Sony PlayStation 5 DualSense 变成面向 Vibe Coding 的掌上语音、快捷键和触摸控制器。

社区开源项目，与 Sony Interactive Entertainment 无隶属或背书关系。

能做什么

使用 DualSense 内置麦克风进行按住说话；L2 按下解除硬件静音，松开恢复静音。
同步手柄麦克风静音键与橙色指示灯。
将方向键和面部按键映射为发送、换行、撤销、删除等 macOS 快捷键。
将触摸板转换成单指鼠标、拖拽、轻点，以及带主轴锁定和惯性的双指连续滚动。
提供只监听 127.0.0.1 的可视化配置、测试和诊断页面。
以用户 LaunchAgent 常驻运行，Terminal 或 Codex 退出后服务仍然存在。

关键边界：内置麦克风必须通过 USB 数据线连接。当前版本不承诺通过 macOS 蓝牙传输 DualSense 麦克风音频。

三步开始

前提：macOS 13 或更高版本、Sony 原装普通 DualSense、可传数据的 USB-C 线和网络连接。

cd dualsense-vibe-controller
./ds5 install
./ds5 permissions

在系统设置的“隐私与安全性 → 辅助功能”中开启 DualSense Vibe Controller，接受首次出现的麦克风授权，然后运行：

./ds5 restart
./ds5 doctor
./ds5 open

./ds5 doctor 应报告 DualSense USB HID、DualSense USB audio、Microphone permission 和服务状态通过。完整图文步骤见快速开始。

默认单手布局

输入	默认动作	行为
L2	`fn` / 豆包语音输入	按住
方向键上	`cmd+z` 撤销	点按
方向键右	`enter` 发送	点按
方向键下	`shift+enter` 换行	点按
方向键左	`delete` 删除	点按
Mic	硬件静音切换	点按
触摸板单指	鼠标移动、轻点、按压拖拽	连续
触摸板双指	纵横滚动、惯性、轻点右键	连续

首次启动默认关闭“控制输出”，便于先观察真实输入；确认映射无误后在页面上开启。

日常命令

./ds5 start        # 启动并登录后自启
./ds5 stop         # 停止并禁用自启
./ds5 restart      # 重启
./ds5 status       # 查看服务和权限状态
./ds5 open         # 启动并打开控制页面
./ds5 permissions  # 打开辅助功能授权入口
./ds5 doctor       # 完整环境与硬件自检
./ds5 logs         # 跟随服务日志
./ds5 uninstall    # 移除 LaunchAgent，保留仓库和配置

./ds5 是唯一受支持的生命周期入口；不要直接运行 scripts/ 中的内部实现。这样能保证始终复用同一个 LaunchAgent、App 路径和 TCC 权限身份。

可迁移性

安装脚本创建仓库私有 .venv，并使用已验证的 Python 依赖锁定文件。
LaunchAgent 在安装时按当前用户和当前目录动态生成，不包含开发者的绝对路径。
config.example.yaml 是可提交默认值；config.yaml 是每台 Mac 的本地配置，不进入 Git。
设备按 Sony VID 和标准 DualSense PID 发现，不绑定某一只手柄的序列号或 HID 路径。
麦克风和辅助功能是 macOS 的逐机授权，无法也不应随仓库复制。

换 Mac、移动目录和复制个性化配置的具体规则见迁移说明。

文档

参与和支持

功能贡献与提交约定：CONTRIBUTING.md
使用问题与脱敏诊断：SUPPORT.md
私密安全报告与边界：SECURITY.md
社区行为准则：CODE_OF_CONDUCT.md

开发验证

./ds5 install --no-start
./scripts/check.sh
./ds5 dev

本项目只在本机读取 HID、USB Audio 和本地配置。控制页面绑定 127.0.0.1，录音与动作统计保存在本地 data/，不会主动上传。

Azerrroth/dualsense-vibe-controller

README