WatchRemote

Apple Watch 音乐遥控器 — 通过本地网络控制 Mac 音乐播放。

功能

• 播放 / 暂停 / 上一曲 / 下一曲
• Digital Crown 旋转调节音量（2% 步进）
• 音量 +/- 按钮及实时音量 HUD
• 连接状态实时指示
• 触觉反馈（可开关）
• 支持所有媒体播放器（Apple Music、Spotify、Chrome 等）
• 适配 41mm–49mm 全尺寸 Apple Watch

架构

Apple Watch ──HTTP──▶ Mac (Python Server)
  SwiftUI App           ├─ AppleScript 模拟媒体键
  NetworkManager        └─ 音量节流 (100ms)

Watch 端通过 HTTP 请求向 Mac 发送控制指令，Mac 端 Python 服务器接收后调用 AppleScript 执行媒体控制。

快速开始

1. 启动 Mac 服务器

cd WatchRemote
python3 mac_server.py

服务器启动后会显示 Mac 的 IP 地址和端口（默认 12266）。

2. 配置 Apple Watch

1. 打开 WatchRemote 应用
2. 点击设置图标
3. 输入 Mac 的 IP 地址
4. 端口保持默认 12266
5. 保存

3. 开始使用

确保 Mac 和 Apple Watch 在同一 Wi-Fi 网络，在 Mac 上播放音乐，即可通过手表控制。

API 端点

端点	方法	说明
/ping	GET	连接检测
/playpause	POST	播放/暂停
/next	POST	下一曲
/previous	POST	上一曲
/volumeup	POST	音量 +6.25%
/volumedown	POST	音量 -6.25%
/volumeup_small	POST	音量 +2%（Digital Crown）
/volumedown_small	POST	音量 -2%（Digital Crown）
/setvolume/{1-100}	POST	设置绝对音量
/volume	GET	获取当前音量
/playstate	GET	获取播放状态

项目结构

WatchRemote/
├── WatchRemote Watch App/
│   ├── ContentView.swift          # 主界面：播放控制 + Crown 音量
│   ├── NetworkManager.swift       # 网络通信与状态管理
│   ├── SettingsView.swift         # 服务器配置界面
│   ├── VolumeControlView.swift    # 音量控制界面
│   └── ScreenSize.swift           # 手表尺寸适配
├── WatchRemote/                   # iOS 伴侣应用（占位）
├── mac_server.py                  # Mac 端 Python 服务器
├── start_server.sh                # 服务器启动脚本
└── diagnose_network.sh            # 网络诊断脚本

技术栈

组件	技术
watchOS 端	Swift 6.0 / SwiftUI / WatchKit / Combine
Mac 服务器	Python 3 / http.server / AppleScript
通信协议	HTTP REST（局域网）

系统要求

• Apple Watch Series 4+，watchOS 11.0+
• macOS 10.15+，Python 3
• Xcode 16.2+（开发）

故障排除

1. 无法连接 — 确认 Mac 和 Watch 在同一 Wi-Fi；检查防火墙是否放行端口 12266；运行 ./diagnose_network.sh 诊断
2. 命令无响应 — 检查 Mac 终端日志输出；确认 macOS 辅助功能权限已授予终端/Python
3. 查看 Mac IP — 服务器启动时自动显示，或执行 ifconfig | grep "inet " | grep -v 127.0.0.1

许可证

MIT License

作者

咕咚