@hashsome/integration.music-assistant 0.1.0

package/dist/index.js

@@ -0,0 +1,423 @@
+import { BaseIntegration, UnknownEntityError, } from '@hashsome/core';
+import { parseUri, SHELVES, toBrowseItem } from './browse.js';
+import { toMediaPlayer } from './mapper.js';
+import { onPlayback, onQueue, positionOf } from './position.js';
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const isMaPlayer = (value) => isRecord(value) && typeof value.player_id === 'string';
+/** Maps a model command onto a Music Assistant `players/cmd/*` command, validating its arguments. */
+function commandFor(name, args) {
+    switch (name) {
+        case 'play':
+            return { command: 'players/cmd/play' };
+        case 'pause':
+            return { command: 'players/cmd/pause' };
+        case 'togglePlay':
+            return { command: 'players/cmd/play_pause' };
+        case 'next':
+            return { command: 'players/cmd/next' };
+        case 'previous':
+            return { command: 'players/cmd/previous' };
+        case 'setVolume': {
+            const volume = args?.volume;
+            if (typeof volume !== 'number' || !Number.isFinite(volume)) {
+                throw new Error('setVolume needs a numeric volume between 0 and 1');
+            }
+            return {
+                command: 'players/cmd/volume_set',
+                args: { volume_level: Math.round(Math.min(1, Math.max(0, volume)) * 100) },
+            };
+        }
+        case 'setMuted':
+            if (typeof args?.muted !== 'boolean') {
+                throw new Error('setMuted needs a boolean "muted"');
+            }
+            return { command: 'players/cmd/volume_mute', args: { muted: args.muted } };
+        case 'setShuffle':
+            if (typeof args?.shuffle !== 'boolean') {
+                throw new Error('setShuffle needs a boolean "shuffle"');
+            }
+            return {
+                command: 'player_queues/shuffle',
+                args: { shuffle_enabled: args.shuffle },
+                idKey: 'queue_id',
+            };
+        case 'seek': {
+            const position = args?.position;
+            if (typeof position !== 'number' || !Number.isFinite(position)) {
+                throw new Error('seek needs a numeric position in seconds');
+            }
+            // Queues are addressed by their own id, which is the player's.
+            return {
+                command: 'player_queues/seek',
+                args: { position: Math.max(0, Math.round(position)) },
+                idKey: 'queue_id',
+            };
+        }
+        case 'playMedia': {
+            const mode = args?.mode ?? 'play';
+            if (typeof args?.item !== 'string' || args.item === '') {
+                throw new Error('playMedia needs an item id');
+            }
+            if (!['play', 'replace', 'next', 'add'].includes(String(mode))) {
+                throw new Error('"mode" must be play, replace, next or add');
+            }
+            return {
+                command: 'player_queues/play_media',
+                args: { media: args.item, option: mode },
+                idKey: 'queue_id',
+            };
+        }
+        default:
+            throw new Error(`A media player has no "${name}" command`);
+    }
+}
+function wsUrl(url) {
+    const parsed = new URL(url);
+    parsed.protocol = parsed.protocol === 'https:' ? 'wss:' : 'ws:';
+    parsed.pathname = `${parsed.pathname.replace(/\/$/, '')}/ws`;
+    return parsed.toString();
+}
+const samePosition = (a, b) => a.item === b.item &&
+    a.elapsed === b.elapsed &&
+    a.resume === b.resume &&
+    a.held === b.held &&
+    a.inherited === b.inherited;
+/** Which track a queue is on, as something comparable: its address when it has one, else its name or place. */
+function itemOf(queue) {
+    // The track's own address. The queue's id for the item is not kept when a stopped queue is
+    // resumed, so it would make a resume look like a different track.
+    const current = queue.current_item;
+    if (isRecord(current)) {
+        const media = current.media_item;
+        if (isRecord(media) && typeof media.uri === 'string') {
+            return media.uri;
+        }
+        if (typeof current.name === 'string') {
+            return current.name;
+        }
+        if (typeof current.queue_item_id === 'string') {
+            return current.queue_item_id;
+        }
+    }
+    return typeof queue.current_index === 'number' ? `#${queue.current_index}` : undefined;
+}
+export class MusicAssistantIntegration extends BaseIntegration {
+    id;
+    #options;
+    #socket;
+    #nextMessageId = 1;
+    /** The last raw player and what its queue says, so either can change without the other. A queue
+     * has the player's id. */
+    #players = new Map();
+    #queues = new Map();
+    #pending = new Map();
+    #stopped = true;
+    #retry = 0;
+    #timer;
+    /** True once the initial handshake has succeeded at least once — only then does a later close
+     * count as a "drop" worth auto-reconnecting; a close during the *first* attempt is a connect()
+     * failure that the runtime's own startup retry loop owns (see `connect()`'s doc comment). */
+    #everConnected = false;
+    constructor(options) {
+        super();
+        this.id = options.id ?? 'ma';
+        this.#options = options;
+    }
+    /** Resolves once authenticated and the initial player list has been fetched. Later drops are
+     * reconnected internally with backoff (mirrors how the runtime treats every integration: it
+     * only calls `connect()` once, at startup). */
+    connect() {
+        if (!this.#stopped) {
+            return Promise.resolve();
+        }
+        this.#stopped = false;
+        this.setStatus('connecting');
+        return this.#open();
+    }
+    disconnect() {
+        this.#stopped = true;
+        clearTimeout(this.#timer);
+        for (const { reject } of this.#pending.values()) {
+            reject(new Error('Disconnected'));
+        }
+        this.#pending.clear();
+        this.#socket?.close();
+        this.#socket = undefined;
+        this.setStatus('disconnected');
+    }
+    async command(entityId, name, args) {
+        if (!this.getEntity(entityId)) {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        const { command, args: commandArgs, idKey = 'player_id' } = commandFor(name, args);
+        await this.#send(command, { [idKey]: entityId, ...commandArgs });
+    }
+    /** One level of the library, or a search across it, through Music Assistant's own API. */
+    async browse(entityId, query) {
+        if (!this.getEntity(entityId)) {
+            throw new UnknownEntityError(this.id, entityId);
+        }
+        if (query.search !== undefined) {
+            return this.#search(query.search);
+        }
+        if (query.path === undefined) {
+            return { items: SHELVES.map((shelf) => ({ ...shelf, playable: false, expandable: true })) };
+        }
+        const shelf = SHELVES.find((candidate) => candidate.id === query.path);
+        const found = shelf ? await this.#shelfItems(shelf.id) : await this.#childItems(query.path);
+        return { ...(shelf ? { title: shelf.title } : {}), items: found };
+    }
+    async #shelfItems(shelfId) {
+        const library = {
+            'shelf:recent': ['music/recently_played_items', { limit: 25 }],
+            'shelf:playlists': ['music/playlists/library_items', { limit: 200, order_by: 'name' }],
+            'shelf:albums': ['music/albums/library_items', { limit: 200, order_by: 'name' }],
+            'shelf:artists': ['music/artists/library_items', { limit: 200, order_by: 'name' }],
+            'shelf:radio': ['music/radios/library_items', { limit: 200, order_by: 'name' }],
+        };
+        const [command, args] = library[shelfId] ?? [];
+        return command ? this.#items(await this.#send(command, args ?? {})) : [];
+    }
+    /** What is inside an album, a playlist or an artist. */
+    async #childItems(uri) {
+        const { provider, type, id } = parseUri(uri);
+        const command = {
+            album: 'music/albums/album_tracks',
+            playlist: 'music/playlists/playlist_tracks',
+            artist: 'music/artists/artist_albums',
+        }[type];
+        if (!command) {
+            throw new Error(`"${uri}" has nothing inside it`);
+        }
+        return this.#items(await this.#send(command, { item_id: id, provider_instance_id_or_domain: provider }));
+    }
+    async #search(text) {
+        const results = await this.#send('music/search', {
+            search_query: text,
+            media_types: ['album', 'artist', 'track', 'playlist', 'radio'],
+            limit: 8,
+        });
+        const groups = isRecord(results)
+            ? [results.albums, results.artists, results.tracks, results.playlists, results.radio]
+            : [];
+        return { title: `Results for “${text}”`, items: groups.flatMap((group) => this.#items(group)) };
+    }
+    #items(list) {
+        return Array.isArray(list)
+            ? list.flatMap((item) => {
+                const mapped = isRecord(item) ? toBrowseItem(item) : undefined;
+                return mapped ? [mapped] : [];
+            })
+            : [];
+    }
+    async #open() {
+        const socket = (this.#options.createSocket ?? ((url) => new WebSocket(url)))(wsUrl(this.#options.url));
+        this.#socket = socket;
+        socket.addEventListener('message', (event) => {
+            this.#handle(String(event.data));
+        });
+        const closed = new Promise((_resolve, reject) => {
+            socket.addEventListener('close', () => {
+                if (this.#socket !== socket) {
+                    return;
+                }
+                this.#socket = undefined;
+                for (const { reject: rejectPending } of this.#pending.values()) {
+                    rejectPending(new Error('Connection lost'));
+                }
+                this.#pending.clear();
+                reject(new Error('Music Assistant connection closed'));
+                // A close during the first handshake is this attempt failing (status is already
+                // 'error', set below) — only a drop after a prior success should move to 'disconnected'
+                // and trigger our own reconnect; a first-attempt failure is retried by the caller.
+                if (this.#everConnected) {
+                    this.setStatus('disconnected');
+                    if (!this.#stopped) {
+                        this.#scheduleReconnect();
+                    }
+                }
+            });
+        });
+        const opened = new Promise((resolve, reject) => {
+            socket.addEventListener('open', () => resolve());
+            socket.addEventListener('error', () => reject(new Error('Music Assistant connection failed')));
+        });
+        try {
+            await Promise.race([opened, closed]);
+            await Promise.race([this.#authenticateAndLoad(), closed]);
+            this.#everConnected = true;
+            this.#retry = 0;
+            this.setStatus('connected');
+        }
+        catch (error) {
+            this.setStatus('error');
+            socket.close();
+            throw error;
+        }
+    }
+    #scheduleReconnect() {
+        const min = this.#options.reconnectMinMs ?? 500;
+        const max = this.#options.reconnectMaxMs ?? 10_000;
+        const delay = Math.min(max, min * 2 ** this.#retry++);
+        this.#timer = setTimeout(() => {
+            if (this.#stopped) {
+                return;
+            }
+            this.setStatus('connecting');
+            this.#open().catch(() => this.#scheduleReconnect());
+        }, delay);
+    }
+    async #authenticateAndLoad() {
+        await this.#send('auth', { token: this.#options.token });
+        const players = await this.#send('players/all', {});
+        const next = new Map();
+        this.#players.clear();
+        if (Array.isArray(players)) {
+            for (const player of players) {
+                if (isMaPlayer(player)) {
+                    this.#players.set(player.player_id, player);
+                    next.set(player.player_id, this.#entityFor(player));
+                }
+            }
+        }
+        this.replaceEntities(next);
+        // Shuffle lives on the queues. They are asked for after the players are known, and without
+        // holding the connection up: a server that does not answer just leaves shuffle unreported.
+        this.#send('player_queues/all', {}).then((queues) => {
+            if (Array.isArray(queues)) {
+                queues.forEach((queue) => this.#applyQueue(queue));
+            }
+        }, () => { });
+    }
+    /** What a player looks like with its queue's shuffle setting and position copied onto it. The
+     * position is the queue's, not the player's: when playback is resumed Music Assistant starts a
+     * new stream at the saved spot, and the player's own counter then starts from 0 again, while
+     * the queue keeps counting through the track. */
+    #entityFor(player) {
+        const queue = this.#queues.get(player.player_id);
+        if (!queue) {
+            // A stopped player's own counter is back at the start: until the queue says more, no position.
+            return toMediaPlayer(player.playback_state === 'idle'
+                ? { ...player, elapsed_time: null, elapsed_time_last_updated: null }
+                : player);
+        }
+        const position = positionOf(queue.position, player.playback_state);
+        return toMediaPlayer({
+            ...player,
+            ...(queue.shuffle !== undefined ? { shuffle_enabled: queue.shuffle } : {}),
+            ...(position !== undefined
+                ? { elapsed_time: position, elapsed_time_last_updated: queue.position.elapsedAt }
+                : {}),
+        });
+    }
+    #applyQueue(queue) {
+        if (!isRecord(queue) || typeof queue.queue_id !== 'string') {
+            return;
+        }
+        const known = this.#queues.get(queue.queue_id) ?? { position: {} };
+        const player = this.#players.get(queue.queue_id);
+        const message = {
+            item: itemOf(queue),
+            elapsed: typeof queue.elapsed_time === 'number' ? queue.elapsed_time : undefined,
+            resume: typeof queue.resume_pos === 'number' ? queue.resume_pos : undefined,
+        };
+        // The player's state says whether it is stopped; the queue's own `state` is not kept in step.
+        const playback = player?.playback_state ?? (typeof queue.state === 'string' ? queue.state : undefined);
+        const next = {
+            ...known,
+            ...(typeof queue.shuffle_enabled === 'boolean' ? { shuffle: queue.shuffle_enabled } : {}),
+            position: onQueue(known.position, message, playback, Date.now() / 1000),
+        };
+        this.#changeQueue(queue.queue_id, known, next);
+    }
+    /** Keeps a queue's new state and, when something it shows changed, the player's entity. */
+    #changeQueue(id, known, next) {
+        if (next.shuffle === known.shuffle && samePosition(next.position, known.position)) {
+            this.#queues.set(id, next);
+            return;
+        }
+        this.#queues.set(id, next);
+        const player = this.#players.get(id);
+        if (player) {
+            this.setEntity(player.player_id, this.#entityFor(player));
+        }
+    }
+    /** A player changed state: a stop remembers where it got to, a start from a stop begins there. */
+    #playerChanged(id, from, to) {
+        const known = this.#queues.get(id);
+        if (known) {
+            this.#queues.set(id, {
+                ...known,
+                position: onPlayback(known.position, from, to, Date.now() / 1000),
+            });
+        }
+    }
+    #send(command, args) {
+        const socket = this.#socket;
+        if (!socket) {
+            return Promise.reject(new Error('Not connected'));
+        }
+        const messageId = String(this.#nextMessageId++);
+        return new Promise((resolve, reject) => {
+            this.#pending.set(messageId, { resolve, reject });
+            socket.send(JSON.stringify({ message_id: messageId, command, args }));
+        });
+    }
+    #handle(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!isRecord(message)) {
+            return;
+        }
+        if (typeof message.event === 'string') {
+            this.#handleEvent(message.event, message.object_id, message.data);
+            return;
+        }
+        if (typeof message.message_id !== 'string') {
+            return;
+        }
+        const pending = this.#pending.get(message.message_id);
+        if (!pending) {
+            return;
+        }
+        this.#pending.delete(message.message_id);
+        if (typeof message.error_code === 'number') {
+            pending.reject(new Error(typeof message.details === 'string'
+                ? message.details
+                : `Music Assistant error ${message.error_code}`));
+        }
+        else if ('result' in message) {
+            pending.resolve(message.result);
+        }
+    }
+    #handleEvent(event, objectId, data) {
+        switch (event) {
+            case 'player_added':
+            case 'player_updated':
+                if (isMaPlayer(data)) {
+                    this.#playerChanged(data.player_id, this.#players.get(data.player_id)?.playback_state, data.playback_state);
+                    this.#players.set(data.player_id, data);
+                    this.setEntity(data.player_id, this.#entityFor(data));
+                }
+                return;
+            case 'queue_added':
+            case 'queue_updated':
+                this.#applyQueue(data);
+                return;
+            case 'player_removed':
+                if (typeof objectId === 'string') {
+                    this.#players.delete(objectId);
+                    this.#queues.delete(objectId);
+                    this.setEntity(objectId, undefined);
+                }
+                return;
+            default:
+                return;
+        }
+    }
+}

package/dist/mapper.d.ts

@@ -0,0 +1,26 @@
+import type { EntityInput } from '@hashsome/core';
+export interface MaPlayerMedia {
+    title?: string | null;
+    artist?: string | null;
+    album?: string | null;
+    image_url?: string | null;
+    duration?: number | null;
+}
+export interface MaPlayer {
+    player_id: string;
+    display_name?: string | null;
+    name?: string | null;
+    available?: boolean;
+    playback_state?: string;
+    volume_level?: number | null;
+    volume_muted?: boolean | null;
+    current_media?: MaPlayerMedia | null;
+    /** The queue's shuffle setting, which Music Assistant keeps on the queue, not on the player: the
+     * integration copies it onto the player it belongs to. */
+    shuffle_enabled?: boolean | null;
+    /** Seconds into the current item, as of `elapsed_time_last_updated` (a UTC epoch in seconds). */
+    elapsed_time?: number | null;
+    elapsed_time_last_updated?: number | null;
+}
+/** Maps a Music Assistant player to the generic `mediaPlayer` entity (everything but `ref`). */
+export declare function toMediaPlayer(player: MaPlayer): EntityInput;

package/dist/mapper.js

@@ -0,0 +1,50 @@
+const PLAYBACK = {
+    playing: 'playing',
+    paused: 'paused',
+    idle: 'idle',
+    buffering: 'buffering',
+};
+/** Maps a Music Assistant player to the generic `mediaPlayer` entity (everything but `ref`). */
+export function toMediaPlayer(player) {
+    const media = player.current_media ?? undefined;
+    const available = player.available !== false;
+    return {
+        kind: 'mediaPlayer',
+        name: player.display_name ?? player.name ?? player.player_id,
+        availability: available ? 'ready' : 'unavailable',
+        playback: available ? (PLAYBACK[player.playback_state ?? ''] ?? 'idle') : 'off',
+        muted: player.volume_muted === true,
+        ...(typeof player.volume_level === 'number' ? { volume: player.volume_level / 100 } : {}),
+        ...(media
+            ? {
+                media: {
+                    ...(media.title ? { title: media.title } : {}),
+                    ...(media.artist ? { artist: media.artist } : {}),
+                    ...(media.album ? { album: media.album } : {}),
+                    ...(media.image_url ? { artworkUrl: media.image_url } : {}),
+                },
+            }
+            : {}),
+        ...(typeof player.shuffle_enabled === 'boolean' ? { shuffle: player.shuffle_enabled } : {}),
+        ...(typeof player.elapsed_time === 'number' &&
+            typeof player.elapsed_time_last_updated === 'number'
+            ? {
+                position: player.elapsed_time,
+                positionUpdatedAt: new Date(player.elapsed_time_last_updated * 1000).toISOString(),
+            }
+            : {}),
+        ...(typeof media?.duration === 'number' ? { duration: media.duration } : {}),
+        capabilities: {
+            volume: typeof player.volume_level === 'number',
+            mute: typeof player.volume_muted === 'boolean',
+            next: true,
+            previous: true,
+            browse: true,
+            search: true,
+            seek: true,
+            shuffle: true,
+            transfer: false,
+            group: false,
+        },
+    };
+}

package/dist/mock.d.ts

@@ -0,0 +1,11 @@
+import { MockIntegration, type EntityInput } from '@hashsome/core';
+export interface MusicAssistantMockOptions {
+    /** Integration id. Defaults to `ma`. */
+    id?: string;
+    /** Extra entities, by local id; they replace a default with the same id. */
+    entities?: Record<string, EntityInput>;
+}
+/** A Music Assistant integration that needs no Music Assistant: representative players, mapped the
+ * same way real ones are, and commands that change their state. For tests, the gallery and
+ * dashboards under development. */
+export declare function createMock(options?: MusicAssistantMockOptions): MockIntegration;

package/dist/mock.js

@@ -0,0 +1,67 @@
+import { MockIntegration, mockLibrary } from '@hashsome/core';
+import { toMediaPlayer } from './mapper.js';
+/** What Music Assistant reports for a few players: one per state a dashboard has to handle. Raw
+ * players, so the mock is built by the same mapping the real integration uses. */
+const players = () => [
+    {
+        player_id: 'living_room',
+        display_name: 'Living room',
+        available: true,
+        playback_state: 'playing',
+        volume_level: 40,
+        volume_muted: false,
+        current_media: {
+            title: 'Blank Space',
+            artist: 'More More',
+            album: '1989',
+            duration: 231,
+            image_url: 'https://picsum.photos/seed/aurora/400',
+        },
+        elapsed_time: 64,
+        elapsed_time_last_updated: Date.now() / 1000,
+    },
+    {
+        player_id: 'kitchen',
+        display_name: 'Kitchen',
+        available: true,
+        playback_state: 'paused',
+        volume_level: 25,
+        volume_muted: true,
+        current_media: {
+            title: 'Dreams',
+            artist: 'Fleetwood Mac',
+            duration: 214,
+            image_url: 'https://picsum.photos/seed/dreams/400',
+        },
+        shuffle_enabled: true,
+        elapsed_time: 95,
+        elapsed_time_last_updated: Date.now() / 1000,
+    },
+    {
+        player_id: 'office',
+        display_name: 'Office',
+        available: true,
+        playback_state: 'idle',
+        volume_level: 15,
+        volume_muted: false,
+    },
+    {
+        player_id: 'garage',
+        display_name: 'Garage',
+        available: false,
+    },
+];
+/** A Music Assistant integration that needs no Music Assistant: representative players, mapped the
+ * same way real ones are, and commands that change their state. For tests, the gallery and
+ * dashboards under development. */
+export function createMock(options = {}) {
+    const entities = {};
+    for (const player of players()) {
+        entities[player.player_id] = toMediaPlayer(player);
+    }
+    return new MockIntegration({
+        id: options.id ?? 'ma',
+        library: mockLibrary(),
+        entities: { ...entities, ...options.entities },
+    });
+}

package/dist/position.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Where playback is, as the dashboard shows it, for one Music Assistant player and its queue.
+ *
+ * Music Assistant does not make this easy. It sends no queue updates while a track plays, only on
+ * changes, so a position has to be carried forward from the last one. A pause on a player that
+ * cannot hold a stream open is really a stop: the queue's counter goes back to the start and only
+ * its `resume_pos` says where playback will pick up, and that number is cleared as playback starts.
+ * Reading each message as the truth makes the counter jump back and forth around a pause.
+ *
+ * So this keeps a position of its own, and follows two rules. While stopped, show where it was
+ * stopped. Once playing, the queue's own counter is the truth, from its first message on.
+ *
+ * Everything here is pure: a state in, a message in, a state out.
+ */
+export interface Position {
+    /** The track the queue is on, to tell a new track from a pause on the same one. */
+    item?: string;
+    /** Where playback was believed to be, in seconds, as of `elapsedAt` (UTC epoch seconds). */
+    elapsed?: number;
+    elapsedAt?: number;
+    /** Where Music Assistant says it will pick the track up again. Only means anything while stopped. */
+    resume?: number;
+    /** Where playback was when it stopped: the last position plus the time since it was seen. */
+    held?: number;
+    /** What the last track's resume spot was, which a new track starts out carrying for a while. */
+    inherited?: number;
+}
+/** A queue message: what it says about the track, the counter and the resume position. */
+export interface QueueMessage {
+    item?: string | undefined;
+    elapsed?: number | undefined;
+    resume?: number | undefined;
+}
+export declare function onQueue(position: Position, message: QueueMessage, playback: string | undefined, now: number): Position;
+/** The player's state changed: a stop remembers where it got to, and a start from a stop begins there. */
+export declare function onPlayback(position: Position, from: string | undefined, to: string | undefined, now: number): Position;
+/** What to show: playing, the counter; stopped, the later of where it was held and the resume spot. */
+export declare function positionOf(position: Position, playback: string | undefined): number | undefined;