Every command is one line in, and the exit code is the truth: 0 it happened, 1 nothing is
playing, 2 the player ignored it, 64 bad arguments, 78 bad config — the same 0 behind the
dialect names, nowplaying-cli and media-control.
| Asked | Run |
|---|---|
| what is playing, where am I, how much is left | nowplayingseek status --json — position and duration in seconds, playing, app |
the same on one line, for read, sed and logs |
nowplayingseek status --minify |
| everything macOS knows about the item | nowplayingseek status --raw — chapters, media type, artwork size, the file's URL |
| pause and learn where it stopped, in one call | nowplayingseek pause --json |
| go back a minute | nowplayingseek backward 60 |
| jump to 12:30 | nowplayingseek seek 12:30 |
| pause, resume, next | nowplayingseek pause, play, next |
| can this Mac be driven at all | nowplayingseek doctor |
| the cover art, as a file | nowplayingseek artwork — prints where it wrote it |
| follow every change, for a status bar | nowplayingseek stream --no-artwork — below |
The three flags work on every command that reads or moves the player: seek 12:30 --json,
forward --minify, position --json, doctor --json, config --json. --json is indented in a
pipe as in a terminal; only a terminal gets colour. The human object at the end repeats
position, duration, timestamp and app in words — parse with jq, or take --minify and
the first match. The order of flags does not matter; --raw with --json is --raw.
A terminal gets a painted status line; a pipe, a file or a hotkey daemon gets the plain one,
▶ 30:57 / 3:15:50 Title (bundle.id), and that one does not change.
Only the elected app can be addressed. When status shows the wrong one,
do not retry — tell the person to press play there instead.
nowplayingseek stream stays and reports what happens: a play, a pause, a seek, a new item. A
terminal gets a log in words. A pipe gets JSON, one object a line, in the protocol of
media-control, so a status bar written for it reads this
unchanged. The first line has an empty payload, the next one the item whole, and after that only
the keys that changed; --no-diff sends the item whole every time.
nowplayingseek stream --no-artwork | jq --unbuffered -c '.payload'elapsedTimeis the position attimestamp, not now: whileplaying, add the seconds since.--no-artworkdrops the cover, several hundred kilobytes of base64 with every new item.--debounce=200holds a burst of seeks back to one line; a play or a pause comes at once.--microsgives the times in whole microseconds, withMicrosin their keys.- It looks every 0.2 s, so a change arrives a fraction of a second late. It ends when its reader
does:
stream | head -2returns.
