homebridge-plex-intermission 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-11-06
+
+### Added
+
+- Players are chosen by device. Choosing the Apple TV includes every Plex app on it, including apps added or reinstalled
+  later, while it plays on your home network. *Choose apps* lists the apps seen on a device, to leave one out.
+- Two devices that report the same name (apps see "Apple TV" for every Apple TV) are noticed, with a log warning, and
+  setup offers *This one* to keep only the one in the room. You can name devices.
+- Diagnostics: a Network check saying whether Plex sees players' real addresses and marks them local, devices and apps
+  left out on each sensor, and each player's platform.
+
+### Changed
+
+- Choices made app by app move to devices when the settings page opens. Apps that weren't chosen are left out, so
+  nothing new changes the lights; press Save to keep it.
+- A player is at home when Plex marks it local or its address is private, so Plex in a Docker bridge network without
+  LAN Networks set still works.
+- Addresses shared by players on different platforms are never used to tell devices apart or follow new IDs.
+
+## [1.0.2] - 2026-11-06
+
+### Fixed
+
+- A player that Plex gives a new ID, after its app is reinstalled or signed in again, keeps changing the lights. When
+  its name, app and LAN address match a chosen player, the sensors follow it as that player and the log says so.
+- A player that only shares a chosen player's name gets a warning in the log instead of being silently ignored.
+
+### Changed
+
+- The Sensors tab offers to add a player with a new ID to the sensors that watch the player it replaces, or to leave it
+  off.
+- Setup: players that share a name show when each last played and the start of its ID, and apps Plex lists without a
+  name show the app Intermission saw them play as.
+- Diagnostics lists the players seen playing, with their app, last play and whether they are chosen or followed.
+
+## [1.0.1] - 2026-10-23
+
+### Fixed
+
+- Players added later with *Change servers, players and libraries* now reach the sensors. Sensors that watched exactly
+  the old choices of players, people or libraries follow the new ones; filters set by hand stay as they are.
+- Sensors saved before this fix that leave out a player chosen in setup get a notice on the Sensors tab, with *Add to
+  the sensor* or *Leave as is*.
+
+### Changed
+
+- Players with the same name, such as Plex and Infuse on one Apple TV, are shown with their app (or the start of their
+  ID) in sensor summaries, filters, the diagnostics file and the log.
+- Saved players take Plex's current name and app when setup runs again.
+- Diagnostics: the log is newest first, and *Watch live* shows the log as it happens, in local time and with names,
+  without downloading anything.
+
 ## [1.0.0] - 2026-10-23
 
 First public release.
@@ -55,5 +107,8 @@ First public release.
   Home app.
 - Lost connections to Plex are retried with their reasons logged, with a warning if Plex stays unreachable.
 
-[Unreleased]: https://github.com/maxrogers/homebridge-plex-intermission/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/maxrogers/homebridge-plex-intermission/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/maxrogers/homebridge-plex-intermission/compare/v1.0.2...v1.1.0
+[1.0.2]: https://github.com/maxrogers/homebridge-plex-intermission/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/maxrogers/homebridge-plex-intermission/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/maxrogers/homebridge-plex-intermission/releases/tag/v1.0.0

package/README.md

@@ -15,7 +15,9 @@ Most Plex plugins give Apple Home a single "playing" sensor. Intermission adds:
 - **Credits timing.** Lights come up when Plex's credits markers say the credits start, never before, re-timed when you skip.
 - **A sensor for each moment.** Playing, paused, credits and nothing playing, so each gets its own scene.
 - **Instant, without polling.** Plex pushes every change, and it works without Plex Pass too.
-- **Sign in with Plex.** Players and libraries come from a list; no tokens or IDs to copy.
+- **Sign in with Plex.** Devices and libraries come from a list; no tokens or IDs to copy.
+- **Choose the device, not the app.** Pick the Apple TV in the room and every Plex app on it counts, including apps
+  added or reinstalled later. Leave out an app on it if you like.
 
 I build things I need for myself, and sometimes I share them. This [Homebridge](https://homebridge.io) plugin is one
 of those: I wanted the room to react to movie night using nothing but Apple Home.
@@ -29,11 +31,11 @@ Intermission never controls your lights; you choose what happens in the Home app
 - **Mid-credits scenes** can dim the lights again, and short pauses or skip bursts never flicker them.
 - **Sensors, not just buttons.** Home can always read a sensor, so a hub restart or a Wi-Fi drop never leaves your
   lights in the wrong state. Buttons cover one-off events such as "Marked as watched".
-- **Filters** by player, person and library (including Live TV), and by the media itself: wide movies, 4K, HDR,
+- **Filters** by device (or app), person and library (including Live TV), and by the media itself: wide movies, 4K, HDR,
   ratings or Plex labels.
 - **A Guide** in the settings page with the Home automations for your preset, including gentle fades, with screenshots.
 - **Diagnostics** in one file for bug reports, never with your Plex sign-in, and without titles or names unless you
-  include them.
+  include them. **Watch live** shows the log as it happens, right in the settings page.
 
 ## Presets
 
@@ -50,7 +52,7 @@ fades made with Convert To Shortcut.
 
 1. In the Homebridge UI, open **Plugins**, search for **Intermission for Plex** and install it.
 2. Open the plugin's settings and **Sign in with Plex**.
-3. Choose your servers, then your players, people and libraries.
+3. Choose your servers, then your devices, people and libraries.
 4. Choose a preset and save. Intermission runs on its own child bridge by default; restart Homebridge, then add it in
    the Home app with the code shown on the Sensors tab.
 5. Make the automations from the Guide tab.
@@ -92,9 +94,13 @@ Intermission talks only to plex.tv and your Plex servers, with no analytics. See
 
 - **Something didn't happen when it should have:** in the plugin's settings, open **Settings**, then **Diagnostics**,
   and download the diagnostics file soon afterwards. It includes Intermission's recent log, so you don't need to turn on
-  extra logging first. It leaves out your Plex sign-in, and titles and names unless you include them.
+  extra logging first. It leaves out your Plex sign-in, and titles and names unless you include them. To see what
+  Intermission makes of something as you do it, press **Watch live** there instead.
 - **Webhooks:** **Settings**, then **Plex Pass and webhooks**, shows whether Plex has the webhook, whether your server's
   Webhooks setting is on, and whether Intermission is listening on its port.
+- **A device's playback is ignored:** a device counts while it plays on your home network. Diagnostics, Network check
+  says whether Plex reports real addresses and marks your players local. Apps report the device's model name ("Apple
+  TV"), so two Apple TVs share one; Intermission notices and setup offers **This one** to keep only the one in the room.
 - **Sensors not in the Home app:** with the child bridge, add Intermission in the Home app with the code on the Sensors
   tab after restarting Homebridge.
 

package/dist/config.js

@@ -74,11 +74,13 @@ export function parseConfig(raw, log) {
     // 0 turns it off, otherwise 1 to 30 minutes.
     const safetyResyncMs = timing.safetyResync === 0 ? 0 : minutes(timing, 'safetyResync', 5 * 60_000, 1, 30);
     const port = webhook.port;
+    const devices = parseDevices(config.devices);
     return {
         name: asString(config.name) ?? 'Intermission',
         setupId: asString(config.setupId),
         servers: parseServers(config.servers),
-        sensors: parseSensors(config.sensors, log),
+        devices,
+        sensors: parseSensors(config.sensors, log, devices),
         webhook: {
             enabled: webhook.enabled !== false,
             port: typeof port === 'number' && Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_WEBHOOK_PORT,
@@ -88,8 +90,21 @@ export function parseConfig(raw, log) {
         safetyResyncMs,
         detailedLogging: config.detailedLogging === true,
         commands: parseCommands(config.commands),
+        ...parseSelection(config.selection),
     };
 }
+function parseSelection(value) {
+    const selection = asRecord(value);
+    const chosenPlayers = {};
+    for (const entry of Array.isArray(selection.players) ? selection.players : []) {
+        const player = asRecord(entry);
+        const id = asString(player.id);
+        if (id) {
+            chosenPlayers[id] = { name: asString(player.name), product: asString(player.product) };
+        }
+    }
+    return { chosenPlayers, ignoredPlayers: asStrings(selection.dismissedPlayers) };
+}
 function parseCommands(value) {
     const section = asRecord(value);
     if (section.enabled !== true || !Array.isArray(section.list)) {
@@ -141,7 +156,20 @@ function parseMedia(value) {
 export function hasMediaConditions(conditions) {
     return Object.keys(conditions).length > 0;
 }
-function parseSensors(value, log) {
+function parseDevices(value) {
+    const seen = new Set();
+    return (Array.isArray(value) ? value : []).flatMap((entry) => {
+        const device = asRecord(entry);
+        const id = asString(device.id);
+        const match = asString(device.match);
+        if (!id || !match || seen.has(id)) {
+            return [];
+        }
+        seen.add(id);
+        return [{ id, name: asString(device.name) ?? match, match, apps: asStrings(device.apps) }];
+    });
+}
+function parseSensors(value, log, devices = []) {
     if (!Array.isArray(value)) {
         return [];
     }
@@ -172,6 +200,9 @@ function parseSensors(value, log) {
             },
             filters: {
                 players: asStrings(filters.players),
+                // An unknown device stays, matching nothing, so the filter never widens to every player.
+                devices: asStrings(filters.devices).map((deviceId) => devices.find((d) => d.id === deviceId) ?? { id: deviceId, name: deviceId, apps: [] }),
+                exceptPlayers: asStrings(filters.exceptPlayers),
                 users: asStrings(filters.users),
                 libraries: asStrings(filters.libraries),
             },

package/dist/controller.js

@@ -4,7 +4,7 @@ import { webhookFromPayload } from './plex/convert.js';
 import { PlexHttpError } from './plex/server.js';
 import { person as markPerson, player as markPlayer, title as markTitle } from './diagnostics.js';
 import { describe } from './errors.js';
-import { contextOf, filterMismatch, matchesFilters, mediaMatches, mediaMismatch, stateHolds } from './sensors/rules.js';
+import { contextOf, filterMismatch, isHome, matchesFilters, onDevice, mediaMatches, mediaMismatch, stateHolds } from './sensors/rules.js';
 const WEBHOOK_ONLY = new Set(WEBHOOK_EVENTS);
 /** How long sensors keep their state from before a restart when Plex cannot be read. */
 const STARTUP_GRACE_MS = 20_000;
@@ -30,6 +30,14 @@ export class Controller {
     /** Media details by rating key: a value once read, or null while reading or when Plex had none. */
     facts = new Map();
     needsFacts;
+    /** Every player some sensor is limited to. Empty when every sensor takes all players. */
+    chosenPlayers;
+    /** Apps pinned to devices that share their name with another device. */
+    pinnedApps;
+    /** Player names chosen as devices (lower case). */
+    deviceNames;
+    /** Unwatched players already pointed out in the log this run. */
+    pointedOut = new Set();
     constructor(options) {
         this.options = options;
         this.engine = new PlaybackEngine({
@@ -39,6 +47,10 @@ export class Controller {
             getMarkers: (ratingKey) => this.call(() => options.getMarkers(ratingKey), []),
             hasCredits: options.hasCredits,
         }, options.config.engine);
+        const devices = options.sensors.flatMap((s) => s.config.filters.devices ?? []);
+        this.pinnedApps = new Set(devices.flatMap((d) => d.apps));
+        this.chosenPlayers = new Set([...options.sensors.flatMap((s) => s.config.filters.players), ...this.pinnedApps]);
+        this.deviceNames = new Set(devices.filter((d) => d.apps.length === 0 && d.match).map((d) => d.match.trim().toLowerCase()));
         this.needsFacts = options.getFacts !== undefined && options.sensors.some((s) => s.config.type !== 'button' && hasMediaConditions(s.config.media));
         this.engine.on('event', (event) => this.onEngineEvent(event));
         options.stream.on('playing', (notification) => this.engine.handleNotification(notification));
@@ -134,6 +146,7 @@ export class Controller {
         log.debug('%s: %s on %s at %ds', event.type, markTitle(event.session.media.title), markPlayer(event.session.playerTitle ?? event.playerId), Math.round(event.positionMs / 1000));
         if (event.type === 'play') {
             this.explainSensors(event.session);
+            void this.learnPlayer(event.session);
         }
         // States first: a button press is delivered to the hub at once and flushes queued state changes
         // with it, so a shortcut started by the press already sees the new states.
@@ -143,7 +156,7 @@ export class Controller {
         else {
             this.becomeReady();
         }
-        this.pressButtons(event.type, contextOf(event.session, undefined, this.options.server.id), event.session);
+        this.pressButtons(event.type, this.context(event.session), event.session);
         if (!this.options.stream.isConnected) {
             this.scheduleResync();
         }
@@ -167,7 +180,7 @@ export class Controller {
         }
     }
     webhookContext(webhook) {
-        const context = contextOf(webhook.session, webhook.media, this.options.server.id);
+        const context = this.context(webhook.session, webhook.media);
         return { ...context, user: context.user ?? webhook.user };
     }
     pressButtons(event, context, session) {
@@ -191,7 +204,7 @@ export class Controller {
                 continue;
             }
             const matching = snapshots.filter((snapshot) => snapshot.session !== undefined
-                && matchesFilters(sensor.config.filters, contextOf(snapshot.session, undefined, this.options.server.id))
+                && matchesFilters(sensor.config.filters, this.context(snapshot.session))
                 && (!hasMediaConditions(sensor.config.media) || mediaMatches(sensor.config.media, this.factsFor(snapshot.session.media))));
             // "Nothing playing" is on while no matching player is busy; the rest are on while any player meets them.
             const holding = matching.find((snapshot) => stateHolds(condition, snapshot, sensor.config.except));
@@ -240,17 +253,82 @@ export class Controller {
      * Logged when an item starts, and again for media conditions once the item's details are read.
      */
     explainSensors(session, mediaOnly = false) {
-        const context = contextOf(session, undefined, this.options.server.id);
+        const context = this.context(session);
         for (const sensor of this.options.sensors) {
             const config = sensor.config;
             if (config.type === 'button' || (mediaOnly && !hasMediaConditions(config.media))) {
                 continue;
             }
-            const reason = filterMismatch(config.filters, context, { player: session.playerTitle, library: session.media.librarySectionTitle })
+            const reason = filterMismatch(config.filters, context, { player: session.playerTitle, product: session.product, library: session.media.librarySectionTitle })
                 ?? (hasMediaConditions(config.media) ? mediaMismatch(config.media, this.factsFor(session.media)) : undefined);
             this.options.log.debug('  %s: %s', config.name, reason ? `ignores this playback: ${reason}` : 'follows this playback');
         }
     }
+    /** What sensor filters match against, with the chosen players a new player ID is followed as. */
+    context(session, media) {
+        const id = session?.playerId;
+        const book = this.options.players;
+        const known = id ? book?.get(id) : undefined;
+        return contextOf(session, media, this.options.server.id, {
+            followedAs: id && !this.options.config.ignoredPlayers.includes(id) ? book?.followedAs(id) : undefined,
+            playerName: session?.playerTitle ?? known?.name,
+            home: isHome(session) ?? isHome(known),
+        });
+    }
+    /**
+     * Records a player that started playing, with its LAN address from the server's session list.
+     * A new Plex ID that matches a chosen app is followed as it (see PlayerBook); one that only looks
+     * like a chosen app, and a name that turns out to belong to two devices, are pointed out once.
+     */
+    async learnPlayer(session) {
+        const { players: book, log, config } = this.options;
+        if (!book) {
+            return;
+        }
+        const listed = session.address ? undefined : await this.call(() => this.options.plex.session(session.playerId, ''), undefined);
+        const player = {
+            ...session,
+            playerTitle: session.playerTitle ?? listed?.playerTitle,
+            product: session.product ?? listed?.product,
+            platform: session.platform ?? listed?.platform,
+            address: session.address ?? listed?.address,
+            local: session.local ?? listed?.local,
+        };
+        const id = player.playerId;
+        const { followed, newlyShared } = book.record(player, this.chosenPlayers, { ignored: config.ignoredPlayers, pinned: this.pinnedApps });
+        const label = `${markPlayer(player.playerTitle ?? id)} (${[player.product, id.slice(0, 8)].filter(Boolean).join(', ')})`;
+        // What was unknown when play started (the name or whether it is at home) may be known now.
+        this.refreshStates();
+        if (newlyShared && this.deviceNames.has((player.playerTitle ?? '').trim().toLowerCase())) {
+            log.warn('Two devices report the player name %s: it played from one address, then another, then the first again. '
+                + 'Both change the lights. To limit it to one, open the plugin settings and choose This one on that device.', markPlayer(player.playerTitle));
+        }
+        if (followed.length > 0) {
+            log.info('%s has a new Plex ID. It has the same name and address as a chosen app, so the sensors follow it. '
+                + 'To make this permanent, open the plugin settings and add it to the sensors.', label);
+            this.explainSensors(player);
+            return;
+        }
+        if (this.chosenPlayers.size === 0 || this.chosenPlayers.has(id) || this.context(player).followedAs
+            || config.ignoredPlayers.includes(id) || this.pointedOut.has(id) || this.onAnyDevice(player)) {
+            return;
+        }
+        const lookalike = [...this.chosenPlayers].some((chosenId) => {
+            const known = { ...config.chosenPlayers[chosenId], ...book.get(chosenId) };
+            return sameText(known.name, player.playerTitle)
+                && (this.pinnedApps.has(chosenId) || !known.product || !player.product || sameText(known.product, player.product));
+        });
+        if (lookalike) {
+            this.pointedOut.add(id);
+            log.warn('%s is playing, but no sensor watches it, though a chosen player has the same name. If Plex gave that player '
+                + 'a new ID (after reinstalling or signing in to the app again), open the plugin settings and add it to the sensors.', label);
+        }
+    }
+    /** Whether any sensor's devices include this player, by name on the home network. */
+    onAnyDevice(session) {
+        const context = this.context(session);
+        return this.options.sensors.some((s) => (s.config.filters.devices ?? []).some((device) => onDevice(device, context)));
+    }
     scheduleResync() {
         const interval = this.options.config.safetyResyncMs;
         if (interval <= 0 || this.resyncTimer || this.stopped) {
@@ -293,3 +371,4 @@ export class Controller {
         this.options.log.warn('%s: %s', context, describe(error));
     }
 }
+const sameText = (a, b) => a !== undefined && b !== undefined && a.trim().toLowerCase() === b.trim().toLowerCase();

package/dist/diagnostics.js

@@ -1,4 +1,4 @@
-import { appendFile, mkdir, readFile, rename, stat } from 'node:fs/promises';
+import { appendFile, mkdir, open, readFile, rename, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 /*
  * Private values (titles, people, players, command lines) are wrapped in invisible markers when
@@ -147,3 +147,29 @@ export async function readDiagnostics(directory, maxLines = 6_000) {
     const lines = [...await read(PREVIOUS_FILE), ...await read(DIAGNOSTICS_FILE)];
     return lines.slice(-maxLines);
 }
+/** The last `maxLines` lines of the kept log, oldest first, reading only the end of the files. */
+export async function tailDiagnostics(directory, maxLines = 200, maxBytes = 64_000) {
+    const tail = async (name, bytes) => {
+        const file = await open(join(directory, name), 'r').catch(() => undefined);
+        if (!file) {
+            return [];
+        }
+        try {
+            const { size } = await file.stat();
+            const length = Math.min(size, bytes);
+            const buffer = Buffer.alloc(length);
+            await file.read(buffer, 0, length, size - length);
+            const lines = buffer.toString('utf8').split('\n').filter(Boolean);
+            // The first line is likely cut part way unless the whole file was read.
+            return length < size ? lines.slice(1) : lines;
+        }
+        finally {
+            await file.close();
+        }
+    };
+    let lines = await tail(DIAGNOSTICS_FILE, maxBytes);
+    if (lines.length < maxLines) {
+        lines = [...await tail(PREVIOUS_FILE, maxBytes), ...lines];
+    }
+    return lines.slice(-maxLines);
+}

package/dist/platform.js

@@ -18,6 +18,7 @@ import { configFingerprint } from './runtime.js';
 import { SensorAccessory } from './sensors/sensor-accessory.js';
 import { CommandHooks, SensorHub } from './sensors/sensor-hub.js';
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js';
+import { PlayerBook } from './players.js';
 import { serverToken, Storage } from './storage.js';
 const DAY_MS = 24 * 60 * 60 * 1000;
 export class IntermissionPlatform {
@@ -102,6 +103,8 @@ export class IntermissionPlatform {
         }
         this.log.debug('Settings: %s.', describeSettings(this.settings));
         const plexServers = servers.map((server) => new PlexServer({ baseUrl: server.url, token: serverToken(credentials, server.id), clientIdentifier: state.clientIdentifier }));
+        const players = new PlayerBook(storage, (message) => this.log.debug(message));
+        await players.load();
         const libraryTypes = new LibraryTypes(servers.map((server, index) => ({ serverId: server.id, libraries: () => plexServers[index].libraries() })));
         await libraryTypes.refresh();
         servers.forEach((server, index) => {
@@ -119,6 +122,7 @@ export class IntermissionPlatform {
                 hasCredits: (media) => libraryTypes.hasCredits(server.id, media),
                 getFacts: (ratingKey) => plex.facts(ratingKey),
                 sensors: hubs.map((hub) => hub.output(index)),
+                players,
             });
             this.controllers.push(controller);
             controller.start();

package/dist/players.js

@@ -0,0 +1,163 @@
+import { describe } from './errors.js';
+/** Seen players are forgotten after this long without playing. */
+const FORGET_AFTER_MS = 90 * 24 * 60 * 60 * 1000;
+/** Sightings kept per name, and how far back they count. */
+const SIGHTINGS_KEPT = 12;
+const SIGHTINGS_MS = 30 * 24 * 60 * 60 * 1000;
+const key = (name) => name.trim().toLowerCase();
+const same = (a, b) => a !== undefined && b !== undefined && key(a) === key(b);
+/**
+ * Remembers players as they play: name, app, LAN address and whether Plex calls them local.
+ *
+ * - Plex gives an app a new ID when it is reinstalled or signed in again, and some filters hold IDs.
+ *   A new ID with the same name, app and address as a chosen app is followed as it; one with the
+ *   same name and address as an app pinned to a device is followed as that app, whatever the app.
+ * - Addresses are only evidence: an address shared by players on different platforms is not
+ *   trusted (Plex behind Docker Desktop or rootless Docker sees every player at one address).
+ * - A name seen at one address, then another, then the first again belongs to two devices; an
+ *   address change only moves it once.
+ *
+ * Kept in `players.json`; the settings page reads it too.
+ */
+export class PlayerBook {
+    storage;
+    onError;
+    records = emptyRecords();
+    saving = Promise.resolve();
+    constructor(storage, onError = () => undefined) {
+        this.storage = storage;
+        this.onError = onError;
+    }
+    async load(now = new Date()) {
+        this.records = parseRecords(await this.storage.readPlayers().catch(() => undefined));
+        const cutoff = now.getTime() - FORGET_AFTER_MS;
+        for (const [id, player] of Object.entries(this.records.seen)) {
+            if (Date.parse(player.lastPlayedAt) < cutoff) {
+                delete this.records.seen[id];
+                delete this.records.followed[id];
+            }
+        }
+    }
+    /** The chosen players a player is followed as. */
+    followedAs(playerId) {
+        return playerId ? this.records.followed[playerId] ?? [] : [];
+    }
+    get(playerId) {
+        return this.records.seen[playerId];
+    }
+    /** Whether players on one device can be told apart from others by this address. */
+    trusted(address) {
+        if (!address) {
+            return false;
+        }
+        const here = Object.values(this.records.seen).filter((p) => p.address === address);
+        const platforms = new Set(here.flatMap((p) => (p.platform ? [key(p.platform)] : [])));
+        const names = new Set(here.flatMap((p) => (p.name ? [key(p.name)] : [])));
+        return platforms.size <= 1 && names.size <= 2;
+    }
+    /** Whether two devices have been seen reporting this name. */
+    isShared(name) {
+        return name !== undefined && this.records.sharedNames[key(name)] !== undefined;
+    }
+    /**
+     * Records a player that started playing. When it is not chosen, not left out and not yet
+     * followed, returns the chosen players it is followed as from now on (see the class comment).
+     * `pinned` holds apps pinned to devices, which need the same name and address but not the same app.
+     */
+    record(session, chosen, options = {}, now = new Date()) {
+        const { playerId } = session;
+        const before = this.records.seen[playerId];
+        const player = {
+            name: session.playerTitle ?? before?.name,
+            product: session.product ?? before?.product,
+            platform: session.platform ?? before?.platform,
+            address: session.address ?? before?.address,
+            local: session.local ?? before?.local,
+            lastPlayedAt: now.toISOString(),
+        };
+        this.records.seen[playerId] = player;
+        const newlyShared = session.address !== undefined && player.name !== undefined && this.sighting(player.name, session.address, now);
+        let followed = [];
+        if (!chosen.has(playerId) && !(options.ignored ?? []).includes(playerId) && !this.records.followed[playerId]
+            && player.name && session.address && this.trusted(session.address)) {
+            followed = [...chosen].filter((id) => {
+                const other = this.records.seen[id];
+                return other !== undefined && other.address === session.address && same(other.name, player.name)
+                    && (options.pinned?.has(id) === true || same(other.product, player.product));
+            });
+            if (followed.length > 0) {
+                this.records.followed[playerId] = followed;
+            }
+        }
+        this.save();
+        return { followed, newlyShared };
+    }
+    /** Adds a sighting; true when it shows for the first time that two devices report this name. */
+    sighting(name, address, now) {
+        if (!this.trusted(address)) {
+            return false;
+        }
+        const k = key(name);
+        const recent = (this.records.sightings[k] ?? []).filter((s) => now.getTime() - Date.parse(s.at) < SIGHTINGS_MS);
+        if (recent.at(-1)?.address !== address) {
+            recent.push({ address, at: now.toISOString() });
+        }
+        else {
+            recent[recent.length - 1] = { address, at: now.toISOString() };
+        }
+        this.records.sightings[k] = recent.slice(-SIGHTINGS_KEPT);
+        // Back at an address after another one: an address change moves a device once, never back.
+        const earlier = recent.slice(0, -2).some((s) => s.address === address);
+        const wasShared = this.records.sharedNames[k] !== undefined;
+        if (earlier) {
+            this.records.sharedNames[k] = now.toISOString();
+        }
+        return earlier && !wasShared;
+    }
+    save() {
+        const snapshot = structuredClone(this.records);
+        this.saving = this.saving
+            .then(() => this.storage.writePlayers(snapshot))
+            .catch((error) => this.onError(`Could not save players.json: ${describe(error)}`));
+    }
+    /** Resolves once pending writes finish. */
+    flush() {
+        return this.saving;
+    }
+}
+const emptyRecords = () => ({ seen: {}, followed: {}, sightings: {}, sharedNames: {} });
+const object = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : {});
+export function parseRecords(value) {
+    const raw = object(value);
+    const records = emptyRecords();
+    for (const [id, entry] of Object.entries(object(raw.seen))) {
+        const player = object(entry);
+        if (typeof player.lastPlayedAt === 'string') {
+            records.seen[id] = {
+                lastPlayedAt: player.lastPlayedAt,
+                ...Object.fromEntries(['name', 'product', 'platform', 'address']
+                    .filter((k) => typeof player[k] === 'string').map((k) => [k, player[k]])),
+                ...(typeof player.local === 'boolean' ? { local: player.local } : {}),
+            };
+        }
+    }
+    for (const [id, targets] of Object.entries(object(raw.followed))) {
+        if (Array.isArray(targets) && targets.length > 0 && targets.every((t) => typeof t === 'string')) {
+            records.followed[id] = targets;
+        }
+    }
+    for (const [name, list] of Object.entries(object(raw.sightings))) {
+        if (Array.isArray(list)) {
+            records.sightings[name] = list.flatMap((s) => {
+                const sighting = object(s);
+                return typeof sighting.address === 'string' && typeof sighting.at === 'string' ? [{ address: sighting.address, at: sighting.at }] : [];
+            });
+        }
+    }
+    for (const [name, at] of Object.entries(object(raw.sharedNames))) {
+        if (typeof at === 'string') {
+            records.sharedNames[name] = at;
+        }
+    }
+    return records;
+}

package/dist/plex/convert.js

@@ -34,6 +34,7 @@ function toSession(playerId, player, user, metadata) {
         playerTitle: player?.title,
         product: player?.product,
         platform: player?.platform,
+        ...(player?.address ? { address: player.address } : {}),
         user,
         local: toBoolean(player?.local),
         media: toMedia(metadata),

package/dist/plex/discovery.js

@@ -68,6 +68,7 @@ export async function discover(servers, plexTv, accountToken) {
                 name: session.playerTitle,
                 product: session.product,
                 platform: session.platform,
+                address: session.address,
                 playingNow: true,
                 lastUsedAt: Date.now(),
             });