Skip to content

feat: media services and automation blueprints (Milestone 3) - #3

Open
ant1fr wants to merge 2 commits into
mainfrom
feat/blueprints
Open

ant1fr wants to merge 2 commits into
mainfrom
feat/blueprints

Conversation

@ant1fr

@ant1fr ant1fr commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Summary

Milestone 3: two new media services and the automation blueprints promised in CLAUDE.md. Grounded in the Smart Frame Engine contract v1.2 (openapi.json: NowPlayingRequest, TmdbDisplayRequest); no field is invented.

Services (capability-gated, translated ServiceValidationError, optional config_entry_id, same patterns as M2)

  • show_now_playing (now_playing): POST /api/display/now-playing. Contract fields (artist, album, title, artwork_url, duration_seconds, position_seconds, enrich_artwork, ephemeral, hold_minutes, push_to_fraimic, show_title, style, ttl_seconds), plus a media_player entity that fills whatever the call leaves out.
  • show_media_poster (display_tmdb): POST /api/display/tmdb. Contract fields (query, media_type, season, year, language, fallback_url, ephemeral, ttl_minutes, hold_minutes, push_to_fraimic), plus media_player.

Blueprints (blueprints/automation/smart_frame_engine/)

Blueprint Does
ambient_weather weather entity condition to set_ambient_context
ambient_presence names of the people at home to set_ambient_context (an empty list clears it)
title_card any trigger to send_title_card, templatable texts
now_playing_cover media player playing music to show_now_playing
tv_poster media player playing a movie/series to show_media_poster

Decisions worth a look

  1. Where the picture comes from differs between the two endpoints (per the contract, not a choice of ours):
    • TMDB poster: the player's picture is the fallback (fallback_url, used only when TMDB has no match).
    • Album cover: the opposite. artwork_url is tried first; the engine's Deezer / MusicBrainz lookup (enrich_artwork) only runs when the cover is missing or unusable. The contract has no "engine first, Home Assistant second" order for covers. The music blueprint has a "Send the player's cover" switch (default on); off makes the engine's lookup the only source.
  2. Absolute URLs. A player's entity_picture is usually relative (/api/media_player_proxy/...). It is made absolute with Home Assistant's internal URL; if none is configured the picture is simply left out (debug log, no error) and the engine's own lookup applies. The engine has to be able to reach that URL: that is a network matter on the user's side.
  3. Live playback position. For a playing track the position is the reported media_position plus the time since media_position_updated_at (capped at the track length), so the engine works out the cover's expiry from the real position.
  4. Blueprint heartbeat. Weather and presence re-send every 30 minutes, with a 180-minute lifetime, so values do not expire while nothing changes and the engine forgets them if Home Assistant stops updating.
  5. State, not attributes. Weather and person entities update attributes constantly; their triggers use to: null so only real state changes fire. The media blueprints listen to media_title and the playing transition, not to position ticks, and count "starts playing with a new title" once.
  6. Optional engine input. config_entry_id: "" would raise entry_not_found, so the blueprints drop empty values from the service data and send config_entry_id only when an engine is picked.
  7. ttl_minutes for posters is 1..1440 (the title card allows 10080); each service enforces its own contract range.
  8. HACS does not install blueprints. The README documents the import buttons and a manual copy.

Verification

Fresh Linux clone of this branch (Python 3.14, HA 2026.10.4):

  • ruff check ., ruff format --check ., mypy custom_components (strict): passed
  • pytest: 360 passed, 4 consecutive runs, and each of the 360 tests also passes alone in its own process (360 of 360 reported exactly "1 passed")
  • Blueprint tests load every file with Home Assistant's own blueprint models and run them as real automations; the five services are replaced by recorders that validate each call with the integration's real schemas. They check exact payloads, the omitted-empty-engine rule, attribute-only changes being ignored, the 20-name / 80-character / 200-character limits, and the renewal timing.
  • Mutation checks: 22 deliberate breakages (blueprint conditions, caps, triggers, and service logic such as position top-up, explicit values winning, capability gating, URL absolutising, the poster TTL range) are each caught by a test. Two initially survived (a renewal test that did not discriminate, and a flawed mutation); both were fixed.

Not verified: hassfest and HACS run in CI only. Nothing has run against a real engine or a real Home Assistant UI import: all HTTP is mocked from the contract's schemas. The blueprints' source_url points at main, so URL import only works once this is merged.

Not in this PR

Clearing the cover when music stops (DELETE /api/queue/ephemeral; the cover already expires with the track), base64 artwork, ttl_minutes: null for title cards, Smart Mix, Immich display services, a real-engine test.

🤖 Generated with Claude Code

ant1fr and others added 2 commits November 20, 2026 09:48
show_now_playing (now_playing) and show_media_poster (display_tmdb) call
POST /api/display/now-playing and /api/display/tmdb. A media_player entity
can fill the fields; values given in the call win. The player's picture is
sent as the cover (music: tried first, then the engine's lookup) or as the
TMDB fallback, made absolute with the internal URL when relative.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…usic and TV

Five blueprints under blueprints/automation/smart_frame_engine that call
the integration's services. Tests load them with Home Assistant's blueprint
models and run them as real automations against the real service schemas.
README documents the import links and where each picture comes from.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant