From 967032014c20687ca5e2883b73030c39c7af8b9d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Markus=20Holzh=C3=A4user?= <markusholzhauser@Mac.fritz.box>
Date: Wed, 8 Apr 2026 22:52:37 +0200
Subject: [PATCH 1/2] feat: add +10s seek forward button to admin control bar
 (#498)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Adds ⏩ +10s button next to volume controls
- Reads current media_position from HA state and seeks to pos + 10s
- Only visible during PLAYING and REVEAL phases
- Adds tooltips to all admin control bar buttons

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 custom_components/beatify/game/state.py       |  6 +++++
 custom_components/beatify/server/websocket.py | 12 +++++++++
 .../beatify/services/media_player.py          | 25 +++++++++++++++++++
 custom_components/beatify/www/admin.html      |  7 +++---
 custom_components/beatify/www/js/admin.js     |  7 ++++++
 5 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/custom_components/beatify/game/state.py b/custom_components/beatify/game/state.py
index 5de6242..b29665b 100644
--- a/custom_components/beatify/game/state.py
+++ b/custom_components/beatify/game/state.py
@@ -1849,6 +1849,12 @@ async def set_volume_on_player(self, level: float) -> bool:
             return await self._media_player_service.set_volume(level)
         return False
 
+    async def seek_forward(self, seconds: int) -> bool:
+        """Seek media player forward by given seconds (#498)."""
+        if self._media_player_service:
+            return await self._media_player_service.seek_forward(seconds)
+        return False
+
     async def play_deferred_song(self, song: dict) -> bool:
         """Play a song that was deferred for intro splash (#321).
 
diff --git a/custom_components/beatify/server/websocket.py b/custom_components/beatify/server/websocket.py
index 4aec423..54029a1 100644
--- a/custom_components/beatify/server/websocket.py
+++ b/custom_components/beatify/server/websocket.py
@@ -421,6 +421,7 @@ async def _handle_admin(
             "next_round": self._admin_next_round,
             "stop_song": self._admin_stop_song,
             "set_volume": self._admin_set_volume,
+            "seek_forward": self._admin_seek_forward,
             "end_game": self._admin_end_game,
             "dismiss_game": self._admin_dismiss_game,
             "rematch_game": self._admin_rematch_game,
@@ -646,6 +647,17 @@ async def _admin_set_volume(
             }
         )
 
+    async def _admin_seek_forward(
+        self, ws: web.WebSocketResponse, data: dict, game_state: GameState
+    ) -> None:
+        """Handle admin seek_forward action (#498)."""
+        if game_state.phase not in (GamePhase.PLAYING, GamePhase.REVEAL):
+            return
+        seconds = data.get("seconds", 10)
+        success = await game_state.seek_forward(seconds)
+        if success:
+            _LOGGER.info("Media seeked forward %ds", seconds)
+
     async def _admin_end_game(
         self, ws: web.WebSocketResponse, data: dict, game_state: GameState
     ) -> None:
diff --git a/custom_components/beatify/services/media_player.py b/custom_components/beatify/services/media_player.py
index 4effc94..87f6ab7 100644
--- a/custom_components/beatify/services/media_player.py
+++ b/custom_components/beatify/services/media_player.py
@@ -551,6 +551,31 @@ async def set_volume(self, level: float) -> bool:
             self._record_error("MEDIA_PLAYER_ERROR", f"Failed to set volume: {err}")
             return False
 
+    async def seek_forward(self, seconds: int) -> bool:
+        """Seek media forward by given seconds (#498).
+
+        Reads current position from HA state and seeks to position + seconds.
+        """
+        try:
+            state = self._hass.states.get(self._entity_id)
+            if not state:
+                return False
+            current_pos = state.attributes.get("media_position", 0) or 0
+            new_pos = current_pos + seconds
+            await self._hass.services.async_call(
+                "media_player",
+                "media_seek",
+                {
+                    "entity_id": self._entity_id,
+                    "seek_position": new_pos,
+                },
+            )
+            return True  # noqa: TRY300
+        except Exception as err:  # noqa: BLE001
+            _LOGGER.error("Failed to seek media: %s", err)  # noqa: TRY400
+            self._record_error("MEDIA_PLAYER_ERROR", f"Failed to seek: {err}")
+            return False
+
     def is_available(self) -> bool:
         """
         Check if media player is available.
diff --git a/custom_components/beatify/www/admin.html b/custom_components/beatify/www/admin.html
index 1ef6347..3b0eb65 100644
--- a/custom_components/beatify/www/admin.html
+++ b/custom_components/beatify/www/admin.html
@@ -514,9 +514,10 @@ <h2 class="section-header"><span class="section-icon" aria-hidden="true">▶️<
                 <button id="admin-stop-song" class="btn btn-secondary btn-compact">
                     <span aria-hidden="true">⏹</span> Stop
                 </button>
-                <button id="admin-vol-down" class="btn btn-secondary btn-compact">🔉</button>
-                <button id="admin-vol-up" class="btn btn-secondary btn-compact">🔊</button>
-                <button id="admin-end-game-playing" class="btn btn-danger btn-compact">End Game</button>
+                <button id="admin-seek-forward" class="btn btn-secondary btn-compact" title="Seek forward 10 seconds">⏩ +10s</button>
+                <button id="admin-vol-down" class="btn btn-secondary btn-compact" title="Volume down">🔉</button>
+                <button id="admin-vol-up" class="btn btn-secondary btn-compact" title="Volume up">🔊</button>
+                <button id="admin-end-game-playing" class="btn btn-danger btn-compact" title="End game">End Game</button>
             </div>
 
             <!-- Player game UI (only shown if admin joined as player) -->
diff --git a/custom_components/beatify/www/js/admin.js b/custom_components/beatify/www/js/admin.js
index bf9e2d8..5e11e64 100644
--- a/custom_components/beatify/www/js/admin.js
+++ b/custom_components/beatify/www/js/admin.js
@@ -129,6 +129,7 @@ document.addEventListener('DOMContentLoaded', async () => {
 
     // Issue #477: Wire game phase control buttons
     document.getElementById('admin-stop-song')?.addEventListener('click', adminStopSong);
+    document.getElementById('admin-seek-forward')?.addEventListener('click', adminSeekForward);
     document.getElementById('admin-vol-down')?.addEventListener('click', adminVolumeDown);
     document.getElementById('admin-vol-up')?.addEventListener('click', adminVolumeUp);
     document.getElementById('admin-end-game-playing')?.addEventListener('click', endGame);
@@ -3025,6 +3026,12 @@ function adminStopSong() {
     }
 }
 
+function adminSeekForward() {
+    if (adminWs && adminWs.readyState === WebSocket.OPEN) {
+        adminWs.send(JSON.stringify({ type: 'admin', action: 'seek_forward', seconds: 10 }));
+    }
+}
+
 function adminVolumeUp() {
     if (adminWs && adminWs.readyState === WebSocket.OPEN) {
         adminWs.send(JSON.stringify({ type: 'admin', action: 'set_volume', direction: 'up' }));

From d12b3ce9840c64285246251c513a225b604df611 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Markus=20Holzh=C3=A4user?= <markusholzhauser@Mac.fritz.box>
Date: Thu, 9 Apr 2026 04:31:29 +0200
Subject: [PATCH 2/2] fix: account for stale cached media_position in
 seek_forward

HA caches media_position and only updates at media_position_updated_at.
Without adjusting for elapsed time since last update, seeking would
jump backward to the stale position then add 10s.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 custom_components/beatify/services/media_player.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/custom_components/beatify/services/media_player.py b/custom_components/beatify/services/media_player.py
index 87f6ab7..9326452 100644
--- a/custom_components/beatify/services/media_player.py
+++ b/custom_components/beatify/services/media_player.py
@@ -5,6 +5,7 @@
 import asyncio
 import logging
 import sys
+from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any
 
 if sys.version_info >= (3, 11):
@@ -561,6 +562,15 @@ async def seek_forward(self, seconds: int) -> bool:
             if not state:
                 return False
             current_pos = state.attributes.get("media_position", 0) or 0
+            # Adjust for stale cached position — HA only updates
+            # media_position at media_position_updated_at
+            updated_at = state.attributes.get("media_position_updated_at")
+            if updated_at:
+                if isinstance(updated_at, str):
+                    updated_at = datetime.fromisoformat(updated_at)
+                elapsed = (datetime.now(timezone.utc) - updated_at).total_seconds()
+                if elapsed > 0:
+                    current_pos += elapsed
             new_pos = current_pos + seconds
             await self._hass.services.async_call(
                 "media_player",