homebridge-plex-intermission 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-23
+
+First public release.
+
+### Playback
+
+- Follows Plex through the server's push notifications and, with Plex Pass, webhooks, using whichever arrives first.
+  No polling.
+- Credits from Plex's credits markers, re-timed on every skip and rewind. Movies and episodes without a marker use 95%
+  of the runtime, or no credits if you turn the fallback off.
+- What counts as the credits, one setting for every sensor: mid-credits scenes count as playing (default), as credits,
+  or only the final credits count.
+- Intros from Plex's intro markers.
+- Pauses under 1.5 seconds and Apple TV skip bursts change nothing.
+- A stop partway through counts after 1 second. A stop in the credits or near the end waits 10 seconds for autoplay,
+  so the next episode, or the movie after a cinema trailer, never passes through Nothing Playing.
+- Sensors keep their state across Homebridge restarts until Plex has been read.
+- Works without Plex Pass, with play noticed at the next progress report. Plex Pass is re-checked daily; when it
+  starts or ends, the log and the settings page say so.
+
+### Sensors
+
+- Occupancy (recommended), motion and contact sensors that are on while something plays, is paused, is in the
+  credits or intro, or while nothing plays, with optional exceptions for the credits and intros.
+- Buttons for one-off events, including the Plex Pass webhook events.
+- Filters by player, person and library, including Live TV.
+- Media conditions: picture shape, resolution, HDR, rating or Plex labels, read from the library item.
+- Presets: Simple, Simple + Credits and Every State (exactly one of four sensors on at a time).
+- Several Plex servers at once.
+- Optional commands, run when a sensor turns on or off or a button is pressed.
+- Runs on its own child bridge by default.
+
+### Settings page
+
+- Sign in with Plex, in a browser window or with a plex.tv/link code.
+- Setup in four steps: servers, Plex Pass and webhooks, players, people and libraries, then a preset.
+- Webhook setup that shows the account's existing webhooks, keeps them, and turns on the server's Webhooks setting.
+- A Guide with the Home automations for your presets, fade recipes made with Convert To Shortcut, and screenshots.
+- Diagnostics: one text file with the setup, the sensors and Intermission's recent log, without the Plex sign-in,
+  tokens, webhook key or public addresses, and with titles and names replaced unless you include them.
+- Reset all settings, or reset Intermission completely.
+
+### Troubleshooting
+
+- The log shows every sensor change with what was playing; Detailed logging adds every Plex report and decision.
+- Intermission keeps its own detailed log whatever the setting, so a problem can be reported without reproducing it.
+- The diagnostics file records the time zone, whether saved settings are running, and whether the bridge is in the
+  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
+[1.0.0]: https://github.com/maxrogers/homebridge-plex-intermission/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxrogers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+<p align="center"><img src="icon.png" width="128" alt="Intermission for Plex"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Intermission for Plex</h1>
+
+<p align="center">Apple Home sensors for every moment of Plex playback, timed to the credits.<br>Lights down when the movie starts, up when the credits roll.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/homebridge-plex-intermission"><img src="https://img.shields.io/npm/v/homebridge-plex-intermission" alt="npm"></a>
+  <a href="https://github.com/maxrogers/homebridge-plex-intermission/actions/workflows/ci.yml"><img src="https://github.com/maxrogers/homebridge-plex-intermission/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT"></a>
+</p>
+
+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.
+
+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.
+
+<p align="center"><img src="docs/settings.png" width="640" alt="The Intermission settings page with the Every State sensors"></p>
+
+## What else it does
+
+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,
+  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.
+
+## Presets
+
+| Preset | Sensors | Good for |
+|---|---|---|
+| Simple | Media Playing | Lights down while anything plays, back up for everything else |
+| Simple + Credits (recommended) | Media Playing, off during the credits | Most living rooms and theaters |
+| Every State | Media Playing, Media Paused, Credits Rolling, Nothing Playing | A different scene for each moment; exactly one sensor is on at a time |
+
+The plugin's **Guide** tab shows the Home automations to make for your preset, with screenshots, including gentle
+fades made with Convert To Shortcut.
+
+## Install
+
+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.
+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.
+
+### Requirements
+
+- Homebridge 2 (Homebridge 1 is not supported)
+- Node.js 22.10 or later, 24 or 26
+- Plex Media Server, signed in to a Plex account
+- For webhooks (Plex Pass), Plex must be able to reach Homebridge on the webhook port, 32550 by default. If Homebridge
+  runs in Docker without host networking, publish that port.
+
+## Plex Pass
+
+Plex Pass on the server owner's account is recommended but not required. Without it:
+
+- Play is noticed with Plex's next progress report, up to about 10 seconds after you press play. Pause, resume, skips,
+  stop and the credits are still instant.
+- Plex doesn't find credits and intro markers for new media. Items that already have markers keep them; others use 95%
+  of the runtime for the credits (you can change or turn off this fallback).
+- Webhook-only events, such as "Marked as watched" and "Added to a library", aren't available for buttons.
+
+If you add Plex Pass later, Intermission notices within a day and offers to set up webhooks.
+
+## How it works
+
+Plex Media Server pushes playback updates over a websocket the moment they happen, and with Plex Pass it also posts
+webhooks. Intermission uses whichever arrives first. When something starts playing, it reads where the credits begin
+and sets a timer for that moment, moving it whenever you skip. Short pauses and skip bursts are ignored, so lights
+never flicker. When playback stops near the end, sensors wait a few seconds in case the next episode autoplays.
+[ARCHITECTURE.md](ARCHITECTURE.md) has the details and the measurements behind them.
+
+## Privacy and security
+
+Your Plex sign-in is stored outside Homebridge's `config.json`, readable only by Homebridge, and never logged.
+Intermission talks only to plex.tv and your Plex servers, with no analytics. See [SECURITY.md](SECURITY.md).
+
+## Troubleshooting
+
+- **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.
+- **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.
+- **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.
+
+## Support
+
+- Found a bug? [Report it](https://github.com/maxrogers/homebridge-plex-intermission/issues/new?template=bug_report.yml)
+  and attach the diagnostics file. Never post your Plex token.
+- Have an idea? [Suggest it](https://github.com/maxrogers/homebridge-plex-intermission/issues/new?template=feature_request.yml).
+- Pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
+- If it makes movie night better, you can [buy me a coffee](https://ko-fi.com/maxrogers).
+
+## Acknowledgements
+
+- [homebridge-plex-credits](https://github.com/DavidD303/homebridge-plex-metadata/tree/credits-aware-playback) by
+  DavidD303, whose credits-marker approach this plugin builds on
+- [homebridge-plex-metadata](https://github.com/davidmuzi/homebridge-plex-metadata) by davidmuzi, which
+  homebridge-plex-credits is based on
+
+## License
+
+[MIT](LICENSE). Not affiliated with or endorsed by Plex, Inc. "Plex" is used only to describe compatibility.

package/config.schema.json

@@ -0,0 +1,19 @@
+{
+  "pluginAlias": "PlexIntermission",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "customUiPath": "./homebridge-ui",
+  "headerDisplay": "Sign-in and sensors are managed in this plugin's own page.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform name",
+        "type": "string",
+        "default": "Intermission",
+        "description": "Shown in the Homebridge log."
+      }
+    }
+  }
+}

package/dist/child-bridge.js

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Homebridge's own child bridge category: Bridge. */
+const BRIDGE_CATEGORY = 2;
+/**
+ * The HomeKit setup URI, computed exactly as HAP-NodeJS does (Accessory.setupURI), so the QR code
+ * Intermission shows is the one the Home app expects.
+ */
+export function setupURI(pincode, category, setupID) {
+    const buffer = Buffer.alloc(8);
+    let low = parseInt(pincode.replace(/-/g, ''), 10);
+    const high = category >> 1;
+    low |= 1 << 28; // Supports IP.
+    buffer.writeUInt32BE(low >>> 0, 4);
+    if (category & 1) {
+        buffer[4] = buffer[4] | (1 << 7);
+    }
+    buffer.writeUInt32BE(high, 0);
+    let payload = (buffer.readUInt32BE(4) + buffer.readUInt32BE(0) * 0x100000000).toString(36).toUpperCase();
+    while (payload.length < 9) {
+        payload = `0${payload}`;
+    }
+    return `X-HM://${payload}${setupID}`;
+}
+/**
+ * Pairing details of Intermission's child bridge, from the file HAP-NodeJS keeps for it in
+ * Homebridge's `persist` folder. The Homebridge UI shows the same code on its own pages.
+ */
+export async function bridgePairing(homebridgeStoragePath, username) {
+    const file = join(homebridgeStoragePath, 'persist', `AccessoryInfo.${username.replace(/:/g, '').toUpperCase()}.json`);
+    let saved;
+    try {
+        saved = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return { published: false, paired: false };
+    }
+    const paired = Object.keys(saved.pairedClients ?? {}).length > 0;
+    if (!saved.pincode || !saved.setupID) {
+        return { published: true, paired };
+    }
+    return { published: true, paired, pincode: saved.pincode, setupURI: setupURI(saved.pincode, saved.category ?? BRIDGE_CATEGORY, saved.setupID) };
+}

package/dist/commands.js

@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process';
+import { commandLine } from './diagnostics.js';
+const PLACEHOLDER = /\{(sensor|state|event|title|type|library|player|user)\}/g;
+const OUTPUT_LIMIT = 4000;
+/** Quotes a value so the shell passes it through as one literal argument. */
+export function shellQuote(value, platform = process.platform) {
+    if (platform === 'win32') {
+        return `"${value.replace(/"/g, '""').replace(/%/g, '%%')}"`;
+    }
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Fills in {placeholders}. Values are quoted, so titles with quotes or `;` can't change the command. */
+export function expandCommand(command, context, platform = process.platform) {
+    return command.replace(PLACEHOLDER, (_match, key) => shellQuote(context[key] ?? '', platform));
+}
+/**
+ * Runs named commands on the Homebridge machine (inside the container when Homebridge runs in
+ * Docker). Each run is independent, limited in time, and logged; failures never affect the sensors.
+ */
+export class CommandRunner {
+    log;
+    timeoutMs;
+    constructor(log, timeoutMs = 30_000) {
+        this.log = log;
+        this.timeoutMs = timeoutMs;
+    }
+    run(command, context) {
+        const line = expandCommand(command.command, context);
+        this.log.debug('Running command "%s": %s', command.name, commandLine(line));
+        return new Promise((resolve) => {
+            let output = '';
+            let timedOut = false;
+            const child = spawn(line, { shell: true, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+            const collect = (chunk) => {
+                if (output.length < OUTPUT_LIMIT) {
+                    output += chunk.toString('utf8').slice(0, OUTPUT_LIMIT - output.length);
+                }
+            };
+            child.stdout.on('data', collect);
+            child.stderr.on('data', collect);
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGKILL');
+            }, this.timeoutMs);
+            let done = false;
+            const finish = (code) => {
+                if (done) {
+                    return;
+                }
+                done = true;
+                clearTimeout(timer);
+                const result = { code, output: output.trim(), timedOut };
+                if (timedOut) {
+                    this.log.warn('Command "%s" took longer than %ds and was stopped.', command.name, Math.round(this.timeoutMs / 1000));
+                }
+                else if (code !== 0) {
+                    this.log.warn('Command "%s" failed (exit %s)%s', command.name, code, result.output ? `: ${result.output.slice(0, 300)}` : '');
+                }
+                else {
+                    this.log.info('Ran command "%s"', command.name);
+                }
+                resolve(result);
+            };
+            child.on('error', (error) => {
+                output += error.message;
+                finish(null);
+            });
+            child.on('close', (code) => finish(code));
+        });
+    }
+}

package/dist/config.js

@@ -0,0 +1,193 @@
+import { DEFAULT_ENGINE_SETTINGS } from './engine/types.js';
+/** Webhook events that only arrive through Plex webhooks (Plex Pass). */
+export const WEBHOOK_EVENTS = [
+    'media.scrobble',
+    'media.rate',
+    'library.new',
+    'library.on.deck',
+    'playback.started',
+    'device.new',
+    'admin.database.backup',
+    'admin.database.corrupted',
+];
+const ENGINE_EVENTS = ['play', 'pause', 'resume', 'stop', 'seek', 'credits.start', 'credits.cancel', 'intro.start', 'intro.end'];
+/**
+ * What a state sensor follows. Playing, Paused and Playing or paused can leave out the credits
+ * and/or the intro (`except`); In the credits and In the intro are those moments themselves.
+ */
+export const STATE_CONDITIONS = ['playing', 'paused', 'active', 'credits', 'intro', 'idle'];
+/** Moments a Playing, Paused or Playing or paused sensor can leave out. */
+export const EXCEPTIONS = ['credits', 'intro'];
+const CAN_EXCEPT = ['playing', 'paused', 'active'];
+export const SENSOR_TYPES = ['occupancy', 'motion', 'contact', 'button'];
+export const DEFAULT_WEBHOOK_PORT = 32550;
+/** Used for movies and episodes that have no credits marker, unless the user turns it off. */
+const DEFAULT_FALLBACK_PERCENT = 95;
+/**
+ * A name the Home app accepts: letters, numbers, spaces and common punctuation, starting and ending
+ * with a letter or number (HAP-NodeJS warns about anything else, and Home may refuse the accessory).
+ */
+export function homeKitName(name, fallback = 'Sensor') {
+    const cleaned = name
+        .replace(/[^\p{L}\p{N}\p{Zs}\u2019'&!._:;()/,-]/gu, '')
+        .replace(/\s+/g, ' ')
+        .replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '');
+    if (cleaned.length >= 2) {
+        return cleaned;
+    }
+    return cleaned ? `${cleaned} ${fallback}` : fallback;
+}
+const asRecord = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : {});
+const asString = (value) => (typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined);
+const asStrings = (value) => (Array.isArray(value) ? value.flatMap((v) => asString(v) ?? []) : []);
+/** A number of seconds from the config, clamped to [min, max] and returned in milliseconds. */
+function seconds(raw, key, fallbackMs, min, max) {
+    const value = raw[key];
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return fallbackMs;
+    }
+    return Math.round(Math.min(max, Math.max(min, value)) * 1000);
+}
+/** Like `seconds`, for a setting stored in minutes. */
+const minutes = (raw, key, fallbackMs, min, max) => seconds(raw, key, fallbackMs / 60, min, max) * 60;
+/**
+ * Reads the platform block of config.json. Unknown or out-of-range values fall back to defaults
+ * or are clamped to the documented ranges; invalid sensors are skipped with a warning.
+ */
+export function parseConfig(raw, log) {
+    const config = asRecord(raw);
+    const timing = asRecord(config.timing);
+    const webhook = asRecord(config.webhook);
+    const fallback = timing.fallbackPercent;
+    const engine = {
+        creditsOffsetMs: seconds(timing, 'creditsOffset', DEFAULT_ENGINE_SETTINGS.creditsOffsetMs, 0, 120),
+        creditsMode: timing.midCredits === 'first' || timing.midCredits === 'final' ? timing.midCredits : 'scenes',
+        fallbackPercent: fallback === null
+            ? null
+            : (typeof fallback === 'number' && Number.isFinite(fallback) ? Math.min(99, Math.max(50, Math.round(fallback))) : DEFAULT_FALLBACK_PERCENT),
+        rearmDistanceMs: seconds(timing, 'rearmDistance', DEFAULT_ENGINE_SETTINGS.rearmDistanceMs, 20, 600),
+        pauseDebounceMs: seconds(timing, 'pauseDebounce', DEFAULT_ENGINE_SETTINGS.pauseDebounceMs, 0, 30),
+        stopHoldMs: seconds(timing, 'stopHold', DEFAULT_ENGINE_SETTINGS.stopHoldMs, 0, 60),
+        minItemLengthMs: seconds(timing, 'minItemLength', DEFAULT_ENGINE_SETTINGS.minItemLengthMs, 0, 3600),
+        seekThresholdMs: DEFAULT_ENGINE_SETTINGS.seekThresholdMs,
+    };
+    // 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;
+    return {
+        name: asString(config.name) ?? 'Intermission',
+        setupId: asString(config.setupId),
+        servers: parseServers(config.servers),
+        sensors: parseSensors(config.sensors, log),
+        webhook: {
+            enabled: webhook.enabled !== false,
+            port: typeof port === 'number' && Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_WEBHOOK_PORT,
+            advertisedUrl: asString(webhook.advertisedUrl),
+        },
+        engine,
+        safetyResyncMs,
+        detailedLogging: config.detailedLogging === true,
+        commands: parseCommands(config.commands),
+    };
+}
+function parseCommands(value) {
+    const section = asRecord(value);
+    if (section.enabled !== true || !Array.isArray(section.list)) {
+        return [];
+    }
+    return section.list.flatMap((entry) => {
+        const command = asRecord(entry);
+        const id = asString(command.id);
+        const name = asString(command.name);
+        const line = asString(command.command);
+        return id && name && line ? [{ id, name, command: line }] : [];
+    });
+}
+function parseServers(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const seen = new Set();
+    return value.flatMap((entry) => {
+        const server = asRecord(entry);
+        const id = asString(server.id);
+        const url = asString(server.url);
+        if (!id || !url || seen.has(id)) {
+            return [];
+        }
+        seen.add(id);
+        return [{ id, name: asString(server.name) ?? 'Plex', url }];
+    });
+}
+function parseMedia(value) {
+    const raw = asRecord(value);
+    const pick = (allowed) => (list) => {
+        const values = asStrings(list).filter((v) => allowed.includes(v));
+        return values.length > 0 ? [...new Set(values)] : undefined;
+    };
+    const strings = (list) => {
+        const values = [...new Set(asStrings(list))];
+        return values.length > 0 ? values : undefined;
+    };
+    const conditions = {
+        shape: raw.shape === 'wide' || raw.shape === 'standard' ? raw.shape : undefined,
+        resolution: pick(['4k', 'hd', 'sd'])(raw.resolution),
+        dynamicRange: pick(['dv', 'hdr', 'sdr'])(raw.dynamicRange),
+        ratings: strings(raw.ratings),
+        labels: strings(raw.labels),
+    };
+    return Object.fromEntries(Object.entries(conditions).filter(([, v]) => v !== undefined));
+}
+export function hasMediaConditions(conditions) {
+    return Object.keys(conditions).length > 0;
+}
+function parseSensors(value, log) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const known = new Set([...ENGINE_EVENTS, ...WEBHOOK_EVENTS]);
+    const seen = new Set();
+    return value.flatMap((entry, index) => {
+        const sensor = asRecord(entry);
+        const id = asString(sensor.id);
+        const given = asString(sensor.name);
+        const type = SENSOR_TYPES.find((t) => t === sensor.type);
+        const name = given && homeKitName(given, type === 'button' ? 'Button' : 'Sensor');
+        if (!id || !name || !type || seen.has(id)) {
+            log.warn('Skipping sensor %d: it needs a unique id, a name and a type.', index + 1);
+            return [];
+        }
+        seen.add(id);
+        const filters = asRecord(sensor.filters);
+        const parsed = {
+            id,
+            name,
+            type,
+            events: [],
+            except: [],
+            run: {
+                on: asStrings(asRecord(sensor.run).on),
+                off: asStrings(asRecord(sensor.run).off),
+                press: asStrings(asRecord(sensor.run).press),
+            },
+            filters: {
+                players: asStrings(filters.players),
+                users: asStrings(filters.users),
+                libraries: asStrings(filters.libraries),
+            },
+            media: type === 'button' ? {} : parseMedia(sensor.media),
+        };
+        if (type === 'button') {
+            parsed.events = asStrings(sensor.events).filter((event) => known.has(event));
+            if (parsed.events.length === 0) {
+                log.warn('Sensor "%s" has no events, so it will never trigger.', name);
+            }
+        }
+        else {
+            parsed.state = STATE_CONDITIONS.find((c) => c === sensor.state) ?? 'playing';
+            const excepted = asStrings(sensor.except).filter((e) => EXCEPTIONS.includes(e));
+            parsed.except = CAN_EXCEPT.includes(parsed.state) ? [...new Set(excepted)] : [];
+        }
+        return [parsed];
+    });
+}