feat: add shortcut configuration for media browser

Author: punxaphil

README.md

@@ -290,6 +290,11 @@ mediaBrowser:
   hideHeader: true # default is false. Hides the header of the media browser section (title and navigation buttons).
   itemsPerRow: 1 # default is 4. Use this to show items as list. Applies to both favorites and media browser.
   onlyFavorites: true # default is false. Hides the media browser button, showing only favorites.
+  shortcut: # Optional shortcut button for quick access to a specific folder in the media browser. media_content_id, media_content_type, and name are required.
+    media_content_id: 'media-source://spotify/library/made-for-you' # Required: The content ID of the folder
+    media_content_type: 'spotify://library' # Required: The content type
+    icon: 'mdi:spotify' # Optional: Icon for the shortcut button (default is bookmark icon)
+    name: 'Made for You' # Required: Tooltip/name for the shortcut button
   favorites: # Settings specific to the favorites view within media browser
     title: My favorites # default is 'Favorites'. Use this to change the title for the favorites view.
     customFavorites: # Read more in 'Custom Favorites' section below
@@ -496,29 +501,62 @@ mediaBrowser:
 
 ### Finding media_content_id (advanced)
 
-If you want to find the `media_content_id` for a specific radio station or playlist, sometimes the above method is not enough. If so, you can use the following method to find it:
-
-1. Open Media tab
-2. Open Chrome Dev Tools
-3. Go to Network tab
-4. Filter on "WS"
-5. Reload page
-6. Now you will see a row `websocket`, click on `websocket`
-7. Select Messages tab
-8. Add filter `play_media`
-9. Now navigate to your playlist, and start playing it
-10. A line will appear, click on it
-11. Expand the JSON object, and look under `service_data`
-    There you will see something like:
-
+If you want to find the `media_content_id` for a specific radio station, playlist, or media browser folder, sometimes the above method is not enough. If so, you can use the following method to find it:
+
+1. Open your browser's Developer Tools (F12 or right-click → Inspect)
+2. Go to the **Network** tab
+3. Filter by **WS** (WebSocket)
+4. Reload the page
+5. Click on the `websocket` connection that appears
+6. Go to the **Messages** tab
+7. Filter messages by:
+   - `play_media` - for finding content to play (custom favorites)
+   - `browse_media` - for finding folder paths (media browser shortcuts)
+8. Navigate to your playlist/folder and start playing it or click on it
+9. A message will appear - click on it and expand the JSON object
+10. Look for `media_content_id` and `media_content_type` in the data
+
+Example for a playable item (custom favorite):
+```json
+{
+  "service_data": {
+    "entity_id": "media_player.living_room",
+    "media_content_id": "spotify://playlist:1Oz4xMzRKtRiEs51243ZknqGJm",
+    "media_content_type": "spotify://playlist"
+  }
+}
 ```
-entity_id: "media_player.kok"
-media_content_id: "spotify://8fb1de564ba7e4c8c4512361860574c83b9/spotify:playlist:1Oz4xMzRKtRiEs51243ZknqGJm"
-media_content_type: "spotify://playlist"
+
+Example for a folder (media browser shortcut):
+```json
+{
+  "type": "media_player/browse_media",
+  "entity_id": "media_player.living_room",
+  "media_content_id": "spotify://8fb1de564ba7e4c8c4561860574c83b9",
+  "media_content_type": "spotify://library"
+}
 ```
 
 ![media_content_id.png](https://github.com/punxaphil/custom-sonos-card/raw/main/img/media_content_id.png)
 
+## Media Browser Shortcut
+
+You can configure a shortcut button in the media browser header that takes you directly to a specific folder. This is especially useful for wall-mounted touch displays where you want quick access to frequently used folders like Spotify playlists.
+
+### Example configuration
+
+```yaml
+type: custom:sonos-card
+mediaBrowser:
+  shortcut:
+    media_content_id: 'spotify://8fb1de564ba7e4c8c4561860574c83b9'
+    media_content_type: 'spotify://library'
+    icon: 'mdi:spotify'
+    name: 'My Spotify'
+```
+
+The shortcut button will appear in the media browser header (both in Favorites and Browse Media views), to the left of the other navigation icons. Clicking it will navigate directly to the specified folder, reducing multiple taps to just one.
+
 ## Dynamic volume level slider
 
 The volume level slider is dynamically adjusting its scale. If volume is below 20% it will show a scale up to 30%. Above

src/editor/schema/media-browser-schema.ts

@@ -14,6 +14,29 @@ export const MEDIA_BROWSER_SCHEMA = [
   },
 ];
 
+export const SHORTCUT_SUB_SCHEMA = [
+  {
+    name: 'media_content_id',
+    type: 'string',
+    help: 'The content ID of the folder (use browser DevTools to find this)',
+  },
+  {
+    name: 'media_content_type',
+    type: 'string',
+    help: 'The content type (e.g., spotify://library)',
+  },
+  {
+    name: 'icon',
+    type: 'string',
+    help: 'Icon for the button (e.g., mdi:spotify). Default is bookmark icon.',
+  },
+  {
+    name: 'name',
+    type: 'string',
+    help: 'Tooltip/name for the shortcut button',
+  },
+];
+
 export const FAVORITES_SUB_SCHEMA = [
   {
     name: 'title',

src/editor/tabs/media-browser-tab.ts

@@ -1,16 +1,19 @@
 import { css, html, TemplateResult } from 'lit';
 import { BaseEditor } from '../base-editor';
-import { FAVORITES_SUB_SCHEMA, MEDIA_BROWSER_SCHEMA } from '../schema/media-browser-schema';
+import { FAVORITES_SUB_SCHEMA, MEDIA_BROWSER_SCHEMA, SHORTCUT_SUB_SCHEMA } from '../schema/media-browser-schema';
+import { MediaBrowserShortcut } from '../../types';
 
 class MediaBrowserTab extends BaseEditor {
   protected render(): TemplateResult {
     const mediaBrowserConfig = this.config.mediaBrowser ?? {};
     const favoritesConfig = mediaBrowserConfig.favorites ?? {};
+    const shortcutConfig = mediaBrowserConfig.shortcut ?? {};
     const exclude = favoritesConfig.exclude ?? [];
     const topItems = favoritesConfig.topItems ?? [];
 
     const mediaBrowserData = { ...mediaBrowserConfig };
     const favoritesData = { ...favoritesConfig, exclude: exclude.join(', '), topItems: topItems.join(', ') };
+    const shortcutData = { ...shortcutConfig };
 
     return html`
       <sonos-card-editor-form
@@ -21,6 +24,15 @@ class MediaBrowserTab extends BaseEditor {
         .changed=${this.mediaBrowserChanged}
       ></sonos-card-editor-form>
 
+      <h3>Shortcut</h3>
+      <sonos-card-editor-form
+        .schema=${SHORTCUT_SUB_SCHEMA}
+        .config=${this.config}
+        .hass=${this.hass}
+        .data=${shortcutData}
+        .changed=${this.shortcutChanged}
+      ></sonos-card-editor-form>
+
       <h3>Favorites</h3>
       <sonos-card-editor-form
         .schema=${FAVORITES_SUB_SCHEMA}
@@ -53,6 +65,26 @@ class MediaBrowserTab extends BaseEditor {
     this.configChanged();
   };
 
+  private shortcutChanged = (ev: CustomEvent) => {
+    const changed = ev.detail.value;
+    const mediaBrowser = this.config.mediaBrowser ?? {};
+    // Remove empty values to clean up config
+    const shortcut = Object.fromEntries(
+      Object.entries({
+        ...(mediaBrowser.shortcut ?? {}),
+        ...changed,
+      }).filter(([, v]) => v !== '' && v !== undefined),
+    );
+    this.config = {
+      ...this.config,
+      mediaBrowser: {
+        ...mediaBrowser,
+        shortcut: Object.keys(shortcut).length > 0 ? (shortcut as unknown as MediaBrowserShortcut) : undefined,
+      },
+    };
+    this.configChanged();
+  };
+
   private favoritesChanged = (ev: CustomEvent) => {
     const changed = ev.detail.value;
     const mediaBrowser = this.config.mediaBrowser ?? {};

src/sections/media-browser.ts

@@ -3,6 +3,7 @@ import { property, state } from 'lit/decorators.js';
 import {
   mdiAlphaABoxOutline,
   mdiArrowLeft,
+  mdiBookmark,
   mdiDotsVertical,
   mdiFolderStar,
   mdiFolderStarOutline,
@@ -17,7 +18,7 @@ import '../components/favorites-list';
 import '../components/favorites-icons';
 import { MEDIA_ITEM_SELECTED } from '../constants';
 import { customEvent } from '../utils/utils';
-import { FavoritesConfig, MediaBrowserConfig, MediaPlayerItem } from '../types';
+import { FavoritesConfig, MediaBrowserConfig, MediaBrowserShortcut, MediaPlayerItem } from '../types';
 import { until } from 'lit-html/directives/until.js';
 import { indexOfWithoutSpecialChars } from '../utils/media-browse-utils';
 
@@ -53,6 +54,25 @@ export class MediaBrowser extends LitElement {
     this.loadLayout();
   }
 
+  private onShortcutClick = () => {
+    const shortcut = this.store.config.mediaBrowser?.shortcut;
+    if (shortcut) {
+      // Navigate to browser view with the shortcut path
+      this.view = 'browser';
+      this.navigateIds = [
+        { media_content_id: undefined, media_content_type: undefined },
+        {
+          media_content_id: shortcut.media_content_id,
+          media_content_type: shortcut.media_content_type,
+          title: shortcut.name,
+        },
+      ];
+      this.currentTitle = shortcut.name || '';
+      this.saveCurrentState();
+      this.updateIsCurrentPathStart();
+    }
+  };
+
   private loadLayout() {
     const savedLayout = localStorage.getItem(LAYOUT_KEY) as LayoutType | null;
     if (savedLayout && ['auto', 'grid', 'list'].includes(savedLayout)) {
@@ -173,12 +193,15 @@ export class MediaBrowser extends LitElement {
     const hideHeader = mediaBrowserConfig.hideHeader ?? false;
     const onlyFavorites = mediaBrowserConfig.onlyFavorites ?? false;
 
+    const shortcut = mediaBrowserConfig.shortcut;
+
     return html`
       ${hideHeader
         ? ''
         : html`<div class="header">
             <div class="spacer"></div>
             <span class="title">${title}</span>
+            ${onlyFavorites ? '' : this.renderShortcutButton(shortcut)}
             ${onlyFavorites
               ? ''
               : html`<ha-icon-button
@@ -198,6 +221,33 @@ export class MediaBrowser extends LitElement {
     `;
   }
 
+  private renderShortcutButton(shortcut: MediaBrowserShortcut | undefined) {
+    // Only show if all required properties are provided
+    if (!shortcut?.media_content_id || !shortcut?.media_content_type || !shortcut?.name) {
+      return '';
+    }
+    const icon = shortcut.icon ?? mdiBookmark;
+    const isActive = this.isInShortcutFolder(shortcut);
+    return html`
+      <ha-icon-button
+        class=${isActive ? 'shortcut-active' : ''}
+        @click=${this.onShortcutClick}
+        title=${shortcut.name}
+        .path=${icon.startsWith('mdi:') ? undefined : icon}
+      >
+        ${icon.startsWith('mdi:') ? html`<ha-icon .icon=${icon}></ha-icon>` : ''}
+      </ha-icon-button>
+    `;
+  }
+
+  private isInShortcutFolder(shortcut: MediaBrowserShortcut): boolean {
+    if (this.view !== 'browser' || this.navigateIds.length < 2) {
+      return false;
+    }
+    // Check if any item in the path matches the shortcut
+    return this.navigateIds.some((nav) => nav.media_content_id === shortcut.media_content_id);
+  }
+
   private renderLayoutMenu() {
     return html`
       <ha-button-menu fixed corner="BOTTOM_END" @action=${this.handleMenuAction}>
@@ -312,6 +362,7 @@ export class MediaBrowser extends LitElement {
     const canGoBack = this.navigateIds.length > 1;
     const hideHeader = mediaBrowserConfig.hideHeader ?? false;
     const title = this.currentTitle || 'Media Browser';
+    const shortcut = mediaBrowserConfig.shortcut;
 
     return html`
       ${hideHeader
@@ -321,6 +372,7 @@ export class MediaBrowser extends LitElement {
               ? html`<ha-icon-button .path=${mdiArrowLeft} @click=${this.goBack}></ha-icon-button>`
               : html`<div class="spacer"></div>`}
             <span class="title">${title}</span>
+            ${this.renderShortcutButton(shortcut)}
             <ha-icon-button .path=${mdiStar} @click=${this.goToFavorites} title="Favorites"></ha-icon-button>
             <ha-icon-button
               class=${this.isCurrentPathStart ? 'startpath-active' : ''}
@@ -404,6 +456,9 @@ export class MediaBrowser extends LitElement {
       ha-icon-button.startpath-active {
         color: var(--accent-color);
       }
+      ha-icon-button.shortcut-active {
+        color: var(--accent-color);
+      }
       sonos-ha-media-player-browse,
       sonos-favorites-icons,
       sonos-favorites-list {

src/types.ts

@@ -103,11 +103,19 @@ export interface FavoritesConfig {
   typeMarginBottom?: string;
 }
 
+export interface MediaBrowserShortcut {
+  icon?: string;
+  name: string;
+  media_content_id: string;
+  media_content_type: string;
+}
+
 export interface MediaBrowserConfig {
   favorites?: FavoritesConfig;
   hideHeader?: boolean;
   itemsPerRow?: number;
   onlyFavorites?: boolean;
+  shortcut?: MediaBrowserShortcut;
 }
 
 export interface GroupsConfig {