homebridge-bluos 0.1.0

package/config.schema.json

@@ -0,0 +1,135 @@
+{
+  "pluginAlias": "BluOS",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "customUiPath": "./homebridge-ui",
+  "headerDisplay": "Exposes BluOS players to HomeKit as a volume slider, a mute switch, volume-preset switches and a battery sensor. Verified on NAD and Bluesound hardware; other BluOS brands run the same firmware and are expected to work. Use **Discover Players** to find zones on your network; every field below can also be edited by hand.",
+  "footerDisplay": "HomeKit has no speaker volume control that the Home app renders, so the volume slider is exposed as a fan. See the [documentation](https://github.com/tbaur/homebridge-bluos#readme) for what this plugin does and does not do.",
+  "schema": {
+    "type": "object",
+    "required": ["name"],
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "BluOS",
+        "description": "Shown in the Homebridge log."
+      },
+      "options": {
+        "title": "Options",
+        "type": "object",
+        "properties": {
+          "sliderService": {
+            "title": "Volume Slider Style",
+            "type": "string",
+            "default": "fan",
+            "oneOf": [
+              { "title": "Fan — recommended", "enum": ["fan"] },
+              { "title": "Lightbulb — affected by \"turn off all the lights\"", "enum": ["lightbulb"] }
+            ],
+            "description": "Both render an identical slider. A lightbulb is swept up by Siri commands aimed at lights, which can silence or max out your speakers."
+          },
+          "discoveryTimeoutSec": {
+            "title": "Discovery Timeout (seconds)",
+            "type": "integer",
+            "default": 5,
+            "minimum": 1,
+            "maximum": 30,
+            "description": "How long to listen for players. Raise it on a busy or slow network."
+          }
+        }
+      },
+      "devices": {
+        "title": "Players",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "title": "Player",
+          "required": ["id", "name", "host"],
+          "properties": {
+            "id": {
+              "title": "Identity",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}$",
+              "description": "Stable identity, normally the MAC address and zone port. Written by discovery. Changing it detaches the accessories from their HomeKit rooms and automations."
+            },
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "maxLength": 64,
+              "description": "The room's name. Accessories are named from it: \"Study\" gives \"Study Volume\", \"Study Mute\" and \"Study Battery\"."
+            },
+            "host": {
+              "title": "Address",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 254,
+              "pattern": "^[A-Za-z0-9]([A-Za-z0-9._-]{0,252}[A-Za-z0-9])?$",
+              "description": "IP address or hostname. Re-resolved automatically if the player's address changes."
+            },
+            "port": {
+              "title": "Port",
+              "type": "integer",
+              "default": 11000,
+              "minimum": 1,
+              "maximum": 65535,
+              "description": "11000 for a normal player. Multi-zone models such as the NAD CI-S2 and CI 580 use 11010, 11020 and 11030 for their extra zones."
+            },
+            "volumeSlider": {
+              "title": "Volume Slider",
+              "type": "boolean",
+              "default": true,
+              "description": "A 0-100 slider for this player's volume."
+            },
+            "sliderService": {
+              "title": "Slider Style Override",
+              "type": "string",
+              "oneOf": [
+                { "title": "Use the platform setting", "enum": [""] },
+                { "title": "Fan", "enum": ["fan"] },
+                { "title": "Lightbulb", "enum": ["lightbulb"] }
+              ]
+            },
+            "mute": {
+              "title": "Mute Switch",
+              "type": "boolean",
+              "default": false,
+              "description": "A switch that is on when the player is muted. Independent of the slider."
+            },
+            "battery": {
+              "title": "Battery Sensor",
+              "type": "boolean",
+              "default": false,
+              "description": "State of charge. Only for players with a battery pack fitted, such as a PULSE FLEX with the BP100."
+            },
+            "volumePresets": {
+              "title": "Volume Presets",
+              "type": "array",
+              "description": "Switches that set one specific level. Safer than a slider in automations, and addressable by name with Siri.",
+              "items": {
+                "type": "object",
+                "required": ["name", "volume"],
+                "properties": {
+                  "name": {
+                    "title": "Name",
+                    "type": "string",
+                    "maxLength": 64
+                  },
+                  "volume": {
+                    "title": "Volume",
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 100
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/api/client.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview BluOS Custom Integration API client.
+ *
+ * Three scheduling rules are enforced here rather than at the call sites, so no
+ * caller can accidentally violate them:
+ *
+ * 1. At least one second between consecutive requests for the same resource on
+ *    the same endpoint. API v1.7 section 2 requires this of long-polling
+ *    clients, and phrases it as a requirement rather than advice.
+ * 2. At least 100 ms between control calls to one endpoint, so a HomeKit scene
+ *    that touches several tiles at once cannot burst a player.
+ * 3. Writes to one chassis are serialised. A NAD CI-S2 or CI 580 exposes several
+ *    zones on one IP; concurrent writes to `:11000` and `:11010` are writes to
+ *    the same box. Different chassis still run in parallel.
+ *
+ * Note that a chassis and a group are different things. Serialisation above is
+ * per chassis, because that is one piece of hardware; grouping is a logical
+ * relationship between zones that may live on different chassis entirely, and it
+ * is expressed per write through {@link WriteScope}.
+ */
+import type { PlayerObservation, PluginLogger } from '../types';
+import { type HttpGet } from './http';
+import { type VolumeResult } from './sync-status';
+/** Where to reach one player zone. */
+export interface Endpoint {
+    host: string;
+    port: number;
+}
+/**
+ * How far a volume write should reach.
+ *
+ * `tellSlaves` maps to the API's `tell_slaves` parameter. False confines the
+ * write to the addressed zone; true lets a group leader carry its followers with
+ * it, which is what the BluOS app does when you move a leader's slider.
+ *
+ * Defaults to false everywhere, so a caller that has not thought about grouping
+ * gets the conservative answer.
+ */
+export interface WriteScope {
+    tellSlaves: boolean;
+}
+/** Injectable collaborators, so tests need neither sockets nor real clocks. */
+export interface BluOSClientOptions {
+    log: PluginLogger;
+    httpGet?: HttpGet;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Talks to BluOS players over the LAN.
+ *
+ * One instance serves the whole fleet: the rate limits and the per-chassis write
+ * lock are only meaningful if every request goes through the same bookkeeping.
+ */
+export declare class BluOSClient {
+    private readonly log;
+    private readonly httpGet;
+    private readonly now;
+    private readonly sleep;
+    /** Last request time, keyed by `endpoint|resource`, for the one-second rule. */
+    private readonly lastResourceRequest;
+    /** Last control call time, keyed by endpoint. */
+    private readonly lastControlRequest;
+    /** Tail of the write queue for each chassis host. */
+    private readonly chassisWriteQueue;
+    constructor(options: BluOSClientOptions);
+    /** Read `/SyncStatus` once, without long-polling. */
+    readSyncStatus(endpoint: Endpoint): Promise<PlayerObservation>;
+    /**
+     * Long-poll `/SyncStatus`, returning when the player's state changes or the
+     * poll window elapses.
+     *
+     * Measured on firmware 4.16.6: with a current etag the request holds for the
+     * full requested window (15.03 s for `timeout=15`), and with a stale etag it
+     * answers in 44 ms. Verified per-zone rather than per-chassis, so a sibling
+     * zone changing volume does not wake this poll.
+     */
+    pollSyncStatus(endpoint: Endpoint, etag: string, signal?: AbortSignal): Promise<PlayerObservation>;
+    /**
+     * Read `/Volume` without changing anything.
+     *
+     * Not on the polling path: `/SyncStatus` is the source of truth for level and
+     * mute, and it long-polls. This exists for the diagnostic scripts and for
+     * confirming what a player reports when a write result looks wrong.
+     */
+    readVolume(endpoint: Endpoint): Promise<VolumeResult>;
+    /**
+     * Set this zone's absolute level.
+     *
+     * `tell_slaves` is always sent explicitly rather than left to the firmware's
+     * default, because the two answers are both defensible and the caller is the
+     * only one that knows which applies: a tile addressing a zone that leads a
+     * group should move the group, and a tile addressing any other zone must move
+     * nothing else. See {@link WriteScope}.
+     *
+     * The player clamps the level into its own configured dB range, so the result
+     * is authoritative and the caller should adopt it rather than assume the
+     * requested value took effect.
+     */
+    setVolume(endpoint: Endpoint, level: number, scope?: WriteScope): Promise<VolumeResult>;
+    /**
+     * Mute or unmute this zone.
+     *
+     * `mute=1` mutes and `mute=0` unmutes. API v1.7's parameter table in section
+     * 3.1 states the opposite, but sections 3.4 and 3.5, the response attribute
+     * tables, and firmware 4.16.6 all agree with the mapping used here: writing
+     * `mute=1` produced `mute="1" muteVolume="72"` on a real player.
+     */
+    setMute(endpoint: Endpoint, muted: boolean, scope?: WriteScope): Promise<VolumeResult>;
+    private control;
+    /**
+     * Queue work behind anything already writing to this chassis.
+     *
+     * The queue tail is stored per host; failures are swallowed for the purpose of
+     * chaining so one rejected write does not poison later ones, while the
+     * original promise still rejects for its own caller.
+     */
+    private withChassisLock;
+    private respectControlRate;
+    /**
+     * Wait out the API's one-second minimum gap between consecutive requests for
+     * the same resource on the same endpoint.
+     */
+    private respectResourceGap;
+    private get;
+}

package/dist/api/client.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview BluOS Custom Integration API client.
+ *
+ * Three scheduling rules are enforced here rather than at the call sites, so no
+ * caller can accidentally violate them:
+ *
+ * 1. At least one second between consecutive requests for the same resource on
+ *    the same endpoint. API v1.7 section 2 requires this of long-polling
+ *    clients, and phrases it as a requirement rather than advice.
+ * 2. At least 100 ms between control calls to one endpoint, so a HomeKit scene
+ *    that touches several tiles at once cannot burst a player.
+ * 3. Writes to one chassis are serialised. A NAD CI-S2 or CI 580 exposes several
+ *    zones on one IP; concurrent writes to `:11000` and `:11010` are writes to
+ *    the same box. Different chassis still run in parallel.
+ *
+ * Note that a chassis and a group are different things. Serialisation above is
+ * per chassis, because that is one piece of hardware; grouping is a logical
+ * relationship between zones that may live on different chassis entirely, and it
+ * is expressed per write through {@link WriteScope}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BluOSClient = void 0;
+const settings_1 = require("../settings");
+const errors_1 = require("../utils/errors");
+const timing_1 = require("../utils/timing");
+const validators_1 = require("../utils/validators");
+const http_1 = require("./http");
+const identity_1 = require("./identity");
+const sync_status_1 = require("./sync-status");
+/**
+ * Talks to BluOS players over the LAN.
+ *
+ * One instance serves the whole fleet: the rate limits and the per-chassis write
+ * lock are only meaningful if every request goes through the same bookkeeping.
+ */
+class BluOSClient {
+    log;
+    httpGet;
+    now;
+    sleep;
+    /** Last request time, keyed by `endpoint|resource`, for the one-second rule. */
+    lastResourceRequest = new Map();
+    /** Last control call time, keyed by endpoint. */
+    lastControlRequest = new Map();
+    /** Tail of the write queue for each chassis host. */
+    chassisWriteQueue = new Map();
+    constructor(options) {
+        this.log = options.log;
+        this.httpGet = options.httpGet ?? http_1.httpGet;
+        this.now = options.now ?? Date.now;
+        this.sleep = options.sleep ?? timing_1.sleep;
+    }
+    /** Read `/SyncStatus` once, without long-polling. */
+    async readSyncStatus(endpoint) {
+        const body = await this.get({
+            endpoint,
+            resource: 'SyncStatus',
+            query: {},
+            totalTimeoutMs: settings_1.STATUS_TIMEOUT_MS,
+        });
+        return (0, sync_status_1.parseSyncStatus)(body, (0, identity_1.formatEndpoint)(endpoint.host, endpoint.port));
+    }
+    /**
+     * Long-poll `/SyncStatus`, returning when the player's state changes or the
+     * poll window elapses.
+     *
+     * Measured on firmware 4.16.6: with a current etag the request holds for the
+     * full requested window (15.03 s for `timeout=15`), and with a stale etag it
+     * answers in 44 ms. Verified per-zone rather than per-chassis, so a sibling
+     * zone changing volume does not wake this poll.
+     */
+    async pollSyncStatus(endpoint, etag, signal) {
+        const body = await this.get({
+            endpoint,
+            resource: 'SyncStatus',
+            query: { timeout: String(settings_1.LONG_POLL_SEC), etag },
+            totalTimeoutMs: settings_1.LONG_POLL_SEC * 1_000 + settings_1.LONG_POLL_READ_SLACK_MS,
+            signal,
+        });
+        return (0, sync_status_1.parseSyncStatus)(body, (0, identity_1.formatEndpoint)(endpoint.host, endpoint.port));
+    }
+    /**
+     * Read `/Volume` without changing anything.
+     *
+     * Not on the polling path: `/SyncStatus` is the source of truth for level and
+     * mute, and it long-polls. This exists for the diagnostic scripts and for
+     * confirming what a player reports when a write result looks wrong.
+     */
+    async readVolume(endpoint) {
+        const body = await this.get({
+            endpoint,
+            resource: 'Volume',
+            query: {},
+            totalTimeoutMs: settings_1.STATUS_TIMEOUT_MS,
+        });
+        return (0, sync_status_1.parseVolume)(body);
+    }
+    /**
+     * Set this zone's absolute level.
+     *
+     * `tell_slaves` is always sent explicitly rather than left to the firmware's
+     * default, because the two answers are both defensible and the caller is the
+     * only one that knows which applies: a tile addressing a zone that leads a
+     * group should move the group, and a tile addressing any other zone must move
+     * nothing else. See {@link WriteScope}.
+     *
+     * The player clamps the level into its own configured dB range, so the result
+     * is authoritative and the caller should adopt it rather than assume the
+     * requested value took effect.
+     */
+    async setVolume(endpoint, level, scope = { tellSlaves: false }) {
+        if (!Number.isInteger(level) || level < settings_1.VOLUME_MIN || level > settings_1.VOLUME_MAX) {
+            throw new RangeError(`volume must be an integer ${settings_1.VOLUME_MIN}-${settings_1.VOLUME_MAX}, got ${level}`);
+        }
+        return this.control(endpoint, {
+            level: String(level),
+            tell_slaves: scope.tellSlaves ? '1' : '0',
+        });
+    }
+    /**
+     * Mute or unmute this zone.
+     *
+     * `mute=1` mutes and `mute=0` unmutes. API v1.7's parameter table in section
+     * 3.1 states the opposite, but sections 3.4 and 3.5, the response attribute
+     * tables, and firmware 4.16.6 all agree with the mapping used here: writing
+     * `mute=1` produced `mute="1" muteVolume="72"` on a real player.
+     */
+    async setMute(endpoint, muted, scope = { tellSlaves: false }) {
+        return this.control(endpoint, {
+            mute: muted ? '1' : '0',
+            tell_slaves: scope.tellSlaves ? '1' : '0',
+        });
+    }
+    async control(endpoint, query) {
+        // Serialised per chassis: zones of a multi-zone player share one box.
+        return this.withChassisLock(endpoint.host, async () => {
+            await this.respectControlRate(endpoint);
+            const body = await this.get({
+                endpoint,
+                resource: 'Volume',
+                query,
+                totalTimeoutMs: settings_1.CONTROL_TIMEOUT_MS,
+            });
+            return (0, sync_status_1.parseVolume)(body);
+        });
+    }
+    /**
+     * Queue work behind anything already writing to this chassis.
+     *
+     * The queue tail is stored per host; failures are swallowed for the purpose of
+     * chaining so one rejected write does not poison later ones, while the
+     * original promise still rejects for its own caller.
+     */
+    async withChassisLock(host, work) {
+        const previous = this.chassisWriteQueue.get(host) ?? Promise.resolve();
+        const run = previous.then(work, work);
+        this.chassisWriteQueue.set(host, run.catch(() => undefined));
+        try {
+            return await run;
+        }
+        finally {
+            // Only clear if nothing else queued behind us in the meantime.
+            if (this.chassisWriteQueue.get(host) === run) {
+                this.chassisWriteQueue.delete(host);
+            }
+        }
+    }
+    async respectControlRate(endpoint) {
+        const key = (0, identity_1.formatEndpoint)(endpoint.host, endpoint.port);
+        const last = this.lastControlRequest.get(key);
+        const elapsed = last === undefined ? Number.POSITIVE_INFINITY : this.now() - last;
+        if (elapsed < settings_1.CONTROL_RATE_LIMIT_MS) {
+            await this.sleep(settings_1.CONTROL_RATE_LIMIT_MS - elapsed);
+        }
+        this.lastControlRequest.set(key, this.now());
+    }
+    /**
+     * Wait out the API's one-second minimum gap between consecutive requests for
+     * the same resource on the same endpoint.
+     */
+    async respectResourceGap(key) {
+        const last = this.lastResourceRequest.get(key);
+        const elapsed = last === undefined ? Number.POSITIVE_INFINITY : this.now() - last;
+        if (elapsed < settings_1.SAME_RESOURCE_MIN_GAP_MS) {
+            await this.sleep(settings_1.SAME_RESOURCE_MIN_GAP_MS - elapsed);
+        }
+        this.lastResourceRequest.set(key, this.now());
+    }
+    async get(request) {
+        const { endpoint, resource, query, totalTimeoutMs, signal } = request;
+        const target = (0, identity_1.formatEndpoint)(endpoint.host, endpoint.port);
+        // The same check the settings page and the configuration validator apply.
+        // Shared rather than restated: two copies of the one defence against a
+        // configuration or cache value altering a request URL would eventually
+        // disagree, and the disagreement would be the security regression.
+        if (!(0, validators_1.isValidHost)(endpoint.host)) {
+            throw new errors_1.ConnectionError(`refusing to contact an invalid host: ${JSON.stringify(endpoint.host)}`);
+        }
+        await this.respectResourceGap(`${target}|${resource}`);
+        const search = new URLSearchParams(query).toString();
+        const url = `http://${target}/${resource}${search.length > 0 ? `?${search}` : ''}`;
+        // Safe to log unsanitised, and the only place in the plugin where wire data
+        // reaches a log line without passing through forLog: the query carries a
+        // player-supplied etag, which URLSearchParams percent-encodes, so no control
+        // character can reach the log. Templating the query by hand would reintroduce
+        // log injection.
+        this.log.debug(`GET ${url}`);
+        const response = await this.httpGet(url, {
+            connectTimeoutMs: settings_1.CONNECT_TIMEOUT_MS,
+            totalTimeoutMs,
+            maxBytes: settings_1.MAX_XML_BYTES,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (response.status !== 200) {
+            throw new errors_1.ProtocolError(`${resource} on ${target} answered HTTP ${response.status}`);
+        }
+        return response.body;
+    }
+}
+exports.BluOSClient = BluOSClient;

package/dist/api/discovery.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview mDNS discovery of BluOS zones.
+ *
+ * Two service types are browsed, because a multi-zone chassis advertises each
+ * zone separately: `_musc._tcp` for primary zones and `_musp._tcp` for the
+ * secondaries of a CI-S2 or CI 580. API v1.7 section 1 is explicit that the port
+ * "should be discovered by use of the MDNS protocol using the services musc.tcp
+ * and musp.tcp", and only the SRV record knows whether a zone is on 11000,
+ * 11010, 11020 or 11030.
+ *
+ * The appendix also describes LSDP, a UDP-broadcast alternative that Lenbrook
+ * says is more reliable than multicast on consumer networks. It is not
+ * implemented: on the network this plugin was developed against, mDNS returned
+ * every zone with full metadata while LSDP returned nothing at all, twice —
+ * first with a global broadcast and then with per-interface subnet broadcasts
+ * and an all-classes query. LSDP also never carries a zone's port, so it could
+ * not replace this path even where it does answer. Manual entry by address
+ * covers networks where multicast is filtered.
+ *
+ * Nothing here is trusted: an endpoint only counts as a player once it has
+ * answered `/SyncStatus`, which is also where authoritative identity comes from.
+ */
+import type { Answer, Question } from 'dns-packet';
+import type { DiscoveredPlayer, PluginLogger } from '../types';
+import type { BluOSClient, Endpoint } from './client';
+/** An mDNS response packet, narrowed to the parts used here. */
+export interface MdnsPacket {
+    answers?: Answer[];
+    additionals?: Answer[];
+}
+/** Where a packet came from. Used as a fallback when no A record is offered. */
+export interface MdnsRemote {
+    address: string;
+}
+/**
+ * The slice of `multicast-dns` this module needs.
+ *
+ * Declared structurally so a test can supply a fake without a socket, and so a
+ * future move to a different mDNS implementation does not ripple outwards.
+ */
+export interface MdnsSession {
+    on(event: 'response', listener: (packet: MdnsPacket, remote: MdnsRemote) => void): void;
+    /**
+     * `error` is fatal for the session (the socket could not be bound); `warning`
+     * covers recoverable trouble such as an undecodable packet. Both must be
+     * subscribed, because an unheard `error` on an EventEmitter is thrown, and a
+     * throw here would take Homebridge down with it.
+     */
+    on(event: 'error' | 'warning', listener: (error: Error) => void): void;
+    query(request: {
+        questions: Question[];
+    }): void;
+    destroy(callback?: () => void): void;
+}
+/** Creates an mDNS session. */
+export type MdnsFactory = () => MdnsSession;
+/** Injectable collaborators for {@link BluOSDiscovery}. */
+export interface DiscoveryOptions {
+    log: PluginLogger;
+    client: BluOSClient;
+    createMdns?: MdnsFactory;
+}
+/** Discovers BluOS zones and confirms them against the API. */
+export declare class BluOSDiscovery {
+    private readonly log;
+    private readonly client;
+    private readonly createMdns;
+    /** Live browse windows, so a shutdown does not have to wait one out. */
+    private readonly openWindows;
+    private cancelled;
+    constructor(options: DiscoveryOptions);
+    /**
+     * Abandon every browse in flight and refuse any that start afterwards.
+     *
+     * A browse window is a referenced timer holding a bound multicast socket, so
+     * without this a shutdown during an address re-resolution keeps the Homebridge
+     * process alive for the rest of the window — up to 30 s per unreachable
+     * player. One-way by design: it is only called when the platform is stopping.
+     */
+    cancelAll(): void;
+    /**
+     * Browse for zones and return the ones that answer `/SyncStatus`.
+     *
+     * Failures are logged and skipped rather than thrown: a single unreachable
+     * player must not deny the user the rest of the fleet.
+     */
+    discover(timeoutSec: number): Promise<DiscoveredPlayer[]>;
+    /**
+     * Verify candidates a few at a time.
+     *
+     * Verification opens a connection and holds it for up to the status timeout,
+     * and nothing throttles distinct endpoints against each other, so verifying
+     * every advertisement at once would let whatever answered the browse decide how
+     * many sockets this plugin opens at one moment.
+     */
+    private verifyAll;
+    /**
+     * Find the current address of an already-known player.
+     *
+     * Called at launch and after a player goes silent, so a DHCP lease change does
+     * not require the user to re-save configuration.
+     */
+    resolveEndpoint(playerId: string, timeoutSec: number): Promise<Endpoint | undefined>;
+    /** Probe one endpoint directly, for the UI's manual-entry path. */
+    probe(endpoint: Endpoint): Promise<DiscoveredPlayer | undefined>;
+    private verify;
+    /**
+     * Turn service instances into addressable endpoints.
+     *
+     * A zone is only usable once its SRV record (for the port) and an IPv4 address
+     * are both known. The address comes from an A record when one was offered, and
+     * otherwise from the responder's own source address, which for a player
+     * advertising its own service is the same machine.
+     */
+    private toEndpoints;
+    /** Collect mDNS records for the configured window. */
+    private browse;
+}
+/**
+ * Default mDNS session.
+ *
+ * `loopback: false` stops us from answering our own queries, and the require is
+ * deferred so that importing this module — which the config UI does — cannot
+ * fail merely because a socket could not be bound.
+ *
+ * Interfaces are enumerated up front because `multicast-dns` does the same from
+ * inside its `listening` handler, where a throw would surface as an uncaught
+ * exception instead of a failed call. Doing it here keeps the failure catchable
+ * by {@link BluOSDiscovery.browse}, which degrades to "discovery unavailable".
+ */
+export declare const defaultMdnsFactory: MdnsFactory;