Targeted Application Pairing System w/ Hotkey Oriented Playback

Taps on your keyboard converted to efficient window hopping.

---

What It Does

1. Window pairing slots (1-9) so one hotkey can jump back to a specific app window.
2. Context-aware pair/focus/minimize flow:
   • First press pairs current window to slot.
   • Later press on same slot focuses paired window.
   • Double-tap while already focused to minimize (configurable).
3. Global media-style controls:
   • YouTube seek/play targeting browser tabs by window title.
   • Spotify transport/seek/volume controls.

---

Windows — AutoHotkey v2

Running with AHK Installation

1. Install AutoHotkey v2.0
2. Run TAPSHOP-windows/TAPSHOP.ahk

Running without AHK Installation

This repository ships source scripts. If you want a standalone .exe, compile TAPSHOP-windows/TAPSHOP.ahk with AutoHotkey v2's compiler (Ahk2Exe).

Tip

• Place script ahk/exe (or shortcut) in %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup to autorun on startup.
• Applications running at admin level will ignore script functions, which can be fixed by also running the script ahk/exe as admin.

Warning

• Setting the run as admin flag on with the script in the Startup folder (as shown below) will NOT autorun the script on startup.
• To allow this script to autorun at admin level on startup, use the native Windows Task Scheduler to bypass the UAC prompt requirement needed for script execution permission.

Hotkey Bindings (Windows)

Windows: Refer to AHK's Hotkeys & List of Keys documentation for modifiers & keycodes.

Hotkey	Action
Win + [1-9]	Pair/focus/minimize slot [1-9]
Ctrl + Win + [1-9]	Unpair slot [1-9]
Ctrl + Win + 0	Unpair all slots
`Win + ``	Show active window stats
`Ctrl + Win + ``	Toggle TAPSHOP GUI
F19 / Ctrl + F19	YouTube rewind 5s / 10s
F20	YouTube play/pause
F21 / Ctrl + F21	YouTube forward 5s / 10s
Media_Prev / Media_Play_Pause / Media_Next	Spotify previous/play-pause/next
Ctrl + Media_Prev / Ctrl + Media_Next	Spotify seek backward/forward
F22	Spotify like/unlike
F23 / F24	Spotify volume down/up
Ctrl + F22 / Ctrl + F23 / Ctrl + F24	System mute / volume down / volume up

---

macOS — Hammerspoon

Setup

1. Install Hammerspoon
2. Copy or symlink TAPSHOP-macos/TAPSHOP.lua into your ~/.hammerspoon/ directory
3. Add require("TAPSHOP") to your ~/.hammerspoon/init.lua
4. Reload Hammerspoon config (⌘ + ⇧ + R from menu bar, or hs.reload())

TAPSHOP stores its macOS files under ~/.hammerspoon/tapshop/:

• settings.json for user-facing preferences and hotkey overrides
• appdata.json for internal persisted state such as pairings and window geometry

Required Permissions (macOS)

1. Grant Hammerspoon Accessibility access in System Settings -> Privacy & Security -> Accessibility.
2. If prompted during Spotify actions, allow Apple Events/Automation permissions for Hammerspoon.

Hotkey Bindings (macOS)

macOS: Refer to Hammerspoon's hs.hotkey documentation.

macOS (TAPSHOP-macos/TAPSHOP.lua)

Hotkey	Action
Cmd + Option + [1-9]	Pair/focus/minimize slot [1-9]
Cmd + Option + Shift + [1-9]	Unpair slot [1-9]
Cmd + Option + Shift + 0	Unpair all slots
`Cmd + Option + ``	Toggle popover UI
Cmd + Option + Left/J	YouTube rewind 5s / 10s
Cmd + Option + Right/L	YouTube forward 5s / 10s
Cmd + Option + K	YouTube play/pause
F19/F20/F21 (+ Ctrl variants)	Optional YouTube bindings (if key exists)
F7/F8/F9 (+ Ctrl variants)	Optional Spotify media + seek bindings
F22/F23/F24	Optional Spotify like + volume bindings
Cmd + Option + Ctrl + ,/. / M	System volume down/up/mute

Hotkeys can be remapped from the popover settings:

1. Press `Cmd + Option + `` to open the popover
2. Click the cog icon in the header
3. Use the General or Hotkeys tab

If you remap the popover shortcut away from `Cmd + Option + ``, TAPSHOP keeps a hidden recovery path: press the default shortcut three times quickly to show the popover.

---

Behavior Notes

• YouTube targeting is title-based and browser-filtered. Expected title pattern includes - YouTube; Subscriptions - YouTube is intentionally ignored.
• Slot minimize behavior is threshold-based (minimizeThreshold), not immediate on first repeat press.
• On macOS, slot pairings persist across Hammerspoon reloads/restarts. Closed paired windows can remain recoverable and relink automatically when a matching window returns, depending on settings.
• On Windows, Spotify transport is sent using WM_APPCOMMAND; on macOS it uses Hammerspoon Spotify APIs + AppleScript helpers.

---

Troubleshooting

• YouTube commands do nothing:
  • Ensure a supported browser window title currently matches a YouTube watch page.
  • Open a video tab once to refresh target detection.
• Pairing hotkeys do nothing on Windows:
  • Check if target app is elevated (run TAPSHOP as admin too).
• macOS hotkeys not firing:
  • Confirm Hammerspoon Accessibility permission is enabled.
  • Some optional F-key bindings are only registered if that key exists in hs.keycodes.map.
  • If you remapped the popover toggle and forgot it, press `Cmd + Option + `` three times quickly to reopen the popover.
• Spotify actions fail on macOS:
  • Open Spotify at least once and allow Automation prompts for Hammerspoon.

---

Repository Layout

Path	Purpose
TAPSHOP-windows/TAPSHOP.ahk	Main Windows implementation (AHK v2)
TAPSHOP-macos/TAPSHOP.lua	Main macOS implementation (Hammerspoon)
GYTP-AHKv2-media-keys	Legacy media-key-focused script
GYTP-AHKv2-keyboard-75	Legacy 75% keyboard variant
GYTP-AHKv1.1-deprecated	Legacy AHK v1.1 script

---

Legacy Versions

The original single-purpose scripts are preserved in their respective folders:

Folder	Description
GYTP-AHKv2-media-keys	AHK v2 — media key hotkeys (original)
GYTP-AHKv2-keyboard-75	AHK v2 — QMK 75% keyboard variant (details)
GYTP-AHKv1.1-deprecated	AHK v1.1 — deprecated

---

License

This project's scripts are provided under the MIT license.

Windows (AHK): The AutoHotkey interpreter is under the GPL-2.0 license. This applies to compiled builds (.exe) because they bundle the AHK script and interpreter. For most users or developers this is not a practical concern, as GPL-2.0 is permissive.

macOS (Hammerspoon/Lua): The macOS stack relies on Hammerspoon (MIT) and Lua (MIT). If you distribute software that includes or depends on them, you must retain their copyright notices and the full MIT license text for each. Hammerspoon’s license is in its repository; Lua’s license is at lua.org/license.html.