I like a computer that obeys keys. My dotfiles are mostly that: a Hyper key, layers, a shortcut for everything I do twice. Media had its keys too — play, pause, next — and one day I added the two that were missing, rewind and fast forward. macOS has such signals; a keyboard can send them.
They were a disappointment. They give neither a position nor a step of your choosing, and every player takes them in its own way. There was no "ten seconds back", the one thing I wanted when I missed a line in a film or a punch in a fight. A player's own arrow keys do it — while its window is in front, and every player in its own way.
So I wanted to do the seeking myself: read where the player is, add ten seconds, tell it to go there. macOS knows all of that — it is the thing in the Control Center widget — and keeps it behind a private door. I tried the tools that open it. One had been broken by macOS 15.4 and stayed so for a year; mended, it still would not move by a step. Nor would the other.
Then a friend bought a keyboard with a knob. Out of the box the knob is volume. He wanted it to wind the video he was watching, in whatever app, like the jog wheel of an editing desk — slowly to find a word, with a flick to cross a scene. There was nothing to bind it to.
That was reason enough. This tool is the command behind those keys and that knob: it seeks what plays by the step you ask for, from anywhere — see Hotkeys. The rest of this page is what it took.
Since macOS 15.4 mediaremoted answers Now Playing reads only to processes whose code-signing
identifier starts with com.apple. (or that hold Apple's private entitlement). Your own compiled
binary gets an empty dictionary and no error. /usr/bin/osascript qualifies, so the whole tool is JavaScript
for Automation that loads the private MediaRemote.framework inside it. That is the same
loophole ungive/mediaremote-adapter
uses through /usr/bin/perl, minus the helper framework and at about half the latency
(about 50 ms for a whole run) — except for artwork, which needs perl too; see
Artwork. A compiled binary can read too — but only if it is signed with an
identifier that begins com.apple., which is posing as Apple: nothing one can ship, and the first
thing a stricter check would stop. The interpreters Apple ships would survive that check.
Three things the API does not tell you:
ElapsedTimeis a snapshot taken atTimestamp, not the position. The live position iselapsed + rate × (now − timestamp).- There is no relative seek.
forward/backwardread, add, and seek to an absolute time. Now Playing refreshes 50–150 ms after a seek in IINA, about 0.6 s in VLC, over a second when a page buffers — so consecutive presses build on the previous target until it catches up. MRMediaRemoteSendCommandreturnstrueimmediately and delivers asynchronously; a process that exits right away never sends the command. The tool polls for the effect.
A key held down is two processes, because hotkey tools run a command once per press: --hold
on the key down keeps stepping, release on the key up tells it to stop through a file in the
temporary directory — one file per direction, which the hold only reads, so a release cannot be
overwritten and lost. A newer --hold takes over from an older one through a file of its own.
On a quick tap the release can get there first; the --hold sees a release newer than itself
and makes its one step.
The one call that carries ArtworkData, MRMediaRemoteGetNowPlayingInfo(queue, block), wants a
real Objective-C block — compiled code, not a script; what was tried from inside osascript
instead, and measured to fail, is in Dead ends below. native/artwork.m is that compiled
code: built by clang — on your Mac when Homebrew installs, in CI for the
release tarball — and loaded, not run, by
/usr/bin/perl through DynaLoader::dl_load_file, the way
ungive/mediaremote-adapter (BSD-3-Clause) loads
its own framework. src/core/system/artwork.js is the rest: one function, artwork only,
no argv parsing or XS boilerplate — nps_get_artwork is a plain zero-argument C function, which
works as a Perl XSUB because dl_install_xsub calls it with arguments it simply never reads.
This is not the dylib osascript refused (Dead ends below): that binary was mapped into
osascript itself, which is arm64e and only maps arm64e code back. Perl is plain arm64 and maps a
plain arm64 bundle same as it always could, and perl — like osascript — is signed com.apple.perl,
which is what macOS 15.4's Now Playing gate actually checks: the signature of the process asking,
not of every image mapped into it. The bundle itself is signed to no one: codesign shows
adhoc,linker-signed, built on the spot or taken from the tarball.
- It drives the app macOS elected as Now Playing — the one in the Control Center widget — and nothing else. macOS elects the app that started playback most recently and keeps it elected for minutes after it pauses, even while another app is audibly playing. So after a voice message in a messenger, the hotkeys drive the paused messenger, not the video you are watching. Press play in the app you mean and it is elected again.
- There is no way around that from outside.
MRMediaRemoteSendCommandToPlayer,…ToApp,…ToClientandMRNowPlayingRequestall accept a target, and for an unentitled callermediaremotedsilently redirects every one of them to the elected app; only Apple's own Music is addressed as asked (measured on macOS 26.6). - Seeking needs the player's cooperation. YouTube in Chromium browsers, IINA and VLC work. A
web page without a MediaSession
seektohandler swallows the call; you get exit 2. - Private API. Apple can close this door in any update. Which builds were run is on the
compatibility page;
nowplayingseek doctor, while something is playing, answers for this Mac. - No artwork bytes from
osascriptalone: the cover comes through/usr/bin/perl, as Artwork tells. What was tried insideosascriptis in Dead ends. - No hotkeys of its own. Bind the command with Karabiner-Elements, Raycast, Hammerspoon or Shortcuts — Hotkeys. A helper that caught keys itself was built and dropped; why is in Dead ends.
- No Mac App Store. Its review is public-API only, and this tool loads the private
MediaRemote.framework. It ships through Homebrew and the release tarball.
Measured 2026-09-18 on macOS 26.6 unless an entry says otherwise; do not retry.
- Addressing a non-elected player. Five routes (
MRNowPlayingRequest initWithPlayerPath:,MRMediaRemoteSendCommandToPlayerwith a plain and with a resolvedMRPlayerPath,…SendCommandToApp,…SendCommandToClient), all through perl + a compiled arm64e helper because JXA cannot pass blocks. A seek addressed to Vivaldi or IINA landed on the elected Music every time; only Music itself is addressed as asked. vorssaint-utils documents the same: "The service may redirect unprivileged requests to the global player." MRMediaRemoteSetOverriddenNowPlayingApplication/…SetNowPlayingApplicationOverrideEnabled. Never call them. They elect nobody and leavemediaremotedwith no elected app at all — playback starting in other apps no longer elects them, and turning the override off does not help. The only fix wassudo killall mediaremoted.- Chapters.
MRMediaRemoteCommandNextChapter/PreviousChapter(100, 101) are delivered and IINA ignores them: it registers no chapter handler with the system.ChapterNumberandTotalChapterCountcan be read; chapter times cannot. Moving by chapter needs a driver for the player, which this project has ruled out. - Artwork bytes from inside
osascript.MRNowPlayingRequest.localNowPlayingItem.nowPlayingInfo— the dictionary--rawprints — carriesArtworkDataHeight,ArtworkDataWidth,ArtworkIdentifierandArtworkMIMEType, neverArtworkData; the item's ownartworkaccessor reads nil and itsmetadataobject has noartworkselector to fall back to (checked on a browser tab's Now Playing item, macOS 26.6.2).ObjC.bindFunctiontakesidfor the block argument ofMRMediaRemoteGetNowPlayingInfo(queue, block)but builds no block from a plain JS function — passing one behaved exactly like passing an explicit$()(nil): the call returns at once, no exception, and the handler never runs even after two seconds spun onNSRunLoop.currentRunLoop. Reading a class's full method table to look for another synchronous accessor hits the same wall as the dylib dead end below:class_copyMethodListreturns an opaque array JXA cannot index without pointer arithmetic. Artwork above is how the bytes are gotten instead. - Hotkeys of our own (2026-09-20). A
setupcommand that bound a key itself, through a small Swift helper using Carbon'sRegisterEventHotKey(the one hotkey API that needs no Accessibility or Input Monitoring permission), was built and then dropped: on macOS 26.6 the helper never received a single press. Registration returnsnoErrfor every keycode — including combinations other apps already hold, soeventHotKeyExistsErrcannot be used to detect a clash either — and the handler installed onGetEventDispatcherTarget()is simply never called from aCFRunLoopRun()process, whether it is a bare binary, aTransformProcessTypeUIElement, or a signed.appbundle launched withopen. Hammerspoon, bound to the same combination on the same machine at the same moment, fired every time. The likely difference is the event loop — Carbon events reach a process throughNSApplication, not a plain run loop — but the fix was not worth a helper binary in a tool that has none: people already bind keys with Karabiner-Elements, Raycast, Hammerspoon or Shortcuts, and docs/hotkeys.md covers those. - A helper dylib inside
osascript. Refused: "mapping process is a platform binary, but mapped file is not". perl, ruby and python load a plain arm64 one; it isosascriptthat wants arm64e.
The tool therefore drives the elected app and only that. This is a decision, not a gap.
