Release 0.7.0: browser-side transition card, visual editor, frame_id

Merges release-0.7-transitions: custom Lovelace card with CSS-based transitions,
ha-form schema-driven visual editor, per-frame entity_picture cache-busting via
frame_id, and supporting camera/init refactors.

Author: eyalgal

README.md

@@ -48,6 +48,13 @@ All behavior is exposed as Home Assistant entities. Adjust everything live witho
 - Manual "Next slide" button still works while paused
 - Survives Home Assistant restarts
 
+### ✨ Transitions
+- Smooth slide transitions rendered in the browser, so they stay buttery even on lower-end hardware
+- Effects: `random`, `none`, `fade`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, `wipe-left`, `wipe-right`, `zoom`
+- `random` picks a different effect per slide (and avoids repeating the previous one)
+- Configurable duration and CSS easing
+- Aspect ratio + fill mode inheritance from the camera entity (cover / contain / blur backdrop)
+
 ### 🎨 Smart Rendering Engine
 
 #### Orientation Mismatch Handling
@@ -82,7 +89,7 @@ The following entities allow you to adjust slideshow behavior without restarting
 | Number | Slide interval | 60 | Any positive integer (seconds) | Time between slides |
 | Number | Album refresh | 24 | Any positive integer (hours) | How often album contents refresh |
 | Number | Pair divider size | 8 | 0-64 (px) | Width of divider between paired images |
-| Number | Image cache size | 150 | 50–1000 (MB) | Memory budget for downloaded image data |
+| Number | Image cache size | 75 | 50-1000 (MB) | Memory budget for downloaded image data (per album) |
 | Select | Fill mode | blur | blur, cover, contain | How images fill the canvas |
 | Select | Orientation mismatch | pair | pair, single, avoid | Handling of portrait and landscape mismatch |
 | Select | Order mode | random | random, album_order, newest_taken, oldest_taken, newest_added, oldest_added | Slide ordering behavior |
@@ -201,6 +208,48 @@ The slideshow camera exposes per-frame metadata as attributes (use with `state_a
 | `byte_size` | int \| null | Original file size in bytes (Google Photos only) |
 | `paused` | bool | Whether the slideshow is paused |
 | `date_filter` | string | Active date filter mode |
+| `frame_id` | int | Monotonic counter incremented on every committed slide. Used by the [card](#-album-slideshow-card) to detect new frames |
+
+---
+
+## 🎞 Album Slideshow Card
+
+The integration ships with a custom Lovelace card that does the slide-to-slide transition entirely in the browser. The server only renders one still per slide change; the card cross-fades in CSS, which the browser composites on the GPU. Result: a smooth dissolve on a Pi 4, even with several albums on screen.
+
+The card is registered automatically when the integration loads; you do **not** need to add it as a HACS frontend repository or configure a Lovelace resource manually. After installing or upgrading, hard-refresh the dashboard once (Ctrl+Shift+R) so the browser picks up the script.
+
+A visual editor is available - pick **Album Slideshow** from the card picker in Lovelace and the form will appear automatically.
+
+### Minimal example
+
+```yaml
+type: custom:album-slideshow-card
+entity: camera.album_slideshow_living_room
+```
+
+### Full options
+
+```yaml
+type: custom:album-slideshow-card
+entity: camera.album_slideshow_living_room
+transition: random          # random | none | fade | slide-left
+                            #   | slide-right | slide-up | slide-down
+                            #   | wipe-left | wipe-right | zoom
+duration: 800               # ms; CSS transition length
+easing: ease-in-out         # any CSS timing function (ease, linear, cubic-bezier(...))
+aspect_ratio: 16/9          # CSS aspect-ratio value (16/9, 4/3, 1/1, auto)
+fit: auto                   # auto | cover | contain
+                            # auto inherits the camera's fill_mode (cover / contain / blur)
+background: '#000'          # color shown behind contained images
+tap_action: none            # none | more-info
+```
+
+### Notes
+
+- `transition: random` picks a different effect per slide and avoids repeating the previous one.
+- `fit: auto` reads the camera's `fill_mode` attribute. `blur` renders the slide as `contain` plus a blurred backdrop layer behind it.
+- Every slide commit increments the camera's `frame_id` attribute. The card cache-busts the camera proxy URL with that value, so the browser refetches a fresh JPEG on every change instead of serving a stale cached image.
+- If the entity is unavailable, the card shows a "Camera not ready" placeholder.
 
 ---
 

custom_components/album_slideshow/__init__.py

@@ -1,19 +1,163 @@
 from __future__ import annotations
 
+import asyncio
+import json
+import logging
+import os
+
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers import entity_registry as er
 
 from .const import DOMAIN, SERVICE_NEXT_SLIDE, SERVICE_REFRESH_ALBUM, ATTR_ENTRY_ID
 from .store import SlideshowStore
 
+_LOGGER = logging.getLogger(__name__)
+
 PLATFORMS: list[str] = ["camera", "sensor", "button", "number", "select", "text", "switch"]
 
+CARD_STATIC_PATH = "/album_slideshow_static"
+CARD_FILE = "album-slideshow-card.js"
+
+
+async def _async_register_card(hass: HomeAssistant) -> None:
+    """Serve the Lovelace card JS and register it as a frontend module.
+
+    Idempotent: only the first config entry to load triggers registration
+    for the HA session. The card lets dashboards cross-fade between slides
+    in the browser (GPU compositor) instead of forcing the camera entity
+    to render a JPEG burst on the event loop.
+    """
+    if hass.data.get(DOMAIN, {}).get("card_registered"):
+        return
+
+    integration_dir = os.path.dirname(__file__)
+    www_dir = os.path.join(integration_dir, "www")
+    card_path = os.path.join(www_dir, CARD_FILE)
+
+    if not os.path.isfile(card_path):
+        # Some HACS upgrade paths (and broken zip extractors) drop the
+        # ``www/`` subdirectory. Try to recover by checking whether the
+        # integration root has the file under a literal-backslash name
+        # (a symptom of zips written with Windows path separators) or
+        # directly at the root, and salvage it into ``www/`` so the
+        # rest of the registration can proceed.
+        recovered = await hass.async_add_executor_job(
+            _recover_card_from_root, integration_dir, www_dir, card_path
+        )
+        if not recovered:
+            _LOGGER.warning(
+                "Album Slideshow card missing on disk (%s). Re-install"
+                " the integration via HACS (3-dot menu -> Redownload)"
+                " or copy %s/%s into the album_slideshow folder."
+                " The custom:album-slideshow-card type will not be"
+                " available until this is fixed.",
+                card_path,
+                "www",
+                CARD_FILE,
+            )
+            return
+
+    try:
+        from homeassistant.components.http import StaticPathConfig
+
+        await hass.http.async_register_static_paths(
+            [StaticPathConfig(CARD_STATIC_PATH, www_dir, False)]
+        )
+    except Exception:  # noqa: BLE001 - many possible failure modes here
+        _LOGGER.exception(
+            "Failed to register static path for Album Slideshow card"
+        )
+        return
+
+    # Cache-bust the card URL with the integration version so dashboards
+    # always pick up the script that matches the running integration
+    # rather than a stale copy from a previous release.
+    version = await hass.async_add_executor_job(
+        _read_manifest_version, integration_dir
+    )
+    card_url = f"{CARD_STATIC_PATH}/{CARD_FILE}"
+    if version:
+        card_url = f"{card_url}?v={version}"
+
+    try:
+        from homeassistant.components.frontend import add_extra_js_url
+
+        add_extra_js_url(hass, card_url)
+    except Exception:  # noqa: BLE001
+        _LOGGER.exception(
+            "Failed to add Album Slideshow card to Lovelace; you can"
+            " still register it manually as a resource at %s",
+            card_url,
+        )
+        return
+
+    hass.data.setdefault(DOMAIN, {})["card_registered"] = True
+    _LOGGER.info("Album Slideshow card registered at %s", card_url)
+
+
+def _read_manifest_version(integration_dir: str) -> str | None:
+    try:
+        with open(
+            os.path.join(integration_dir, "manifest.json"),
+            "r",
+            encoding="utf-8",
+        ) as fh:
+            return json.load(fh).get("version")
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _recover_card_from_root(
+    integration_dir: str, www_dir: str, card_path: str
+) -> bool:
+    """Salvage the card file from a broken extraction.
+
+    PowerShell's ``Compress-Archive`` writes zip entries with backslash
+    separators, which Linux unzip implementations may treat as literal
+    filenames. The resulting layout is::
+
+        custom_components/album_slideshow/www\\album-slideshow-card.js
+
+    instead of the expected ``www/album-slideshow-card.js``. Move it to
+    the right place so subsequent installs don't need a re-download.
+    """
+    candidates = [
+        os.path.join(integration_dir, f"www\\{CARD_FILE}"),
+        os.path.join(integration_dir, CARD_FILE),
+    ]
+    for src in candidates:
+        if os.path.isfile(src):
+            try:
+                os.makedirs(www_dir, exist_ok=True)
+                os.replace(src, card_path)
+                _LOGGER.info(
+                    "Recovered Album Slideshow card from %s", src
+                )
+                return True
+            except OSError:
+                _LOGGER.exception(
+                    "Found candidate card at %s but could not move it"
+                    " to %s",
+                    src,
+                    card_path,
+                )
+                return False
+    return False
+
 
 async def _async_cleanup_legacy_entities(hass: HomeAssistant, entry: ConfigEntry) -> None:
     registry = er.async_get(hass)
+    # Server-side transitions were tried in earlier 0.7-rc builds and
+    # removed before the first public 0.7 pre-release because the
+    # resource cost on low-end hardware was too high. Drop any leftover
+    # transition entities so users don't see stale disabled rows under
+    # the device.
     legacy_unique_ids = {
         f"{entry.entry_id}_max_items",
+        f"{entry.entry_id}_transition",
+        f"{entry.entry_id}_transition_duration_ms",
+        f"{entry.entry_id}_transition_fps",
     }
 
     for entity in er.async_entries_for_config_entry(registry, entry.entry_id):
@@ -25,6 +169,17 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     from .coordinator import AlbumCoordinator
 
     hass.data.setdefault(DOMAIN, {})
+    # Domain-wide concurrency limit on compose work. Multiple album cameras
+    # share HA's small executor pool; without coordination they can all
+    # decode + render in parallel and saturate the loop. One ticket means
+    # at most one album does PIL work at a time, queueing the rest.
+    if "compose_semaphore" not in hass.data[DOMAIN]:
+        hass.data[DOMAIN]["compose_semaphore"] = asyncio.Semaphore(1)
+
+    # Register the Lovelace card once per HA session. The card runs the
+    # GPU-composited transitions in the browser so the camera entity
+    # itself never has to render a transition burst on the event loop.
+    await _async_register_card(hass)
 
     await _async_cleanup_legacy_entities(hass, entry)
 
@@ -76,5 +231,13 @@ async def _refresh_album(call) -> None:
 async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
     if unload_ok:
-        hass.data[DOMAIN].pop(entry.entry_id, None)
+        domain_data = hass.data.get(DOMAIN, {})
+        domain_data.pop(entry.entry_id, None)
+        # Drop the shared semaphore once the last album is gone so it's
+        # re-created if the integration is re-added later.
+        entry_keys = [
+            k for k in domain_data.keys() if k != "compose_semaphore"
+        ]
+        if not entry_keys:
+            domain_data.pop("compose_semaphore", None)
     return unload_ok