@lox-audio-server/sonos 0.1.0

package/dist/esm/sonos/api/websocket.js

@@ -0,0 +1,310 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SonosWebSocketApi = void 0;
+const ws_1 = __importDefault(require("ws"));
+const node_crypto_1 = require("node:crypto");
+const constants_1 = require("../constants");
+const errors_1 = require("../errors");
+const audioClip_1 = require("./namespaces/audioClip");
+const groups_1 = require("./namespaces/groups");
+const groupVolume_1 = require("./namespaces/groupVolume");
+const playback_1 = require("./namespaces/playback");
+const playbackMetadata_1 = require("./namespaces/playbackMetadata");
+const playbackSession_1 = require("./namespaces/playbackSession");
+const playerVolume_1 = require("./namespaces/playerVolume");
+const homeTheater_1 = require("./namespaces/homeTheater");
+class SonosWebSocketApi {
+    websocketUrl;
+    ws;
+    resultFutures = new Map();
+    stopCalled = false;
+    heartbeatTimer;
+    heartbeatIntervalMs;
+    retryDelayMs;
+    retryJitterMs;
+    maxReconnects;
+    audioClip;
+    groups;
+    groupVolume;
+    playback;
+    playbackMetadata;
+    playbackSession;
+    playerVolume;
+    homeTheater;
+    logger = console;
+    onConnect;
+    onDisconnect;
+    constructor(websocketUrl, opts = {}) {
+        this.websocketUrl = websocketUrl;
+        this.audioClip = new audioClip_1.AudioClipNamespace(this);
+        this.groups = new groups_1.GroupsNamespace(this);
+        this.groupVolume = new groupVolume_1.GroupVolumeNamespace(this);
+        this.playback = new playback_1.PlaybackNamespace(this);
+        this.playbackMetadata = new playbackMetadata_1.PlaybackMetadataNamespace(this);
+        this.playbackSession = new playbackSession_1.PlaybackSessionNamespace(this);
+        this.playerVolume = new playerVolume_1.PlayerVolumeNamespace(this);
+        this.homeTheater = new homeTheater_1.HomeTheaterNamespace(this);
+        this.heartbeatIntervalMs = opts.heartbeatIntervalMs ?? 30000;
+        this.retryDelayMs = opts.retryDelayMs ?? 2000;
+        this.retryJitterMs = opts.retryJitterMs ?? 500;
+        this.maxReconnects = opts.maxReconnects;
+    }
+    get connected() {
+        return Boolean(this.ws && this.ws.readyState === ws_1.default.OPEN);
+    }
+    async connect() {
+        if (this.ws) {
+            throw new errors_1.InvalidState('Already connected');
+        }
+        this.logger.debug?.(`Connecting to Sonos WebSocket ${this.websocketUrl}`);
+        this.stopCalled = false;
+        try {
+            this.ws = new ws_1.default(this.websocketUrl, {
+                headers: {
+                    'X-Sonos-Api-Key': constants_1.LOCAL_API_TOKEN,
+                    'Sec-WebSocket-Protocol': 'v1.api.smartspeaker.audio',
+                },
+                rejectUnauthorized: false,
+                perMessageDeflate: true,
+                maxPayload: 0,
+            });
+        }
+        catch (err) {
+            throw new errors_1.CannotConnect('Failed to create websocket', err);
+        }
+        await new Promise((resolve, reject) => {
+            if (!this.ws)
+                return reject(new errors_1.CannotConnect('No websocket'));
+            this.ws.once('open', () => resolve());
+            this.ws.once('error', (err) => reject(new errors_1.CannotConnect('Failed to connect', err)));
+        });
+        this.ws.on('message', (data) => this.handleRawMessage(data));
+        this.ws.on('close', () => {
+            this.clearHeartbeat();
+        });
+        this.ws.on('error', (err) => {
+            this.logger.warn?.('WebSocket error', err);
+        });
+        this.ws.on('pong', () => {
+            // noop; pong receipt confirms liveness
+        });
+        this.startHeartbeat();
+        await this.onConnect?.();
+    }
+    async startListening() {
+        this.stopCalled = false;
+        while (!this.stopCalled) {
+            let attempts = 0;
+            try {
+                if (!this.connected) {
+                    await this.connect();
+                }
+                const reason = await this.waitForClose();
+                if (this.stopCalled)
+                    break;
+                await this.onDisconnect?.(reason);
+                this.logger.warn?.('WebSocket closed, reconnecting...', reason);
+                attempts += 1;
+                if (this.maxReconnects && attempts > this.maxReconnects) {
+                    this.logger.error?.('Max reconnect attempts reached');
+                    break;
+                }
+                await this.delay(this.computeRetryDelay(attempts));
+            }
+            catch (err) {
+                if (this.stopCalled)
+                    break;
+                this.logger.warn?.('WebSocket listen error, reconnecting...', err);
+                await this.onDisconnect?.(err instanceof Error ? err.message : undefined);
+                attempts += 1;
+                if (this.maxReconnects && attempts > this.maxReconnects) {
+                    this.logger.error?.('Max reconnect attempts reached after error');
+                    break;
+                }
+                await this.delay(this.computeRetryDelay(attempts));
+            }
+        }
+    }
+    async disconnect() {
+        this.stopCalled = true;
+        this.clearHeartbeat();
+        for (const pending of this.resultFutures.values()) {
+            pending.reject(new errors_1.ConnectionClosed('Connection closed'));
+        }
+        this.resultFutures.clear();
+        if (this.ws && this.ws.readyState === ws_1.default.OPEN) {
+            await new Promise((resolve) => {
+                this.ws?.once('close', () => resolve());
+                this.ws?.close();
+            });
+        }
+        this.ws = undefined;
+    }
+    async sendCommand(namespace, command, options, pathParams) {
+        if (!this.connected || !this.ws)
+            throw new errors_1.InvalidState('Not connected');
+        const cmdId = (0, node_crypto_1.randomUUID)();
+        const cmdMessage = {
+            namespace: `${namespace}:${constants_1.API_VERSION}`,
+            command,
+            cmdId,
+            ...(pathParams ?? {}),
+        };
+        const payload = [cmdMessage, options ?? {}];
+        const resultPromise = new Promise((resolve, reject) => {
+            this.resultFutures.set(cmdId, { resolve, reject });
+        });
+        await this.send(payload);
+        return resultPromise.finally(() => this.resultFutures.delete(cmdId));
+    }
+    sendCommandNoWait(namespace, command, options, pathParams) {
+        if (!this.connected || !this.ws)
+            throw new errors_1.NotConnected('Not connected');
+        const cmdMessage = {
+            namespace: `${namespace}:${constants_1.API_VERSION}`,
+            command,
+            cmdId: (0, node_crypto_1.randomUUID)(),
+            ...(pathParams ?? {}),
+        };
+        const payload = [cmdMessage, options ?? {}];
+        void this.send(payload);
+    }
+    async send(payload) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN) {
+            throw new errors_1.NotConnected('Not connected');
+        }
+        if (this.logger && this.logger.log && constants_1.LOG_LEVEL_VERBOSE) {
+            this.logger.log?.(constants_1.LOG_LEVEL_VERBOSE, 'Publishing message', payload);
+        }
+        const data = JSON.stringify(payload);
+        await new Promise((resolve, reject) => {
+            this.ws?.send(data, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    handleRawMessage(raw) {
+        try {
+            const parsed = JSON.parse(raw.toString());
+            try {
+                this.handleIncoming(parsed);
+            }
+            catch (err) {
+                this.logger.error?.('Failed to handle Sonos message', err);
+            }
+        }
+        catch (err) {
+            this.logger.error?.('Invalid JSON from Sonos', err);
+        }
+    }
+    handleIncoming(raw) {
+        if (!Array.isArray(raw) || raw.length !== 2) {
+            this.logger.error?.('Invalid Sonos message shape', raw);
+            return;
+        }
+        const [msg, msgData] = raw;
+        if (!msg || typeof msg !== 'object') {
+            throw new errors_1.InvalidMessage('Received malformed message');
+        }
+        // error response
+        if ('errorCode' in msgData) {
+            const errData = msgData;
+            if ('cmdId' in msg && msg.cmdId) {
+                const future = this.resultFutures.get(msg.cmdId);
+                future?.reject(new errors_1.FailedCommand(errData.errorCode, errData.reason));
+            }
+            else {
+                this.logger.error?.('Unhandled error', msgData);
+            }
+            return;
+        }
+        // command result
+        if ('success' in msg) {
+            if (msg.cmdId && this.resultFutures.has(msg.cmdId)) {
+                const pending = this.resultFutures.get(msg.cmdId);
+                if (msg.success) {
+                    pending?.resolve(msgData);
+                }
+                else {
+                    pending?.reject(new errors_1.FailedCommand(String(msgData['_objectType'] ?? 'unknown')));
+                }
+            }
+            return;
+        }
+        // event
+        if (msg.type) {
+            const namespaces = [
+                this.audioClip,
+                this.groups,
+                this.groupVolume,
+                this.playbackMetadata,
+                this.playbackSession,
+                this.playback,
+                this.playerVolume,
+                this.homeTheater,
+            ];
+            const target = namespaces.find((ns) => ns.eventType === msg.type);
+            if (target) {
+                target.handleEvent(msg, msgData);
+            }
+            else {
+                this.logger.debug?.(`Unhandled event type ${msg.type}`);
+            }
+            return;
+        }
+        this.logger.debug?.('Unhandled message', raw);
+    }
+    async waitForClose() {
+        return new Promise((resolve, reject) => {
+            const ws = this.ws;
+            if (!ws)
+                return reject(new errors_1.NotConnected('No websocket'));
+            const onClose = (code, reason) => {
+                ws.removeListener('error', onError);
+                resolve(`${code}:${reason.toString()}`);
+            };
+            const onError = (err) => {
+                ws.removeListener('close', onClose);
+                reject(new errors_1.ConnectionFailed(err));
+            };
+            ws.once('close', onClose);
+            ws.once('error', onError);
+        });
+    }
+    startHeartbeat() {
+        this.clearHeartbeat();
+        if (!this.heartbeatIntervalMs)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+                return;
+            try {
+                this.ws.ping();
+            }
+            catch (err) {
+                this.logger.warn?.('Heartbeat ping failed', err);
+                this.ws.terminate();
+            }
+        }, this.heartbeatIntervalMs);
+    }
+    clearHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = undefined;
+    }
+    async delay(ms) {
+        await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    computeRetryDelay(attempt) {
+        const base = this.retryDelayMs * Math.min(2 ** (attempt - 1), 8);
+        const jitter = Math.random() * this.retryJitterMs;
+        return base + jitter;
+    }
+}
+exports.SonosWebSocketApi = SonosWebSocketApi;

package/dist/esm/sonos/client.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SonosClient = void 0;
+const websocket_1 = require("./api/websocket");
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const group_1 = require("./group");
+const player_1 = require("./player");
+const utils_1 = require("./utils");
+class SonosClient {
+    playerIp;
+    api;
+    playerId;
+    householdId;
+    player = null;
+    groupMap = new Map();
+    subscribers = [];
+    logger;
+    bootstrapPromise = null;
+    connectedPlayerIds = new Set();
+    constructor(playerIp, options = {}) {
+        this.playerIp = playerIp;
+        this.logger = options.logger ?? console;
+    }
+    get groups() {
+        return Array.from(this.groupMap.values());
+    }
+    subscribe(cb, eventFilter, objectIdFilter) {
+        const eventSet = eventFilter == null
+            ? undefined
+            : Array.isArray(eventFilter)
+                ? new Set(eventFilter)
+                : new Set([eventFilter]);
+        const objectSet = objectIdFilter == null
+            ? undefined
+            : Array.isArray(objectIdFilter)
+                ? new Set(objectIdFilter)
+                : new Set([objectIdFilter]);
+        const sub = {
+            cb,
+            eventFilter: eventSet,
+            objectIdFilter: objectSet,
+        };
+        this.subscribers.push(sub);
+        return () => {
+            this.subscribers = this.subscribers.filter((s) => s !== sub);
+        };
+    }
+    signalEvent(event) {
+        for (const sub of this.subscribers) {
+            if (sub.eventFilter && !sub.eventFilter.has(event.eventType))
+                continue;
+            if (sub.objectIdFilter && event.objectId && !sub.objectIdFilter.has(event.objectId)) {
+                continue;
+            }
+            sub.cb(event);
+        }
+    }
+    async connect(options) {
+        const discovery = await (0, utils_1.getDiscoveryInfo)(this.playerIp, options);
+        this.playerId = discovery.playerId;
+        this.householdId = discovery.householdId;
+        this.api = new websocket_1.SonosWebSocketApi(discovery.websocketUrl, {
+            heartbeatIntervalMs: options?.heartbeatIntervalMs,
+            retryDelayMs: options?.retryDelayMs,
+            retryJitterMs: options?.retryJitterMs,
+            maxReconnects: options?.maxReconnects,
+        });
+        if (options?.logger)
+            this.api.logger = options.logger;
+        this.api.onConnect = () => this.handleSocketConnected();
+        this.api.onDisconnect = (reason) => this.handleSocketDisconnected(reason);
+        await this.api.connect();
+    }
+    async disconnect() {
+        for (const group of this.groupMap.values()) {
+            group.cleanup();
+        }
+        await this.api.disconnect();
+    }
+    async start() {
+        await this.bootstrap();
+        await this.api.startListening();
+    }
+    async bootstrap(reconnect = false) {
+        if (this.bootstrapPromise)
+            return this.bootstrapPromise;
+        this.bootstrapPromise = (async () => {
+            if (!this.api || !this.api.connected) {
+                await this.connect();
+            }
+            if (reconnect || this.groupMap.size) {
+                for (const group of this.groupMap.values())
+                    group.cleanup();
+                this.groupMap.clear();
+            }
+            const groupsData = await this.api.groups.getGroups(this.householdId, true);
+            for (const groupData of groupsData.groups) {
+                await this.setupGroup(groupData);
+            }
+            const playerData = groupsData.players.find((p) => p.id === this.playerId);
+            if (!playerData) {
+                throw new errors_1.FailedCommand('playerNotFound', 'Local player not returned in groups response');
+            }
+            this.player = new player_1.SonosPlayer(this, playerData);
+            await this.player.init();
+            this.connectedPlayerIds = new Set(groupsData.players.map((p) => p.id));
+            await this.api.groups.subscribe(this.householdId, (data) => this.handleGroupsEvent(data));
+            this.signalEvent({ eventType: constants_1.EventType.CONNECTED, objectId: this.playerId });
+        })();
+        try {
+            await this.bootstrapPromise;
+        }
+        finally {
+            this.bootstrapPromise = null;
+        }
+    }
+    async createGroup(playerIds, musicContextGroupId) {
+        await this.api.groups.createGroup(this.householdId, playerIds, musicContextGroupId);
+    }
+    async setupGroup(groupData) {
+        const group = new group_1.SonosGroup(this, groupData);
+        this.groupMap.set(group.id, group);
+        await group.init();
+        if (this.player)
+            this.player.checkActiveGroup();
+    }
+    handleGroupsEvent(groupsData) {
+        for (const groupData of groupsData.groups) {
+            const existing = this.groupMap.get(groupData.id);
+            if (existing) {
+                existing.updateData(groupData);
+                continue;
+            }
+            void this.setupGroup(groupData);
+        }
+        const removedIds = new Set(this.groupMap.keys());
+        for (const g of groupsData.groups)
+            removedIds.delete(g.id);
+        for (const removedId of removedIds) {
+            const group = this.groupMap.get(removedId);
+            group?.cleanup();
+            this.groupMap.delete(removedId);
+            this.signalEvent({
+                eventType: constants_1.EventType.GROUP_REMOVED,
+                objectId: removedId,
+                data: group,
+            });
+        }
+        const incomingPlayers = new Set(groupsData.players.map((p) => p.id));
+        // removals
+        for (const prev of Array.from(this.connectedPlayerIds)) {
+            if (!incomingPlayers.has(prev)) {
+                this.signalEvent({
+                    eventType: constants_1.EventType.PLAYER_REMOVED,
+                    objectId: prev,
+                    data: prev,
+                });
+                this.connectedPlayerIds.delete(prev);
+            }
+        }
+        // updates/additions
+        for (const playerData of groupsData.players) {
+            if (playerData.id === this.playerId && this.player) {
+                this.player.updateData(playerData);
+            }
+            if (!this.connectedPlayerIds.has(playerData.id)) {
+                this.connectedPlayerIds.add(playerData.id);
+                this.signalEvent({
+                    eventType: constants_1.EventType.PLAYER_ADDED,
+                    objectId: playerData.id,
+                    data: playerData,
+                });
+            }
+        }
+    }
+    async handleSocketConnected() {
+        try {
+            await this.bootstrap(true);
+        }
+        catch (err) {
+            this.logger.error?.('Failed to bootstrap after reconnect', err);
+        }
+    }
+    handleSocketDisconnected(reason) {
+        this.signalEvent({
+            eventType: constants_1.EventType.DISCONNECTED,
+            objectId: this.playerId,
+            data: reason,
+        });
+    }
+}
+exports.SonosClient = SonosClient;

package/dist/esm/sonos/constants.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventType = exports.API_VERSION = exports.LOG_LEVEL_VERBOSE = exports.LOCAL_API_TOKEN = void 0;
+exports.LOCAL_API_TOKEN = '123e4567-e89b-12d3-a456-426655440000';
+exports.LOG_LEVEL_VERBOSE = 5;
+exports.API_VERSION = 1;
+var EventType;
+(function (EventType) {
+    EventType["GROUP_ADDED"] = "group_added";
+    EventType["GROUP_UPDATED"] = "group_updated";
+    EventType["GROUP_REMOVED"] = "group_removed";
+    EventType["PLAYER_ADDED"] = "player_added";
+    EventType["PLAYER_UPDATED"] = "player_updated";
+    EventType["PLAYER_REMOVED"] = "player_removed";
+    EventType["CONNECTED"] = "connected";
+    EventType["DISCONNECTED"] = "disconnected";
+    EventType["MATCH_ALL"] = "match_all";
+})(EventType || (exports.EventType = EventType = {}));

package/dist/esm/sonos/errors.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FailedCommand = exports.InvalidMessage = exports.InvalidState = exports.NotConnected = exports.ConnectionFailed = exports.CannotConnect = exports.ConnectionClosed = exports.TransportError = exports.SonosError = void 0;
+class SonosError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+exports.SonosError = SonosError;
+class TransportError extends SonosError {
+    causeError;
+    constructor(message, error) {
+        super(message);
+        this.causeError = error;
+    }
+}
+exports.TransportError = TransportError;
+class ConnectionClosed extends TransportError {
+}
+exports.ConnectionClosed = ConnectionClosed;
+class CannotConnect extends TransportError {
+}
+exports.CannotConnect = CannotConnect;
+class ConnectionFailed extends TransportError {
+    constructor(error) {
+        super(error ? `${error.message}` : 'Connection failed.', error);
+    }
+}
+exports.ConnectionFailed = ConnectionFailed;
+class NotConnected extends SonosError {
+}
+exports.NotConnected = NotConnected;
+class InvalidState extends SonosError {
+}
+exports.InvalidState = InvalidState;
+class InvalidMessage extends SonosError {
+}
+exports.InvalidMessage = InvalidMessage;
+class FailedCommand extends SonosError {
+    errorCode;
+    details;
+    constructor(errorCode, details) {
+        super(`Command failed: ${details ?? errorCode}`);
+        this.errorCode = errorCode;
+        this.details = details;
+    }
+}
+exports.FailedCommand = FailedCommand;