Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,12 @@ Official Home Assistant custom integration (`smart_frame_engine`) for **Smart Fr
- `custom_components/smart_frame_engine/image.py` — Live preview entity of currently rendered frame image
- `custom_components/smart_frame_engine/manifest.json` — HA integration metadata (strict `hassfest` key sorting)
- `custom_components/smart_frame_engine/sensor.py` — Active source/mode, media title, engine version, ambient context
- `custom_components/smart_frame_engine/services.py` — Service handlers (capability-gated, `ServiceValidationError`), registered once from `async_setup`
- `custom_components/smart_frame_engine/services.py` — Service handlers (ambient context, title card, album cover, poster; capability-gated, `ServiceValidationError`), registered once from `async_setup`. Album covers: the player's picture is tried first, then the engine's own lookup; TMDB posters: the player's picture is only the fallback
- `custom_components/smart_frame_engine/services.yaml` — Service definitions & UI selectors
- `custom_components/smart_frame_engine/strings.json` — Base UI & error strings (must stay identical to `translations/en.json`)
- `custom_components/smart_frame_engine/switch.py` — Family Mode toggle
- `custom_components/smart_frame_engine/translations/en.json` & `fr.json` — Complete English & French translations
- `blueprints/automation/smart_frame_engine/` — Ready-to-use YAML blueprints (weather/presence context, title cards)
- `blueprints/automation/smart_frame_engine/` — Ready-to-use YAML blueprints (weather/presence context, title cards, album covers, movie/series posters). They only call this integration's services, are validated by `tests/test_blueprints.py` (loaded with HA's blueprint models and run as real automations), and are **not installed by HACS** (users import them by URL; keep the README import links in step)
- `tests/` — `pytest` + `pytest-homeassistant-custom-component`
- `hacs.json` — HACS metadata
- `pyproject.toml` — `ruff`, `mypy`, `pytest` configuration
Expand Down
50 changes: 48 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ Custom [Home Assistant](https://www.home-assistant.io/) integration for
[Smart Frame Engine](https://github.com/ant1fr/Smart-Frame-Engine), installable through
[HACS](https://hacs.xyz/) or manually.

> **Status:** work in progress. Discovery, setup, authentication, compatibility checks, entities
> and services are in place; blueprints follow in a later milestone.
> **Status:** work in progress. Discovery, setup, authentication, compatibility checks, entities,
> services and blueprints are in place. It has been tested against the engine's API contract
> (v1.2), not yet against a real engine.

## Requirements

Expand Down Expand Up @@ -62,9 +63,54 @@ data:
ttl_minutes: 120
```

- `smart_frame_engine.show_now_playing` (needs `now_playing`): shows the album cover of the music
playing. Pass a `media_player` and the artist, album, title, position and cover are read from it;
anything you set yourself wins. Other fields: `artist`, `album`, `title`, `artwork_url`,
`duration_seconds`, `position_seconds`, `style` (`sleeve` or `vinyl`), `show_title`,
`enrich_artwork`, `ephemeral`, `ttl_seconds`, `hold_minutes`, `push_to_fraimic`.
- `smart_frame_engine.show_media_poster` (needs `display_tmdb`): finds a movie or series on TMDB
and shows its poster. Pass a `media_player` and the title, type (movie or series) and season are
read from it. Other fields: `query`, `media_type`, `season`, `year`, `language`, `fallback_url`,
`ephemeral`, `ttl_minutes` (1 to 1440), `hold_minutes`, `push_to_fraimic`.

```yaml
action: smart_frame_engine.show_now_playing
data:
media_player: media_player.kitchen
```

A service called on an engine that lacks the capability fails with a clear message instead of
sending a request.

### Where the picture comes from

- **Album covers:** the cover of the media player is sent to the engine and **tried first**. If it
is missing or unusable, the engine looks one up itself (Deezer, then MusicBrainz / Cover Art
Archive). Set `use_media_player_picture: false` to always let the engine look it up.
- **Movie and series posters:** the engine looks the title up on TMDB, and the picture of the media
player is only the **fallback**, used when TMDB has no match.
- The picture of a media player is a Home Assistant address, so the engine must be able to reach
Home Assistant's **internal URL** (Settings > System > Network). Without an internal URL no
picture is sent, and the engine's own lookup applies.

## Blueprints

Ready-to-use automations are in [`blueprints/automation/smart_frame_engine`](blueprints/automation/smart_frame_engine).
HACS does not install blueprints: import each one with its button (Settings > Automations >
Blueprints), or copy the files into `config/blueprints/automation/smart_frame_engine/`.

| Blueprint | What it does | Import |
| --- | --- | --- |
| `ambient_weather.yaml` | Tells the engine about the weather of a weather entity | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fant1fr%2FSmart-Frame-Engine-HA%2Fblob%2Fmain%2Fblueprints%2Fautomation%2Fsmart_frame_engine%2Fambient_weather.yaml) |
| `ambient_presence.yaml` | Tells the engine which people are home | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fant1fr%2FSmart-Frame-Engine-HA%2Fblob%2Fmain%2Fblueprints%2Fautomation%2Fsmart_frame_engine%2Fambient_presence.yaml) |
| `title_card.yaml` | Shows a text card when your trigger fires | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fant1fr%2FSmart-Frame-Engine-HA%2Fblob%2Fmain%2Fblueprints%2Fautomation%2Fsmart_frame_engine%2Ftitle_card.yaml) |
| `now_playing_cover.yaml` | Shows the album cover of the music playing | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fant1fr%2FSmart-Frame-Engine-HA%2Fblob%2Fmain%2Fblueprints%2Fautomation%2Fsmart_frame_engine%2Fnow_playing_cover.yaml) |
| `tv_poster.yaml` | Shows the poster of the movie or series playing | [![Import](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2Fant1fr%2FSmart-Frame-Engine-HA%2Fblob%2Fmain%2Fblueprints%2Fautomation%2Fsmart_frame_engine%2Ftv_poster.yaml) |

The weather and presence blueprints re-send their value every 30 minutes, and each value expires
on its own after its lifetime, so the engine forgets it if Home Assistant stops updating it. Every
blueprint has an optional engine input, only needed when you have several engines.

## License

[MIT](LICENSE)
82 changes: 82 additions & 0 deletions blueprints/automation/smart_frame_engine/ambient_presence.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
blueprint:
name: Smart Frame Engine - Tell the frame who is home
description: >-
Keeps the list of people who are home in the ambient context of Smart Frame Engine, so the
engine can favour their photos.


The people are sent by name (their `person` entity's name), so the names must match the
people known to Immich. When nobody is home the list is emptied, which clears it in the
engine. It is updated when someone arrives or leaves, when Home Assistant starts, and every
30 minutes. Each update expires on its own after the lifetime below.
domain: automation
source_url: https://github.com/ant1fr/Smart-Frame-Engine-HA/blob/main/blueprints/automation/smart_frame_engine/ambient_presence.yaml
author: ant1fr
homeassistant:
min_version: 2026.1.0
input:
persons:
name: People
description: The people to follow (up to 20 can be at home at the same time).
selector:
entity:
multiple: true
filter:
domain: person
ttl_minutes:
name: Lifetime
description: >-
How long the engine keeps the list without an update, in minutes. It is renewed every 30
minutes, so keep this above 30.
default: 180
selector:
number:
min: 1
max: 10080
mode: box
unit_of_measurement: min
engine:
name: Smart Frame Engine
description: Only needed when you have several engines. Leave empty otherwise.
default: ""
selector:
config_entry:
integration: smart_frame_engine

mode: restart
max_exceeded: silent

variables:
persons: !input persons
ttl_minutes: !input ttl_minutes
engine: !input engine
# The engine takes at most 20 names of at most 80 characters.
home_names: >-
{% set ns = namespace(names=[]) %}
{% for person in persons if is_state(person, 'home') %}
{% set ns.names = ns.names + [(state_attr(person, 'friendly_name') or person)[:80]] %}
{% endfor %}
{{ ns.names[:20] }}

triggers:
- trigger: state
entity_id: !input persons
# Only the state (home, away...): other attributes change for unrelated reasons.
to: null
id: changed
- trigger: homeassistant
event: start
id: started
- trigger: time_pattern
minutes: "/30"
id: renew

actions:
- alias: Tell the engine who is home
action: smart_frame_engine.set_ambient_context
data: >-
{{ dict({
'config_entry_id': engine,
'presence': home_names,
'ttl_minutes': ttl_minutes,
}.items() | rejectattr('1', 'in', ['', none]) | list) }}
77 changes: 77 additions & 0 deletions blueprints/automation/smart_frame_engine/ambient_weather.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
blueprint:
name: Smart Frame Engine - Tell the frame about the weather
description: >-
Keeps the weather of a weather entity in the ambient context of Smart Frame Engine, so the
engine can favour fitting pictures.


The weather is sent when it changes, when Home Assistant starts, and every 30 minutes. Each
value expires on its own after the lifetime below, so the engine forgets it if Home Assistant
stops updating it. The weather entity's condition is sent as is (for example `rainy`,
`sunny` or `clear-night`).
domain: automation
source_url: https://github.com/ant1fr/Smart-Frame-Engine-HA/blob/main/blueprints/automation/smart_frame_engine/ambient_weather.yaml
author: ant1fr
homeassistant:
min_version: 2026.1.0
input:
weather_entity:
name: Weather entity
selector:
entity:
filter:
domain: weather
ttl_minutes:
name: Lifetime
description: >-
How long the engine keeps the weather without an update, in minutes. It is renewed every
30 minutes, so keep this above 30.
default: 180
selector:
number:
min: 1
max: 10080
mode: box
unit_of_measurement: min
engine:
name: Smart Frame Engine
description: Only needed when you have several engines. Leave empty otherwise.
default: ""
selector:
config_entry:
integration: smart_frame_engine

mode: restart
max_exceeded: silent

variables:
weather_entity: !input weather_entity
ttl_minutes: !input ttl_minutes
engine: !input engine

triggers:
- trigger: state
entity_id: !input weather_entity
# Only the condition: temperature and other attributes change all the time.
to: null
id: changed
- trigger: homeassistant
event: start
id: started
- trigger: time_pattern
minutes: "/30"
id: renew

conditions:
- condition: template
value_template: "{{ states(weather_entity) not in ['unknown', 'unavailable'] }}"

actions:
- alias: Tell the engine about the weather
action: smart_frame_engine.set_ambient_context
data: >-
{{ dict({
'config_entry_id': engine,
'weather': states(weather_entity),
'ttl_minutes': ttl_minutes,
}.items() | rejectattr('1', 'in', ['', none]) | list) }}
143 changes: 143 additions & 0 deletions blueprints/automation/smart_frame_engine/now_playing_cover.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
blueprint:
name: Smart Frame Engine - Show the album cover of the music playing
description: >-
Shows the cover of the track that a media player is playing, with the artist and album, and
puts the previous image back when the track should be over.


The cover of the media player is sent to the engine and tried first. If it is missing or
unusable, the engine looks one up itself (Deezer, then MusicBrainz / Cover Art Archive).
Turn off "Send the player's cover" to always let the engine look it up. The picture of a
media player is a Home Assistant address, so the engine must be able to reach Home
Assistant's internal URL (Settings > System > Network).


Sending the same album again only extends its time on the frame, so it is safe that this
runs on every track change.
domain: automation
source_url: https://github.com/ant1fr/Smart-Frame-Engine-HA/blob/main/blueprints/automation/smart_frame_engine/now_playing_cover.yaml
author: ant1fr
homeassistant:
min_version: 2026.1.0
input:
media_player:
name: Media player
description: The player whose music is shown.
selector:
entity:
filter:
domain: media_player
send_artwork:
name: Send the player's cover
description: >-
On: the player's cover is tried first, and the engine's lookup is the safety net. Off:
the engine always looks the cover up itself.
default: true
selector:
boolean:
style:
name: Style
default: ""
selector:
select:
options:
- label: Engine default
value: ""
- label: Sleeve
value: sleeve
- label: Vinyl record
value: vinyl
show_title:
name: Print the track title
description: >-
Without the title, every track of the same album shares one picture, so the frame is
only refreshed when the album changes.
default: ""
selector:
select:
options:
- label: Engine default
value: ""
- label: "Yes"
value: "yes"
- label: "No"
value: "no"
hold_minutes:
name: Protect from refresh
description: >-
Minutes during which scheduled refreshes will not replace the cover. 0 means the
engine's default.
default: 0
selector:
number:
min: 0
max: 10080
mode: box
unit_of_measurement: min
ttl_seconds:
name: Duration
description: >-
Seconds before the previous image returns. 0 means it is worked out from the length of
the track.
default: 0
selector:
number:
min: 0
max: 86400
mode: box
unit_of_measurement: s
engine:
name: Smart Frame Engine
description: Only needed when you have several engines. Leave empty otherwise.
default: ""
selector:
config_entry:
integration: smart_frame_engine

# The latest track wins.
mode: restart
max_exceeded: silent

variables:
media_player: !input media_player
send_artwork: !input send_artwork
style: !input style
show_title: !input show_title
hold_minutes: !input hold_minutes
ttl_seconds: !input ttl_seconds
engine: !input engine

triggers:
- trigger: state
entity_id: !input media_player
to: playing
id: started
# Changes while playing. Position updates are not listened to: they come every few seconds.
- trigger: state
entity_id: !input media_player
attribute: media_title
id: title

conditions:
- condition: template
value_template: "{{ is_state(media_player, 'playing') }}"
# Starting playback with a new title fires both triggers: count it once, as 'started'.
- condition: template
value_template: "{{ trigger.id == 'started' or trigger.from_state.state == 'playing' }}"
# Radio streams and some sources report no artist: there is nothing to show then.
- condition: template
value_template: "{{ (state_attr(media_player, 'media_artist') or '') | string | trim != '' }}"

actions:
- alias: Show the cover
action: smart_frame_engine.show_now_playing
data: >-
{{ dict({
'config_entry_id': engine,
'media_player': media_player,
'use_media_player_picture': send_artwork,
'style': style,
'show_title': ((show_title == 'yes') if show_title else none),
'hold_minutes': hold_minutes or none,
'ttl_seconds': ttl_seconds or none,
}.items() | rejectattr('1', 'in', ['', none]) | list) }}
Loading
Loading