@lox-audio-server/sonos 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# lox-sonos-controller
+
+TypeScript Sonos controller that talks directly to the local WebSocket API on a Sonos player.
+
+## Install
+
+```bash
+npm install @lox-audio-server/sonos
+```
+
+Node.js 18+ is required.
+
+## Usage
+
+```ts
+import { SonosClient, EventType } from '@lox-audio-server/sonos';
+
+async function main() {
+const client = new SonosClient('192.168.1.50'); // IP of any Sonos player
+await client.connect();
+
+  // Listen for group/player updates
+  client.subscribe((evt) => console.log(evt.eventType, evt.objectId));
+
+  // Start websocket + initial sync (blocks until socket closes)
+  await client.start();
+
+  // Access player + groups
+  const player = client.player;
+  const [group] = client.groups;
+  await group.play();
+}
+
+void main();
+```
+
+### Opties
+
+`SonosClient` accepteert optionele betrouwbaarheidsettings:
+
+- `heartbeatIntervalMs` (default 30000)
+- `retryDelayMs` (default 2000) + `retryJitterMs` (default 500)
+- `maxReconnects` (default onbeperkt)
+
+## Features
+
+- Local Sonos WebSocket client (token-based TLS)
+- Group + player state sync with event callbacks
+- Playback controls: play/pause/seek/skip, play modes, line-in, cloud queue/stream
+- Group management: create/modify membership
+- Volume controls for player + group, duck/unduck
+- Audio clips + home theater helper
+
+## Notes
+
+- The local API uses a self-signed TLS certificate; the client disables certificate validation for this connection, matching the official behavior.
+- Only one player connection is handled per client instance (per Sonos requirements). Create multiple clients for multiple players.

package/dist/esm/index.js

@@ -0,0 +1,27 @@
+"use strict";
+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 });
+exports.SonosPlayer = exports.SonosGroup = exports.SonosClient = void 0;
+var client_1 = require("./sonos/client");
+Object.defineProperty(exports, "SonosClient", { enumerable: true, get: function () { return client_1.SonosClient; } });
+var group_1 = require("./sonos/group");
+Object.defineProperty(exports, "SonosGroup", { enumerable: true, get: function () { return group_1.SonosGroup; } });
+var player_1 = require("./sonos/player");
+Object.defineProperty(exports, "SonosPlayer", { enumerable: true, get: function () { return player_1.SonosPlayer; } });
+__exportStar(require("./sonos/models"), exports);
+__exportStar(require("./sonos/types"), exports);
+__exportStar(require("./sonos/constants"), exports);
+__exportStar(require("./sonos/errors"), exports);

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SonosNamespace = void 0;
+/**
+ * Base helper for namespace handlers.
+ */
+class SonosNamespace {
+    api;
+    namespace;
+    eventKey;
+    listeners = new Map();
+    eventType;
+    constructor(api, namespace, eventType, eventKey) {
+        this.api = api;
+        this.namespace = namespace;
+        this.eventKey = eventKey;
+        this.eventType = eventType;
+    }
+    async handleSubscribe(id, callback) {
+        if (this.listeners.has(id)) {
+            this.api.logger.error(`Duplicate subscription detected for ${id}`);
+        }
+        await this.api.sendCommand(this.namespace, 'subscribe', undefined, { [this.eventKey]: id });
+        this.listeners.set(id, callback);
+        return () => {
+            this.listeners.delete(id);
+            this.api.sendCommandNoWait(this.namespace, 'unsubscribe', undefined, { [this.eventKey]: id });
+        };
+    }
+    handleEvent(event, eventData) {
+        const id = event[this.eventKey];
+        if (typeof id === 'string') {
+            const handler = this.listeners.get(id);
+            handler?.(eventData);
+        }
+    }
+}
+exports.SonosNamespace = SonosNamespace;

package/dist/esm/sonos/api/namespaces/audioClip.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioClipNamespace = void 0;
+const namespace_1 = require("../namespace");
+class AudioClipNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'audioClip', 'audioClip', 'playerId');
+    }
+    async loadAudioClip(playerId, options) {
+        return this.api.sendCommand(this.namespace, 'loadAudioClip', {
+            name: options.name,
+            appId: options.appId,
+            priority: options.priority,
+            clipType: options.clipType,
+            streamUrl: options.streamUrl,
+            httpAuthorization: options.httpAuthorization,
+            volume: options.volume,
+            clipLEDBehavior: options.clipLEDBehavior,
+        }, { playerId });
+    }
+    async subscribe(playerId, callback) {
+        return this.handleSubscribe(playerId, callback);
+    }
+}
+exports.AudioClipNamespace = AudioClipNamespace;

package/dist/esm/sonos/api/namespaces/groupVolume.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroupVolumeNamespace = void 0;
+const namespace_1 = require("../namespace");
+class GroupVolumeNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'groupVolume', 'groupVolume', 'groupId');
+    }
+    async setVolume(groupId, volume) {
+        await this.api.sendCommand(this.namespace, 'setVolume', { volume }, { groupId });
+    }
+    async getVolume(groupId) {
+        return this.api.sendCommand(this.namespace, 'getVolume', undefined, { groupId });
+    }
+    async setMute(groupId, muted) {
+        await this.api.sendCommand(this.namespace, 'setMute', { muted }, { groupId });
+    }
+    async setRelativeVolume(groupId, volumeDelta) {
+        await this.api.sendCommand(this.namespace, 'setRelativeVolume', { volumeDelta }, { groupId });
+    }
+    async subscribe(groupId, callback) {
+        return this.handleSubscribe(groupId, callback);
+    }
+}
+exports.GroupVolumeNamespace = GroupVolumeNamespace;

package/dist/esm/sonos/api/namespaces/groups.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroupsNamespace = void 0;
+const namespace_1 = require("../namespace");
+class GroupsNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'groups', 'groups', 'householdId');
+    }
+    async modifyGroupMembers(groupId, playerIdsToAdd, playerIdsToRemove) {
+        return this.api.sendCommand(this.namespace, 'modifyGroupMembers', { playerIdsToAdd, playerIdsToRemove }, { groupId });
+    }
+    async setGroupMembers(groupId, playerIds, areaIds) {
+        const options = { playerIds };
+        if (areaIds)
+            options.areaIds = areaIds;
+        return this.api.sendCommand(this.namespace, 'setGroupMembers', options, { groupId });
+    }
+    async getGroups(householdId, includeDeviceInfo = false) {
+        return this.api.sendCommand(this.namespace, 'getGroups', { includeDeviceInfo }, { householdId });
+    }
+    async createGroup(householdId, playerIds, musicContextGroupId) {
+        const options = { playerIds };
+        if (musicContextGroupId)
+            options.musicContextGroupId = musicContextGroupId;
+        return this.api.sendCommand(this.namespace, 'createGroup', options, { householdId });
+    }
+    async subscribe(householdId, callback) {
+        return this.handleSubscribe(householdId, callback);
+    }
+}
+exports.GroupsNamespace = GroupsNamespace;

package/dist/esm/sonos/api/namespaces/homeTheater.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HomeTheaterNamespace = void 0;
+const namespace_1 = require("../namespace");
+class HomeTheaterNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'homeTheater', 'homeTheaterStatus', 'playerId');
+    }
+    async loadHomeTheaterPlayback(playerId) {
+        await this.api.sendCommand(this.namespace, 'loadHomeTheaterPlayback', undefined, { playerId });
+    }
+}
+exports.HomeTheaterNamespace = HomeTheaterNamespace;

package/dist/esm/sonos/api/namespaces/playback.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaybackNamespace = void 0;
+const namespace_1 = require("../namespace");
+class PlaybackNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'playback', 'playbackStatus', 'groupId');
+    }
+    async getPlaybackStatus(groupId) {
+        return this.api.sendCommand(this.namespace, 'getPlaybackStatus', undefined, { groupId });
+    }
+    async loadLineIn(groupId, deviceId, playOnCompletion = false) {
+        const options = {};
+        if (deviceId)
+            options.deviceId = deviceId;
+        options.playOnCompletion = playOnCompletion;
+        await this.api.sendCommand(this.namespace, 'loadLineIn', options, { groupId });
+    }
+    async loadContent(groupId, content) {
+        await this.api.sendCommand(this.namespace, 'loadContent', content, { groupId });
+    }
+    async pause(groupId) {
+        await this.api.sendCommand(this.namespace, 'pause', undefined, { groupId });
+    }
+    async play(groupId) {
+        await this.api.sendCommand(this.namespace, 'play', undefined, { groupId });
+    }
+    async togglePlayPause(groupId) {
+        await this.api.sendCommand(this.namespace, 'togglePlayPause', undefined, { groupId });
+    }
+    async setPlayModes(groupId, playModes) {
+        await this.api.sendCommand(this.namespace, 'setPlayModes', { playModes }, { groupId });
+    }
+    async seek(groupId, positionMillis, itemId) {
+        const options = { positionMillis };
+        if (itemId)
+            options.itemId = itemId;
+        await this.api.sendCommand(this.namespace, 'seek', options, { groupId });
+    }
+    async seekRelative(groupId, deltaMillis, itemId) {
+        const options = { deltaMillis };
+        if (itemId)
+            options.itemId = itemId;
+        await this.api.sendCommand(this.namespace, 'seekRelative', options, { groupId });
+    }
+    async skipToNextTrack(groupId) {
+        await this.api.sendCommand(this.namespace, 'skipToNextTrack', undefined, { groupId });
+    }
+    async skipToPreviousTrack(groupId) {
+        await this.api.sendCommand(this.namespace, 'skipToPreviousTrack', undefined, { groupId });
+    }
+    async subscribe(groupId, callback) {
+        return this.handleSubscribe(groupId, callback);
+    }
+}
+exports.PlaybackNamespace = PlaybackNamespace;

package/dist/esm/sonos/api/namespaces/playbackMetadata.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaybackMetadataNamespace = void 0;
+const namespace_1 = require("../namespace");
+class PlaybackMetadataNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'playbackMetadata', 'metadataStatus', 'groupId');
+    }
+    async getMetadataStatus(groupId) {
+        return this.api.sendCommand(this.namespace, 'getMetadataStatus', undefined, { groupId });
+    }
+    async subscribe(groupId, callback) {
+        return this.handleSubscribe(groupId, callback);
+    }
+}
+exports.PlaybackMetadataNamespace = PlaybackMetadataNamespace;

package/dist/esm/sonos/api/namespaces/playbackSession.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaybackSessionNamespace = void 0;
+const namespace_1 = require("../namespace");
+class PlaybackSessionNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'playbackSession', 'playbackSession', 'sessionId');
+    }
+    async createSession(groupId, appId, appContext, accountId, customData) {
+        const options = { appId, appContext };
+        if (accountId)
+            options.accountId = accountId;
+        if (customData)
+            options.customData = customData;
+        return this.api.sendCommand(this.namespace, 'createSession', options, { groupId });
+    }
+    async loadCloudQueue(sessionId, queueBaseUrl, options) {
+        await this.api.sendCommand(this.namespace, 'loadCloudQueue', {
+            queueBaseUrl,
+            httpAuthorization: options.httpAuthorization,
+            useHttpAuthorizationForMedia: options.useHttpAuthorizationForMedia,
+            itemId: options.itemId,
+            queueVersion: options.queueVersion,
+            positionMillis: options.positionMillis,
+            playOnCompletion: options.playOnCompletion,
+            trackMetadata: options.trackMetadata,
+        }, { sessionId });
+    }
+    async loadStreamUrl(sessionId, streamUrl, options = {}) {
+        await this.api.sendCommand(this.namespace, 'loadStreamUrl', {
+            streamUrl,
+            playOnCompletion: options.playOnCompletion,
+            stationMetadata: options.stationMetadata,
+            itemId: options.itemId,
+        }, { sessionId });
+    }
+    async refreshCloudQueue(sessionId) {
+        await this.api.sendCommand(this.namespace, 'refreshCloudQueue', undefined, { sessionId });
+    }
+    async seek(sessionId, positionMillis, itemId) {
+        const options = { positionMillis };
+        if (itemId)
+            options.itemId = itemId;
+        await this.api.sendCommand(this.namespace, 'seek', options, { sessionId });
+    }
+    async seekRelative(sessionId, deltaMillis, itemId) {
+        const options = { deltaMillis };
+        if (itemId)
+            options.itemId = itemId;
+        await this.api.sendCommand(this.namespace, 'seekRelative', options, { sessionId });
+    }
+    async skipToItem(sessionId, itemId, options = {}) {
+        await this.api.sendCommand(this.namespace, 'skipToItem', {
+            itemId,
+            queueVersion: options.queueVersion,
+            positionMillis: options.positionMillis,
+            playOnCompletion: options.playOnCompletion,
+        }, { sessionId });
+    }
+    async suspend(sessionId, queueVersion) {
+        await this.api.sendCommand(this.namespace, 'suspend', queueVersion ? { queueVersion } : undefined, { sessionId });
+    }
+    async subscribe(sessionId, callback) {
+        return this.handleSubscribe(sessionId, callback);
+    }
+}
+exports.PlaybackSessionNamespace = PlaybackSessionNamespace;

package/dist/esm/sonos/api/namespaces/playerVolume.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlayerVolumeNamespace = void 0;
+const namespace_1 = require("../namespace");
+class PlayerVolumeNamespace extends namespace_1.SonosNamespace {
+    constructor(api) {
+        super(api, 'playerVolume', 'playerVolume', 'playerId');
+    }
+    async setVolume(playerId, volume, muted) {
+        const options = {};
+        if (typeof volume === 'number')
+            options.volume = volume;
+        if (typeof muted === 'boolean')
+            options.muted = muted;
+        await this.api.sendCommand(this.namespace, 'setVolume', options, { playerId });
+    }
+    async getVolume(playerId) {
+        return this.api.sendCommand(this.namespace, 'getVolume', undefined, { playerId });
+    }
+    async duck(playerId, durationMillis) {
+        await this.api.sendCommand(this.namespace, 'duck', durationMillis ? { durationMillis } : undefined, { playerId });
+    }
+    async unduck(playerId) {
+        await this.api.sendCommand(this.namespace, 'unduck', undefined, { playerId });
+    }
+    async setMute(playerId, muted) {
+        await this.api.sendCommand(this.namespace, 'setMute', { muted }, { playerId });
+    }
+    async setRelativeVolume(playerId, volumeDelta, muted) {
+        const options = {};
+        if (typeof volumeDelta === 'number')
+            options.volumeDelta = volumeDelta;
+        if (typeof muted === 'boolean')
+            options.muted = muted;
+        await this.api.sendCommand(this.namespace, 'setRelativeVolume', options, { playerId });
+    }
+    async subscribe(playerId, callback) {
+        return this.handleSubscribe(playerId, callback);
+    }
+}
+exports.PlayerVolumeNamespace = PlayerVolumeNamespace;