YamKeys

🌐 English | Русский

A lightweight, native macOS menu bar daemon for controlling Yandex Music via function keys.

---

Overview

YamKeys is a background daemon designed for macOS that binds function keys F7, F8, and F9 directly to the official Yandex Music desktop application (ru.yandex.desktop.music). It intercepts physical key events at the HID layer to provide seamless playback control while preventing macOS from launching default media players such as Apple Music.

┌─────────────────────────────────────────────────────────┐
│                      YamKeys Daemon                     │
├─────────────┬───────────────────────────────────────────┤
│  Key Press  │ Action                                    │
├─────────────┼───────────────────────────────────────────┤
│     F7      │ Previous Track                            │
│     F8      │ Play / Pause (or launch app if closed)    │
│     F9      │ Next Track                                │
└─────────────┴───────────────────────────────────────────┘

---

Key Features

• Direct Application Control: Targets the native Yandex Music desktop application process without interfering with browser media.
• Smart App Dispatching: Pressing F8 when Yandex Music is closed automatically launches the application; when running, it toggles playback state.
• System Event Interception: Captures function key presses via CGEventTap to override default system media behaviors.
• Native Menu Bar Interface: Operates in accessory mode (LSUIElement = true) with a template status icon that adapts to macOS light and dark themes.
• Thread-Safe Architecture: Uses os_unfair_lock for thread safety without introducing input latency or high CPU usage.

---

Technical Architecture

File	Purpose
main.swift	Application entry point and permission polling lifecycle.
StatusBarController.swift	Status bar item, menu construction, and system event handlers.
EventTapListener.swift	Thread-safe low-level CGEventTap keyboard event listener.
YandexMusicController.swift	Process detection and media key dispatching for Yandex Music.
PermissionManager.swift	macOS TCC Accessibility authorization management.
Localization.swift	Native system language detection and UI string localization.

---

Installation & Building

Requirements

• macOS 11.0 Big Sur or later
• Accessibility (TCC) permission granted

Building from Source

# Clone the repository
git clone https://github.com/Fuheshka/YamKeys.git
cd YamKeys

# Build release binary and package installer
./scripts/package-release.sh

The build script compiles the release binary via SwiftPM, applies a code signature with a stable designated identifier, and produces YamKeys.app, YamKeys-v1.0.0.dmg, and YamKeys-v1.0.0.zip inside the dist/ directory.

---

License

This project is licensed under the terms of the MIT License. See the LICENSE file for details.