# 媒体控制键使用指南

## 已实现的媒体控制功能

本音乐播放器已完整支持 **系统级媒体控制键**，包括 macOS 和 Windows 平台。

---

## 🎹 支持的媒体键

### 1. 播放/暂停
- **快捷键**: `MediaPlayPause` (系统媒体播放/暂停键)
- **功能**: 
  - 当播放列表为空时，自动从当前音乐库加载并播放第一首歌曲
  - 当有播放列表时，切换播放/暂停状态
- **触发方式**:
  - 键盘上的专用媒体播放/暂停键
  - macOS: Fn + F10（部分键盘）
  - Windows: 专用媒体键或 Fn 组合键

### 2. 上一曲
- **快捷键**: `MediaPrevTrack` (系统媒体上一曲键)
- **功能**: 切换到播放列表中的上一首歌曲
- **触发方式**:
  - 键盘上的专用媒体上一曲键
  - macOS: Fn + F11（部分键盘）
  - Windows: 专用媒体键或 Fn 组合键

### 3. 下一曲
- **快捷键**: `MediaNextTrack` (系统媒体下一曲键)
- **功能**: 切换到播放列表中的下一首歌曲
- **触发方式**:
  - 键盘上的专用媒体下一曲键
  - macOS: Fn + F12（部分键盘）
  - Windows: 专用媒体键或 Fn 组合键

---

## 💻 平台差异

### macOS
- 使用 CGO 调用 Carbon/Cocoa 框架监听系统媒体键
- 支持所有带有媒体控制键的 Mac 键盘
- 无需辅助功能权限

### Windows
- 使用 CGO 调用 Win32 API 注册全局热键
- 支持标准多媒体键盘
- 后台轮询消息队列处理热键事件

---

## 🔧 技术实现

### 架构设计
```
┌─────────────────┐
│  MediaKeyService │
│   (统一接口)     │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼───┐ ┌──▼──────┐
│macOS  │ │Windows  │
│实现   │ │实现     │
└───────┘ └─────────┘
```

### 核心代码
- **服务层**: `backend/mediakeyservice.go` - 跨平台抽象接口
- **macOS**: `backend/mediakeyservice_darwin.go` - Carbon 框架实现
- **Windows**: `backend/mediakeyservice_windows.go` - Win32 API 实现
- **菜单绑定**: `main.go` - MenuItem.SetAccelerator() 绑定

---

## ⚠️ 注意事项

1. **焦点要求**: 
   - 应用窗口必须处于前台或获得焦点
   - 系统媒体键为全局热键，但 Wails v3 当前实现需要应用活跃

2. **键盘兼容性**:
   - 需要物理媒体键或 Fn 组合键支持
   - 普通键盘若无媒体键，需使用系统虚拟键盘或第三方工具

3. **Wails v3 限制**:
   - 当前为 Alpha 版本，部分功能可能不稳定
   - 暂不支持纯全局快捷键（后台运行时）

---

## 🎯 使用建议

1. **测试方法**:
   ```bash
   # 启动开发服务器
   wails3 dev
   ```
   使用键盘媒体键测试播放控制

2. **故障排查**:
   - 检查后端日志确认媒体键注册成功
   - 验证键盘是否支持媒体键
   - 确保应用窗口获得焦点

3. **未来优化**:
   - 等待 Wails v3 正式版支持全局快捷键
   - 可考虑自行实现原生桥接以支持后台运行

---

## 📝 更新日志

- ✅ 播放/暂停：绑定 `MediaPlayPause`
- ✅ 上一曲：绑定 `MediaPrevTrack`
- ✅ 下一曲：绑定 `MediaNextTrack`
- ✅ macOS 完整支持（Carbon 框架）
- ✅ Windows 完整支持（Win32 API）