wiim2mqtt 0.1.0

package/lib/device.js

@@ -0,0 +1,998 @@
+/**
+ * Device: one WiiM, one normalised state. Feeds from UPnP events (primary), HTTP API seed +
+ * adaptive polling (safety net) and emits friendly item changes. See ROADMAP §3.7.
+ *
+ * Events:
+ *  - 'connected' (bool)            http api reachable
+ *  - 'change' (item, value, opts)  opts.retain false for position
+ *  - 'upnp' ('events'|'polling'|'off')
+ */
+
+import {EventEmitter} from 'node:events';
+import http from 'node:http';
+import https from 'node:https';
+import {parseMetadata, parseDuration, EMPTY_TRACK} from './didl.js';
+import {
+    PLAY_STATES,
+    TRANSPORT_STATES,
+    SWITCHABLE_SOURCES,
+    sourceFromMode,
+    sourceFromMedium,
+    loopToRepeatShuffle,
+} from './commands.js';
+import {HttpApi} from './api.js';
+
+const TRACK_ITEMS = [
+    'title',
+    'artist',
+    'album',
+    'album_art',
+    'quality',
+    'sample_rate',
+    'bit_depth',
+    'bitrate',
+    'origin_source',
+];
+const MISS_ITEMS = ['play_state', 'volume', 'mute'];
+const MISS_WINDOW = 5 * 60 * 1000;
+const MISS_LIMIT = 3;
+const HEALTHY_AFTER = 10 * 60 * 1000;
+const IDLE_POLL = 5000;
+const HEALTHY_POLL = 30000;
+const DEVICE_POLL = 60000;
+const UNREACHABLE_POLL_MAX = 30000;
+
+export class Device extends EventEmitter {
+    /**
+     * @param {object} options
+     * @param {import('./api.js').HttpApi} options.api
+     * @param {import('./upnp.js').UpnpClient} [options.upnp] null for --no-upnp
+     * @param {number} [options.pollInterval] seconds, fast poll cadence
+     * @param {number} [options.positionInterval] seconds, 0 = off
+     * @param {boolean} [options.albumArtData] fetch and emit album_art_data
+     * @param {object} [options.log]
+     * @param {object} [options.timers] {setTimeout, clearTimeout, setInterval, clearInterval}
+     * @param {() => number} [options.now]
+     * @param {(baseUrl: string) => HttpApi} [options.createApi] for the multiroom master
+     */
+    constructor({
+        api,
+        upnp = null,
+        pollInterval = 1,
+        positionInterval = 1,
+        albumArtData = false,
+        log,
+        timers,
+        now,
+        createApi,
+    }) {
+        super();
+        this.api = api;
+        this.upnp = upnp;
+        this.pollInterval = Math.max(200, pollInterval * 1000);
+        this.positionInterval = positionInterval * 1000;
+        this.albumArtData = albumArtData;
+        this.log = log || {debug() {}, info() {}, warn() {}, error() {}};
+        this.timers = timers || {setTimeout, clearTimeout};
+        this.now = now || Date.now;
+        this.createApi = createApi || ((baseUrl) => new HttpApi({baseUrl, log: this.log}));
+
+        this.state = new Map();
+        this.connected = undefined;
+        this.running = false;
+        this.mode = upnp ? 'polling' : 'off';
+        this.misses = [];
+        this.lastMissAt = 0;
+        this.subscribedAt = 0;
+        this.pollTimer = undefined;
+        this.deviceTimer = undefined;
+        this.positionTimer = undefined;
+        this.quickPollTimer = undefined;
+        this.metaTimer = undefined;
+        this.verifyTimers = new Set();
+        this.anchor = {position: 0, at: 0};
+        this.trackKey = '';
+        this.unreachableSince = 0;
+        this.failures = 0;
+        this.masterApi = undefined;
+        this.masterUrl = undefined;
+        this.pollPending = false;
+        this.lastArtUrl = undefined;
+    }
+
+    get(item) {
+        return this.state.get(item);
+    }
+
+    /** Set a friendly item; emits 'change' when the value differs. */
+    set(item, value, opts = {}) {
+        const previous = this.state.get(item);
+        const changed = JSON.stringify(previous) !== JSON.stringify(value);
+        if (changed || opts.force) {
+            this.state.set(item, value);
+            this.emit('change', item, value, opts);
+        }
+        return changed;
+    }
+
+    /*
+     * lifecycle
+     */
+
+    async start() {
+        this.running = true;
+        if (this.upnp) {
+            this.upnp.on('event', (event) => this.onEvent(event));
+            this.upnp.on('subscribed', ({service}) => this.onSubscribed(service));
+            this.upnp.on('lost', ({service, error, retryIn}) => this.onLost(service, error, retryIn));
+        }
+        await this.connect();
+    }
+
+    /** Establish the http connection and seed; retried by the poll loop while unreachable. */
+    async connect() {
+        try {
+            await this.refreshDevice();
+        } catch (err) {
+            this.setConnected(false, err);
+            this.schedulePoll();
+            return;
+        }
+        this.setConnected(true);
+        if (this.upnp) {
+            await this.describeUpnp();
+        }
+        await this.seed();
+        if (this.upnp) {
+            await this.subscribeUpnp();
+        } else {
+            this.setMode('off');
+        }
+        this.schedulePoll();
+        this.scheduleDevicePoll();
+    }
+
+    async describeUpnp() {
+        try {
+            const desc = await this.upnp.describe();
+            if (desc.model && !this.get('model')) {
+                this.set('model', desc.model);
+            }
+        } catch (err) {
+            this.log.warn('upnp description unavailable, polling only:', err.message);
+        }
+    }
+
+    async subscribeUpnp() {
+        if (!this.upnp.description) {
+            this.setMode('polling');
+            return;
+        }
+        try {
+            await this.upnp.subscribe(['AVTransport', 'RenderingControl', 'PlayQueue']);
+        } catch (err) {
+            this.log.warn('upnp subscribe failed, polling only:', err.message);
+            this.setMode('polling');
+        }
+    }
+
+    async stop() {
+        this.running = false;
+        for (const timer of [
+            this.pollTimer,
+            this.deviceTimer,
+            this.positionTimer,
+            this.quickPollTimer,
+            this.metaTimer,
+            ...this.verifyTimers,
+        ]) {
+            this.timers.clearTimeout(timer);
+        }
+        this.verifyTimers.clear();
+        if (this.upnp) {
+            await this.upnp.stop();
+        }
+        this.api.close();
+        if (this.masterApi) {
+            this.masterApi.close();
+        }
+    }
+
+    setConnected(connected, err) {
+        if (connected === this.connected) {
+            return;
+        }
+        this.connected = connected;
+        if (connected) {
+            const downtime = this.unreachableSince ? Math.round((this.now() - this.unreachableSince) / 1000) : 0;
+            this.log.info('api reachable', this.api.baseUrl, downtime ? `(after ${downtime} s)` : '');
+            this.unreachableSince = 0;
+            this.failures = 0;
+        } else {
+            this.unreachableSince = this.now();
+            this.log.warn('api unreachable', this.api.baseUrl, err ? `(${err.message})` : '');
+            this.stopPositionTimer();
+        }
+        this.emit('connected', connected);
+    }
+
+    setMode(mode) {
+        if (mode === this.mode) {
+            return;
+        }
+        const previous = this.mode;
+        this.mode = mode;
+        this.log[mode === 'events' ? 'info' : 'warn']('upnp state source', previous, '→', mode);
+        this.set('upnp', mode);
+        this.emit('upnp', mode);
+        this.schedulePoll();
+    }
+
+    /*
+     * seeding / refresh
+     */
+
+    async seed() {
+        await this.refresh('status');
+        await this.refresh('metadata');
+        await this.refresh('presets');
+        await this.refresh('group');
+    }
+
+    /** Explicit refresh (get/<item> or after set). */
+    async refresh(what) {
+        try {
+            switch (what) {
+                case 'status':
+                    if (this.upnp && this.upnp.description) {
+                        try {
+                            this.applyInfoEx(await this.upnp.getInfoEx());
+                        } catch (err) {
+                            this.log.debug('upnp GetInfoEx failed, using http:', err.message);
+                        }
+                    }
+                    await this.pollStatus({seed: true});
+                    return;
+                case 'metadata':
+                    return this.fetchMetaInfo();
+                case 'presets':
+                    return this.refreshPresets();
+                case 'device':
+                    return this.refreshDevice();
+                case 'group':
+                    return this.refreshGroup();
+                default:
+                    throw new Error(`unknown refresh ${what}`);
+            }
+        } catch (err) {
+            this.onApiError(err, `refresh ${what}`);
+        }
+    }
+
+    async refreshDevice() {
+        const raw = await this.api.statusEx();
+        this.applyStatusEx(raw);
+        return raw;
+    }
+
+    applyStatusEx(raw) {
+        const str = (v) => (v === undefined || v === null ? '' : String(v));
+        if (raw.DeviceName !== undefined) {
+            this.set('device_name', str(raw.DeviceName));
+        }
+        const model = str(raw.project || raw.priv_prj || raw.hardware);
+        if (model) {
+            this.set('model', model);
+        }
+        if (raw.firmware !== undefined) {
+            this.set('firmware', str(raw.firmware));
+        }
+        if (raw.uuid !== undefined) {
+            this.set('uuid', str(raw.uuid));
+        }
+        if (raw.MAC !== undefined) {
+            this.set('mac', str(raw.MAC));
+        }
+        const ip = [raw.eth0, raw.apcli0, raw.eth2].map(str).find((v) => v && v !== '0.0.0.0');
+        if (ip) {
+            this.set('ip', ip);
+        }
+        if (raw.RSSI !== undefined && Number.isFinite(Number(raw.RSSI)) && !(Number(raw.RSSI) === 0 && !raw.BSSID)) {
+            this.set('rssi', Number(raw.RSSI));
+        }
+        const updateAvailable = str(raw.VersionUpdate) === '1';
+        this.set('update_available', updateAvailable);
+        this.set('firmware_update', {
+            installed_version: str(raw.firmware),
+            latest_version: updateAvailable && raw.NewVer ? str(raw.NewVer) : str(raw.firmware),
+        });
+        if (raw.group !== undefined) {
+            this.groupFlag = str(raw.group) === '1';
+        }
+        // a slave's master, if the firmware tells us (OQ-44)
+        const masterKey = Object.keys(raw).find((k) => /master.*ip|host_ip|masterip/i.test(k));
+        if (masterKey && str(raw[masterKey]) && str(raw[masterKey]) !== '0.0.0.0') {
+            this.set('group_master', str(raw[masterKey]));
+        }
+        this.applyGroupRole();
+        if (raw.plm_support !== undefined || raw.capability !== undefined) {
+            // source list is model dependent; until we know the bits, expose the documented switchable set
+            this.set('source_list', SWITCHABLE_SOURCES);
+        } else if (this.get('source_list') === undefined) {
+            this.set('source_list', SWITCHABLE_SOURCES);
+        }
+    }
+
+    async refreshPresets() {
+        let presets = [];
+        let max;
+        try {
+            presets = await this.api.presetInfo();
+        } catch (err) {
+            this.log.debug('getPresetInfo failed:', err.message);
+        }
+        if (this.upnp && this.upnp.description && this.upnp.description.services.PlayQueue) {
+            try {
+                const mapping = await this.upnp.getKeyMapping();
+                max = mapping.maxNumber;
+                if (presets.length === 0) {
+                    presets = mapping.presets;
+                }
+            } catch (err) {
+                this.log.debug('upnp GetKeyMapping failed:', err.message);
+            }
+        }
+        this.set(
+            'preset_list',
+            presets.map(({number, name, source, pic}) => ({number, name, source, pic})),
+        );
+        this.set('preset_max', max || Math.max(12, ...presets.map((p) => p.number)));
+    }
+
+    async refreshGroup() {
+        let slaves = [];
+        try {
+            slaves = await this.api.slaveList();
+        } catch (err) {
+            if (err.code !== 'EUNKNOWN' && err.code !== 'EFAILED' && err.code !== 'EFORMAT') {
+                throw err;
+            }
+        }
+        this.set(
+            'group_slaves',
+            slaves.map(({name, ip, uuid}) => ({name, ip, uuid})),
+        );
+        this.applyGroupRole();
+    }
+
+    applyGroupRole() {
+        const slaves = this.get('group_slaves');
+        let role = 'standalone';
+        if (this.groupFlag || this.get('group_role_hint') === 'slave') {
+            role = 'slave';
+        } else if (Array.isArray(slaves) && slaves.length > 0) {
+            role = 'master';
+        }
+        this.set('group_role', role);
+        if (role !== 'slave') {
+            this.set('group_master', '');
+            this.detachMaster();
+        } else {
+            this.attachMaster();
+        }
+        if (role !== 'master' && Array.isArray(slaves) && slaves.length) {
+            this.set('group_slaves', []);
+        }
+    }
+
+    attachMaster() {
+        const ip = this.get('group_master');
+        if (!ip) {
+            this.log.debug('group: slave, master ip unknown - no metadata mirroring');
+            return;
+        }
+        const url = `https://${ip}`;
+        if (this.masterUrl === url) {
+            return;
+        }
+        this.detachMaster();
+        this.masterUrl = url;
+        this.masterApi = this.createApi(url);
+        this.log.info('group: slave of', ip, '- mirroring its playback state');
+    }
+
+    detachMaster() {
+        if (this.masterApi) {
+            this.masterApi.close();
+            this.masterApi = undefined;
+            this.masterUrl = undefined;
+        }
+    }
+
+    /*
+     * polling
+     */
+
+    schedulePoll() {
+        this.timers.clearTimeout(this.pollTimer);
+        if (!this.running) {
+            return;
+        }
+        let delay;
+        if (!this.connected) {
+            delay = Math.min(IDLE_POLL * Math.max(1, this.failures), UNREACHABLE_POLL_MAX);
+        } else if (this.mode === 'events') {
+            delay = HEALTHY_POLL;
+        } else {
+            const playing = ['playing', 'loading'].includes(this.get('play_state'));
+            delay = playing ? this.pollInterval : IDLE_POLL;
+        }
+        this.pollTimer = this.timers.setTimeout(() => this.poll(), delay);
+    }
+
+    scheduleDevicePoll() {
+        this.timers.clearTimeout(this.deviceTimer);
+        if (!this.running) {
+            return;
+        }
+        this.deviceTimer = this.timers.setTimeout(async () => {
+            if (this.connected) {
+                try {
+                    await this.refreshDevice();
+                    await this.refreshGroup();
+                } catch (err) {
+                    this.onApiError(err, 'device poll');
+                }
+            }
+            this.scheduleDevicePoll();
+        }, DEVICE_POLL);
+    }
+
+    /** One poll cycle. */
+    async poll() {
+        if (!this.running || this.pollPending) {
+            return;
+        }
+        this.pollPending = true;
+        try {
+            if (!this.connected) {
+                await this.connect();
+                return;
+            }
+            await this.pollStatus({});
+        } catch (err) {
+            this.onApiError(err, 'poll');
+        } finally {
+            this.pollPending = false;
+            if (this.connected) {
+                this.schedulePoll();
+            }
+        }
+    }
+
+    /** Quick poll ~1 s after an event, to pick up mode/queue/position the event did not carry. */
+    scheduleQuickPoll() {
+        if (this.quickPollTimer || !this.connected) {
+            return;
+        }
+        this.quickPollTimer = this.timers.setTimeout(async () => {
+            this.quickPollTimer = undefined;
+            try {
+                await this.pollStatus({quick: true});
+            } catch (err) {
+                this.onApiError(err, 'quick poll');
+            }
+        }, 1000);
+    }
+
+    async pollStatus({seed = false, quick = false}) {
+        const status = await this.api.playerStatus();
+        this.failures = 0;
+        if (!this.connected) {
+            this.setConnected(true);
+        }
+        const detectMisses = this.mode === 'events' && !seed && !quick && this.now() - this.subscribedAt > 5000;
+        const before = detectMisses ? Object.fromEntries(MISS_ITEMS.map((i) => [i, this.get(i)])) : undefined;
+        this.applyPlayerStatus(status, {seed});
+        if (detectMisses) {
+            const missed = MISS_ITEMS.filter((i) => before[i] !== undefined && before[i] !== this.get(i));
+            if (missed.length) {
+                this.onMiss(missed);
+            }
+        }
+        if (this.masterApi) {
+            await this.mirrorMaster();
+        }
+    }
+
+    applyPlayerStatus(status, {seed = false} = {}) {
+        const playState = PLAY_STATES[status.status] || (status.status ? 'stopped' : undefined);
+        if (status.mode === 99 || status.type === 1) {
+            this.state.set('group_role_hint', 'slave');
+        } else {
+            this.state.delete('group_role_hint');
+        }
+        this.applySource(sourceFromMode(status.mode));
+        this.set('volume', status.vol);
+        this.set('mute', status.mute);
+        const {repeat, shuffle} = loopToRepeatShuffle(status.loop);
+        this.set('repeat', repeat);
+        this.set('shuffle', shuffle);
+        this.set('queue_index', status.plicurr);
+        this.set('queue_length', status.plicount);
+        if (status.totlen > 0) {
+            this.set('duration', Math.round(status.totlen / 1000));
+        }
+        this.setAnchor(Math.round(status.curpos / 1000));
+        if (playState) {
+            this.applyPlayState(playState);
+        }
+        // http metadata only fills gaps; upnp/getMetaInfo are richer
+        if (status.title !== undefined && status.title !== '' && playState !== 'stopped') {
+            if (!this.get('title')) {
+                this.applyTrack({
+                    ...EMPTY_TRACK,
+                    title: status.title,
+                    artist: status.artist === 'unknown' ? '' : status.artist || '',
+                    album: status.album === 'unknown' ? '' : status.album || '',
+                });
+            }
+        }
+        if (seed) {
+            this.set('upnp', this.mode);
+        }
+    }
+
+    applyInfoEx(info) {
+        const playState = TRANSPORT_STATES[info.transportState];
+        const medium = sourceFromMedium(info.playMedium);
+        if (medium) {
+            this.applySource(medium);
+        }
+        if (info.volume !== undefined && info.volume !== '') {
+            this.set('volume', Number(info.volume));
+        }
+        if (info.mute !== undefined && info.mute !== '') {
+            this.set('mute', info.mute === '1' || info.mute === 'true');
+        }
+        if (info.loopMode !== undefined && info.loopMode !== '') {
+            const {repeat, shuffle} = loopToRepeatShuffle(info.loopMode);
+            this.set('repeat', repeat);
+            this.set('shuffle', shuffle);
+        }
+        const duration = parseDuration(info.duration);
+        if (duration) {
+            this.set('duration', duration);
+        }
+        const track = parseMetadata(info.metadata);
+        if (track) {
+            if (!track.originSource && info.trackSource) {
+                track.originSource = String(info.trackSource);
+            }
+            this.applyTrack(track);
+        }
+        if (info.trackSource) {
+            this.state.set('track_source', String(info.trackSource));
+        }
+        // after the track: a track change resets the position anchor
+        const position = parseDuration(info.position);
+        if (position !== null) {
+            this.setAnchor(position);
+        }
+        if (playState) {
+            this.applyPlayState(playState);
+        }
+    }
+
+    /*
+     * upnp events
+     */
+
+    onSubscribed() {
+        if (!this.subscribedAt) {
+            this.subscribedAt = this.now();
+        }
+        this.evaluateMode();
+    }
+
+    onLost(service, error, retryIn) {
+        this.log.warn(
+            'upnp subscription',
+            service,
+            'lost:',
+            error && error.message ? error.message : error,
+            `- retry in ${retryIn} s`,
+        );
+        this.subscribedAt = 0;
+        this.evaluateMode();
+    }
+
+    onMiss(items) {
+        const now = this.now();
+        this.misses = this.misses.filter((t) => now - t < MISS_WINDOW);
+        this.misses.push(now);
+        this.lastMissAt = now;
+        this.log.debug('upnp events missed a change of', items.join(', '), `(${this.misses.length}/${MISS_LIMIT})`);
+        if (this.misses.length >= MISS_LIMIT) {
+            this.log.warn('upnp events unreliable (missed', items.join(', '), ') - polling and re-subscribing');
+            this.misses = [];
+            this.evaluateMode();
+            if (this.upnp) {
+                this.upnp.resubscribe('events missed changes');
+            }
+        }
+    }
+
+    evaluateMode() {
+        if (!this.upnp) {
+            this.setMode('off');
+            return;
+        }
+        const subscribed = this.upnp.subscribed;
+        const healthy = !this.lastMissAt || this.now() - this.lastMissAt > HEALTHY_AFTER;
+        this.setMode(subscribed && healthy ? 'events' : 'polling');
+    }
+
+    onEvent({service, variables}) {
+        if (!this.connected) {
+            return;
+        }
+        this.evaluateMode();
+        let quickPoll = false;
+        for (const [name, value] of Object.entries(variables)) {
+            switch (name) {
+                case 'TransportState': {
+                    const playState = TRANSPORT_STATES[value];
+                    if (playState) {
+                        this.applyPlayState(playState);
+                        quickPoll = true;
+                    }
+                    break;
+                }
+                case 'CurrentTrackMetaData': {
+                    const track = parseMetadata(value);
+                    if (track) {
+                        this.applyTrack(track);
+                        quickPoll = true;
+                    }
+                    break;
+                }
+                case 'AVTransportURIMetaData': {
+                    if (variables.CurrentTrackMetaData === undefined) {
+                        const track = parseMetadata(value);
+                        if (track) {
+                            this.applyTrack(track);
+                        }
+                    }
+                    break;
+                }
+                case 'Volume':
+                    this.set('volume', Number(value));
+                    break;
+                case 'Mute':
+                    this.set('mute', value === '1' || value === 'true');
+                    break;
+                case 'LoopMode': {
+                    const {repeat, shuffle} = loopToRepeatShuffle(value);
+                    this.set('repeat', repeat);
+                    this.set('shuffle', shuffle);
+                    break;
+                }
+                case 'RelativeTimePosition':
+                    // applied after the loop: a track change in the same event resets the anchor
+                    break;
+                case 'CurrentTrackDuration': {
+                    const dur = parseDuration(value);
+                    if (dur) {
+                        this.set('duration', dur);
+                    }
+                    break;
+                }
+                case 'PlaybackStorageMedium': {
+                    const source = sourceFromMedium(value);
+                    if (source) {
+                        this.applySource(source);
+                    } else {
+                        quickPoll = true;
+                    }
+                    break;
+                }
+                case 'TrackSource':
+                    this.state.set('track_source', String(value));
+                    if (!this.get('origin_source') && value) {
+                        this.set('origin_source', String(value));
+                    }
+                    quickPoll = true;
+                    break;
+                case 'NumberOfTracks':
+                    this.set('queue_length', Number(value) || 0);
+                    break;
+                case 'CurrentTrack':
+                    this.set('queue_index', Number(value) || 0);
+                    break;
+                case 'Slave':
+                case 'SlaveList':
+                    this.refresh('group');
+                    break;
+                default:
+                    this.log.debug('upnp event', service, name, 'ignored');
+            }
+        }
+        if (variables.RelativeTimePosition !== undefined) {
+            const pos = parseDuration(variables.RelativeTimePosition);
+            if (pos !== null) {
+                this.setAnchor(pos);
+            }
+        }
+        if (quickPoll) {
+            this.scheduleQuickPoll();
+        }
+    }
+
+    /*
+     * normalised state helpers
+     */
+
+    applyPlayState(playState) {
+        const changed = this.set('play_state', playState);
+        if (playState === 'stopped') {
+            this.clearTrack();
+        }
+        if (playState === 'playing') {
+            this.startPositionTimer();
+        } else {
+            this.stopPositionTimer();
+            if (changed) {
+                this.publishPosition();
+            }
+        }
+        if (changed) {
+            this.schedulePoll();
+        }
+    }
+
+    applySource(source) {
+        const previous = this.get('source');
+        if (this.set('source', source) && previous !== undefined) {
+            this.clearTrack();
+        }
+    }
+
+    applyTrack(track) {
+        const key = [track.title, track.artist, track.album, track.uri].join('|');
+        const changed = key !== this.trackKey;
+        this.trackKey = key;
+        this.set('title', track.title);
+        this.set('artist', track.artist);
+        this.set('album', track.album);
+        this.set('album_art', track.albumArt);
+        this.set('quality', track.quality);
+        this.set('sample_rate', track.sampleRate);
+        this.set('bit_depth', track.bitDepth);
+        this.set('bitrate', track.bitrate);
+        this.set('origin_source', track.originSource || this.state.get('track_source') || '');
+        if (track.duration) {
+            this.set('duration', track.duration);
+        }
+        if (changed) {
+            this.setAnchor(0);
+            this.scheduleMetaInfo();
+        }
+        this.updateAlbumArt();
+    }
+
+    clearTrack() {
+        this.trackKey = '';
+        for (const item of TRACK_ITEMS) {
+            this.set(item, ['sample_rate', 'bit_depth', 'bitrate'].includes(item) ? null : '');
+        }
+        this.set('duration', 0);
+        this.setAnchor(0);
+        this.updateAlbumArt();
+    }
+
+    /** Fill gaps (sample rate, art, …) from getMetaInfo shortly after a track change. */
+    scheduleMetaInfo() {
+        this.timers.clearTimeout(this.metaTimer);
+        this.metaTimer = this.timers.setTimeout(() => {
+            this.metaTimer = undefined;
+            this.fetchMetaInfo().catch((err) => this.onApiError(err, 'getMetaInfo'));
+        }, 1000);
+    }
+
+    async fetchMetaInfo() {
+        const meta = await this.api.metaInfo();
+        if (!meta || this.get('play_state') === 'stopped') {
+            return;
+        }
+        const fill = (item, value) => {
+            if (
+                value !== null &&
+                value !== '' &&
+                (this.get(item) === '' || this.get(item) === null || this.get(item) === undefined)
+            ) {
+                this.set(item, value);
+            }
+        };
+        fill('title', meta.title);
+        fill('artist', meta.artist);
+        fill('album', meta.album);
+        fill('album_art', meta.albumArt);
+        fill('sample_rate', meta.sampleRate);
+        fill('bit_depth', meta.bitDepth);
+        fill('bitrate', meta.bitrate);
+        this.updateAlbumArt();
+    }
+
+    async mirrorMaster() {
+        try {
+            const status = await this.masterApi.playerStatus();
+            const playState = PLAY_STATES[status.status];
+            if (playState) {
+                this.applyPlayState(playState);
+            }
+            if (status.totlen > 0) {
+                this.set('duration', Math.round(status.totlen / 1000));
+            }
+            this.setAnchor(Math.round(status.curpos / 1000));
+            const meta = await this.masterApi.metaInfo();
+            const track = meta
+                ? {...EMPTY_TRACK, ...meta, uri: ''}
+                : {...EMPTY_TRACK, title: status.title || '', artist: status.artist || '', album: status.album || ''};
+            if (track.title) {
+                this.applyTrack(track);
+            }
+        } catch (err) {
+            this.log.debug('group: master', this.masterUrl, 'not answering:', err.message);
+        }
+    }
+
+    /*
+     * position
+     */
+
+    setAnchor(position) {
+        this.anchor = {position, at: this.now()};
+        this.publishPosition();
+    }
+
+    currentPosition() {
+        let position = this.anchor.position;
+        if (this.get('play_state') === 'playing' && this.anchor.at) {
+            position += Math.floor((this.now() - this.anchor.at) / 1000);
+        }
+        const duration = this.get('duration');
+        if (duration > 0) {
+            position = Math.min(position, duration);
+        }
+        return Math.max(0, position);
+    }
+
+    publishPosition() {
+        this.set('position', this.currentPosition(), {retain: false, force: true});
+    }
+
+    startPositionTimer() {
+        if (this.positionTimer || this.positionInterval <= 0) {
+            return;
+        }
+        const tick = () => {
+            this.publishPosition();
+            this.positionTimer = this.timers.setTimeout(tick, this.positionInterval);
+        };
+        this.positionTimer = this.timers.setTimeout(tick, this.positionInterval);
+    }
+
+    stopPositionTimer() {
+        this.timers.clearTimeout(this.positionTimer);
+        this.positionTimer = undefined;
+    }
+
+    /*
+     * album art bytes
+     */
+
+    updateAlbumArt() {
+        if (!this.albumArtData) {
+            return;
+        }
+        const url = this.get('album_art') || '';
+        if (url === this.lastArtUrl) {
+            return;
+        }
+        this.lastArtUrl = url;
+        if (!url) {
+            this.set('album_art_data', null);
+            return;
+        }
+        fetchBytes(url)
+            .then((buffer) => {
+                if (this.get('album_art') === url) {
+                    this.set('album_art_data', buffer);
+                }
+            })
+            .catch((err) => this.log.debug('album art fetch failed', url, err.message));
+    }
+
+    /*
+     * commands
+     */
+
+    /** Send a command; `target: 'master'` routes it to the group master. */
+    async command(cmd, {target} = {}) {
+        if (target === 'master') {
+            const ip = this.get('group_master');
+            if (!ip) {
+                throw new Error('group master unknown');
+            }
+            const api = this.masterApi || this.createApi(`https://${ip}`);
+            return api.command(cmd);
+        }
+        return this.api.command(cmd);
+    }
+
+    /** Re-read the given items 500 ms after a set and warn when nothing changed (W-15). */
+    verify(items, before) {
+        if (!items || items.length === 0) {
+            return;
+        }
+        const timer = this.timers.setTimeout(async () => {
+            this.verifyTimers.delete(timer);
+            try {
+                await this.pollStatus({quick: true});
+                if (items.includes('group_role') || items.includes('group_slaves')) {
+                    await this.refreshGroup();
+                }
+                const unchanged = items.filter((i) => JSON.stringify(before[i]) === JSON.stringify(this.get(i)));
+                if (unchanged.length === items.length) {
+                    this.log.warn('set had no visible effect on', items.join(', '));
+                }
+            } catch (err) {
+                this.onApiError(err, 'verify');
+            }
+        }, 500);
+        this.verifyTimers.add(timer);
+    }
+
+    onApiError(err, context) {
+        if (err && (err.code === 'ECONNFAILED' || err.code === 'ETIMEDOUT')) {
+            this.failures++;
+            if (this.failures >= 2) {
+                this.setConnected(false, err);
+            } else {
+                this.log.debug(context, err.message);
+            }
+            this.schedulePoll();
+            return;
+        }
+        this.log.warn(context, 'failed:', err && err.message ? err.message : err);
+    }
+}
+
+/** Fetch a small binary resource (album art); TLS verification off because WiiM serves art from its self-signed host. */
+export function fetchBytes(url, {maxBytes = 2 * 1024 * 1024, timeout = 10000} = {}) {
+    return new Promise((resolve, reject) => {
+        const transport = url.startsWith('https:') ? https : http;
+        const req = transport.get(url, {rejectUnauthorized: false, timeout}, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                reject(new Error(`http ${res.statusCode}`));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            res.on('data', (c) => {
+                size += c.length;
+                if (size > maxBytes) {
+                    req.destroy(new Error('too large'));
+                    return;
+                }
+                chunks.push(c);
+            });
+            res.on('end', () => resolve(Buffer.concat(chunks)));
+            res.on('error', reject);
+        });
+        req.on('timeout', () => req.destroy(new Error('timeout')));
+        req.on('error', reject);
+    });
+}