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
21 changes: 21 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,27 @@ jobs:
- name: Checkout
uses: actions/checkout@v7

# The tag (v1.0.0-rc.2) and pyproject.toml (1.0.0rc2) spell the same release differently;
# compare them as versions so a forgotten bump can't ship an image showing another version.
- name: Check the tag matches pyproject.toml
run: |
python3 - <<'PY'
import os, re, tomllib

def normalize(version: str) -> str:
"""Reduce SemVer (1.0.0-rc.2) and PEP 440 (1.0.0rc2) to one spelling."""
version = version.lstrip("v").split("+")[0]
version = re.sub(r"[-.]?(alpha|a)[-.]?(\d+)", r"a\2", version)
version = re.sub(r"[-.]?(beta|b)[-.]?(\d+)", r"b\2", version)
return re.sub(r"[-.]?rc[-.]?(\d+)", r"rc\1", version)

tag = os.environ["GITHUB_REF_NAME"]
declared = tomllib.load(open("pyproject.toml", "rb"))["project"]["version"]
if normalize(tag) != normalize(declared):
raise SystemExit(f"Tag {tag} does not match pyproject.toml version {declared}")
print(f"Tag {tag} matches pyproject.toml version {declared}")
PY

- name: Compute image name (registry paths must be lowercase)
run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"

Expand Down
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.
5 changes: 5 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,11 @@ RUN pip install --no-deps .
ENV NUMBA_CACHE_DIR=/app/.numba_cache
RUN mkdir -p /app/.numba_cache && chown app:app /app/.numba_cache

# Marks images built outside a release tag (``+<build>`` after the version in the UI); empty for
# release images. Declared late so changing it never invalidates the layers above.
ARG APP_BUILD=""
ENV APP_BUILD=${APP_BUILD}

USER app
RUN python -c "from app.processor.dither import warm_up; warm_up()"
VOLUME ["/data"]
Expand Down
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
9 changes: 8 additions & 1 deletion app/api/routes/system.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
from app.services.delivery import FrameTelemetry, LastDelivery, PendingUpload
from app.services.ephemeral import EphemeralView
from app.services.scheduler import SchedulerSnapshot
from app.version import release_label

router = APIRouter(prefix="/api", tags=["system"])

Expand Down Expand Up @@ -83,7 +84,12 @@ class ServiceConfigured(BaseModel):
class StatusResponse(BaseModel):
"""Overall system status."""

version: str
version: str = Field(description="Engine version (PEP 440, same as /api/health)")
release: str = Field(
description="Version as spelled by the git tag and the Docker image tag (SemVer, e.g. "
"1.0.0-rc.2), with +<build> appended for images built outside a release tag; "
"informational, for display only"
)
uptime_s: float
auth_enabled: bool
auth_mode: str = Field(description="open, key (API key only) or password (admin login)")
Expand Down Expand Up @@ -131,6 +137,7 @@ async def status(
started_at: float = request.app.state.started_at
return StatusResponse(
version=__version__,
release=release_label(),
uptime_s=round(time.monotonic() - started_at, 1),
auth_enabled=auth.mode != "open",
auth_mode=auth.mode,
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
3 changes: 2 additions & 1 deletion app/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@
from app.services.ephemeral import EphemeralService
from app.services.now_playing import NowPlayingService
from app.services.scheduler import SchedulerService, immich_runner, tmdb_runner
from app.version import release_label

logger = logging.getLogger(__name__)

Expand Down Expand Up @@ -217,7 +218,7 @@ async def _on_config_change(_: RuntimeConfig) -> None:
logger.info(
"Smart Frame Engine %s started (instance=%s, data_dir=%s, auth=%s, root_path=%r, "
"panel=%s, power_mode=%s, pending=%s, scheduler=%s)",
__version__,
release_label(),
identity.instance_id,
settings.data_dir,
auth_state.mode,
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",
)
Loading