A command-line tool for macOS. It seeks whatever is playing.
Five seconds back. Five seconds forward. From a key, with any app in front: a browser tab, IINA, VLC, Music, Spotify. A keyboard with a knob turns into a jog wheel: flick it past the ad in a video, wind back over a line you missed.
macOS has no such key. This is the command behind it.
I tune my computer with hotkeys — my dotfiles are mostly that. I gave the rewind and fast-forward signals a key each. They were no pleasure: no step of my choosing, and every player took them in its own way. I tried what there was, to do the seeking myself; none did.
Then a friend bought a keyboard with a knob and wanted it to wind whatever he was watching. So I made this. The longer story.
brew install servitola/tap/nowplayingseekIt comes through Homebrew; if brew is not on this Mac yet, the one line on its front page puts it there.
One script, also installed as nps. No dependencies. It runs on osascript, which is already there.
Homebrew 7 wants third-party taps trusted: the full name above trusts this one formula, no more. No Homebrew? Download the release tarball instead.
Give forward and backward a key each, through an app that catches it. Two such apps:
 |
 |
|---|---|
| Shortcuts — the app every Mac already has, nothing else to install. A press moves by the step you wrote. | Karabiner-Elements — free, for those who remap keys. Hold the key: it moves off in small steps, gathers pace, settles. Release, and it stops. |
| Step by step → | The rule to import → |
Hammerspoon, skhd, a Stream Deck, a foot pedal: anything that runs a command.
 |
A keyboard with a knob has a jog wheel. Turned slowly, it moves by seconds. Flicked, by minutes. The Karabiner-Elements rule → |
| Command | |
|---|---|
forward [time], backward [time] |
by a step, 5 s unless told otherwise |
forward --knob, backward --knob |
one click of a keyboard knob: 5 s, longer the faster it spins |
status |
title, app, position / duration |
watch |
stays: where it is, second by second, and what happens to it |
stream |
stays: every change as it happens; JSON lines in a pipe, for scripts |
position, duration |
seconds |
seek <time> |
to 754, 12:34 or 1:02:03 |
toggle, play, pause, next, previous |
transport |
doctor |
exit 0 when Now Playing is readable |
artwork [path] |
the cover art, to a file |
config, config set <setting> <value> |
the settings in effect; change one |
--json, --minify, --raw |
on any of the above: the answer as JSON, as JSON on one line, as the keys macOS itself holds |
Every command answers with where things stand. A seek returns when the player has moved, not before.
Exit 0: done. 1: nothing is playing. 2: the player did not listen.
Every command and flag, the ones for hotkeys included: nps --help.
- It drives the one app macOS elected as Now Playing, the one in Control Center. To choose another, press play there.
- A web page must know how to seek. YouTube does. A page that does not: exit 2.
- It stands on a private API. Apple may close it in any update. Which builds work: compatibility.
- Hotkeys and pedals — Shortcuts, Karabiner-Elements, Hammerspoon, skhd: a key, a hold.
- A keyboard knob — the Karabiner-Elements rule that makes it a jog wheel, step by step.
- The curve, the knob, the config file — how a held key gathers pace, and every number that can be changed.
- For scripts and AI agents — one line in, JSON out, and an exit code that is the truth.
- Moving over — from nowplaying-cli, media-control, playerctl, mpc, shpotify: the same words work.
- Compared with — nowplaying-cli, media-control, a player's own keys.
- Compatibility — which macOS builds it was tested on.
- How it works — why it is a script and not a binary, and why it exists.
- Questions — the ones people type into a search box.
- Development — build, test, lint; the rules.
AGPL-3.0 © servitola. For a commercial licence, open an issue.