@groovenet/player 0.1.2 → 0.1.4

package/build/server/store.d.ts

@@ -0,0 +1,33 @@
+import { Pool } from "pg";
+import { type CreateServerPlayer, type PlayerTrackRef, type ServerPlayer, type ServerPlayerState } from "@groovenet/contracts";
+import type { Track } from "@groovenet/client";
+export declare class ServerPlayerError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+export interface PlayerStore {
+    list(): Promise<ServerPlayer[]>;
+    create(input: CreateServerPlayer, state: ServerPlayerState): Promise<ServerPlayer>;
+    save(player: ServerPlayer, expectedRevision: number): Promise<ServerPlayer>;
+    checkpoint(player: ServerPlayer): Promise<void>;
+    resolve(ref: PlayerTrackRef): Promise<Track | null>;
+}
+/** Only the elected worker writes this table; every command also uses CAS. */
+export declare class PostgresPlayerStore implements PlayerStore {
+    readonly pool: Pool;
+    private lease?;
+    private onLost?;
+    constructor(pool: Pool);
+    acquire(onLost: () => void): Promise<void>;
+    heartbeat(): Promise<void>;
+    release(): Promise<void>;
+    private row;
+    list(): Promise<ServerPlayer[]>;
+    create(input: CreateServerPlayer, state: ServerPlayerState): Promise<ServerPlayer>;
+    save(player: ServerPlayer, expectedRevision: number): Promise<ServerPlayer>;
+    checkpoint(player: ServerPlayer): Promise<void>;
+    resolve(ref: PlayerTrackRef): Promise<Track | null>;
+    private mapError;
+}
+//# sourceMappingURL=store.d.ts.map

package/build/server/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/server/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmB,MAAM,IAAI,CAAC;AAC3C,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACnJ,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,qBAAa,iBAAkB,SAAQ,KAAK;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM;IAAmB,QAAQ,CAAC,MAAM;IAAnE,YAAqB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAW,MAAM,SAAM,EAAqB;CAC/F;AACD,MAAM,WAAW,WAAW;IAC1B,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAChC,MAAM,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACnF,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5E,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;CACrD;AAED,8EAA8E;AAC9E,qBAAa,mBAAoB,YAAW,WAAW;IAGzC,QAAQ,CAAC,IAAI,EAAE,IAAI;IAF/B,OAAO,CAAC,KAAK,CAAC,CAAa;IAC3B,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,YAAqB,IAAI,EAAE,IAAI,EAAI;IAE7B,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAW/C;IAEK,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAG/B;IAEK,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB7B;IAED,OAAO,CAAC,GAAG;IAIL,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAGpC;IAEK,MAAM,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAKvF;IAEK,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAMhF;IAEK,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpD;IAEK,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAIxD;IAED,OAAO,CAAC,QAAQ;CAIjB"}

package/build/server/store.js

@@ -0,0 +1,108 @@
+import { serverPlayerSchema } from "@groovenet/contracts";
+export class ServerPlayerError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 409) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+/** Only the elected worker writes this table; every command also uses CAS. */
+export class PostgresPlayerStore {
+    pool;
+    lease;
+    onLost;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async acquire(onLost) {
+        const client = await this.pool.connect();
+        try {
+            const result = await client.query("SELECT pg_try_advisory_lock(693, 1) AS acquired");
+            if (!result.rows[0]?.acquired)
+                throw new ServerPlayerError("WORKER_ALREADY_RUNNING", "Another player worker owns the engine lifecycles", 503);
+            this.lease = client;
+            this.onLost = onLost;
+            this.pool.on("error", onLost);
+            client.once("error", onLost);
+            client.once("end", onLost);
+        }
+        catch (error) {
+            client.release();
+            throw error;
+        }
+    }
+    async heartbeat() {
+        if (!this.lease)
+            throw new ServerPlayerError("WORKER_UNAVAILABLE", "Player worker has no database lease", 503);
+        await this.lease.query("SELECT 1");
+    }
+    async release() {
+        const lease = this.lease;
+        this.lease = undefined;
+        try {
+            if (lease) {
+                try {
+                    await lease.query("SELECT pg_advisory_unlock(693, 1)");
+                }
+                finally {
+                    lease.release();
+                }
+            }
+        }
+        finally {
+            if (this.onLost) {
+                this.pool.off("error", this.onLost);
+                lease?.off("error", this.onLost);
+                lease?.off("end", this.onLost);
+                this.onLost = undefined;
+            }
+            await this.pool.end();
+        }
+    }
+    row(row) {
+        return serverPlayerSchema.parse({ id: row.id, name: row.name, engine_id: row.engine_id, revision: Number(row.revision), assigned_output: row.assigned_output, state: row.state });
+    }
+    async list() {
+        const result = await this.pool.query("SELECT * FROM server_players ORDER BY id");
+        return result.rows.map((row) => this.row(row));
+    }
+    async create(input, state) {
+        try {
+            const result = await this.pool.query("INSERT INTO server_players(id, name, engine_id, state) VALUES ($1, $2, $3, $4::jsonb) RETURNING *", [input.id, input.name, input.engine_id, JSON.stringify(state)]);
+            return this.row(result.rows[0]);
+        }
+        catch (error) {
+            throw this.mapError(error);
+        }
+    }
+    async save(player, expectedRevision) {
+        try {
+            const result = await this.pool.query(`UPDATE server_players SET name=$2, assigned_output=$3, state=$4::jsonb, revision=revision+1, updated_at=now() WHERE id=$1 AND revision=$5 RETURNING *`, [player.id, player.name, player.assigned_output, JSON.stringify(player.state), expectedRevision]);
+            if (!result.rows[0])
+                throw new ServerPlayerError("REVISION_CONFLICT", "Player changed; refresh its state before retrying");
+            return this.row(result.rows[0]);
+        }
+        catch (error) {
+            throw this.mapError(error);
+        }
+    }
+    async checkpoint(player) {
+        // Do not bump the edit revision for elapsed-time updates. CAS prevents a
+        // delayed checkpoint from overwriting a newer command or queue transition.
+        await this.pool.query("UPDATE server_players SET state=$2::jsonb, updated_at=now() WHERE id=$1 AND revision=$3", [player.id, JSON.stringify(player.state), player.revision]);
+    }
+    async resolve(ref) {
+        const result = await this.pool.query("SELECT t.* FROM tracks t WHERE track_id=$1 AND friend_id=$2 LIMIT 2", [ref.track_id, ref.friend_id]);
+        if (result.rows.length !== 1)
+            return null;
+        return result.rows[0];
+    }
+    mapError(error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "23505")
+            return new ServerPlayerError("ASSIGNMENT_CONFLICT", "Player ID, engine, or speaker is already assigned");
+        return error;
+    }
+}
+//# sourceMappingURL=store.js.map

package/build/server/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/server/store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAA2F,MAAM,sBAAsB,CAAC;AAGnJ,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACrB,IAAI;IAAoC,MAAM;IAAnE,YAAqB,IAAY,EAAE,OAAe,EAAW,MAAM,GAAG,GAAG;QAAI,KAAK,CAAC,OAAO,CAAC,CAAC;oBAAvE,IAAI;sBAAoC,MAAM;IAA0B,CAAC;CAC/F;AASD,8EAA8E;AAC9E,MAAM,OAAO,mBAAmB;IAGT,IAAI;IAFjB,KAAK,CAAc;IACnB,MAAM,CAAc;IAC5B,YAAqB,IAAU;oBAAV,IAAI;IAAS,CAAC;IAEnC,KAAK,CAAC,OAAO,CAAC,MAAkB;QAC9B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;YACrF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ;gBAAE,MAAM,IAAI,iBAAiB,CAAC,wBAAwB,EAAE,kDAAkD,EAAE,GAAG,CAAC,CAAC;YAC9I,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YACrB,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC7B,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAAC,MAAM,KAAK,CAAC;QAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,SAAS;QACb,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,iBAAiB,CAAC,oBAAoB,EAAE,qCAAqC,EAAE,GAAG,CAAC,CAAC;QAC/G,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC;YACH,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC;oBAAC,MAAM,KAAK,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;gBAAC,CAAC;wBACvD,CAAC;oBAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBAAC,CAAC;YAC9B,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBACpC,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBACjC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC/B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;YAC1B,CAAC;YACD,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,GAAG,CAAC,GAA4B;QACtC,OAAO,kBAAkB,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,eAAe,EAAE,GAAG,CAAC,eAAe,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IACpL,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QACjF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAyB,EAAE,KAAwB;QAC9D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,mGAAmG,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC1M,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAoB,EAAE,gBAAwB;QACvD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,uJAAuJ,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;YAChS,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBAAE,MAAM,IAAI,iBAAiB,CAAC,mBAAmB,EAAE,mDAAmD,CAAC,CAAC;YAC3H,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAAoB;QACnC,yEAAyE;QACzE,2EAA2E;QAC3E,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,yFAAyF,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/K,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAmB;QAC/B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,qEAAqE,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;QAC3I,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAU,CAAC;IACjC,CAAC;IAEO,QAAQ,CAAC,KAAc;QAC7B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,IAAI,iBAAiB,CAAC,qBAAqB,EAAE,mDAAmD,CAAC,CAAC;QAC9L,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/build/types.d.ts

@@ -36,9 +36,11 @@ export interface PlaybackBackend {
     setVolume(volume: number): Promise<void>;
     listDevices(): Promise<AudioDevice[]>;
     setOutputDevice(deviceId: string): Promise<void>;
+    /** Transport evidence for server resume policy; selected alone is not connected. */
+    outputConnection?(): Promise<"connected" | "disconnected" | "unknown">;
     close(): Promise<void>;
 }
-export type PlayerErrorCode = "NO_AUDIO" | "MPV_NOT_FOUND" | "MPV_EXITED" | "MPV_IPC" | "STREAM_FAILED" | "DEVICE_UNAVAILABLE" | "INVALID_ARGUMENT";
+export type PlayerErrorCode = "NO_AUDIO" | "MPV_NOT_FOUND" | "MPV_EXITED" | "MPV_IPC" | "STREAM_FAILED" | "DEVICE_UNAVAILABLE" | "INVALID_ARGUMENT" | "ENGINE_UNAVAILABLE" | "ENGINE_INCOMPATIBLE" | "ENGINE_AUTH" | "ENGINE_TIMEOUT" | "ENGINE_API" | "DEVICE_BUSY" | "DEVICE_AUTH" | "PLAYBACK_INTERRUPTED";
 export declare class PlayerError extends Error {
     readonly code: PlayerErrorCode;
     constructor(code: PlayerErrorCode, message: string, options?: ErrorOptions);

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9F,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC9F,GAAG,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/F,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACtC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,eAAe,GACf,YAAY,GACZ,SAAS,GACT,eAAe,GACf,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,eAAe;IADhC,YACW,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAE9F,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC9D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC9F,GAAG,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC/F,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACtC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,oFAAoF;IACpF,gBAAgB,CAAC,IAAI,OAAO,CAAC,WAAW,GAAG,cAAc,GAAG,SAAS,CAAC,CAAC;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,eAAe,GACf,YAAY,GACZ,SAAS,GACT,eAAe,GACf,oBAAoB,GACpB,kBAAkB,GAClB,oBAAoB,GACpB,qBAAqB,GACrB,aAAa,GACb,gBAAgB,GAChB,YAAY,GACZ,aAAa,GACb,aAAa,GACb,sBAAsB,CAAC;AAE3B,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,eAAe;IADhC,YACW,IAAI,EAAE,eAAe,EAC9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF"}

package/build/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAyDA,MAAM,OAAO,WAAY,SAAQ,KAAK;IAEzB,IAAI;IADf,YACW,IAAqB,EAC9B,OAAe,EACf,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;oBAJf,IAAI;QAKb,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAmEA,MAAM,OAAO,WAAY,SAAQ,KAAK;IAEzB,IAAI;IADf,YACW,IAAqB,EAC9B,OAAe,EACf,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;oBAJf,IAAI;QAKb,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/owntone/Dockerfile

@@ -0,0 +1,27 @@
+# OwnTone is GPL-2.0; this image is built from the pinned upstream source plus
+# terminal-v1.patch. Keep both available when distributing a derived image.
+FROM alpine:3.22 AS build
+RUN apk add --no-cache alsa-lib-dev autoconf automake avahi-dev bison confuse-dev \
+    curl curl-dev flex g++ gawk gcc gettext-dev gnutls-dev gperf json-c-dev \
+    libevent-dev libgcrypt-dev libplist-dev libsodium-dev libtool libunistring-dev \
+    libwebsockets-dev libxml2-dev make protobuf-c-dev sqlite-dev ffmpeg-dev patch
+WORKDIR /source
+RUN curl -fsSL https://codeload.github.com/owntone/owntone-server/tar.gz/d6fb3edf5831de38134ebd92fcf09a730ddd37aa -o source.tar.gz \
+    && echo 'b2c391e25295ea9d598dba70e23dcbe31635ae38f36ac570aa61f7c803d98f98  source.tar.gz' | sha256sum -c - \
+    && tar -xzf source.tar.gz --strip-components=1 && rm source.tar.gz
+COPY terminal-v1.patch /source/terminal-v1.patch
+RUN patch -p1 < terminal-v1.patch \
+    && autoreconf -fi -I /usr/share/gettext/m4 \
+    && ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var \
+       --disable-install_systemd --disable-install_user --disable-webinterface \
+    && make -j2 && make DESTDIR=/output install \
+    && (cd src/libairptp && ./configure --prefix=/usr --enable-daemon && make -j2 && make DESTDIR=/output install) \
+    && rm -rf /output/var && make clean
+
+FROM alpine:3.22
+RUN apk add --no-cache alsa-lib avahi confuse curl dbus ffmpeg gnutls json-c \
+    libevent libgcrypt libplist libsodium libunistring libuuid libwebsockets libxml2 protobuf-c sqlite-libs
+COPY --from=build /output/ /
+# Corresponding source and patch are included for reproducibility/distribution.
+COPY --from=build /source/ /usr/src/owntone/
+ENTRYPOINT ["/usr/sbin/owntone", "-f", "-c", "/etc/owntone.conf"]

package/owntone/smoke.mjs

@@ -0,0 +1,135 @@
+// Network-isolated engine + real adapter test. Docker is required; no speakers,
+// production volumes, port publication or host packages are used.
+// Build the player and engine image first, then: node owntone/smoke.mjs
+import assert from "node:assert/strict";
+import { execFile, execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { OwnToneBackend } from "../build/ownToneBackend.js";
+
+const exec = promisify(execFile);
+const name = `groovenet-692-smoke-${process.pid}`;
+const dir = mkdtempSync(join(tmpdir(), "groovenet-692-"));
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const docker = (...args) => execFileSync("docker", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+const config = `general {
+ uid = "nobody"
+ db_path = "/tmp/engine/library.db"
+ cache_dir = "/tmp/engine"
+ logfile = "/dev/stderr"
+ loglevel = log
+ trusted_networks = { "localhost" }
+ bind_address = "127.0.0.1"
+ speaker_autoselect = no
+}
+library {
+ name = "Groovenet 692 isolated"
+ port = 13689
+ directories = { "/tmp/media" }
+ clear_queue_on_stop_disable = true
+}
+audio { type = "dummy" }
+mpd { port = 0 }
+`;
+writeFileSync(join(dir, "engine.conf"), config);
+const transport = async (input, init = {}) => {
+  const args = ["exec", name, "curl", "-sS", "--max-time", "5", "-X", init.method ?? "GET", "-w", "\n%{http_code}"];
+  for (const [key, value] of Object.entries(init.headers ?? {})) args.push("-H", `${key}: ${value}`);
+  if (init.body) args.push("-d", String(init.body));
+  args.push(String(input));
+  const { stdout } = await exec("docker", args, { signal: init.signal });
+  const split = stdout.lastIndexOf("\n");
+  const status = Number(stdout.slice(split + 1));
+  return new Response(status === 204 ? null : stdout.slice(0, split), { status });
+};
+const read = async (path) => (await transport(`http://127.0.0.1:13689/api/${path}`)).json();
+const put = (path) => transport(`http://127.0.0.1:13689/api/${path}`, { method: "PUT" });
+const wait = async (predicate, message) => {
+  const deadline = Date.now() + 12000;
+  while (Date.now() < deadline) {
+    if (await predicate()) return;
+    await delay(100);
+  }
+  throw new Error(`Timed out: ${message}`);
+};
+let backend;
+try {
+  docker("run", "-d", "--name", name, "--network", "none", "--mount", `type=bind,src=${join(dir, "engine.conf")},dst=/tmp/engine.conf,readonly`, "--entrypoint", "/bin/sh", "groovenet-owntone:692-test", "-ec", `
+    mkdir -p /tmp/engine /tmp/media /run/dbus
+    chown nobody /tmp/engine /tmp/media
+    ffmpeg -y -v error -f lavfi -i 'sine=frequency=440:duration=3' -af volume=0.01 /tmp/media/short.wav
+    ffmpeg -y -v error -f lavfi -i 'sine=frequency=440:duration=15' -af volume=0.01 /tmp/media/long.wav
+    rm -f /run/dbus/pid /run/dbus/dbus.pid /run/avahi-daemon/pid
+    dbus-uuidgen --ensure
+    dbus-daemon --system --fork
+    avahi-daemon --daemonize --no-drop-root
+    exec /usr/sbin/owntone -f -c /tmp/engine.conf
+  `);
+  await wait(async () => {
+    try { return (await read("search?type=tracks&expression=media_kind%20is%20music")).tracks.items.length === 2; }
+    catch { return false; }
+  }, "fixture index");
+  const devices = await read("outputs");
+  assert.equal(devices.outputs.length, 1);
+  const outputId = devices.outputs[0].id;
+  backend = new OwnToneBackend({ apiUrl: "http://127.0.0.1:13689/api", outputId, fetch: transport, pollIntervalMs: 100 });
+  let ended = 0;
+  const errors = [];
+  const positions = [];
+  backend.on("ended", () => ended++).on("error", (error) => errors.push(error)).on("position", (position) => positions.push(position));
+  await backend.load({ url: "file:///tmp/media/short.wav" });
+  await wait(() => ended === 1 || errors.length > 0, "natural completion");
+  assert.deepEqual(errors, []);
+  assert.equal(ended, 1);
+  assert.equal((await read("player")).groovenet_terminal.reason, "eof");
+  console.log("PASS: natural EOF emitted exactly once through the real adapter");
+  await backend.load({ url: "file:///tmp/media/long.wav" });
+  await wait(() => positions.some((p) => p > 0.1), "position progress");
+  await backend.pause(true);
+  await backend.seek(5);
+  await backend.pause(false);
+  await backend.setVolume(5);
+  await put("player/stop");
+  await wait(() => errors.length > 0, "explicit external stop");
+  assert.equal(ended, 1);
+  assert.equal(errors.at(-1).code, "PLAYBACK_INTERRUPTED");
+  assert.equal((await read("player")).groovenet_terminal.reason, "interrupted");
+  console.log("PASS: external stop does not advance; pause/resume/absolute seek/volume accepted");
+  errors.length = 0;
+  await backend.load({ url: "file:///tmp/media/long.wav" });
+  await put("queue/clear");
+  await wait(() => errors.length > 0, "external queue replacement");
+  assert.equal(ended, 1);
+  assert.equal(errors.at(-1).code, "PLAYBACK_INTERRUPTED");
+  console.log("PASS: external queue replacement does not advance");
+  await backend.close();
+  backend = undefined;
+  // Restart the same container: its DB survives, but its signal epoch must not.
+  const beforeRestart = (await read("player")).groovenet_terminal.instance;
+  backend = new OwnToneBackend({ apiUrl: "http://127.0.0.1:13689/api", outputId, fetch: transport, pollIntervalMs: 100 });
+  let restartEnded = 0;
+  const restartErrors = [];
+  backend.on("ended", () => restartEnded++).on("error", (error) => restartErrors.push(error));
+  await backend.load({ url: "file:///tmp/media/long.wav" });
+  docker("restart", name);
+  await wait(async () => {
+    try { return (await read("player")).groovenet_terminal.instance !== beforeRestart; }
+    catch { return false; }
+  }, "new engine epoch");
+  await wait(() => restartErrors.some((error) => error.code === "PLAYBACK_INTERRUPTED"), "restart reconciliation");
+  assert.equal(restartEnded, 0);
+  assert.equal((await read("player")).state, "stop");
+  console.log("PASS: engine restart changes epoch and never replays or advances");
+  await backend.close();
+  backend = undefined;
+  console.log("PASS: isolated smoke complete (dummy output only; no audible hardware validation)");
+} catch (error) {
+  try { execFileSync("docker", ["logs", "--tail", "50", name], { stdio: "inherit" }); } catch { /* not started */ }
+  throw error;
+} finally {
+  await backend?.close().catch(() => {});
+  try { docker("rm", "-f", name); } catch { /* already gone */ }
+  rmSync(dir, { recursive: true, force: true });
+}

package/owntone/terminal-v1.patch

@@ -0,0 +1,96 @@
+--- a/src/player.h
++++ b/src/player.h
+@@ -44,0 +45 @@
++  bool gn_connected;
+@@ -72,0 +74,6 @@
++
++  /* Groovenet terminal signal v1; snapshotted on the player thread. */
++  char gn_instance[33];
++  uint32_t gn_sequence;
++  uint32_t gn_item_id;
++  const char *gn_reason;
+--- a/src/player.c
++++ b/src/player.c
+@@ -201,0 +202,3 @@
++  // Never report an input/output failure as natural completion.
++  bool gn_failed;
++
+@@ -341,0 +345,14 @@
++
++// Groovenet terminal signal. All access is confined to the player thread.
++static char gn_instance[33];
++static uint32_t gn_sequence;
++static uint32_t gn_item_id;
++static const char *gn_reason = "none";
++
++static void
++gn_terminal(uint32_t item_id, const char *reason)
++{
++  gn_sequence++;
++  gn_item_id = item_id;
++  gn_reason = reason;
++}
+@@ -1023,0 +1041,2 @@
++  pb_session.reading_now->gn_failed = true;
++  gn_terminal(pb_session.reading_now->item_id, "input_error");
+@@ -1090,0 +1110,3 @@
++
++  gn_terminal(pb_session.playing_now->item_id,
++    pb_session.playing_now->gn_failed ? "failed" : "eof");
+@@ -1499,0 +1522,9 @@
++  if ((!device || status == OUTPUT_STATE_FAILED || (status == OUTPUT_STATE_STOPPED && player_state == PLAY_PLAYING))
++      && pb_session.playing_now)
++    {
++      pb_session.playing_now->gn_failed = true;
++      if (pb_session.reading_now)
++        pb_session.reading_now->gn_failed = true;
++      gn_terminal(pb_session.playing_now->item_id, "output_lost");
++    }
++
+@@ -1516,7 +1547,3 @@
+-      if (!device->resurrect)
+-	goto out;
+-
+-      DPRINTF(E_LOG, L_PLAYER, "Attempting reconnection in %d sec to the %s device '%s'\n", PLAYER_SPEAKER_RESURRECT_TIME, device->type_name, device->name);
+-
+-      // TODO do this internally instead of through the worker
+-      worker_execute(player_speaker_resurrect, &(device->id), sizeof(device->id), PLAYER_SPEAKER_RESURRECT_TIME);
++      // Groovenet never automatically reclaims a failed/taken-over receiver.
++      // A new explicit play/output-selection action is required.
++      goto out;
+@@ -1791,0 +1819,3 @@
++  if (pb_session.playing_now)
++    gn_terminal(pb_session.playing_now->item_id, "interrupted");
++
+@@ -1910,0 +1941,4 @@
++  memcpy(status->gn_instance, gn_instance, sizeof(status->gn_instance));
++  status->gn_sequence = gn_sequence;
++  status->gn_item_id = gn_item_id;
++  status->gn_reason = gn_reason;
+@@ -2564,0 +2599 @@
++  spk->gn_connected = (device->session != NULL);
+@@ -3943 +3978,7 @@
+-  int ret;
++  unsigned char nonce[16];
++  unsigned int i;
++  int ret;
++
++  gcry_create_nonce(nonce, sizeof(nonce));
++  for (i = 0; i < sizeof(nonce); i++)
++    snprintf(gn_instance + i * 2, 3, "%02x", nonce[i]);
+--- a/src/httpd_jsonapi.c
++++ b/src/httpd_jsonapi.c
+@@ -1631,0 +1632,3 @@
++  json_object_object_add(output, "busy", json_object_new_boolean(spk->busy));
++  json_object_object_add(output, "connected", json_object_new_boolean(spk->gn_connected));
++  json_object_object_add(output, "prevent_playback", json_object_new_boolean(spk->prevent_playback));
+@@ -2198,0 +2202,9 @@
++
++  /* Additive, versioned extension: stock OwnTone clients ignore these fields. */
++  json_object *terminal = json_object_new_object();
++  json_object_object_add(terminal, "version", json_object_new_int(1));
++  json_object_object_add(terminal, "instance", json_object_new_string(status.gn_instance));
++  json_object_object_add(terminal, "sequence", json_object_new_int64(status.gn_sequence));
++  json_object_object_add(terminal, "item_id", json_object_new_int64(status.gn_item_id));
++  json_object_object_add(terminal, "reason", json_object_new_string(status.gn_reason));
++  json_object_object_add(reply, "groovenet_terminal", terminal);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groovenet/player",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Headless playback core and mpv backend for Groovenet",
   "type": "module",
   "engines": {
@@ -8,6 +8,10 @@
   },
   "main": "build/index.js",
   "types": "build/index.d.ts",
+  "bin": {
+    "groovenet-mpris": "build/mprisBin.js",
+    "groovenet-player-server": "build/server/bin.js"
+  },
   "exports": {
     ".": {
       "import": "./build/index.js",
@@ -20,6 +24,10 @@
     "./testing": {
       "import": "./build/testing.js",
       "types": "./build/testing.d.ts"
+    },
+    "./server": {
+      "types": "./build/server/manager.d.ts",
+      "import": "./build/server/manager.js"
     }
   },
   "scripts": {
@@ -29,16 +37,25 @@
     "test:coverage": "vitest run --coverage"
   },
   "files": [
-    "build/"
+    "build/",
+    "MPRIS.md",
+    "OWNTONE.md",
+    "SERVER_PLAYERS.md",
+    "owntone/",
+    "scripts/mpris-smoke.mjs"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@groovenet/client": "^3.3.0"
+    "@groovenet/client": "^3.5.0",
+    "@groovenet/contracts": "1.2.0",
+    "pg": "8.23.1",
+    "zod": "4.6.7"
   },
   "devDependencies": {
-    "@types/node": "^26.6.4",
+    "@types/node": "^26.6.5",
+    "@types/pg": "8.23.1",
     "@vitest/coverage-v8": "^5.0.3",
     "typescript": "^7.0",
     "vitest": "^5.0.0"
@@ -48,5 +65,8 @@
     "type": "git",
     "url": "git+https://github.com/Public-Vinyl-Radio/groovenet.git",
     "directory": "packages/groovenet-player"
+  },
+  "optionalDependencies": {
+    "dbus-next": "0.10.2"
   }
 }

package/scripts/mpris-smoke.mjs

@@ -0,0 +1,54 @@
+// Run on Linux: dbus-run-session -- node packages/groovenet-player/scripts/mpris-smoke.mjs
+// Requires built workspaces, optional dbus-next dependency, dbus and playerctl.
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { PlayerDaemon, PlayerCore, TrackResolver } from "../build/index.js";
+import { TestPlaybackBackend } from "../build/testing.js";
+import { startMpris } from "../build/mpris.js";
+
+const dir = await mkdtemp(join(tmpdir(), "groovenet-mpris-"));
+const backend = new TestPlaybackBackend();
+const player = new PlayerCore(backend, new TrackResolver({}, { apiBase: "http://unused/api" }));
+const paths = { socketPath: join(dir, "player.sock"), pidPath: join(dir, "player.pid") };
+const daemon = new PlayerDaemon({ player, paths });
+const ctl = async (...args) => (await promisify(execFile)("playerctl", ["--player=groovenet", ...args])).stdout.trim();
+let close;
+try {
+  player.add(["First", "Second"].map((title) => ({ title, track_id: title, artist: "Artist", album: "Album", friend_id: 1, local_audio_url: `${title}.mp3` })));
+  await daemon.start();
+  close = await startMpris(paths.socketPath);
+  assert.ok(close, "MPRIS must be enabled in this session");
+  assert.equal(await ctl("status"), "Stopped");
+  await ctl("play");
+  assert.equal(await ctl("status"), "Playing");
+  assert.equal(await ctl("metadata", "xesam:title"), "First");
+  assert.equal(await ctl("metadata", "xesam:artist"), "Artist");
+  assert.equal(await ctl("metadata", "xesam:album"), "Album");
+  await ctl("play-pause");
+  assert.equal(await ctl("status"), "Paused");
+  await ctl("position", "12.5");
+  assert.equal(Number(await ctl("position")), 12.5);
+  await ctl("position", "2+");
+  assert.equal(Number(await ctl("position")), 14.5);
+  await ctl("play-pause");
+  assert.equal(await ctl("status"), "Playing");
+  await ctl("next");
+  assert.equal(await ctl("metadata", "xesam:title"), "Second");
+  await ctl("previous");
+  assert.equal(await ctl("metadata", "xesam:title"), "First");
+  await ctl("stop");
+  assert.equal(await ctl("status"), "Stopped");
+  assert.equal(player.snapshot.queue.length, 2);
+  await close();
+  await player.play();
+  assert.equal(player.snapshot.status, "playing");
+  console.log("MPRIS playerctl smoke test passed.");
+} finally {
+  await close?.();
+  await daemon.stop();
+  await rm(dir, { recursive: true, force: true });
+}