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
5 changes: 4 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,7 @@ pytest

Providers live in `app/providers/`. Implement the provider base class, return an `ImageAsset`,
register it where the existing providers are wired in `app/main.py`, and add tests next to the
existing provider tests. Open a *Feature request* first if you want to discuss the design.
existing provider tests. To make the source usable in Smart Mix, describe the rules it accepts in
`app/providers/<name>/rule_spec.py` (see `immich_rule_spec()`) and add it to `default_catalog()`
in `app/services/rule_catalog.py`: the Smart Mix editor builds its form from that descriptor, and
`tests/test_rule_catalog.py` checks it against your request model. Open a *Feature request* first if you want to discuss the design.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,8 @@ Want it to refresh by itself? Turn on the scheduler in *Settings → Frame & sch

- **Smart Mix**: a weighted playlist ("60% family, 25% travel, 15% movie posters") for
scheduled refreshes, plus **Random Discovery** that occasionally digs up a forgotten photo.
Entries are built from friendly presets and forms (people, albums, themes, posters...): no
JSON to write.
- **Ambient context**: Home Assistant can say who is home, the weather or the season; the engine
leans the playlist that way for a while, then forgets on its own.
- **Battery frames**: in deep-sleep mode, new pictures wait in a queue and are delivered the
Expand Down
26 changes: 26 additions & 0 deletions app/api/routes/smart_mix.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
from app.providers.immich.models import ImmichDisplayRequest, MatchMode, OnThisDay
from app.providers.tmdb.models import TmdbDisplayRequest
from app.services.display import DisplayResult
from app.services.rule_catalog import Placeholder, RuleKindSpec, default_catalog, placeholders
from app.services.scheduler import ContextView, validation_summary
from app.services.smart_mix import DEFAULT_CONTEXT_WEIGHT, MixContext

Expand Down Expand Up @@ -245,6 +246,31 @@ async def clear_context(scheduler: SchedulerDep) -> ClearedResponse:
return ClearedResponse(cleared=had)


# --- Rule editor catalog ---------------------------------------------------------------
class RuleKindsResponse(BaseModel):
"""What each source kind accepts, for building a rule editor."""

kinds: list[RuleKindSpec] = Field(
description="Descriptor of every runnable source kind that has one; a kind listed in "
"supported_kinds of GET /api/smart-mix but missing here can only be edited as raw params"
)
placeholders: list[Placeholder] = Field(
description="{name} placeholders a rule's text may contain, expanded on every run"
)


@router.get(
"/kinds",
response_model=RuleKindsResponse,
summary="Describe the rules each source kind accepts",
)
async def get_rule_kinds(scheduler: SchedulerDep) -> RuleKindsResponse:
"""Fields, choices, presets and summary recipe of each source kind (providers own them)."""
runnable = set(scheduler.supported_kinds)
kinds = [spec for spec in default_catalog().all() if spec.kind in runnable]
return RuleKindsResponse(kinds=kinds, placeholders=placeholders())


# --- Inspection ------------------------------------------------------------------------
class MixEntryView(BaseModel):
index: int
Expand Down
1 change: 1 addition & 0 deletions app/core/contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
"random_discovery": ("PUT", "/api/config"),
"smart_mix": ("GET", "/api/smart-mix"),
"smart_mix_context": ("POST", "/api/smart-mix/context"),
"smart_mix_kinds": ("GET", "/api/smart-mix/kinds"),
"title_card": ("POST", "/api/display/title-card"),
"upload_image": ("POST", "/api/display/upload"),
}
Expand Down
203 changes: 203 additions & 0 deletions app/providers/immich/rule_spec.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
"""How an Immich rule is presented in the Smart Mix editor (see ``app/services/rule_catalog.py``).

The keys are fields of ``ImmichDisplayRequest``; ``tests/test_rule_catalog.py`` keeps them in sync.
"""

from __future__ import annotations

from app.services.rule_catalog import (
Condition,
FieldSpec,
Option,
Preset,
RuleKindSpec,
SummaryPart,
)


def _mode_is(*modes: str) -> Condition:
return Condition(field="mode", any_of=list(modes))


def immich_rule_spec() -> RuleKindSpec:
"""Descriptor of the ``immich`` source kind."""
return RuleKindSpec(
kind="immich",
label="Immich photos",
description="Photos from your Immich libraries, filtered by people, album or theme.",
icon="🖼️",
service="immich",
fields=[
FieldSpec(
key="mode",
label="Pick photos from",
widget="segmented",
default="random",
options=[
Option(value="random", label="Anywhere", help="Any photo matching the filters"),
Option(value="favorites", label="Favorites", help="Photos you starred"),
Option(value="album", label="An album"),
Option(value="search", label="A theme", help="Describe it, e.g. a beach"),
],
),
FieldSpec(
key="album_name",
label="Album",
widget="album",
help="Photos are picked from this album.",
show_when=[_mode_is("album")],
required_when=[_mode_is("album")],
),
FieldSpec(
key="clip_queries",
label="Themes",
widget="text_list",
help="Describe what you want to see; a photo matching any phrase can be picked. "
"Placeholders such as {season} follow the calendar.",
placeholder="e.g. {season} landscape",
show_when=[_mode_is("search")],
required_when=[_mode_is("search")],
max=10,
),
FieldSpec(
key="persons",
label="People",
widget="person_list",
help="Only photos with these people. Leave empty to use the people chosen in "
"Settings > Immich.",
),
FieldSpec(
key="match_mode",
label="Photos must show",
widget="segmented",
nullable=True,
options=[
Option(value="any", label="Any of them"),
Option(value="all", label="All of them"),
],
show_when=[Condition(field="persons", filled=True)],
),
FieldSpec(
key="on_this_day",
label="On this day",
widget="on_this_day",
help="Memories: photos taken around today's date in previous years.",
show_when=[
Condition(field="taken_after", filled=False),
Condition(field="taken_before", filled=False),
],
),
FieldSpec(
key="taken_after",
label="Taken after",
widget="date",
time="00:00:00",
group="advanced",
show_when=[Condition(field="on_this_day", filled=False)],
),
FieldSpec(
key="taken_before",
label="Taken before",
widget="date",
time="23:59:59",
group="advanced",
show_when=[Condition(field="on_this_day", filled=False)],
),
FieldSpec(
key="accounts",
label="Immich accounts",
widget="account_list",
help="Limit the selection to these accounts. Leave empty for all of them.",
group="advanced",
),
FieldSpec(
key="always_include",
label="Always include",
widget="person_list",
help="People added to every selection. Leave empty to use Settings > Immich.",
group="advanced",
),
FieldSpec(
key="whole_library",
label="Ignore the default filters",
widget="bool",
help="Do not apply the people, album and favorites chosen in Settings > Immich.",
group="advanced",
),
FieldSpec(
key="fit",
label="Framing",
widget="segmented",
nullable=True,
group="advanced",
options=[
Option(value="smart_crop", label="Smart crop", help="Fill the frame"),
Option(value="contain", label="Whole photo", help="Never cropped"),
],
),
],
presets=[
Preset(
id="favorites",
label="Favorites",
description="Photos you starred in Immich.",
icon="⭐",
params={"mode": "favorites"},
),
Preset(
id="on-this-day",
label="On this day",
description="Photos taken around today's date in previous years.",
icon="📅",
params={"on_this_day": {}},
weight=2.0,
),
Preset(
id="person",
label="A person",
description="Photos of one or more people.",
icon="🧑",
params={"mode": "random", "persons": []},
edit_first=True,
),
Preset(
id="album",
label="An album",
description="Photos from one album.",
icon="📚",
params={"mode": "album"},
edit_first=True,
),
Preset(
id="theme",
label="A theme",
description="Photos matching a description, such as a beach or snow.",
icon="🔎",
params={"mode": "search", "clip_queries": ["beach vacation"]},
edit_first=True,
),
Preset(
id="season",
label="Photos of the season",
description="Landscapes that follow the calendar: spring, summer, autumn, winter.",
icon="🍂",
params={"mode": "search", "clip_queries": ["{season} landscape"]},
),
Preset(
id="whole-library",
label="Whole library",
description="Any photo, ignoring the default people, album and favorites filters.",
icon="🌍",
params={"mode": "random", "whole_library": True},
),
],
summary=[
SummaryPart(template="Favorites", when=[_mode_is("favorites")]),
SummaryPart(template="Album: {value}", field="album_name", when=[_mode_is("album")]),
SummaryPart(template="Theme: {value}", field="clip_queries", when=[_mode_is("search")]),
SummaryPart(template="People: {value}", field="persons"),
SummaryPart(template="On this day", field="on_this_day"),
SummaryPart(template="Whole library", field="whole_library"),
],
summary_fallback="Any photo",
)
97 changes: 97 additions & 0 deletions app/providers/tmdb/rule_spec.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
"""How a TMDB rule is presented in the Smart Mix editor (see ``app/services/rule_catalog.py``).

The keys are fields of ``TmdbRequest``; ``tests/test_rule_catalog.py`` keeps them in sync. Only
the lookup is stored in a rule: the scheduler never replays the fallback picture or the
ephemeral settings of a direct push.
"""

from __future__ import annotations

from app.services.rule_catalog import (
Condition,
FieldSpec,
Option,
Preset,
RuleKindSpec,
SummaryPart,
)


def tmdb_rule_spec() -> RuleKindSpec:
"""Descriptor of the ``tmdb`` source kind."""
return RuleKindSpec(
kind="tmdb",
label="Movie & TV posters",
description="The HD poster of a movie or series from TMDB, shown whole (never cropped).",
icon="🎬",
service="tmdb",
fields=[
FieldSpec(
key="query",
label="Title",
widget="text",
required=True,
placeholder="e.g. Blade Runner",
),
FieldSpec(
key="media_type",
label="Look for",
widget="segmented",
default="multi",
options=[
Option(value="multi", label="Movie or series"),
Option(value="movie", label="Movie"),
Option(value="tv", label="TV series"),
],
),
FieldSpec(
key="year",
label="Year",
widget="int",
help="Release year, to tell remakes apart. Optional.",
min=1870,
max=2200,
),
FieldSpec(
key="season",
label="Season",
widget="int",
help="Prefer the poster of this season. Optional.",
min=0,
max=100,
show_when=[Condition(field="media_type", any_of=["tv", "multi", None])],
),
FieldSpec(
key="language",
label="Poster language",
widget="text",
help="Overrides the language set in Settings > TMDB, e.g. fr-FR or en-US.",
placeholder="Default",
group="advanced",
),
],
presets=[
Preset(
id="movie",
label="A movie poster",
description="The poster of one movie.",
icon="🎞️",
params={"query": "Blade Runner", "media_type": "movie"},
edit_first=True,
),
Preset(
id="series",
label="A series poster",
description="The poster of a series, optionally of one season.",
icon="📺",
params={"query": "Severance", "media_type": "tv", "season": 1},
edit_first=True,
),
],
summary=[
SummaryPart(template="{value}", field="query"),
SummaryPart(template="{value}", field="year"),
SummaryPart(template="Season {value}", field="season"),
],
summary_fallback="Poster (no title yet)",
)
Loading