homebridge-bluos 0.1.0

package/dist/devices/base-accessory.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Shared accessory behaviour: honesty about unknown state, and
+ * writes that answer HomeKit inside its patience.
+ *
+ * Two rules are implemented once, here, because getting either wrong produces
+ * bugs that are very hard to diagnose from a user's description.
+ *
+ * Never guess a characteristic value. Until a player has actually been read, and
+ * whenever it has stopped answering, reads fail with
+ * `SERVICE_COMMUNICATION_FAILURE` so the Home app shows No Response. A plausible
+ * default is worse than no answer: it makes automations fire against fiction.
+ *
+ * Never let a write outlive HomeKit's patience. HAP-NodeJS warns at three
+ * seconds and abandons a write at nine, discarding the eventual result. A set
+ * handler therefore returns within {@link HOMEKIT_WRITE_BUDGET_MS} and finishes
+ * anything slower in the background, where its outcome still reaches HomeKit
+ * through the normal update path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAccessory = void 0;
+const settings_1 = require("../settings");
+const utils_1 = require("../utils");
+/** Base class for every accessory this plugin exposes. */
+class BaseAccessory {
+    host;
+    accessory;
+    context;
+    /** True once a real observation has been applied. */
+    observed = false;
+    /** True while the player is not answering. */
+    offline = false;
+    /** Throttles repeated warnings about the same persistent failure. */
+    lastWarningAt = 0;
+    /** Ensures a one-time explanation is logged only once. */
+    warnedOnce = new Set();
+    constructor(init) {
+        this.host = init.host;
+        this.accessory = init.accessory;
+        this.context = init.context;
+        this.configureAccessoryInformation();
+    }
+    get deviceId() {
+        return this.context.deviceId;
+    }
+    get displayName() {
+        return this.accessory.displayName;
+    }
+    /** Apply a fresh observation, and remember that state is now known. */
+    applyObservation(observation, reason) {
+        this.offline = false;
+        this.observed = true;
+        this.lastWarningAt = 0;
+        this.refreshAccessoryInformation(observation);
+        this.updateFromObservation(observation, reason);
+    }
+    /**
+     * Report that the player could not be reached.
+     *
+     * Characteristic values are left untouched rather than zeroed: HomeKit is told
+     * the accessory is unreachable, and inventing a value on the way out would
+     * defeat that.
+     */
+    noteUnreachable(error) {
+        const wasOnline = !this.offline;
+        this.offline = true;
+        const now = Date.now();
+        if (wasOnline || now - this.lastWarningAt > settings_1.POLL_FAILURE_REWARN_MS) {
+            this.lastWarningAt = now;
+            // The player id is included because two accessories may legitimately share a
+            // display name, and this is the line a user pastes into a bug report.
+            this.host.log.warn(`${(0, utils_1.forLog)(this.displayName)} [${(0, utils_1.forLog)(this.deviceId)}] is not responding: `
+                + (0, utils_1.describeError)(error));
+        }
+        else {
+            this.host.log.debug(`${(0, utils_1.forLog)(this.displayName)} [${(0, utils_1.forLog)(this.deviceId)}] still not responding: `
+                + (0, utils_1.describeError)(error));
+        }
+        this.markUnavailable();
+    }
+    /** True once this accessory has seen a real reading. */
+    hasObservedState() {
+        return this.observed && !this.offline;
+    }
+    /**
+     * The error to return from a read when the true value is unknown.
+     *
+     * `SERVICE_COMMUNICATION_FAILURE` is what makes the Home app render No
+     * Response, which is the honest answer before the first successful poll.
+     */
+    communicationFailure() {
+        return new this.host.hap.HapStatusError(-70402 /* this.host.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE */);
+    }
+    /** Throw if this accessory has no observed state to report. */
+    requireObservedState() {
+        if (!this.hasObservedState()) {
+            throw this.communicationFailure();
+        }
+    }
+    /**
+     * How far this accessory's volume writes should reach.
+     *
+     * A zone that leads a group carries its followers with it, matching what the
+     * BluOS app does when you move a leader's slider: the tile is the group's
+     * control while the group exists. Every other zone — standalone, or a follower
+     * addressed directly — moves alone, because a tile labelled one room must not
+     * quietly change another.
+     *
+     * Derived from the last observation rather than remembered, so ungrouping takes
+     * effect on the next poll without any bookkeeping here. When a player reports
+     * no grouping at all the answer is false, which is the pre-grouping behaviour.
+     */
+    writeScope() {
+        const leads = this.host.observationFor(this.deviceId)?.syncRole === 'primary';
+        return { tellSlaves: leads };
+    }
+    /** One info line after a HomeKit write reached the player. */
+    logAction(action, scope) {
+        const suffix = scope.tellSlaves ? ' (group)' : '';
+        this.host.log.info(`${(0, utils_1.forLog)(this.displayName)}: ${action}${suffix}`);
+    }
+    /** Log an explanation the first time a condition is met, then stay quiet. */
+    warnOnce(key, message) {
+        if (this.warnedOnce.has(key)) {
+            this.host.log.debug(message);
+            return;
+        }
+        this.warnedOnce.add(key);
+        this.host.log.warn(message);
+    }
+    /**
+     * Run a HomeKit write, returning once it finishes or the budget expires.
+     *
+     * Slow work is not cancelled when the budget runs out, only stopped being
+     * waited on: the player will still apply the change, and the resulting state
+     * reaches HomeKit through the poll that our own write triggers.
+     */
+    async completeWithinBudget(label, work) {
+        let finished = false;
+        const tracked = work()
+            .catch((error) => {
+            this.host.log.warn(`${(0, utils_1.forLog)(this.displayName)} ${label} failed: ${(0, utils_1.describeError)(error)}`);
+            if (!finished) {
+                // Surfaces to HomeKit as a failed write when we are still inside the
+                // budget; afterwards HAP has stopped listening and the log is all we
+                // have, which is why the message above is unconditional.
+                throw error;
+            }
+        })
+            .finally(() => {
+            finished = true;
+        });
+        const outcome = await (0, utils_1.raceTimeout)(tracked, settings_1.HOMEKIT_WRITE_BUDGET_MS);
+        if (outcome === utils_1.TIMED_OUT) {
+            this.host.log.debug(`${(0, utils_1.forLog)(this.displayName)} ${label} exceeded ${settings_1.HOMEKIT_WRITE_BUDGET_MS}ms; `
+                + 'completing in the background');
+            // Prevents an unhandled rejection once nothing is awaiting this any more.
+            tracked.catch(() => undefined);
+        }
+    }
+    /**
+     * The service this accessory's state lives on, created if necessary.
+     *
+     * Reusing a restored service rather than replacing it is what preserves the
+     * user's HomeKit room assignment, name and automations across a restart.
+     */
+    requireService(type) {
+        // Matched by UUID against the restored service list rather than through
+        // `getService`, whose generic signature does not admit a concrete service
+        // subclass without a cast.
+        const existing = this.accessory.services.find((service) => service.UUID === type.UUID);
+        return existing ?? this.accessory.addService(new type(this.displayName));
+    }
+    /**
+     * Remove a service this accessory no longer represents.
+     *
+     * Needed when a setting changes which service carries the state, since the
+     * accessory itself is adopted rather than recreated and would otherwise keep
+     * both — one of them unbound to any handler.
+     */
+    dropService(type) {
+        const stale = this.accessory.services.find((service) => service.UUID === type.UUID);
+        if (stale === undefined) {
+            return;
+        }
+        this.host.log.info(`${(0, utils_1.forLog)(this.displayName)} changed control style; removing the previous control`);
+        this.accessory.removeService(stale);
+    }
+    /**
+     * Publish identity to HomeKit.
+     *
+     * SerialNumber is the opaque generated value rather than the player's MAC: the
+     * Home app displays it, so it ends up in screenshots and bug reports, and on a
+     * multi-zone chassis a MAC is shared between zones anyway.
+     */
+    configureAccessoryInformation() {
+        const { Characteristic, Service: HapService } = this.host.hap;
+        const information = this.accessory.getService(HapService.AccessoryInformation)
+            ?? this.accessory.addService(HapService.AccessoryInformation);
+        information
+            .setCharacteristic(Characteristic.Manufacturer, this.context.brand)
+            .setCharacteristic(Characteristic.Model, this.context.model)
+            .setCharacteristic(Characteristic.SerialNumber, this.context.serialNumber)
+            .setCharacteristic(Characteristic.FirmwareRevision, this.host.pluginVersion)
+            .setCharacteristic(Characteristic.Name, this.displayName);
+    }
+    /** Update identity from a live reading, when the player knows better. */
+    refreshAccessoryInformation(observation) {
+        const { Characteristic, Service: HapService } = this.host.hap;
+        const information = this.accessory.getService(HapService.AccessoryInformation);
+        if (information === undefined) {
+            return;
+        }
+        // Sanitised on the way in, exactly like the same fields from configuration:
+        // these come off the wire from an unauthenticated endpoint, they can be as
+        // long as the whole response body, and they land in HomeKit characteristics
+        // and in the on-disk accessory cache.
+        const brand = observation.brand === undefined ? undefined : (0, utils_1.forDisplay)(observation.brand);
+        const rawModel = observation.modelName ?? observation.model;
+        const model = rawModel === undefined ? undefined : (0, utils_1.forDisplay)(rawModel);
+        if (brand !== undefined && brand !== this.context.brand) {
+            this.context.brand = brand;
+            information.updateCharacteristic(Characteristic.Manufacturer, brand);
+        }
+        if (model !== undefined && model !== this.context.model) {
+            this.context.model = model;
+            information.updateCharacteristic(Characteristic.Model, model);
+        }
+    }
+}
+exports.BaseAccessory = BaseAccessory;

package/dist/devices/battery-accessory.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview State of charge for a portable player.
+ *
+ * `/SyncStatus` already carries `<battery level charging/>` on players with a
+ * battery pack fitted, so this costs one service and no extra traffic. A player
+ * without a pack never reports the element, and the accessory then reports No
+ * Response rather than inventing a charge level.
+ */
+import type { PlayerObservation, RefreshReason } from '../types';
+import { BaseAccessory, type AccessoryInit } from './base-accessory';
+/** A battery sensor for one player. */
+export declare class BatteryAccessory extends BaseAccessory {
+    private readonly service;
+    private level;
+    private charging;
+    constructor(init: AccessoryInit);
+    private readLevel;
+    private readLowBattery;
+    private readChargingState;
+    private requireBattery;
+    protected updateFromObservation(observation: PlayerObservation, _reason: RefreshReason): void;
+    protected markUnavailable(): void;
+}

package/dist/devices/battery-accessory.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview State of charge for a portable player.
+ *
+ * `/SyncStatus` already carries `<battery level charging/>` on players with a
+ * battery pack fitted, so this costs one service and no extra traffic. A player
+ * without a pack never reports the element, and the accessory then reports No
+ * Response rather than inventing a charge level.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatteryAccessory = void 0;
+const utils_1 = require("../utils");
+const base_accessory_1 = require("./base-accessory");
+/** Below this percentage HomeKit is told the battery is low. */
+const LOW_BATTERY_THRESHOLD = 20;
+/** A battery sensor for one player. */
+class BatteryAccessory extends base_accessory_1.BaseAccessory {
+    service;
+    level;
+    charging = false;
+    constructor(init) {
+        super(init);
+        const { Characteristic: Char, Service: HapService } = this.host.hap;
+        this.service = this.requireService(HapService.Battery);
+        this.service.setCharacteristic(Char.Name, this.displayName);
+        this.service.getCharacteristic(Char.BatteryLevel).onGet(() => this.readLevel());
+        this.service.getCharacteristic(Char.StatusLowBattery).onGet(() => this.readLowBattery());
+        this.service.getCharacteristic(Char.ChargingState).onGet(() => this.readChargingState());
+    }
+    readLevel() {
+        this.requireBattery();
+        return this.level ?? 0;
+    }
+    readLowBattery() {
+        this.requireBattery();
+        const { Characteristic: Char } = this.host.hap;
+        return (this.level ?? 100) <= LOW_BATTERY_THRESHOLD
+            ? Char.StatusLowBattery.BATTERY_LEVEL_LOW
+            : Char.StatusLowBattery.BATTERY_LEVEL_NORMAL;
+    }
+    readChargingState() {
+        this.requireBattery();
+        const { Characteristic: Char } = this.host.hap;
+        return this.charging ? Char.ChargingState.CHARGING : Char.ChargingState.NOT_CHARGING;
+    }
+    requireBattery() {
+        this.requireObservedState();
+        if (this.level === undefined) {
+            throw this.communicationFailure();
+        }
+    }
+    updateFromObservation(observation, _reason) {
+        const battery = observation.battery;
+        if (battery === undefined) {
+            if (this.level !== undefined) {
+                this.level = undefined;
+            }
+            this.warnOnce('no-battery', `${(0, utils_1.forLog)(this.displayName)} reports no battery pack; disable the battery sensor `
+                + 'for this player in the plugin settings');
+            this.markUnavailable();
+            return;
+        }
+        this.level = battery.level;
+        this.charging = battery.charging;
+        const { Characteristic: Char } = this.host.hap;
+        this.service.updateCharacteristic(Char.BatteryLevel, battery.level);
+        this.service.updateCharacteristic(Char.StatusLowBattery, battery.level <= LOW_BATTERY_THRESHOLD
+            ? Char.StatusLowBattery.BATTERY_LEVEL_LOW
+            : Char.StatusLowBattery.BATTERY_LEVEL_NORMAL);
+        this.service.updateCharacteristic(Char.ChargingState, battery.charging ? Char.ChargingState.CHARGING : Char.ChargingState.NOT_CHARGING);
+    }
+    markUnavailable() {
+        const { Characteristic: Char } = this.host.hap;
+        const error = this.communicationFailure();
+        this.service.updateCharacteristic(Char.BatteryLevel, error);
+        this.service.updateCharacteristic(Char.StatusLowBattery, error);
+        this.service.updateCharacteristic(Char.ChargingState, error);
+    }
+}
+exports.BatteryAccessory = BatteryAccessory;

package/dist/devices/host.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The contract between an accessory and the platform.
+ *
+ * Accessories depend on this narrow interface rather than on the platform class,
+ * which keeps the import graph acyclic and lets a test drive an accessory with a
+ * handful of stubs instead of a whole platform.
+ */
+import type { HAP, PlatformAccessory } from 'homebridge';
+import type { BluOSClient, Endpoint } from '../api/client';
+import type { PlayerObservation, PluginLogger } from '../types';
+import type { VolumeResult } from '../api/sync-status';
+/** What an accessory may ask of the platform. */
+export interface AccessoryHost {
+    readonly log: PluginLogger;
+    readonly hap: HAP;
+    /** Shared client, so every request goes through one set of rate limits. */
+    readonly client: BluOSClient;
+    /** Plugin version, reported to HomeKit as FirmwareRevision. */
+    readonly pluginVersion: string;
+    /** Current address of a player, or undefined when it is not configured. */
+    endpointFor(deviceId: string): Endpoint | undefined;
+    /** Latest observation for a player, if one has been made since launch. */
+    observationFor(deviceId: string): PlayerObservation | undefined;
+    /**
+     * Adopt the authoritative state returned by a write.
+     *
+     * Also invalidates any long-poll response already in flight for that player,
+     * so a reply that was computed before the write cannot overwrite the result of
+     * it. This is the whole set/poll race defence, and it lives here so that every
+     * accessory gets it without having to reimplement it.
+     */
+    adoptWriteResult(deviceId: string, result: VolumeResult): void;
+    /**
+     * Persist accessory context after a change worth surviving a restart.
+     *
+     * Pass the accessory whose context changed. Omitting it rewrites the context of
+     * every active accessory, which is only wanted when several changed at once.
+     */
+    persistContext(accessory?: PlatformAccessory): void;
+}

package/dist/devices/host.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The contract between an accessory and the platform.
+ *
+ * Accessories depend on this narrow interface rather than on the platform class,
+ * which keeps the import graph acyclic and lets a test drive an accessory with a
+ * handful of stubs instead of a whole platform.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/devices/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Devices barrel.
+ */
+export * from './base-accessory';
+export * from './battery-accessory';
+export * from './host';
+export * from './mute-accessory';
+export * from './volume-accessory';
+export * from './volume-preset-accessory';

package/dist/devices/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Devices barrel.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base-accessory"), exports);
+__exportStar(require("./battery-accessory"), exports);
+__exportStar(require("./host"), exports);
+__exportStar(require("./mute-accessory"), exports);
+__exportStar(require("./volume-accessory"), exports);
+__exportStar(require("./volume-preset-accessory"), exports);

package/dist/devices/mute-accessory.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The mute switch.
+ *
+ * On means muted, which reads correctly in an automation: "turn on Study Mute"
+ * silences the study.
+ *
+ * Mute is deliberately kept independent of the volume slider. Switching the
+ * slider off writes level zero instead of muting, so the two controls never fight
+ * over one piece of state, and a scene can mute a room without disturbing the
+ * level it will return to. That works because the player remembers the pre-mute
+ * level itself: measured on firmware 4.16.6, `mute=1` reports
+ * `volume="0" muteVolume="72"` and unmuting restores 72 unaided.
+ *
+ * Muting a zone that leads a group mutes the group, for the same reason its
+ * slider moves the group: while the group exists, the leader's tile is the
+ * group's control. Muting a follower directly silences only that follower.
+ */
+import type { PlayerObservation, RefreshReason } from '../types';
+import { BaseAccessory, type AccessoryInit } from './base-accessory';
+/** A mute switch for one player. */
+export declare class MuteAccessory extends BaseAccessory {
+    private readonly service;
+    /** Last mute state read from the player. */
+    private muted;
+    constructor(init: AccessoryInit);
+    private readOn;
+    private writeOn;
+    protected updateFromObservation(observation: PlayerObservation, _reason: RefreshReason): void;
+    protected markUnavailable(): void;
+}

package/dist/devices/mute-accessory.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The mute switch.
+ *
+ * On means muted, which reads correctly in an automation: "turn on Study Mute"
+ * silences the study.
+ *
+ * Mute is deliberately kept independent of the volume slider. Switching the
+ * slider off writes level zero instead of muting, so the two controls never fight
+ * over one piece of state, and a scene can mute a room without disturbing the
+ * level it will return to. That works because the player remembers the pre-mute
+ * level itself: measured on firmware 4.16.6, `mute=1` reports
+ * `volume="0" muteVolume="72"` and unmuting restores 72 unaided.
+ *
+ * Muting a zone that leads a group mutes the group, for the same reason its
+ * slider moves the group: while the group exists, the leader's tile is the
+ * group's control. Muting a follower directly silences only that follower.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MuteAccessory = void 0;
+const utils_1 = require("../utils");
+const base_accessory_1 = require("./base-accessory");
+/** A mute switch for one player. */
+class MuteAccessory extends base_accessory_1.BaseAccessory {
+    service;
+    /** Last mute state read from the player. */
+    muted;
+    constructor(init) {
+        super(init);
+        const { Characteristic: Char, Service: HapService } = this.host.hap;
+        this.service = this.requireService(HapService.Switch);
+        this.service.setCharacteristic(Char.Name, this.displayName);
+        this.service
+            .getCharacteristic(Char.On)
+            .onGet(() => this.readOn())
+            .onSet(async (value) => this.writeOn(value));
+    }
+    readOn() {
+        this.requireObservedState();
+        return this.muted === true;
+    }
+    async writeOn(value) {
+        const shouldMute = value === true;
+        await this.completeWithinBudget('mute write', async () => {
+            const endpoint = this.host.endpointFor(this.deviceId);
+            if (endpoint === undefined) {
+                throw new Error('player is no longer configured');
+            }
+            const scope = this.writeScope();
+            const result = await this.host.client.setMute(endpoint, shouldMute, scope);
+            this.host.adoptWriteResult(this.deviceId, result);
+            this.logAction(shouldMute ? 'ON' : 'OFF', scope);
+            if (result.muted !== shouldMute) {
+                this.warnOnce('mute-refused', `${(0, utils_1.forLog)(this.displayName)} did not accept mute=${shouldMute ? 1 : 0}`);
+            }
+        });
+    }
+    updateFromObservation(observation, _reason) {
+        this.muted = observation.muted;
+        this.service.updateCharacteristic(this.host.hap.Characteristic.On, observation.muted);
+    }
+    markUnavailable() {
+        this.service.updateCharacteristic(this.host.hap.Characteristic.On, this.communicationFailure());
+    }
+}
+exports.MuteAccessory = MuteAccessory;

package/dist/devices/volume-accessory.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The volume slider.
+ *
+ * HomeKit has no speaker volume control that the Home app renders, so the slider
+ * borrows one. Fanv2 `RotationSpeed` is the default and a Lightbulb's
+ * `Brightness` is offered as an alternative; they look identical in the Home app.
+ * The default is the fan because "turn off all the lights" and "set the lights to
+ * 100%" both sweep up a Lightbulb, and a speaker jumping to full volume because
+ * someone addressed the lights is a genuinely bad outcome. Every mature plugin in
+ * this space carries the same warning.
+ *
+ * Mapping to BluOS:
+ *
+ * - The slider position is the player's 0..100 level. The player converts that to
+ *   its own configured dB range, which differs per player and per configuration —
+ *   two identical PULSE FLEX 2i units measured 0.7 dB apart at levels 26 and 35 —
+ *   so the level is deliberately passed through rather than scaled here.
+ * - Off means level zero. A muted player reports `volume="0"`, so an external mute
+ *   shows up as Off without this accessory having to know about mute at all.
+ * - Any explicit level write unmutes first, because a slider that appears to move
+ *   while the player stays silent is indistinguishable from a broken plugin.
+ */
+import type { PlayerObservation, RefreshReason } from '../types';
+import { BaseAccessory, type AccessoryInit } from './base-accessory';
+/** A volume slider for one player. */
+export declare class VolumeAccessory extends BaseAccessory {
+    private readonly surface;
+    /** Last level read from the player. Undefined until the first observation. */
+    private level;
+    /** True when the player reports a fixed output level. */
+    private fixedVolume;
+    /** Level awaiting a coalesced write. */
+    private pendingLevel;
+    /** In-flight coalesced write, shared by every handler that queued into it. */
+    private flush;
+    constructor(init: AccessoryInit);
+    private buildSurface;
+    private bindHandlers;
+    private readActive;
+    private readLevel;
+    /**
+     * Refuse a read when the value would be a guess.
+     *
+     * A fixed-output player is treated the same as an unreachable one: there is no
+     * level to report and writing one would do nothing, so No Response is the
+     * truthful answer rather than a slider that silently ignores input.
+     */
+    private requireSlider;
+    private writeActive;
+    private writeLevel;
+    /**
+     * Record the intended level and write it once the coalescing window closes.
+     *
+     * The most recent request wins, which is what makes the `Active` + level pair
+     * that HomeKit sends when a slider leaves zero result in a single write.
+     */
+    private queueLevel;
+    private applyPendingLevel;
+    protected updateFromObservation(observation: PlayerObservation, _reason: RefreshReason): void;
+    protected markUnavailable(): void;
+}