wiim2mqtt 0.1.0

package/lib/didl.js

@@ -0,0 +1,272 @@
+/**
+ * Pure parsers for UPnP event payloads and track metadata as WiiM/LinkPlay devices send them.
+ *
+ * - GENA NOTIFY bodies: <e:propertyset><e:property><LastChange>…</LastChange></e:property>…
+ * - LastChange: <Event><InstanceID val="0"><TransportState val="PLAYING"/>…</InstanceID></Event>
+ * - Metadata: DIDL-Lite XML (dc:/upnp:/song: elements) or, on some firmware, JSON.
+ *
+ * Lenient on purpose: firmware 4.8.611135–4.8.612733 emitted song:* elements without a
+ * namespace declaration and titles may contain bare '&'.
+ */
+
+import {XMLParser} from 'fast-xml-parser';
+
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '',
+    ignoreDeclaration: true,
+    removeNSPrefix: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
+    trimValues: true,
+    processEntities: true,
+    htmlEntities: true,
+    isArray: (name) => name === 'e:property' || name === 'property' || name === 'item' || name === 'res',
+});
+
+/** Escape bare '&' that would break XML parsing; keep well-formed entities. */
+export function sanitizeXml(text) {
+    return String(text).replace(/&(?!(?:[a-zA-Z][a-zA-Z0-9]*|#\d+|#x[0-9a-fA-F]+);)/g, '&amp;');
+}
+
+function unescape(text) {
+    return String(text)
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCodePoint(parseInt(n, 16)))
+        .replace(/&amp;/g, '&');
+}
+
+/** Find the first child whose local name (without namespace prefix) matches. */
+function local(obj, name) {
+    if (!obj || typeof obj !== 'object') {
+        return undefined;
+    }
+    for (const key of Object.keys(obj)) {
+        const idx = key.indexOf(':');
+        if ((idx === -1 ? key : key.slice(idx + 1)) === name) {
+            return obj[key];
+        }
+    }
+    return undefined;
+}
+
+function textOf(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return textOf(value[0]);
+    }
+    if (typeof value === 'object') {
+        return value['#text'] === undefined ? undefined : String(value['#text']);
+    }
+    return String(value);
+}
+
+function safeParse(xml) {
+    try {
+        return parser.parse(xml);
+    } catch {
+        try {
+            return parser.parse(sanitizeXml(xml));
+        } catch {
+            return undefined;
+        }
+    }
+}
+
+/**
+ * Parse a GENA NOTIFY body into {variable: value} (values are strings; LastChange stays
+ * a string for parseLastChange).
+ */
+export function parsePropertySet(xml) {
+    const doc = safeParse(xml);
+    const set = local(doc, 'propertyset');
+    const props = local(set, 'property');
+    const result = {};
+    for (const prop of Array.isArray(props) ? props : props ? [props] : []) {
+        for (const [key, value] of Object.entries(prop)) {
+            const name = key.includes(':') ? key.slice(key.indexOf(':') + 1) : key;
+            const text = textOf(value);
+            result[name] = text === undefined ? '' : text;
+        }
+    }
+    return result;
+}
+
+/**
+ * Parse an AVTransport / RenderingControl LastChange document into {Variable: value}.
+ * RenderingControl channel variables (Volume, Mute) only keep channel "Master".
+ * The misspelled LoopMpde is aliased to LoopMode.
+ */
+export function parseLastChange(xml) {
+    const doc = safeParse(String(xml));
+    const event = local(doc, 'Event');
+    const instance = local(event, 'InstanceID');
+    const inst = Array.isArray(instance) ? instance[0] : instance;
+    const result = {};
+    if (!inst || typeof inst !== 'object') {
+        return result;
+    }
+    for (const [key, raw] of Object.entries(inst)) {
+        if (key === 'val' || key === '#text') {
+            continue;
+        }
+        const name = key.includes(':') ? key.slice(key.indexOf(':') + 1) : key;
+        const entries = Array.isArray(raw) ? raw : [raw];
+        for (const entry of entries) {
+            if (!entry || typeof entry !== 'object') {
+                continue;
+            }
+            if (entry.channel !== undefined && entry.channel !== 'Master') {
+                continue;
+            }
+            if (entry.val === undefined) {
+                continue;
+            }
+            result[name === 'LoopMpde' ? 'LoopMode' : name] = String(entry.val);
+        }
+    }
+    return result;
+}
+
+const EMPTY_TRACK = Object.freeze({
+    title: '',
+    artist: '',
+    album: '',
+    albumArt: '',
+    quality: '',
+    sampleRate: null,
+    bitDepth: null,
+    bitrate: null,
+    originSource: '',
+    duration: null,
+    uri: '',
+});
+
+/** DIDL res@duration: H:MM:SS per spec, but WiiM sends plain milliseconds ("205000"). */
+export function parseResDuration(value) {
+    if (value !== undefined && value !== null && /^\d+$/.test(String(value).trim())) {
+        return Math.round(Number(value) / 1000);
+    }
+    return parseDuration(value);
+}
+
+/** "0:03:25.000" / "03:25" / "205" → seconds (integer) or null */
+export function parseDuration(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const text = String(value).trim();
+    if (/^\d+$/.test(text)) {
+        return Number(text);
+    }
+    const parts = text.split(':').map((p) => Number(p));
+    if (parts.some((p) => !Number.isFinite(p))) {
+        return null;
+    }
+    let seconds = 0;
+    for (const part of parts) {
+        seconds = seconds * 60 + part;
+    }
+    return Math.round(seconds);
+}
+
+function intOrNull(value) {
+    if (value === undefined || value === null || value === '') {
+        return null;
+    }
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+
+/**
+ * Parse track metadata (DIDL-Lite XML or JSON) into a normalised track object.
+ * Returns null for empty / NOT_IMPLEMENTED metadata.
+ */
+export function parseMetadata(input) {
+    if (input === undefined || input === null) {
+        return null;
+    }
+    const text = String(input).trim();
+    if (text === '' || text === 'NOT_IMPLEMENTED') {
+        return null;
+    }
+    if (text.startsWith('{')) {
+        try {
+            return fromJson(JSON.parse(text));
+        } catch {
+            return null;
+        }
+    }
+    const doc = safeParse(unescapeIfEscaped(text));
+    const didl = local(doc, 'DIDL-Lite');
+    let item = local(didl, 'item');
+    if (Array.isArray(item)) {
+        item = item[0];
+    }
+    if (!item || typeof item !== 'object') {
+        return null;
+    }
+    const get = (name) => {
+        const v = textOf(local(item, name));
+        return v === undefined ? '' : unescape(v);
+    };
+    const resList = local(item, 'res');
+    const res = Array.isArray(resList) ? resList[0] : resList;
+    const resText = textOf(res);
+    const resDuration = res && typeof res === 'object' ? res.duration : undefined;
+    return {
+        ...EMPTY_TRACK,
+        title: get('title'),
+        artist: get('artist') || get('creator'),
+        album: get('album'),
+        albumArt: get('albumArtURI'),
+        quality: get('actualQuality') || get('quality'),
+        sampleRate: intOrNull(get('rate_hz')),
+        bitDepth: intOrNull(get('format_s')),
+        bitrate: intOrNull(get('bitrate')),
+        originSource: get('originSource'),
+        duration: parseResDuration(resDuration),
+        uri: resText === undefined ? '' : unescape(resText),
+    };
+}
+
+/** LastChange values arrive XML-escaped inside the attribute; fast-xml-parser already unescapes attributes. */
+function unescapeIfEscaped(text) {
+    return text.startsWith('&lt;') ? unescape(text) : text;
+}
+
+function fromJson(obj) {
+    if (!obj || typeof obj !== 'object') {
+        return null;
+    }
+    const pick = (...keys) => {
+        for (const key of keys) {
+            if (obj[key] !== undefined && obj[key] !== null && obj[key] !== '') {
+                return String(obj[key]);
+            }
+        }
+        return '';
+    };
+    return {
+        ...EMPTY_TRACK,
+        title: pick('title', 'dc:title', 'Title'),
+        artist: pick('artist', 'upnp:artist', 'dc:creator', 'creator', 'Artist'),
+        album: pick('album', 'upnp:album', 'Album'),
+        albumArt: pick('albumArtURI', 'upnp:albumArtURI', 'albumArtUri', 'albumart', 'cover'),
+        quality: pick('actualQuality', 'song:actualQuality', 'quality'),
+        sampleRate: intOrNull(pick('rate_hz', 'song:rate_hz', 'sampleRate')),
+        bitDepth: intOrNull(pick('format_s', 'song:format_s', 'bitDepth')),
+        bitrate: intOrNull(pick('bitrate', 'song:bitrate', 'bitRate')),
+        originSource: pick('originSource', 'song:originSource'),
+        duration: parseDuration(pick('duration')),
+        uri: pick('res', 'uri', 'url'),
+    };
+}
+
+export {EMPTY_TRACK};

package/lib/hadiscovery.js

@@ -0,0 +1,190 @@
+/**
+ * Home Assistant MQTT discovery (device-based, HA >= 2024.11).
+ * https://www.home-assistant.io/integrations/mqtt/#device-discovery-payload
+ *
+ * HA has no MQTT media_player platform, so the streamer is exposed as a bundle of entities:
+ * number (volume), switches (mute, shuffle), selects (source, repeat, preset), buttons
+ * (play/pause/stop/next/prev/toggle), sensors (track + diagnostics), an image (album art)
+ * and an update entity (firmware).
+ */
+
+import {REPEAT_MODES, SWITCHABLE_SOURCES} from './commands.js';
+
+const BUTTONS = [
+    {item: 'play', name: 'Play', icon: 'mdi:play'},
+    {item: 'pause', name: 'Pause', icon: 'mdi:pause'},
+    {item: 'stop', name: 'Stop', icon: 'mdi:stop'},
+    {item: 'next', name: 'Next', icon: 'mdi:skip-next'},
+    {item: 'prev', name: 'Previous', icon: 'mdi:skip-previous'},
+    {item: 'toggle', name: 'Play/Pause', icon: 'mdi:play-pause'},
+];
+
+const SENSORS = [
+    {item: 'play_state', name: 'Play state', icon: 'mdi:play-pause'},
+    {item: 'title', name: 'Title', icon: 'mdi:music-note'},
+    {item: 'artist', name: 'Artist', icon: 'mdi:account-music'},
+    {item: 'album', name: 'Album', icon: 'mdi:album'},
+    {item: 'quality', name: 'Quality', icon: 'mdi:quality-high'},
+    {item: 'sample_rate', name: 'Sample rate', icon: 'mdi:sine-wave', unit: 'Hz'},
+    {item: 'bit_depth', name: 'Bit depth', icon: 'mdi:numeric'},
+    {item: 'bitrate', name: 'Bitrate', icon: 'mdi:speedometer', unit: 'kbit/s'},
+    {item: 'origin_source', name: 'Origin', icon: 'mdi:cloud-outline'},
+    {item: 'duration', name: 'Duration', icon: 'mdi:timer-outline', unit: 's'},
+    {item: 'group_role', name: 'Group role', icon: 'mdi:speaker-multiple'},
+    {item: 'device_name', name: 'Device name', category: 'diagnostic'},
+    {item: 'model', name: 'Model', category: 'diagnostic'},
+    {item: 'firmware', name: 'Firmware', category: 'diagnostic'},
+    {item: 'ip', name: 'IP address', category: 'diagnostic'},
+    {item: 'mac', name: 'MAC address', category: 'diagnostic'},
+    {item: 'rssi', name: 'Wi-Fi signal', category: 'diagnostic', unit: 'dBm', icon: 'mdi:wifi'},
+    {item: 'upnp', name: 'State source', category: 'diagnostic', icon: 'mdi:lan-connect'},
+];
+
+/**
+ * Build the discovery payload.
+ * @param {object} input
+ * @param {string} input.name instance name / topic prefix
+ * @param {string} [input.prefix] discovery prefix (default "homeassistant")
+ * @param {(item: string) => *} input.get last known value of a friendly item
+ * @param {{name: string, version: string, homepage?: string}} input.pkg
+ * @param {boolean} [input.jsonPayloads] status payloads are {val, ts, lc} JSON
+ * @param {boolean} [input.albumArtData] album_art_data topic is published
+ * @returns {{topic: string, payload: object}}
+ */
+export function buildDiscovery({name, prefix = 'homeassistant', get, pkg, jsonPayloads = false, albumArtData = false}) {
+    const id = 'wiim2mqtt_' + String(name).replace(/[^a-zA-Z0-9_-]/g, '_');
+    const status = (item) => `${name}/status/${item}`;
+    const set = (item) => `${name}/set/${item}`;
+    const valueTemplate = jsonPayloads ? '{{ value_json.val }}' : undefined;
+
+    const common = (item, extra) => ({
+        p: extra.p,
+        uniq_id: `${id}_${item}`,
+        name: extra.name,
+        ...(extra.p !== 'button' && {stat_t: status(item)}),
+        ...(valueTemplate && extra.p !== 'button' && extra.p !== 'image' && {val_tpl: valueTemplate}),
+        ...(extra.icon && {ic: extra.icon}),
+        ...(extra.category && {ent_cat: extra.category}),
+        ...(extra.unit && {unit_of_meas: extra.unit}),
+    });
+
+    const components = {};
+
+    components.volume = {
+        ...common('volume', {p: 'number', name: 'Volume', icon: 'mdi:volume-high'}),
+        cmd_t: set('volume'),
+        min: 0,
+        max: 100,
+        step: 1,
+        mode: 'slider',
+    };
+
+    components.mute = {
+        ...common('mute', {p: 'switch', name: 'Mute', icon: 'mdi:volume-mute'}),
+        cmd_t: set('mute'),
+        pl_on: 'true',
+        pl_off: 'false',
+        stat_on: 'true',
+        stat_off: 'false',
+    };
+
+    components.shuffle = {
+        ...common('shuffle', {p: 'switch', name: 'Shuffle', icon: 'mdi:shuffle'}),
+        cmd_t: set('shuffle'),
+        pl_on: 'true',
+        pl_off: 'false',
+        stat_on: 'true',
+        stat_off: 'false',
+    };
+
+    components.repeat = {
+        ...common('repeat', {p: 'select', name: 'Repeat', icon: 'mdi:repeat'}),
+        cmd_t: set('repeat'),
+        options: REPEAT_MODES,
+    };
+
+    const sources =
+        Array.isArray(get('source_list')) && get('source_list').length ? get('source_list') : SWITCHABLE_SOURCES;
+    components.source = {
+        ...common('source', {p: 'select', name: 'Source', icon: 'mdi:import'}),
+        cmd_t: set('source'),
+        options: sources,
+    };
+
+    const presets = get('preset_list');
+    if (Array.isArray(presets) && presets.length) {
+        components.preset = {
+            ...common('preset', {p: 'select', name: 'Preset', icon: 'mdi:playlist-star'}),
+            uniq_id: `${id}_preset`,
+            cmd_t: set('preset'),
+            // presets are fire-and-forget: no state topic, HA shows the last chosen one
+            stat_t: undefined,
+            val_tpl: undefined,
+            options: presets.map((p) => p.name || `Preset ${p.number}`),
+        };
+        delete components.preset.stat_t;
+        delete components.preset.val_tpl;
+    }
+
+    for (const button of BUTTONS) {
+        components['button_' + button.item] = {
+            ...common('button_' + button.item, {p: 'button', name: button.name, icon: button.icon}),
+            cmd_t: set(button.item),
+            pl_prs: 'true',
+        };
+    }
+
+    for (const sensor of SENSORS) {
+        if (get(sensor.item) === undefined) {
+            continue;
+        }
+        components[sensor.item] = common(sensor.item, {p: 'sensor', ...sensor});
+    }
+
+    components.album_art = {
+        p: 'image',
+        uniq_id: `${id}_album_art`,
+        name: 'Album art',
+        ic: 'mdi:image-album',
+        ...(albumArtData
+            ? {image_topic: status('album_art_data'), cont_type: 'image/jpeg'}
+            : {url_topic: status('album_art'), ...(jsonPayloads && {url_tpl: '{{ value_json.val }}'})}),
+    };
+
+    if (get('firmware') !== undefined) {
+        components.update = {
+            p: 'update',
+            uniq_id: `${id}_update`,
+            name: 'Firmware',
+            ent_cat: 'diagnostic',
+            stat_t: status('firmware_update'),
+            val_tpl: jsonPayloads ? '{{ value_json.val | to_json }}' : undefined,
+            dev_cla: 'firmware',
+        };
+        if (!jsonPayloads) {
+            delete components.update.val_tpl;
+        }
+    }
+
+    const payload = {
+        dev: {
+            ids: [id, ...(get('uuid') ? [String(get('uuid'))] : [])],
+            name: name,
+            mf: 'WiiM',
+            ...(get('model') && {mdl: String(get('model'))}),
+            ...(get('firmware') && {sw: String(get('firmware'))}),
+            ...(get('mac') && {cns: [['mac', String(get('mac')).toLowerCase()]]}),
+            ...(get('ip') && {cu: `https://${get('ip')}`}),
+        },
+        o: {
+            name: pkg.name,
+            sw: pkg.version,
+            ...(pkg.homepage && {url: pkg.homepage}),
+        },
+        avty: [{t: `${name}/connected`, avty_tpl: "{{ 'online' if (value | int(0)) >= 2 else 'offline' }}"}],
+        qos: 0,
+        cmps: components,
+    };
+
+    return {topic: `${prefix}/device/${id}/config`, payload};
+}