@lox-audio-server/sonos 0.1.0

package/dist/sonos/client.d.ts

@@ -0,0 +1,44 @@
+import { SonosWebSocketApi } from './api/websocket';
+import { EventType } from './constants';
+import { SonosGroup } from './group';
+import { SonosPlayer } from './player';
+import { DiscoveryOptions } from './utils';
+import { SonosEvent } from './types';
+type Subscriber = {
+    cb: (event: SonosEvent) => void;
+    eventFilter?: Set<EventType>;
+    objectIdFilter?: Set<string>;
+};
+export interface SonosClientOptions extends DiscoveryOptions {
+    logger?: Console;
+    heartbeatIntervalMs?: number;
+    retryDelayMs?: number;
+    retryJitterMs?: number;
+    maxReconnects?: number;
+}
+export declare class SonosClient {
+    private playerIp;
+    api: SonosWebSocketApi;
+    playerId: string;
+    householdId: string;
+    player: SonosPlayer | null;
+    private groupMap;
+    private subscribers;
+    private logger;
+    private bootstrapPromise;
+    private connectedPlayerIds;
+    constructor(playerIp: string, options?: SonosClientOptions);
+    get groups(): SonosGroup[];
+    subscribe(cb: Subscriber['cb'], eventFilter?: EventType | EventType[] | null, objectIdFilter?: string | string[] | null): () => void;
+    signalEvent(event: SonosEvent): void;
+    connect(options?: SonosClientOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    start(): Promise<void>;
+    private bootstrap;
+    createGroup(playerIds: string[], musicContextGroupId?: string): Promise<void>;
+    private setupGroup;
+    private handleGroupsEvent;
+    private handleSocketConnected;
+    private handleSocketDisconnected;
+}
+export {};

package/dist/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/sonos/constants.d.ts

@@ -0,0 +1,14 @@
+export declare const LOCAL_API_TOKEN = "123e4567-e89b-12d3-a456-426655440000";
+export declare const LOG_LEVEL_VERBOSE = 5;
+export declare const API_VERSION = 1;
+export declare enum EventType {
+    GROUP_ADDED = "group_added",
+    GROUP_UPDATED = "group_updated",
+    GROUP_REMOVED = "group_removed",
+    PLAYER_ADDED = "player_added",
+    PLAYER_UPDATED = "player_updated",
+    PLAYER_REMOVED = "player_removed",
+    CONNECTED = "connected",
+    DISCONNECTED = "disconnected",
+    MATCH_ALL = "match_all"
+}

package/dist/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/sonos/errors.d.ts

@@ -0,0 +1,25 @@
+export declare class SonosError extends Error {
+    constructor(message: string);
+}
+export declare class TransportError extends SonosError {
+    readonly causeError?: Error;
+    constructor(message: string, error?: Error);
+}
+export declare class ConnectionClosed extends TransportError {
+}
+export declare class CannotConnect extends TransportError {
+}
+export declare class ConnectionFailed extends TransportError {
+    constructor(error?: Error);
+}
+export declare class NotConnected extends SonosError {
+}
+export declare class InvalidState extends SonosError {
+}
+export declare class InvalidMessage extends SonosError {
+}
+export declare class FailedCommand extends SonosError {
+    readonly errorCode: string;
+    readonly details?: string;
+    constructor(errorCode: string, details?: string);
+}

package/dist/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;

package/dist/sonos/group.d.ts

@@ -0,0 +1,58 @@
+import { SonosClient } from './client';
+import { Container, ContainerType, Group, MetadataStatus, MusicService, PlayBackState, PlayModes, SessionStatus, Track } from './types';
+import { PlaybackActionsWrapper, PlayModesWrapper } from './models';
+export declare class SonosGroup {
+    private client;
+    private data;
+    activeSessionId: string | null;
+    private playbackStatus;
+    private playbackMetadata;
+    private playbackStatusUpdatedAt;
+    private volumeData;
+    private playModes;
+    private playbackActions;
+    private unsubscribeCallbacks;
+    constructor(client: SonosClient, data: Group);
+    init(): Promise<void>;
+    cleanup(): void;
+    get id(): string;
+    get name(): string;
+    get coordinatorId(): string;
+    get playerIds(): string[];
+    get areaIds(): string[];
+    get playbackState(): PlayBackState;
+    get playbackMetadataStatus(): MetadataStatus | null;
+    get playbackActionsWrapper(): PlaybackActionsWrapper;
+    get playModesWrapper(): PlayModesWrapper;
+    get positionSeconds(): number;
+    get isDucking(): boolean;
+    get activeService(): MusicService | string | null;
+    get containerType(): ContainerType | string | null;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    stop(): Promise<void>;
+    togglePlayPause(): Promise<void>;
+    skipToNextTrack(): Promise<void>;
+    skipToPreviousTrack(): Promise<void>;
+    setPlayModes(options: PlayModes): Promise<void>;
+    seek(positionMillis: number): Promise<void>;
+    seekRelative(deltaMillis: number): Promise<void>;
+    loadLineIn(deviceId?: string, playOnCompletion?: boolean): Promise<void>;
+    modifyGroupMembers(playerIdsToAdd: string[], playerIdsToRemove: string[]): Promise<void>;
+    setGroupMembers(playerIds: string[], areaIds?: string[]): Promise<void>;
+    createPlaybackSession(appId?: string, appContext?: string, accountId?: string, customData?: Record<string, unknown>): Promise<SessionStatus>;
+    playStreamUrl(url: string, metadata?: Container): Promise<void>;
+    playCloudQueue(queueBaseUrl: string, options: {
+        httpAuthorization?: string;
+        useHttpAuthorizationForMedia?: boolean;
+        itemId?: string;
+        queueVersion?: string;
+        positionMillis?: number;
+        trackMetadata?: Track;
+    }): Promise<void>;
+    updateData(newData: Group): void;
+    private ensureSession;
+    private handlePlaybackStatusUpdate;
+    private handleMetadataUpdate;
+    private handleVolumeUpdate;
+}

package/dist/sonos/group.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SonosGroup = void 0;
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const types_1 = require("./types");
+const models_1 = require("./models");
+class SonosGroup {
+    client;
+    data;
+    activeSessionId = null;
+    playbackStatus = null;
+    playbackMetadata = null;
+    playbackStatusUpdatedAt = 0;
+    volumeData = null;
+    playModes = new models_1.PlayModesWrapper({});
+    playbackActions = new models_1.PlaybackActionsWrapper({});
+    unsubscribeCallbacks = [];
+    constructor(client, data) {
+        this.client = client;
+        this.data = data;
+    }
+    async init() {
+        try {
+            this.volumeData = await this.client.api.groupVolume.getVolume(this.id);
+            this.playbackStatus = await this.client.api.playback.getPlaybackStatus(this.id);
+            this.playbackStatusUpdatedAt = Date.now();
+            this.playbackActions = new models_1.PlaybackActionsWrapper(this.playbackStatus.availablePlaybackActions ?? {});
+            this.playModes = new models_1.PlayModesWrapper(this.playbackStatus.playModes ?? {});
+            this.playbackMetadata = await this.client.api.playbackMetadata.getMetadataStatus(this.id);
+            this.unsubscribeCallbacks = [
+                await this.client.api.playback.subscribe(this.id, (data) => this.handlePlaybackStatusUpdate(data)),
+                await this.client.api.groupVolume.subscribe(this.id, (data) => this.handleVolumeUpdate(data)),
+                await this.client.api.playbackMetadata.subscribe(this.id, (data) => this.handleMetadataUpdate(data)),
+            ];
+        }
+        catch (err) {
+            if (err instanceof errors_1.FailedCommand && err.errorCode === 'groupCoordinatorChanged') {
+                this.volumeData = null;
+                this.playbackStatus = null;
+                this.playbackActions = new models_1.PlaybackActionsWrapper({});
+                this.playModes = new models_1.PlayModesWrapper({});
+                this.playbackMetadata = null;
+                return;
+            }
+            throw err;
+        }
+        this.client.signalEvent({
+            eventType: constants_1.EventType.GROUP_ADDED,
+            objectId: this.id,
+            data: this,
+        });
+    }
+    cleanup() {
+        for (const cb of this.unsubscribeCallbacks)
+            cb();
+        this.unsubscribeCallbacks = [];
+    }
+    get id() {
+        return this.data.id;
+    }
+    get name() {
+        return this.data.name;
+    }
+    get coordinatorId() {
+        return this.data.coordinatorId;
+    }
+    get playerIds() {
+        return this.data.playerIds;
+    }
+    get areaIds() {
+        return this.data.areaIds ?? [];
+    }
+    get playbackState() {
+        return (this.playbackStatus?.playbackState ??
+            this.data.playbackState ??
+            types_1.PlayBackState.IDLE);
+    }
+    get playbackMetadataStatus() {
+        return this.playbackMetadata;
+    }
+    get playbackActionsWrapper() {
+        return this.playbackActions;
+    }
+    get playModesWrapper() {
+        return this.playModes;
+    }
+    get positionSeconds() {
+        if (!this.playbackStatus)
+            return 0;
+        if (this.playbackState === types_1.PlayBackState.PLAYING) {
+            const elapsed = (Date.now() - this.playbackStatusUpdatedAt) / 1000;
+            return (this.playbackStatus.positionMillis ?? 0) / 1000 + elapsed;
+        }
+        return (this.playbackStatus.positionMillis ?? 0) / 1000;
+    }
+    get isDucking() {
+        return this.playbackStatus?.isDucking ?? false;
+    }
+    get activeService() {
+        return (0, models_1.normalizeMusicService)(this.playbackMetadata?.container?.id?.serviceId);
+    }
+    get containerType() {
+        return (0, models_1.normalizeContainerType)(this.playbackMetadata?.container?.type);
+    }
+    async play() {
+        await this.client.api.playback.play(this.id);
+    }
+    async pause() {
+        await this.client.api.playback.pause(this.id);
+    }
+    async stop() {
+        try {
+            if (this.activeSessionId) {
+                await this.client.api.playbackSession.suspend(this.activeSessionId);
+            }
+        }
+        catch (err) {
+            if (!(err instanceof errors_1.FailedCommand))
+                throw err;
+            try {
+                await this.playStreamUrl('clear');
+            }
+            catch {
+                // ignore
+            }
+        }
+        finally {
+            this.activeSessionId = null;
+        }
+    }
+    async togglePlayPause() {
+        await this.client.api.playback.togglePlayPause(this.id);
+    }
+    async skipToNextTrack() {
+        await this.client.api.playback.skipToNextTrack(this.id);
+    }
+    async skipToPreviousTrack() {
+        await this.client.api.playback.skipToPreviousTrack(this.id);
+    }
+    async setPlayModes(options) {
+        await this.client.api.playback.setPlayModes(this.id, options);
+    }
+    async seek(positionMillis) {
+        await this.client.api.playback.seek(this.id, positionMillis);
+    }
+    async seekRelative(deltaMillis) {
+        await this.client.api.playback.seekRelative(this.id, deltaMillis);
+    }
+    async loadLineIn(deviceId, playOnCompletion = false) {
+        await this.client.api.playback.loadLineIn(this.id, deviceId, playOnCompletion);
+    }
+    async modifyGroupMembers(playerIdsToAdd, playerIdsToRemove) {
+        await this.client.api.groups.modifyGroupMembers(this.id, playerIdsToAdd, playerIdsToRemove);
+    }
+    async setGroupMembers(playerIds, areaIds) {
+        await this.client.api.groups.setGroupMembers(this.id, playerIds, areaIds);
+    }
+    async createPlaybackSession(appId = 'com.lox.sonos.playback', appContext = '1', accountId, customData) {
+        const session = await this.client.api.playbackSession.createSession(this.id, appId, appContext, accountId, customData);
+        this.activeSessionId = session.sessionId;
+        return session;
+    }
+    async playStreamUrl(url, metadata) {
+        await this.ensureSession();
+        if (!this.activeSessionId)
+            throw new Error('No active session');
+        await this.client.api.playbackSession.loadStreamUrl(this.activeSessionId, url, {
+            playOnCompletion: true,
+            stationMetadata: metadata,
+        });
+    }
+    async playCloudQueue(queueBaseUrl, options) {
+        await this.ensureSession();
+        if (!this.activeSessionId)
+            throw new Error('No active session');
+        await this.client.api.playbackSession.loadCloudQueue(this.activeSessionId, queueBaseUrl, {
+            ...options,
+            playOnCompletion: true,
+        });
+    }
+    updateData(newData) {
+        let changed = false;
+        for (const [key, value] of Object.entries(newData)) {
+            if (this.data[key] !== value) {
+                this.data[key] = value;
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.client.signalEvent({
+                eventType: constants_1.EventType.GROUP_UPDATED,
+                objectId: this.id,
+                data: this,
+            });
+        }
+    }
+    async ensureSession() {
+        if (!this.activeSessionId) {
+            await this.createPlaybackSession();
+        }
+    }
+    handlePlaybackStatusUpdate(data) {
+        this.playbackStatus = data;
+        this.playbackStatusUpdatedAt = Date.now();
+        this.playbackActions = new models_1.PlaybackActionsWrapper(data.availablePlaybackActions ?? {});
+        this.playModes = new models_1.PlayModesWrapper(data.playModes ?? {});
+        this.client.signalEvent({
+            eventType: constants_1.EventType.GROUP_UPDATED,
+            objectId: this.id,
+            data: this,
+        });
+    }
+    handleMetadataUpdate(data) {
+        this.playbackMetadata = data;
+        this.client.signalEvent({
+            eventType: constants_1.EventType.GROUP_UPDATED,
+            objectId: this.id,
+            data: this,
+        });
+    }
+    handleVolumeUpdate(data) {
+        this.volumeData = data;
+        this.client.signalEvent({
+            eventType: constants_1.EventType.GROUP_UPDATED,
+            objectId: this.id,
+            data: this,
+        });
+    }
+}
+exports.SonosGroup = SonosGroup;

package/dist/sonos/models.d.ts

@@ -0,0 +1,20 @@
+import { ContainerType, MusicService, PlaybackActions, PlayModes } from './types';
+export declare class PlaybackActionsWrapper {
+    private raw;
+    constructor(raw: PlaybackActions);
+    get canSkipForward(): boolean;
+    get canSkipBackward(): boolean;
+    get canPlay(): boolean;
+    get canPause(): boolean;
+    get canStop(): boolean;
+}
+export declare class PlayModesWrapper {
+    raw: PlayModes;
+    constructor(raw: PlayModes);
+    get crossfade(): boolean | undefined;
+    get repeat(): boolean | undefined;
+    get repeatOne(): boolean | undefined;
+    get shuffle(): boolean | undefined;
+}
+export declare function normalizeContainerType(containerType?: string): ContainerType | string | null;
+export declare function normalizeMusicService(serviceId?: string): MusicService | string | null;