{"id":51129729,"url":"https://github.com/apakchan/fn-music-pause","last_synced_at":"2026-06-25T11:01:20.314Z","repository":{"id":366165778,"uuid":"1270239597","full_name":"apakchan/fn-music-pause","owner":"apakchan","description":"Pause media while holding Fn, resume when released. A small Hammerspoon utility for macOS voice-input workflows.","archived":false,"fork":false,"pushed_at":"2026-06-20T14:24:38.000Z","size":41,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T16:09:28.507Z","etag":null,"topics":["hammerspoon","macos","media-control","voice-input"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apakchan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-15T14:16:45.000Z","updated_at":"2026-06-20T14:24:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/apakchan/fn-music-pause","commit_stats":null,"previous_names":["apakchan/fn-music-pause"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/apakchan/fn-music-pause","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apakchan%2Ffn-music-pause","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apakchan%2Ffn-music-pause/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apakchan%2Ffn-music-pause/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apakchan%2Ffn-music-pause/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apakchan","download_url":"https://codeload.github.com/apakchan/fn-music-pause/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apakchan%2Ffn-music-pause/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34771664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hammerspoon","macos","media-control","voice-input"],"created_at":"2026-06-25T11:01:14.360Z","updated_at":"2026-06-25T11:01:20.291Z","avatar_url":"https://github.com/apakchan.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fn-music-pause\n\nPause media while holding `Fn`, resume when you release it.\n\nThis is a small [Hammerspoon](https://www.hammerspoon.org/) utility for macOS voice-input workflows. It was built for cases where you hold `Fn` to speak, but background music keeps playing while you are talking.\n\n## How It Works\n\nBy default, `fn-music-pause` listens for macOS `Fn` flag changes:\n\n- Short `Fn` tap: do nothing, so input methods and system shortcuts can use it normally.\n- Hold `Fn` for at least `0.15` seconds: check supported media apps and browser tabs across open browser windows; pause only if something is currently playing.\n- `Fn` up after a hold-triggered pause: resume only the source or browser tabs that were paused.\n\nIf the current source is already paused or stopped, pressing `Fn` leaves it paused.\nIf multiple browser tabs are playing at once, the playing tabs are paused together; already-paused tabs stay paused.\nFor Chromium browsers, audible tab indicators are checked first so the script only touches tabs that are currently playing audio.\nWhen the frontmost app does not pause anything, remaining supported apps are checked concurrently instead of one by one.\n\nThe listener does not swallow the `Fn` event, so your voice input method can still receive it.\n\n## Requirements\n\n- macOS\n- Hammerspoon\n- Hammerspoon Accessibility permission in macOS System Settings\n- The `hs` CLI is optional for tests, but useful:\n\n```lua\nhs.ipc.cliInstall()\n```\n\n## Install\n\nClone the repo and run:\n\n```bash\n./install.sh\n```\n\nThen open or reload Hammerspoon.\n\nThe installer copies the Lua modules into `~/.hammerspoon`. If `~/.hammerspoon/init.lua` already exists, it creates a timestamped backup before appending:\n\n```lua\nrequire(\"fn_music_pause\")\n```\n\n## Manual Install\n\nCopy these files into `~/.hammerspoon`:\n\n```text\nhammerspoon/fn_music_pause.lua\nhammerspoon/fn_music_pause_core.lua\nhammerspoon/fn_music_pause_player.lua\n```\n\nThen add this to `~/.hammerspoon/init.lua`:\n\n```lua\nrequire(\"fn_music_pause\")\n```\n\nReload Hammerspoon.\n\n## Configuration\n\nOptional configuration can be set before `require(\"fn_music_pause\")`:\n\n```lua\nfnMusicPauseConfig = {\n  mode = \"app\",\n  holdDelay = 0.15,\n  appleScriptTimeout = 1.0,\n  appleScriptConcurrency = 4,\n  browserTabChunkSize = 4,\n  alert = true,\n  log = true,\n}\n\nrequire(\"fn_music_pause\")\n```\n\nOptions:\n\n- `mode = \"app\"`: default. Uses app-specific AppleScript control for Spotify, Apple Music, Safari, Google Chrome, Brave Browser, Microsoft Edge, and Arc.\n- `mode = \"mediaKey\"`: compatibility mode. Uses the system Play/Pause media key as a toggle.\n- `holdDelay = 0.15`: seconds to hold `Fn` before media pause starts. Raise it, for example to `0.2`, if normal short taps trigger media pausing too often.\n- `appleScriptTimeout = 1.0`: maximum seconds to wait for one AppleScript media-control call before skipping it, so an unresponsive browser cannot freeze Hammerspoon indefinitely.\n- `appleScriptConcurrency = 4`: maximum concurrent AppleScript jobs for app and browser-tab checks.\n- `browserTabChunkSize = 4`: number of browser tabs checked by one tab-level AppleScript job when audible-tab detection is unavailable.\n- `mediaKeyFallback = true`: when `mode = \"app\"`, fall back to the media key only if no supported app is running.\n- `alert = false`: disable the Hammerspoon startup alert.\n- `log = false`: disable `~/.hammerspoon/fn-music-pause.log`.\n- `logPath = \"/path/to/log\"`: use a custom log path.\n- `autoStart = false`: load the module without starting the listener.\n\n## Known Limitations\n\nThe default `app` mode only controls supported apps. Browser support targets media elements across open tabs, and depends on AppleScript/Automation permissions. Safari may also require enabling \"Allow JavaScript from Apple Events\" in the Develop menu.\n\nWhen Chromium browsers do not allow JavaScript from Apple Events, `fn-music-pause` falls back to audible tab indicators in the browser tab strip and sends media keys only to tabs that were reported as playing audio.\n\nThe `mediaKey` mode is intentionally simple and low-latency, but it is a toggle. If the current media source is paused, pressing `Fn` can start playback. Use it only when you explicitly want the old media-key behavior.\n\n## Test\n\nWith Hammerspoon running and the `hs` CLI installed:\n\n```bash\n./scripts/run-tests.sh\n```\n\nExpected output:\n\n```text\nfn_music_pause_core_test: ok\nfn_music_pause_player_test: ok\nfn_music_pause_test: ok\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapakchan%2Ffn-music-pause","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapakchan%2Ffn-music-pause","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapakchan%2Ffn-music-pause/lists"}