upnext-adapter-nowplaying 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,120 @@
+# upnext-adapter-nowplaying
+
+[![npm](https://img.shields.io/npm/v/upnext-adapter-nowplaying)](https://www.npmjs.com/package/upnext-adapter-nowplaying)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/tothienbao6a0/upnext/blob/main/LICENSE)
+
+**Read and control whatever your Mac is playing — including a browser tab —
+without an extension.**
+
+macOS keeps a system-wide Now Playing register: the thing Control Center shows,
+and the thing your keyboard's play/pause key talks to. Anything that publishes
+to it is reachable — a YouTube tab in Chrome, a podcast in Safari, VLC, Doppler,
+Music, Spotify.
+
+```ts
+import { readNowPlaying, sendTransport } from 'upnext-adapter-nowplaying';
+
+await readNowPlaying();
+// { bundleId: 'com.google.Chrome', label: 'Google Chrome', playing: true,
+//   title: 'Acquired — Jensen Huang', artist: 'YouTube',
+//   elapsedMs: 60000, durationMs: 3600000 }
+
+await sendTransport('pause');   // pauses it, whatever it is
+```
+
+That works with no browser extension, no accessibility permission, and no
+per-site integration.
+
+## As a queue entry
+
+The interesting use isn't observation — it's **not interrupting people**.
+
+```ts
+import { Runtime } from 'upnext-core';
+import { NowPlayingAdapter, NOW_PLAYING_URI } from 'upnext-adapter-nowplaying';
+
+const runtime = new Runtime({ adapters: [new NowPlayingAdapter(), ...others] });
+
+runtime.enqueue(NOW_PLAYING_URI);                 // let their podcast finish
+runtime.enqueue({ title: 'Bad Habit' });          // then take over
+
+await runtime.play();
+```
+
+An agent adding to someone's listening instead of cutting across it. When their
+episode ends, the queue moves on by itself.
+
+And if they skip to something else in that tab, the runtime notices and adopts
+it — their choice wins, which is the default everywhere in upnext.
+
+## What it can and cannot do
+
+This adapter answers to exactly one entry, `nowplaying:current`, meaning *the
+thing that is on*. It cannot be handed a track, because there is no way to ask
+the register to start one — so it scores zero for every other locator rather
+than claiming it could.
+
+```ts
+{
+  endOfTrack:      'poll',           // the register does not notify; we sample it
+  position:        'authoritative',  // elapsed comes from the player itself
+  pause:           true,
+  seek:            false,            // the bridge cannot pass seek options cleanly
+  volume:          false,            // the register exposes no volume
+  search:          false,
+  externalControl: true,             // the strongest case in the library
+}
+```
+
+`externalControl` has never meant more than it does here. The runtime is a
+guest: the item was chosen by somebody else, in an app it does not control, and
+it can change underneath at any moment.
+
+`stop()` pauses rather than quitting. The queue moving on is not a reason to
+take somebody's podcast away from them.
+
+## How it works, and the honest caveats
+
+It reaches `MediaRemote`, a **private Apple framework**, through JXA's
+Objective-C bridge. Private API is normally a bad trade, so:
+
+- **There is no public equivalent.** `MPNowPlayingInfoCenter` publishes *your
+  own* app's state. Nothing public reads another app's.
+- **Apple began gating MediaRemote behind an entitlement in macOS 15.4**, which
+  broke the usual command-line tools. The gate applies to processes asking
+  directly; script execution through `osascript` still resolves it. Verified
+  working on **macOS 26.5.2**.
+- **The alternative is worse.** Shipping a helper binary that borrows a system
+  binary's entitlements is a far larger and more fragile dependency than a
+  script you can read in full — and you can: it's in
+  [`src/mediaremote.ts`](./src/mediaremote.ts), about forty lines.
+- **Every failure answers null.** The day Apple closes this, the adapter reports
+  itself unavailable, the registry excludes it, and the rest of your queue
+  carries on.
+
+**macOS only.** On any other platform `init()` fails cleanly and
+`getState().adapters` shows `available: false` with the reason.
+
+### It filters out things that aren't media
+
+macOS's now-playing client is *whatever last made a sound*. A received voice
+message leaves Messages sitting there as the now-playing app, with no title and
+a seven-second "track". Requiring a title and a real duration is what separates
+*something is playing* from *something made a noise once*.
+
+## Compared with the other adapters
+
+| | starts tracks | who chose it | can be changed under you |
+|---|:---:|---|:---:|
+| `upnext-adapter-local` | ✅ | you | no |
+| `upnext-adapter-browser` | ✅ | you | no |
+| `upnext-adapter-spotify` | ✅ | you, mostly | **yes** |
+| **`upnext-adapter-nowplaying`** | ❌ | **somebody else** | **yes** |
+
+This is the far end of the capability spectrum the whole library is built
+around — and a useful proof that the contract stretches that far without
+bending.
+
+---
+
+Full docs: **https://github.com/tothienbao6a0/upnext** · Apache-2.0

package/dist/src/adapter.d.ts

@@ -0,0 +1,61 @@
+import type { Adapter, AdapterReading, Binding, Capabilities, MediaRef } from 'upnext-core';
+import { type NowPlayingReading } from './reading.js';
+/** The one thing this adapter can be asked for. */
+export declare const NOW_PLAYING_URI = "nowplaying:current";
+export interface NowPlayingAdapterOptions {
+    id?: string;
+    /** Injected for tests, and for a host that has its own source of truth. */
+    read?: () => Promise<NowPlayingReading | null>;
+    send?: (command: 'play' | 'pause') => Promise<boolean>;
+}
+/**
+ * Whatever the machine is already playing, as a queue entry.
+ *
+ * Every other adapter is handed a locator and told to play it. This one cannot
+ * be: there is no way to ask macOS's Now Playing register to start a particular
+ * track. What it *can* do is see what some other app is playing — a browser tab,
+ * VLC, anything in Control Center — and work the transport.
+ *
+ * So it answers to exactly one entry, `nowplaying:current`, meaning *the thing
+ * that is on*. That turns out to be worth having:
+ *
+ *   runtime.enqueue('nowplaying:current');   // let their podcast finish
+ *   runtime.enqueue({ title: 'Bad Habit' }); // then take over
+ *
+ * which is an agent adding to someone's listening instead of interrupting it.
+ *
+ * It also sits at the far end of the capability spectrum — further than the
+ * Spotify adapter, which at least starts the tracks it plays. Here the runtime
+ * is a guest: the item was chosen by somebody else, in an app it does not
+ * control, and it can be changed underneath at any moment. `externalControl`
+ * has never meant more than it does here.
+ */
+export declare class NowPlayingAdapter implements Adapter {
+    #private;
+    readonly id: string;
+    readonly capabilities: Capabilities;
+    constructor(options?: NowPlayingAdapterOptions);
+    init(): Promise<void>;
+    /**
+     * Only ever `nowplaying:current`. This adapter cannot be handed a track.
+     *
+     * Scoring anything else above zero would be claiming it could start a file or
+     * a Spotify URI, and it cannot start anything at all.
+     */
+    match(ref: MediaRef): number;
+    resolve(ref: MediaRef): Promise<Binding | null>;
+    /** Nothing to load. Something else already did. */
+    load(binding: Binding): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    /**
+     * Pause, never kill.
+     *
+     * The runtime moving on to its own next entry is not a reason to take
+     * somebody's podcast away from them — and there is no "stop" in this register
+     * anyway, only a transport.
+     */
+    stop(): Promise<void>;
+    poll(): Promise<AdapterReading>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/src/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,OAAO,EACP,YAAY,EACZ,QAAQ,EACT,MAAM,aAAa,CAAC;AAErB,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE5E,mDAAmD;AACnD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAEpD,MAAM,WAAW,wBAAwB;IACvC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAkB,YAAW,OAAO;;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,QAAQ,CAAC,YAAY,EAAE,YAAY,CAcjC;gBAKU,OAAO,GAAE,wBAA6B;IAK5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM;IAItB,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAuBrD,mDAAmD;IAC7C,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC;CAwBtC"}

package/dist/src/adapter.js

@@ -0,0 +1,131 @@
+import { defaultCapabilities } from 'upnext-core';
+import { isAvailable, readNowPlaying, sendTransport } from './mediaremote.js';
+import { hasEnded, readingUri } from './reading.js';
+/** The one thing this adapter can be asked for. */
+export const NOW_PLAYING_URI = 'nowplaying:current';
+/**
+ * Whatever the machine is already playing, as a queue entry.
+ *
+ * Every other adapter is handed a locator and told to play it. This one cannot
+ * be: there is no way to ask macOS's Now Playing register to start a particular
+ * track. What it *can* do is see what some other app is playing — a browser tab,
+ * VLC, anything in Control Center — and work the transport.
+ *
+ * So it answers to exactly one entry, `nowplaying:current`, meaning *the thing
+ * that is on*. That turns out to be worth having:
+ *
+ *   runtime.enqueue('nowplaying:current');   // let their podcast finish
+ *   runtime.enqueue({ title: 'Bad Habit' }); // then take over
+ *
+ * which is an agent adding to someone's listening instead of interrupting it.
+ *
+ * It also sits at the far end of the capability spectrum — further than the
+ * Spotify adapter, which at least starts the tracks it plays. Here the runtime
+ * is a guest: the item was chosen by somebody else, in an app it does not
+ * control, and it can be changed underneath at any moment. `externalControl`
+ * has never meant more than it does here.
+ */
+export class NowPlayingAdapter {
+    id;
+    capabilities = {
+        ...defaultCapabilities,
+        // No notifications from the register; we sample it.
+        endOfTrack: 'poll',
+        // Elapsed time comes from the player itself, not from a clock of ours.
+        position: 'authoritative',
+        pause: true,
+        // The register exposes no volume, and its seek command takes options the
+        // JXA bridge cannot pass cleanly. Declaring either would be a lie.
+        seek: false,
+        volume: false,
+        search: false,
+        // The strongest case in the library: we did not even start this.
+        externalControl: true,
+    };
+    #options;
+    #binding = null;
+    constructor(options = {}) {
+        this.id = options.id ?? 'nowplaying';
+        this.#options = options;
+    }
+    async init() {
+        if (this.#options.read)
+            return; // Injected: nothing to probe.
+        if (!(await isAvailable())) {
+            throw new Error('macOS Now Playing is unavailable here — this adapter needs macOS and the MediaRemote framework');
+        }
+    }
+    /**
+     * Only ever `nowplaying:current`. This adapter cannot be handed a track.
+     *
+     * Scoring anything else above zero would be claiming it could start a file or
+     * a Spotify URI, and it cannot start anything at all.
+     */
+    match(ref) {
+        return ref.uri === NOW_PLAYING_URI ? 1 : 0;
+    }
+    async resolve(ref) {
+        if (this.match(ref) === 0)
+            return null;
+        const reading = await this.#read();
+        // Nothing is playing, so there is nothing to adopt. Failing here is right:
+        // the entry meant "the thing that is on" and there is no such thing.
+        if (!reading)
+            return null;
+        return {
+            adapterId: this.id,
+            // The synthesised locator changes with the track, which is what lets the
+            // runtime notice the person skipping in their browser.
+            nativeUri: readingUri(reading),
+            ref: {
+                ...ref,
+                title: reading.title,
+                artist: reading.artist,
+                durationMs: reading.durationMs,
+                meta: { app: reading.label, bundleId: reading.bundleId },
+            },
+        };
+    }
+    /** Nothing to load. Something else already did. */
+    async load(binding) {
+        this.#binding = binding;
+    }
+    async play() {
+        await this.#send('play');
+    }
+    async pause() {
+        await this.#send('pause');
+    }
+    /**
+     * Pause, never kill.
+     *
+     * The runtime moving on to its own next entry is not a reason to take
+     * somebody's podcast away from them — and there is no "stop" in this register
+     * anyway, only a transport.
+     */
+    async stop() {
+        await this.#send('pause');
+        this.#binding = null;
+    }
+    async poll() {
+        const reading = await this.#read();
+        if (!reading) {
+            // The app went away, or stopped publishing. Whatever we were following is
+            // over as far as anyone can tell from here.
+            return { status: 'ended', nativeUri: null };
+        }
+        return {
+            status: hasEnded(reading) ? 'ended' : reading.playing ? 'playing' : 'paused',
+            positionMs: reading.elapsedMs,
+            durationMs: reading.durationMs,
+            nativeUri: readingUri(reading),
+        };
+    }
+    #read() {
+        return (this.#options.read ?? readNowPlaying)();
+    }
+    #send(command) {
+        return (this.#options.send ?? sendTransport)(command);
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/src/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+export { NowPlayingAdapter, NOW_PLAYING_URI } from './adapter.js';
+export type { NowPlayingAdapterOptions } from './adapter.js';
+export { readNowPlaying, sendTransport, isAvailable, COMMANDS } from './mediaremote.js';
+export type { TransportCommand } from './mediaremote.js';
+export { parseReading, readingUri, hasEnded } from './reading.js';
+export type { NowPlayingReading } from './reading.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACxF,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { NowPlayingAdapter, NOW_PLAYING_URI } from './adapter.js';
+export { readNowPlaying, sendTransport, isAvailable, COMMANDS } from './mediaremote.js';
+export { parseReading, readingUri, hasEnded } from './reading.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGlE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGxF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC"}

package/dist/src/mediaremote.d.ts

@@ -0,0 +1,30 @@
+import { type NowPlayingReading } from './reading.js';
+/**
+ * MediaRemote's command numbers.
+ *
+ * Only the transport is here. The register exposes no volume, and its seek
+ * command takes options this bridge cannot pass cleanly — which is exactly why
+ * the adapter declares `seek: false` and `volume: false` rather than pretending.
+ */
+export declare const COMMANDS: {
+    readonly play: 0;
+    readonly pause: 1;
+    readonly togglePlayPause: 2;
+    readonly next: 4;
+    readonly previous: 5;
+};
+export type TransportCommand = keyof typeof COMMANDS;
+/**
+ * What macOS is playing right now, whichever app is playing it.
+ *
+ * Exported on its own because it is useful without a queue: a host that only
+ * wants to show what is on, or to know whether to duck, needs this and nothing
+ * else. Answers null when nothing is playing, when the reading is not media, or
+ * when the framework is unavailable.
+ */
+export declare function readNowPlaying(): Promise<NowPlayingReading | null>;
+/** Send a transport command to whatever the system considers now-playing. */
+export declare function sendTransport(command: TransportCommand): Promise<boolean>;
+/** Whether this machine can answer at all. Used by the adapter's `init`. */
+export declare function isAvailable(): Promise<boolean>;
+//# sourceMappingURL=mediaremote.d.ts.map

package/dist/src/mediaremote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaremote.d.ts","sourceRoot":"","sources":["../../src/mediaremote.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AA4DpE;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ;;;;;;CAMX,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,QAAQ,CAAC;AAqCrD;;;;;;;GAOG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAOxE;AAED,6EAA6E;AAC7E,wBAAsB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ/E;AAED,4EAA4E;AAC5E,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAUpD"}

package/dist/src/mediaremote.js

@@ -0,0 +1,144 @@
+import { execFile } from 'node:child_process';
+import { parseReading } from './reading.js';
+/**
+ * macOS's own Now Playing register — how this reaches everything that isn't a
+ * dedicated integration: a browser tab, VLC, Doppler, anything that shows up in
+ * Control Center.
+ *
+ * This talks to `MediaRemote`, a private framework, through JXA's Objective-C
+ * bridge. Private API is normally a bad trade, so the justification:
+ *
+ *   - There is no public equivalent. `MPNowPlayingInfoCenter` publishes *your
+ *     own* app's state; nothing public reads another app's.
+ *   - Apple began gating MediaRemote behind an entitlement in macOS 15.4, which
+ *     broke the usual command-line tools. The gate applies to processes asking
+ *     directly; script execution through `osascript` still resolves it, and
+ *     that was verified on macOS 26.5.
+ *   - The alternative is shipping a helper binary that borrows a system
+ *     binary's entitlements — a far larger and more fragile dependency than a
+ *     script you can read in full, here, above.
+ *
+ * Every failure answers null rather than throwing, so the day Apple closes this
+ * the adapter reports itself unavailable and the rest of the queue carries on.
+ */
+const FRAMEWORK = '/System/Library/PrivateFrameworks/MediaRemote.framework/';
+const SCRIPT_TIMEOUT_MS = 4000;
+const READ_SCRIPT = `
+ObjC.import('Foundation')
+function run() {
+  var bundle = $.NSBundle.bundleWithPath('${FRAMEWORK}')
+  if (!bundle || !bundle.load) return ''
+  var R = $.NSClassFromString('MRNowPlayingRequest')
+  if (!R) return ''
+  var path = R.localNowPlayingPlayerPath
+  if (!path || path.isNil()) return ''
+  var client = path.client
+  if (!client || client.isNil()) return ''
+  var item = R.localNowPlayingItem
+  if (!item || item.isNil()) return ''
+  var info = item.nowPlayingInfo
+  if (!info || info.isNil()) return ''
+
+  var str = function (v) { try { return v && !v.isNil() ? String(v.js) : '' } catch (e) { return '' } }
+  var key = function (k) { try { var v = info.valueForKey(k); return v && !v.isNil() ? v.js : null } catch (e) { return null } }
+  var num = function (k) { var v = key(k); var n = typeof v === 'number' ? v : parseFloat(v); return isFinite(n) ? n : 0 }
+
+  return JSON.stringify({
+    bundleId: str(client.bundleIdentifier),
+    label: str(client.displayName),
+    playing: R.localIsPlaying === true,
+    title: String(key('kMRMediaRemoteNowPlayingInfoTitle') || ''),
+    artist: String(key('kMRMediaRemoteNowPlayingInfoArtist') || ''),
+    album: String(key('kMRMediaRemoteNowPlayingInfoAlbum') || ''),
+    elapsed: num('kMRMediaRemoteNowPlayingInfoElapsedTime'),
+    duration: num('kMRMediaRemoteNowPlayingInfoDuration')
+  })
+}
+`;
+/**
+ * MediaRemote's command numbers.
+ *
+ * Only the transport is here. The register exposes no volume, and its seek
+ * command takes options this bridge cannot pass cleanly — which is exactly why
+ * the adapter declares `seek: false` and `volume: false` rather than pretending.
+ */
+export const COMMANDS = {
+    play: 0,
+    pause: 1,
+    togglePlayPause: 2,
+    next: 4,
+    previous: 5,
+};
+/**
+ * The queue argument is load-bearing: passing nil there hangs the script
+ * indefinitely, and a hung `osascript` would stall every poll behind it.
+ */
+const commandScript = (code) => `
+ObjC.import('Foundation')
+function run() {
+  var bundle = $.NSBundle.bundleWithPath('${FRAMEWORK}')
+  if (!bundle || !bundle.load) return ''
+  var R = $.NSClassFromString('MRNowPlayingRequest')
+  if (!R) return ''
+  var path = R.localNowPlayingPlayerPath
+  if (!path || path.isNil()) return ''
+  var req = R.alloc.initWithPlayerPath(path)
+  req.sendCommandOptionsQueueCompletion(
+    ${code},
+    $.NSDictionary.dictionary,
+    $.NSOperationQueue.mainQueue.underlyingQueue,
+    $()
+  )
+  return 'ok'
+}
+`;
+function jxa(script) {
+    return new Promise((resolve, reject) => {
+        execFile('osascript', ['-l', 'JavaScript', '-e', script], { timeout: SCRIPT_TIMEOUT_MS }, (error, stdout) => (error ? reject(error) : resolve(stdout)));
+    });
+}
+/**
+ * What macOS is playing right now, whichever app is playing it.
+ *
+ * Exported on its own because it is useful without a queue: a host that only
+ * wants to show what is on, or to know whether to duck, needs this and nothing
+ * else. Answers null when nothing is playing, when the reading is not media, or
+ * when the framework is unavailable.
+ */
+export async function readNowPlaying() {
+    if (process.platform !== 'darwin')
+        return null;
+    try {
+        return parseReading(await jxa(READ_SCRIPT));
+    }
+    catch {
+        return null;
+    }
+}
+/** Send a transport command to whatever the system considers now-playing. */
+export async function sendTransport(command) {
+    if (process.platform !== 'darwin')
+        return false;
+    try {
+        const out = await jxa(commandScript(COMMANDS[command]));
+        return out.trim() === 'ok';
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this machine can answer at all. Used by the adapter's `init`. */
+export async function isAvailable() {
+    if (process.platform !== 'darwin')
+        return false;
+    try {
+        // An empty answer still means the bridge resolved — nothing is playing,
+        // which is a fine state. Only a thrown error means it cannot work here.
+        await jxa(READ_SCRIPT);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=mediaremote.js.map

package/dist/src/mediaremote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaremote.js","sourceRoot":"","sources":["../../src/mediaremote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAA0B,MAAM,cAAc,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,SAAS,GAAG,0DAA0D,CAAC;AAC7E,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B,MAAM,WAAW,GAAG;;;4CAGwB,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BpD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,eAAe,EAAE,CAAC;IAClB,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;CACH,CAAC;AAIX;;;GAGG;AACH,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC;;;4CAGI,SAAS;;;;;;;;MAQ/C,IAAI;;;;;;;CAOT,CAAC;AAEF,SAAS,GAAG,CAAC,MAAc;IACzB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,WAAW,EACX,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,EAClC,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAC9B,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAC7D,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,MAAM,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAyB;IAC3D,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACxD,OAAO,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC;QACH,wEAAwE;QACxE,wEAAwE;QACxE,MAAM,GAAG,CAAC,WAAW,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/src/reading.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What the system says is playing, and whether to believe it is music.
+ *
+ * Kept pure and separate from the script that fetches it, so every decision
+ * here is testable without macOS — and so a captured reading from a real
+ * machine can be replayed verbatim in a test.
+ */
+export interface NowPlayingReading {
+    /** The app that owns Now Playing: `com.google.Chrome`, `com.spotify.client`. */
+    bundleId: string;
+    /** Its human name, as Control Center shows it. */
+    label: string;
+    playing: boolean;
+    title: string;
+    artist: string;
+    album?: string;
+    elapsedMs: number;
+    durationMs: number;
+}
+/**
+ * Parse a reading, or answer null when there is nothing worth showing.
+ *
+ * The filter is the load-bearing part. macOS's Now Playing client is *whatever
+ * last made a sound*, which includes things that are not media at all — a
+ * received voice message leaves Messages sitting there as the now-playing app
+ * with no title and a seven-second "track". Treating that as a queue entry
+ * would put a transport bar on a notification chime.
+ *
+ * Requiring a title and a real duration is what separates "something is
+ * playing" from "something made a noise once".
+ */
+export declare function parseReading(raw: string): NowPlayingReading | null;
+/**
+ * A locator for something we do not own.
+ *
+ * Every other adapter has a real identifier to point at — a file path, a
+ * Spotify URI. Here there is only "whatever is playing", so identity has to be
+ * synthesised from what the system reports. It matters that this *changes when
+ * the track does*: it is the only way the runtime can tell that the person
+ * skipped to something else in their browser, which is the entire reason this
+ * adapter declares `externalControl`.
+ */
+export declare function readingUri(reading: NowPlayingReading): string;
+/**
+ * Has this finished?
+ *
+ * Players park at exactly their duration and go on reporting the finished track
+ * indefinitely, so "at the end and not playing" has to count as over — waiting
+ * for the position to exceed the duration waits forever.
+ */
+export declare function hasEnded(reading: NowPlayingReading): boolean;
+//# sourceMappingURL=reading.d.ts.map

package/dist/src/reading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reading.d.ts","sourceRoot":"","sources":["../../src/reading.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAyBlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAE5D"}

package/dist/src/reading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reading.js","sourceRoot":"","sources":["../../src/reading.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "upnext-adapter-nowplaying",
+  "version": "0.1.0",
+  "description": "Read and control whatever macOS is playing \u2014 a browser tab, VLC, Doppler, anything that publishes to Control Center.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": "./dist/src/index.js"
+  },
+  "files": [
+    "dist/src",
+    "src"
+  ],
+  "dependencies": {
+    "upnext-core": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tothienbao6a0/upnext.git",
+    "directory": "packages/adapter-nowplaying"
+  },
+  "homepage": "https://github.com/tothienbao6a0/upnext#readme",
+  "bugs": {
+    "url": "https://github.com/tothienbao6a0/upnext/issues"
+  },
+  "keywords": [
+    "audio",
+    "macos",
+    "now-playing",
+    "mediaremote",
+    "control-center",
+    "upnext-adapter"
+  ]
+}

package/src/adapter.ts

@@ -0,0 +1,162 @@
+import { defaultCapabilities } from 'upnext-core';
+import type {
+  Adapter,
+  AdapterReading,
+  Binding,
+  Capabilities,
+  MediaRef,
+} from 'upnext-core';
+import { isAvailable, readNowPlaying, sendTransport } from './mediaremote.js';
+import { hasEnded, readingUri, type NowPlayingReading } from './reading.js';
+
+/** The one thing this adapter can be asked for. */
+export const NOW_PLAYING_URI = 'nowplaying:current';
+
+export interface NowPlayingAdapterOptions {
+  id?: string;
+  /** Injected for tests, and for a host that has its own source of truth. */
+  read?: () => Promise<NowPlayingReading | null>;
+  send?: (command: 'play' | 'pause') => Promise<boolean>;
+}
+
+/**
+ * Whatever the machine is already playing, as a queue entry.
+ *
+ * Every other adapter is handed a locator and told to play it. This one cannot
+ * be: there is no way to ask macOS's Now Playing register to start a particular
+ * track. What it *can* do is see what some other app is playing — a browser tab,
+ * VLC, anything in Control Center — and work the transport.
+ *
+ * So it answers to exactly one entry, `nowplaying:current`, meaning *the thing
+ * that is on*. That turns out to be worth having:
+ *
+ *   runtime.enqueue('nowplaying:current');   // let their podcast finish
+ *   runtime.enqueue({ title: 'Bad Habit' }); // then take over
+ *
+ * which is an agent adding to someone's listening instead of interrupting it.
+ *
+ * It also sits at the far end of the capability spectrum — further than the
+ * Spotify adapter, which at least starts the tracks it plays. Here the runtime
+ * is a guest: the item was chosen by somebody else, in an app it does not
+ * control, and it can be changed underneath at any moment. `externalControl`
+ * has never meant more than it does here.
+ */
+export class NowPlayingAdapter implements Adapter {
+  readonly id: string;
+
+  readonly capabilities: Capabilities = {
+    ...defaultCapabilities,
+    // No notifications from the register; we sample it.
+    endOfTrack: 'poll',
+    // Elapsed time comes from the player itself, not from a clock of ours.
+    position: 'authoritative',
+    pause: true,
+    // The register exposes no volume, and its seek command takes options the
+    // JXA bridge cannot pass cleanly. Declaring either would be a lie.
+    seek: false,
+    volume: false,
+    search: false,
+    // The strongest case in the library: we did not even start this.
+    externalControl: true,
+  };
+
+  #options: NowPlayingAdapterOptions;
+  #binding: Binding | null = null;
+
+  constructor(options: NowPlayingAdapterOptions = {}) {
+    this.id = options.id ?? 'nowplaying';
+    this.#options = options;
+  }
+
+  async init(): Promise<void> {
+    if (this.#options.read) return; // Injected: nothing to probe.
+    if (!(await isAvailable())) {
+      throw new Error(
+        'macOS Now Playing is unavailable here — this adapter needs macOS and the MediaRemote framework',
+      );
+    }
+  }
+
+  /**
+   * Only ever `nowplaying:current`. This adapter cannot be handed a track.
+   *
+   * Scoring anything else above zero would be claiming it could start a file or
+   * a Spotify URI, and it cannot start anything at all.
+   */
+  match(ref: MediaRef): number {
+    return ref.uri === NOW_PLAYING_URI ? 1 : 0;
+  }
+
+  async resolve(ref: MediaRef): Promise<Binding | null> {
+    if (this.match(ref) === 0) return null;
+
+    const reading = await this.#read();
+    // Nothing is playing, so there is nothing to adopt. Failing here is right:
+    // the entry meant "the thing that is on" and there is no such thing.
+    if (!reading) return null;
+
+    return {
+      adapterId: this.id,
+      // The synthesised locator changes with the track, which is what lets the
+      // runtime notice the person skipping in their browser.
+      nativeUri: readingUri(reading),
+      ref: {
+        ...ref,
+        title: reading.title,
+        artist: reading.artist,
+        durationMs: reading.durationMs,
+        meta: { app: reading.label, bundleId: reading.bundleId },
+      },
+    };
+  }
+
+  /** Nothing to load. Something else already did. */
+  async load(binding: Binding): Promise<void> {
+    this.#binding = binding;
+  }
+
+  async play(): Promise<void> {
+    await this.#send('play');
+  }
+
+  async pause(): Promise<void> {
+    await this.#send('pause');
+  }
+
+  /**
+   * Pause, never kill.
+   *
+   * The runtime moving on to its own next entry is not a reason to take
+   * somebody's podcast away from them — and there is no "stop" in this register
+   * anyway, only a transport.
+   */
+  async stop(): Promise<void> {
+    await this.#send('pause');
+    this.#binding = null;
+  }
+
+  async poll(): Promise<AdapterReading> {
+    const reading = await this.#read();
+
+    if (!reading) {
+      // The app went away, or stopped publishing. Whatever we were following is
+      // over as far as anyone can tell from here.
+      return { status: 'ended', nativeUri: null };
+    }
+
+    return {
+      status: hasEnded(reading) ? 'ended' : reading.playing ? 'playing' : 'paused',
+      positionMs: reading.elapsedMs,
+      durationMs: reading.durationMs,
+      nativeUri: readingUri(reading),
+    };
+  }
+
+  #read(): Promise<NowPlayingReading | null> {
+    return (this.#options.read ?? readNowPlaying)();
+  }
+
+  #send(command: 'play' | 'pause'): Promise<boolean> {
+    return (this.#options.send ?? sendTransport)(command);
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { NowPlayingAdapter, NOW_PLAYING_URI } from './adapter.js';
+export type { NowPlayingAdapterOptions } from './adapter.js';
+
+export { readNowPlaying, sendTransport, isAvailable, COMMANDS } from './mediaremote.js';
+export type { TransportCommand } from './mediaremote.js';
+
+export { parseReading, readingUri, hasEnded } from './reading.js';
+export type { NowPlayingReading } from './reading.js';

package/src/mediaremote.ts

@@ -0,0 +1,153 @@
+import { execFile } from 'node:child_process';
+import { parseReading, type NowPlayingReading } from './reading.js';
+
+/**
+ * macOS's own Now Playing register — how this reaches everything that isn't a
+ * dedicated integration: a browser tab, VLC, Doppler, anything that shows up in
+ * Control Center.
+ *
+ * This talks to `MediaRemote`, a private framework, through JXA's Objective-C
+ * bridge. Private API is normally a bad trade, so the justification:
+ *
+ *   - There is no public equivalent. `MPNowPlayingInfoCenter` publishes *your
+ *     own* app's state; nothing public reads another app's.
+ *   - Apple began gating MediaRemote behind an entitlement in macOS 15.4, which
+ *     broke the usual command-line tools. The gate applies to processes asking
+ *     directly; script execution through `osascript` still resolves it, and
+ *     that was verified on macOS 26.5.
+ *   - The alternative is shipping a helper binary that borrows a system
+ *     binary's entitlements — a far larger and more fragile dependency than a
+ *     script you can read in full, here, above.
+ *
+ * Every failure answers null rather than throwing, so the day Apple closes this
+ * the adapter reports itself unavailable and the rest of the queue carries on.
+ */
+
+const FRAMEWORK = '/System/Library/PrivateFrameworks/MediaRemote.framework/';
+const SCRIPT_TIMEOUT_MS = 4000;
+
+const READ_SCRIPT = `
+ObjC.import('Foundation')
+function run() {
+  var bundle = $.NSBundle.bundleWithPath('${FRAMEWORK}')
+  if (!bundle || !bundle.load) return ''
+  var R = $.NSClassFromString('MRNowPlayingRequest')
+  if (!R) return ''
+  var path = R.localNowPlayingPlayerPath
+  if (!path || path.isNil()) return ''
+  var client = path.client
+  if (!client || client.isNil()) return ''
+  var item = R.localNowPlayingItem
+  if (!item || item.isNil()) return ''
+  var info = item.nowPlayingInfo
+  if (!info || info.isNil()) return ''
+
+  var str = function (v) { try { return v && !v.isNil() ? String(v.js) : '' } catch (e) { return '' } }
+  var key = function (k) { try { var v = info.valueForKey(k); return v && !v.isNil() ? v.js : null } catch (e) { return null } }
+  var num = function (k) { var v = key(k); var n = typeof v === 'number' ? v : parseFloat(v); return isFinite(n) ? n : 0 }
+
+  return JSON.stringify({
+    bundleId: str(client.bundleIdentifier),
+    label: str(client.displayName),
+    playing: R.localIsPlaying === true,
+    title: String(key('kMRMediaRemoteNowPlayingInfoTitle') || ''),
+    artist: String(key('kMRMediaRemoteNowPlayingInfoArtist') || ''),
+    album: String(key('kMRMediaRemoteNowPlayingInfoAlbum') || ''),
+    elapsed: num('kMRMediaRemoteNowPlayingInfoElapsedTime'),
+    duration: num('kMRMediaRemoteNowPlayingInfoDuration')
+  })
+}
+`;
+
+/**
+ * MediaRemote's command numbers.
+ *
+ * Only the transport is here. The register exposes no volume, and its seek
+ * command takes options this bridge cannot pass cleanly — which is exactly why
+ * the adapter declares `seek: false` and `volume: false` rather than pretending.
+ */
+export const COMMANDS = {
+  play: 0,
+  pause: 1,
+  togglePlayPause: 2,
+  next: 4,
+  previous: 5,
+} as const;
+
+export type TransportCommand = keyof typeof COMMANDS;
+
+/**
+ * The queue argument is load-bearing: passing nil there hangs the script
+ * indefinitely, and a hung `osascript` would stall every poll behind it.
+ */
+const commandScript = (code: number) => `
+ObjC.import('Foundation')
+function run() {
+  var bundle = $.NSBundle.bundleWithPath('${FRAMEWORK}')
+  if (!bundle || !bundle.load) return ''
+  var R = $.NSClassFromString('MRNowPlayingRequest')
+  if (!R) return ''
+  var path = R.localNowPlayingPlayerPath
+  if (!path || path.isNil()) return ''
+  var req = R.alloc.initWithPlayerPath(path)
+  req.sendCommandOptionsQueueCompletion(
+    ${code},
+    $.NSDictionary.dictionary,
+    $.NSOperationQueue.mainQueue.underlyingQueue,
+    $()
+  )
+  return 'ok'
+}
+`;
+
+function jxa(script: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      'osascript',
+      ['-l', 'JavaScript', '-e', script],
+      { timeout: SCRIPT_TIMEOUT_MS },
+      (error, stdout) => (error ? reject(error) : resolve(stdout)),
+    );
+  });
+}
+
+/**
+ * What macOS is playing right now, whichever app is playing it.
+ *
+ * Exported on its own because it is useful without a queue: a host that only
+ * wants to show what is on, or to know whether to duck, needs this and nothing
+ * else. Answers null when nothing is playing, when the reading is not media, or
+ * when the framework is unavailable.
+ */
+export async function readNowPlaying(): Promise<NowPlayingReading | null> {
+  if (process.platform !== 'darwin') return null;
+  try {
+    return parseReading(await jxa(READ_SCRIPT));
+  } catch {
+    return null;
+  }
+}
+
+/** Send a transport command to whatever the system considers now-playing. */
+export async function sendTransport(command: TransportCommand): Promise<boolean> {
+  if (process.platform !== 'darwin') return false;
+  try {
+    const out = await jxa(commandScript(COMMANDS[command]));
+    return out.trim() === 'ok';
+  } catch {
+    return false;
+  }
+}
+
+/** Whether this machine can answer at all. Used by the adapter's `init`. */
+export async function isAvailable(): Promise<boolean> {
+  if (process.platform !== 'darwin') return false;
+  try {
+    // An empty answer still means the bridge resolved — nothing is playing,
+    // which is a fine state. Only a thrown error means it cannot work here.
+    await jxa(READ_SCRIPT);
+    return true;
+  } catch {
+    return false;
+  }
+}