机械键盘音效应用

一个轻量级的 macOS 原生应用程序，为任何键盘提供机械键盘音效。

功能特性

• 🎵 实时音效: 为每次按键提供即时的机械键盘音效
• 🔧 多种音效包: 支持 Cherry MX Blue、Brown、Red 等多种机械轴音效
• ⚡ 轻量级: 应用体积小于 10MB，内存占用低于 50MB
• 🔒 隐私保护: 仅监听键盘事件，不记录任何按键内容
• 🎛️ 简洁界面: 只有音效开关和音效选择两个控件
• 🚀 原生性能: 使用 Swift 和 SwiftUI 构建，启动时间小于 0.5 秒

系统要求

• macOS 13.0 或更高版本
• 辅助功能权限（用于全局键盘监听）

安装和使用

1. 构建应用程序

# 克隆项目
git clone <repository-url>
cd MechanicalKeyboardSound

# 使用 Xcode 打开项目
open MechanicalKeyboardSound.xcodeproj

# 在 Xcode 中构建并运行
# 或使用命令行构建
xcodebuild -project MechanicalKeyboardSound.xcodeproj -scheme MechanicalKeyboardSound -configuration Release build

2. 授予权限

首次运行时，应用程序会请求辅助功能权限：

1. 点击"请求权限"按钮
2. 在系统对话框中点击"打开系统偏好设置"
3. 在"隐私与安全性" > "辅助功能"中勾选应用程序
4. 重新启动应用程序

3. 开始使用

1. 确保"启用音效"开关已打开
2. 选择喜欢的音效包
3. 点击"开始监听"
4. 开始打字享受机械键盘音效！

开发指南

项目结构

MechanicalKeyboardSound/
├── Core/                          # 核心业务逻辑
│   ├── Models.swift              # 数据模型
│   ├── GlobalKeyboardMonitor.swift  # 全局键盘监听
│   ├── AudioEngine.swift        # 音频引擎
│   ├── PermissionManager.swift   # 权限管理
│   └── SettingsManager.swift     # 设置管理
├── UI/                           # 用户界面（预留）
├── Resources/                    # 资源文件
│   └── Assets.xcassets          # 图标和颜色资源
├── MechanicalKeyboardSoundApp.swift  # 主应用程序
├── ContentView.swift            # 主界面视图
└── Info.plist                   # 应用程序配置

核心组件

GlobalKeyboardMonitor

• 使用 CGEvent API 监听全局键盘事件
• 支持键盘按下和释放事件
• 自动处理权限检查

AudioEngine

• 基于 AVAudioEngine 的音频播放系统
• 支持多音效包管理
• 低延迟音效播放

PermissionManager

• 辅助功能权限检查和请求
• 系统偏好设置自动打开
• 登录项管理

SettingsManager

• 设置的持久化存储
• 实时设置变更通知
• 设置导入/导出功能

调试

1. 在 Xcode 中调试:

   # 打开项目
   open MechanicalKeyboardSound.xcodeproj
   
   # 在 Xcode 中按 Cmd+R 运行

2. 查看日志:

   • 在 Xcode 控制台查看应用程序日志
   • 或在终端中查看系统日志：

   log stream --predicate 'subsystem contains "MechanicalKeyboardSound"'

3. 权限问题调试:

   • 检查"系统偏好设置" > "隐私与安全性" > "辅助功能"
   • 确保应用程序已被勾选

打包和分发

开发版本打包

# 构建 Release 版本
xcodebuild -project MechanicalKeyboardSound.xcodeproj \
           -scheme MechanicalKeyboardSound \
           -configuration Release \
           -derivedDataPath ./build \
           build

# 应用程序位于
./build/Build/Products/Release/MechanicalKeyboardSound.app

创建分发包

# 创建 DMG 文件（需要安装 create-dmg）
brew install create-dmg

create-dmg \
  --volname "机械键盘音效" \
  --window-pos 200 120 \
  --window-size 600 300 \
  --icon-size 100 \
  --icon "MechanicalKeyboardSound.app" 175 120 \
  --hide-extension "MechanicalKeyboardSound.app" \
  --app-drop-link 425 120 \
  "MechanicalKeyboardSound.dmg" \
  "./build/Build/Products/Release/"

无签名分发

由于应用程序设计为无需代码签名运行：

1. 用户首次运行时会看到 Gatekeeper 警告
2. 右键点击应用程序，选择"打开"
3. 在对话框中点击"打开"确认

性能指标

• 应用体积: ~3-8MB
• 内存使用: ~20-50MB
• CPU 使用: 空闲时 <1%
• 音频延迟: <10ms
• 启动时间: <0.5秒

故障排除

常见问题

1. 应用程序无法启动

   • 检查 macOS 版本是否为 13.0 或更高
   • 尝试右键点击应用程序选择"打开"

2. 没有声音

   • 检查音效开关是否已启用
   • 检查系统音量设置
   • 确保系统未静音

3. 键盘监听不工作

   • 检查辅助功能权限是否已授予
   • 重新启动应用程序
   • 在系统偏好设置中重新勾选权限

4. 应用程序崩溃

   • 查看 Xcode 控制台或系统日志
   • 检查是否有权限问题
   • 重置应用程序设置

获取帮助

如果遇到问题，请：

1. 查看应用程序日志
2. 检查系统权限设置
3. 尝试重新安装应用程序
4. 提交 Issue 并附上详细的错误信息

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献

欢迎提交 Pull Request 和 Issue！

更新日志

v1.0.0

• 初始版本发布
• 支持 3 种机械键盘音效包
• 全局键盘监听功能
• 简洁的用户界面