homebridge-xbox-tv 4.2.2 → 4.3.1

package/CHANGELOG.md

@@ -18,6 +18,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - For plugin < v4.1.0 use Homebridge UI <= v5.5.0
 - For plugin >= v4.1.0 use Homebridge UI >= v5.13.0
 
+## [4.3.1] - (27.09.2026)
+
+### Changes
+
+- changed: the Home Assistant icons of the system menus are dark gray without a background, the same style as in the other plugins
+
+## [4.3.0] - (27.09.2026)
+
+### Changes
+
+- added: Home Assistant app icons in the media browser and the media card. Store apps and games use their logo or box art from the public Microsoft Store catalog, Dashboard, Settings, Television and the other system menus use icons bundled with the plugin (MQTT Universal Media Player integration 0.5.0 or newer)
+- added: Home Assistant media search in the apps (MQTT Universal Media Player integration 0.7.0 or newer)
+
 ## [4.2.2] - (24.09.2026)
 
 ### Changes

package/icons/LICENSE

@@ -0,0 +1,22 @@
+Input icons rendered to PNG from Material Design Icons 7.4.47 by Pictogrammers (https://pictogrammers.com/library/mdi/).
+
+Pictogrammers Free License
+--------------------------
+
+This icon collection is released as free, open source, and GPL friendly by
+the [Pictogrammers](http://pictogrammers.com/) icon group. You may use it
+for commercial projects, open source projects, or anything really.
+
+# Icons: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+Some of the icons are redistributed under the Apache 2.0 license. All other
+icons are either redistributed under their respective licenses or are
+distributed under the Apache 2.0 license.
+
+# Fonts: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+All web and desktop fonts are distributed under the Apache 2.0 license. Web
+and desktop fonts contain some icons that are redistributed under the Apache
+2.0 license. All other icons are either redistributed under their respective
+licenses or are distributed under the Apache 2.0 license.
+
+# Code: MIT (https://opensource.org/licenses/MIT)
+The MIT license applies to all non-font and non-icon files.

package/package.json

@@ -1,7 +1,7 @@
 {
   "displayName": "Xbox TV",
   "name": "homebridge-xbox-tv",
-  "version": "4.2.2",
+  "version": "4.3.1",
   "description": "Homebridge plugin to control Xbox game consoles.",
   "license": "MIT",
   "author": "grzegorz914",
@@ -22,6 +22,7 @@
   },
   "files": [
     "src",
+    "icons",
     "homebridge-ui",
     "index.js",
     "config.schema.json",

package/src/appicons.js

@@ -0,0 +1,77 @@
+import { readFile } from 'fs/promises';
+import axios from 'axios';
+
+// Icons of the console apps for Home Assistant.
+// Store apps and games: the logo or box art from the public Microsoft Store catalog, no sign in needed.
+// Dashboard, Settings and the other system menus are not in the Store, they use icons bundled with the plugin,
+// Material Design Icons (Apache 2.0, https://pictogrammers.com) rendered to PNG in /icons
+const IconsDir = new URL('../icons/', import.meta.url);
+const CatalogUrl = 'https://displaycatalog.mp.microsoft.com/v7.0/products';
+const ImagePurposes = ['Logo', 'BoxArt', 'FeaturePromotionalSquareArt', 'Tile', 'Poster'];
+const MaxCachedImages = 200;
+
+const MenuIcons = {
+    'Screensaver': 'monitor-shimmer',
+    'Dashboard': 'view-dashboard',
+    'Settings': 'cog',
+    'Television': 'television-classic',
+    'SettingsTv': 'tune-vertical',
+    'Accessory': 'microsoft-xbox-controller',
+    'NetworkTroubleshooter': 'lan-check',
+    'MicrosoftStore': 'shopping',
+    'XboxGuide': 'microsoft-xbox'
+};
+
+class AppIconsStore {
+    constructor() {
+        this.client = axios.create({ timeout: 10000 });
+        this.bundled = new Map();
+        // Product id to image url, null when the catalog has no image
+        this.urls = new Map();
+        this.images = new Map();
+    }
+
+    async bundledIcon(name) {
+        if (!this.bundled.has(name)) this.bundled.set(name, await readFile(new URL(`${name}.png`, IconsDir)).catch(() => null));
+        return this.bundled.get(name);
+    }
+
+    async imageUrl(productId) {
+        if (this.urls.has(productId)) return this.urls.get(productId);
+
+        const { data } = await this.client.get(CatalogUrl, { params: { bigIds: productId, market: 'US', languages: 'en-US' } });
+        const images = data?.Products?.[0]?.LocalizedProperties?.[0]?.Images ?? [];
+        const image = ImagePurposes.map(purpose => images.find(i => i.ImagePurpose === purpose && i.Uri)).find(Boolean);
+        const url = image ? `${image.Uri.startsWith('//') ? 'https:' : ''}${image.Uri}?w=256&h=256` : null;
+        this.urls.set(productId, url);
+        return url;
+    }
+
+    // PNG or JPEG bytes of an app (input with oneStoreProductId, isGame), the bundled icon when there is no Store image
+    async get(input) {
+        const productId = String(input?.oneStoreProductId ?? '');
+        if (MenuIcons[productId]) return this.bundledIcon(MenuIcons[productId]);
+
+        const fallback = () => this.bundledIcon(input?.isGame ? 'gamepad-variant' : 'application');
+        if (!productId) return fallback();
+        if (this.images.has(productId)) return this.images.get(productId) ?? fallback();
+
+        let image = null;
+        try {
+            const url = await this.imageUrl(productId);
+            if (url) {
+                const { data } = await this.client.get(url, { responseType: 'arraybuffer' });
+                image = Buffer.from(data);
+            }
+        } catch {
+            // Network error, not cached so the next request tries again
+            return fallback();
+        }
+
+        this.images.set(productId, image);
+        while (this.images.size > MaxCachedImages) this.images.delete(this.images.keys().next().value);
+        return image ?? fallback();
+    }
+}
+
+export default new AppIconsStore();

package/src/hadiscovery.js

@@ -14,6 +14,10 @@ class HaDiscovery {
         this.uniqueId = this.objectId;
         this.name = config.name;
         this.deviceClass = config.deviceClass;
+        // Separate play, pause and stop buttons in the Home Assistant media card
+        this.assumedState = config.assumedState === true;
+        // Players with the same group id can be grouped in Home Assistant, e.g. the zones of one receiver
+        this.group = config.group?.id ? { id: String(config.group.id), leader: config.group.leader === true } : null;
         this.device = config.device ?? {};
         this.commands = config.commands ?? {};
 
@@ -21,9 +25,12 @@ class HaDiscovery {
         this.stateTopic = `${mqtt.config.prefix}/HA State`;
         this.commandTopic = `${mqtt.config.prefix}/Set`;
         this.imageTopic = config.image ? `${mqtt.config.prefix}/HA Image` : null;
+        // Media browser icons requested by Home Assistant with the BrowseImage key, answered by answerBrowseImage
+        this.browseImageTopic = config.browseImages ? `${mqtt.config.prefix}/HA Browse Image` : null;
 
         this.sources = [];
         this.soundModes = [];
+        this.browse = [];
         this.state = {};
         this.lastConfig = '';
         this.lastState = '';
@@ -31,9 +38,11 @@ class HaDiscovery {
     }
 
     // Publish (or republish when changed) the retained discovery message
-    async publishConfig({ sources = this.sources, soundModes = this.soundModes } = {}) {
+    // browse: media browser folders [{ name, type, items: [{ id, name }] }], at most MaxBrowseItems items in total
+    async publishConfig({ sources = this.sources, soundModes = this.soundModes, browse = this.browse } = {}) {
         this.sources = uniqueByName(sources);
         this.soundModes = uniqueByName(soundModes);
+        this.browse = limitBrowse(browse);
 
         const device = { identifiers: [this.uniqueId], name: this.name };
         for (const [key, value] of Object.entries(this.device)) {
@@ -44,14 +53,18 @@ class HaDiscovery {
             platform: PLATFORM,
             unique_id: this.uniqueId,
             device_class: this.deviceClass,
+            ...(this.assumedState ? { assumed_state: true } : {}),
+            ...(this.group ? { group: this.group } : {}),
             state_topic: this.stateTopic,
             command_topic: this.commandTopic,
             availability_topic: this.mqtt.availabilityTopic,
             ...(this.imageTopic ? { image_topic: this.imageTopic } : {}),
+            ...(this.browseImageTopic ? { browse_image_topic: this.browseImageTopic } : {}),
             device,
             commands: this.commands,
             sources: this.sources,
-            sound_modes: this.soundModes
+            sound_modes: this.soundModes,
+            ...(this.browse.length > 0 ? { browse: this.browse } : {})
         };
 
         const payload = JSON.stringify(config);
@@ -83,6 +96,21 @@ class HaDiscovery {
         return true;
     }
 
+    // Answer a media browser icon request, not retained, an empty payload when the item has no icon
+    async answerBrowseImage(key, fetchImage) {
+        // The key becomes a topic level, only the md5 hex key of the integration is accepted
+        if (!this.browseImageTopic || !/^[a-f0-9]{32}$/.test(String(key))) return false;
+
+        let image = null;
+        try {
+            image = await fetchImage();
+        } catch {
+            image = null;
+        }
+        await new Promise(resolve => this.mqtt.mqttClient.publish(`${this.browseImageTopic}/${key}`, image ?? '', { qos: 0 }, () => resolve()));
+        return true;
+    }
+
     // Merge a partial state and publish it retained when something changed
     async updateState(partial) {
         for (const [key, value] of Object.entries(partial)) {
@@ -98,6 +126,24 @@ class HaDiscovery {
     }
 }
 
+// The discovery message stays small enough for the broker and Home Assistant, big bouquets are cut
+const MaxBrowseItems = 2000;
+function limitBrowse(folders) {
+    let left = MaxBrowseItems;
+    const result = [];
+    for (const folder of folders ?? []) {
+        const name = String(folder.name ?? '').trim();
+        const items = (folder.items ?? [])
+            .filter(item => item.id !== undefined && item.id !== null && String(item.name ?? '').trim())
+            .slice(0, Math.max(left, 0))
+            .map(item => ({ id: item.id, name: String(item.name).trim() }));
+        if (!name || items.length === 0) continue;
+        left -= items.length;
+        result.push({ name, ...(folder.type ? { type: folder.type } : {}), items });
+    }
+    return result;
+}
+
 // Home Assistant needs unique names, keep the first item for a duplicated name
 function uniqueByName(items) {
     const seen = new Set();

package/src/xboxdevice.js

@@ -3,6 +3,7 @@ import XboxWebApi from './webApi/xboxwebapi.js';
 import XboxLocalApi from './localApi/xboxlocalapi.js';
 import Functions from './functions.js';
 import HaDiscovery from './hadiscovery.js';
+import AppIcons from './appicons.js';
 import { DefaultInputs, WebApi } from './constants.js';
 
 let Accessory, Characteristic, Service, Categories, Encode, AccessoryUUID;
@@ -83,6 +84,12 @@ class XboxDevice extends EventEmitter {
     }
 
     async setOverExternalIntegration(integration, key, value) {
+        // Media browser icon of an app, the id is the oneStoreProductId, works without the web api
+        if (key === 'BrowseImage') {
+            const input = this.inputsServices?.find(i => i.oneStoreProductId === value?.id) ?? { oneStoreProductId: value?.id };
+            return await this.ha?.answerBrowseImage(value?.key, () => AppIcons.get(input));
+        }
+
         if (!this.consoleAuthorized && this.logWarn) {
             this.emit('warn', `Set over external integration not possible, web api not enabled`);
             return;
@@ -1009,6 +1016,9 @@ class XboxDevice extends EventEmitter {
         try {
             this.ha = new HaDiscovery(this.mqtt1, {
                 objectId: `xbox_${this.liveId}`,
+                // App icons from the Microsoft Store, system menus with icons bundled with the plugin
+                image: true,
+                browseImages: true,
                 name: this.name,
                 deviceClass: 'receiver',
                 device: {
@@ -1055,6 +1065,10 @@ class XboxDevice extends EventEmitter {
                 source: input?.oneStoreProductId,
                 app_name: input?.name ?? ''
             });
+
+            // Icon of the current app
+            const productId = this.power ? input?.oneStoreProductId ?? null : null;
+            this.ha.updateImage(productId, () => AppIcons.get(input)).catch(() => { });
         } catch (error) {
             if (this.logWarn) this.emit('warn', `HA Discovery state error: ${error}`);
         }