homebridge-sonos-scenes 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,141 @@
+import type { PlatformConfig } from "homebridge";
+export declare const PLUGIN_NAME = "homebridge-sonos-scenes";
+export declare const PLATFORM_NAME = "SonosScenes";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type SceneSourceKind = "favorite" | "line_in" | "tv";
+export type SceneTrigger = "on" | "off" | "test";
+export interface FavoriteSource {
+    kind: "favorite";
+    favoriteId: string;
+    favoriteName?: string;
+}
+export interface LineInSource {
+    kind: "line_in";
+    deviceId: string;
+    deviceName?: string;
+    playOnCompletion?: boolean;
+}
+export interface TvSource {
+    kind: "tv";
+    deviceId: string;
+    deviceName?: string;
+    playOnCompletion?: boolean;
+}
+export type SceneSource = FavoriteSource | LineInSource | TvSource;
+export interface SceneVolume {
+    playerId: string;
+    volume: number;
+}
+export interface OffBehaviorNone {
+    kind: "none";
+}
+export interface OffBehaviorUngroup {
+    kind: "ungroup";
+}
+export type SceneOffBehavior = OffBehaviorNone | OffBehaviorUngroup;
+export interface SceneDefinition {
+    id: string;
+    name: string;
+    householdId: string;
+    coordinatorPlayerId: string;
+    memberPlayerIds: string[];
+    source?: SceneSource;
+    coordinatorVolume?: number;
+    playerVolumes: SceneVolume[];
+    offBehavior: SceneOffBehavior;
+    settleMs: number;
+    retryCount: number;
+    retryDelayMs: number;
+    autoResetMs: number;
+}
+export interface LocalTransportConfig {
+    kind: "local";
+    fixturePath?: string;
+    enableLiveDiscovery: boolean;
+    discoveryTimeoutMs: number;
+    requestTimeoutMs: number;
+    allowTvSource: boolean;
+}
+export interface ScenesPlatformConfig extends PlatformConfig {
+    platform: typeof PLATFORM_NAME;
+    name: string;
+    logLevel: LogLevel;
+    defaultHouseholdId?: string;
+    transport: LocalTransportConfig;
+    scenes: SceneDefinition[];
+}
+export interface SonosHouseholdSummary {
+    id: string;
+    displayName: string;
+}
+export interface SonosFavorite {
+    id: string;
+    name: string;
+    uri?: string;
+}
+export interface SonosPlayer {
+    id: string;
+    name: string;
+    model?: string;
+    capabilities: string[];
+    deviceIds: string[];
+    groupId?: string;
+    isCoordinator: boolean;
+    fixedVolume: boolean;
+    sourceOptions: SceneSourceKind[];
+}
+export interface SonosGroup {
+    id: string;
+    name: string;
+    coordinatorId: string;
+    playerIds: string[];
+    playbackState?: string;
+}
+export interface HouseholdSnapshot {
+    id: string;
+    displayName: string;
+    players: SonosPlayer[];
+    groups: SonosGroup[];
+    favorites: SonosFavorite[];
+}
+export interface TopologySnapshot {
+    capturedAt: string;
+    origin: "live" | "fixture";
+    households: HouseholdSnapshot[];
+}
+export interface SceneLogEntry {
+    timestamp: string;
+    level: LogLevel;
+    scope: string;
+    message: string;
+    sceneId?: string;
+    trigger?: SceneTrigger;
+}
+export interface SceneRunResult {
+    ok: boolean;
+    sceneId: string;
+    trigger: SceneTrigger;
+    logs: SceneLogEntry[];
+    errors: string[];
+    snapshot?: TopologySnapshot;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface SonosTransport {
+    readonly kind: string;
+    supportsSource(kind: SceneSourceKind): boolean;
+    discoverHouseholds(): Promise<SonosHouseholdSummary[]>;
+    discoverTopology(): Promise<TopologySnapshot>;
+    setGroupMembers(householdId: string, coordinatorPlayerId: string, memberPlayerIds: string[]): Promise<void>;
+    modifyGroupMembers(householdId: string, coordinatorPlayerId: string, membersToAdd: string[], membersToRemove: string[]): Promise<void>;
+    loadLineIn(householdId: string, coordinatorPlayerId: string, deviceId: string, playOnCompletion?: boolean): Promise<void>;
+    loadFavorite(householdId: string, coordinatorPlayerId: string, favoriteId: string): Promise<void>;
+    loadTv?(householdId: string, coordinatorPlayerId: string, deviceId: string, playOnCompletion?: boolean): Promise<void>;
+    setGroupVolume(householdId: string, coordinatorPlayerId: string, volume: number): Promise<void>;
+    setPlayerVolume(householdId: string, playerId: string, volume: number): Promise<void>;
+    ungroup(householdId: string, coordinatorPlayerId: string, memberPlayerIds?: string[]): Promise<void>;
+    subscribe?(listener: (snapshot: TopologySnapshot) => void): Promise<() => Promise<void> | void>;
+}

package/dist/src/types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_NAME = exports.PLUGIN_NAME = void 0;
+exports.PLUGIN_NAME = "homebridge-sonos-scenes";
+exports.PLATFORM_NAME = "SonosScenes";
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";;;AAEa,QAAA,WAAW,GAAG,yBAAyB,CAAC;AACxC,QAAA,aAAa,GAAG,aAAa,CAAC"}

package/dist/src/ui/serverApi.d.ts

@@ -0,0 +1,11 @@
+import type { SceneDefinition, SceneRunResult, ScenesPlatformConfig, TopologySnapshot, ValidationResult } from "../types";
+export declare function createDefaultUiConfig(): ScenesPlatformConfig;
+export declare function discoverForUi(configInput: Partial<ScenesPlatformConfig> | undefined): Promise<{
+    snapshot: TopologySnapshot;
+}>;
+export declare function validateSceneForUi(configInput: Partial<ScenesPlatformConfig> | undefined, sceneInput: Partial<SceneDefinition>): Promise<{
+    validation: ValidationResult;
+    normalizedScene: SceneDefinition;
+    snapshot: TopologySnapshot;
+}>;
+export declare function runTestForUi(configInput: Partial<ScenesPlatformConfig> | undefined, sceneInput: Partial<SceneDefinition>): Promise<SceneRunResult>;

package/dist/src/ui/serverApi.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDefaultUiConfig = createDefaultUiConfig;
+exports.discoverForUi = discoverForUi;
+exports.validateSceneForUi = validateSceneForUi;
+exports.runTestForUi = runTestForUi;
+const config_1 = require("../config");
+const discoveryService_1 = require("../discoveryService");
+const logger_1 = require("../logger");
+const sceneRunner_1 = require("../sceneRunner");
+const transports_1 = require("../transports");
+function createDefaultUiConfig() {
+    return (0, config_1.normalizePlatformConfig)(undefined);
+}
+async function buildServices(configInput) {
+    const config = (0, config_1.normalizePlatformConfig)(configInput);
+    const collector = new logger_1.MemoryLogCollector();
+    const logger = new logger_1.StructuredLogger("ui", config.logLevel, undefined, collector);
+    const transport = (0, transports_1.createTransport)(config);
+    const discoveryService = new discoveryService_1.DiscoveryService(transport);
+    const sceneRunner = new sceneRunner_1.SceneRunner(discoveryService, transport, logger);
+    return {
+        config,
+        transport,
+        discoveryService,
+        sceneRunner,
+        collector,
+    };
+}
+async function discoverForUi(configInput) {
+    const services = await buildServices(configInput);
+    return {
+        snapshot: await services.discoveryService.refresh(),
+    };
+}
+async function validateSceneForUi(configInput, sceneInput) {
+    const services = await buildServices(configInput);
+    const snapshot = await services.discoveryService.refresh();
+    const normalizedScene = (0, config_1.normalizeScene)(sceneInput);
+    const validation = (0, config_1.validateSceneDefinition)(normalizedScene, snapshot, services.transport);
+    return {
+        validation,
+        normalizedScene,
+        snapshot,
+    };
+}
+async function runTestForUi(configInput, sceneInput) {
+    const services = await buildServices(configInput);
+    const scene = (0, config_1.normalizeScene)(sceneInput);
+    return services.sceneRunner.runTest(scene);
+}
+//# sourceMappingURL=serverApi.js.map

package/dist/src/ui/serverApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverApi.js","sourceRoot":"","sources":["../../../src/ui/serverApi.ts"],"names":[],"mappings":";;AAOA,sDAEC;AAmBD,sCAOC;AAED,gDAcC;AAED,oCAOC;AA5DD,sCAA6F;AAC7F,0DAAuD;AACvD,sCAAiE;AACjE,gDAA6C;AAC7C,8CAAgD;AAGhD,SAAgB,qBAAqB;IACnC,OAAO,IAAA,gCAAuB,EAAC,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,WAAsD;IACjF,MAAM,MAAM,GAAG,IAAA,gCAAuB,EAAC,WAAW,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,IAAI,2BAAkB,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,yBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACjF,MAAM,SAAS,GAAG,IAAA,4BAAe,EAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,gBAAgB,GAAG,IAAI,mCAAgB,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,WAAW,GAAG,IAAI,yBAAW,CAAC,gBAAgB,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAEzE,OAAO;QACL,MAAM;QACN,SAAS;QACT,gBAAgB;QAChB,WAAW;QACX,SAAS;KACV,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,aAAa,CACjC,WAAsD;IAEtD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAClD,OAAO;QACL,QAAQ,EAAE,MAAM,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE;KACpD,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,kBAAkB,CACtC,WAAsD,EACtD,UAAoC;IAEpC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;IAC3D,MAAM,eAAe,GAAG,IAAA,uBAAc,EAAC,UAAU,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,IAAA,gCAAuB,EAAC,eAAe,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAE1F,OAAO;QACL,UAAU;QACV,eAAe;QACf,QAAQ;KACT,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,YAAY,CAChC,WAAsD,EACtD,UAAoC;IAEpC,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,IAAA,uBAAc,EAAC,UAAU,CAAC,CAAC;IACzC,OAAO,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC"}

package/examples/config.example.json

@@ -0,0 +1,48 @@
+{
+  "platforms": [
+    {
+      "platform": "SonosScenes",
+      "name": "Sonos Scenes",
+      "logLevel": "info",
+      "transport": {
+        "kind": "local",
+        "enableLiveDiscovery": true,
+        "fixturePath": "./examples/sample-topology.json",
+        "discoveryTimeoutMs": 2500,
+        "requestTimeoutMs": 5000,
+        "allowTvSource": false
+      },
+      "scenes": [
+        {
+          "id": "upper-level-line-in",
+          "name": "Upper Level Line In",
+          "householdId": "local-household",
+          "coordinatorPlayerId": "RINCON_UPPER_LEVEL",
+          "memberPlayerIds": [
+            "RINCON_PRIMARY_BEDROOM"
+          ],
+          "source": {
+            "kind": "line_in",
+            "deviceId": "RINCON_UPPER_LEVEL",
+            "deviceName": "Upper Level",
+            "playOnCompletion": true
+          },
+          "coordinatorVolume": 20,
+          "playerVolumes": [
+            {
+              "playerId": "RINCON_PRIMARY_BEDROOM",
+              "volume": 16
+            }
+          ],
+          "offBehavior": {
+            "kind": "ungroup"
+          },
+          "settleMs": 750,
+          "retryCount": 3,
+          "retryDelayMs": 750,
+          "autoResetMs": 1000
+        }
+      ]
+    }
+  ]
+}

package/examples/sample-topology.json

@@ -0,0 +1,77 @@
+{
+  "capturedAt": "2026-04-18T00:00:00.000Z",
+  "households": [
+    {
+      "id": "local-household",
+      "displayName": "Local Sonos",
+      "players": [
+        {
+          "id": "RINCON_UPPER_LEVEL",
+          "name": "Upper Level",
+          "capabilities": [
+            "PLAYBACK",
+            "LINE_IN",
+            "AIRPLAY"
+          ],
+          "deviceIds": [
+            "RINCON_UPPER_LEVEL"
+          ],
+          "groupId": "GROUP_UPPER_LEVEL",
+          "isCoordinator": true,
+          "fixedVolume": false,
+          "sourceOptions": [
+            "line_in",
+            "favorite"
+          ]
+        },
+        {
+          "id": "RINCON_PRIMARY_BEDROOM",
+          "name": "Primary Bedroom",
+          "capabilities": [
+            "PLAYBACK",
+            "AIRPLAY"
+          ],
+          "deviceIds": [
+            "RINCON_PRIMARY_BEDROOM"
+          ],
+          "groupId": "GROUP_PRIMARY_BEDROOM",
+          "isCoordinator": true,
+          "fixedVolume": false,
+          "sourceOptions": [
+            "favorite"
+          ]
+        }
+      ],
+      "groups": [
+        {
+          "id": "GROUP_UPPER_LEVEL",
+          "name": "Upper Level",
+          "coordinatorId": "RINCON_UPPER_LEVEL",
+          "playerIds": [
+            "RINCON_UPPER_LEVEL"
+          ],
+          "playbackState": "PLAYBACK_STATE_IDLE"
+        },
+        {
+          "id": "GROUP_PRIMARY_BEDROOM",
+          "name": "Primary Bedroom",
+          "coordinatorId": "RINCON_PRIMARY_BEDROOM",
+          "playerIds": [
+            "RINCON_PRIMARY_BEDROOM"
+          ],
+          "playbackState": "PLAYBACK_STATE_IDLE"
+        }
+      ],
+      "favorites": [
+        {
+          "id": "favorite-line-in-demo",
+          "name": "Line-In Demo"
+        },
+        {
+          "id": "favorite-kexp",
+          "name": "KEXP"
+        }
+      ]
+    }
+  ]
+}