Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
110 commits
Select commit Hold shift + click to select a range
6207303
chore: add pyproject, tooling config and package skeleton
ant1fr Nov 14, 2026
2841f49
feat: add environment settings and runtime config models
ant1fr Nov 14, 2026
fb41e3c
feat: add atomic JSON persistence for config and history
ant1fr Nov 14, 2026
a63d4e5
feat: add API key auth, root path and log masking middleware
ant1fr Nov 14, 2026
aef4dc0
feat: add app factory with config, health and status endpoints
ant1fr Nov 14, 2026
ec68533
feat: add URL, upload size and image validation helpers
ant1fr Nov 14, 2026
2dace08
test: cover settings, stores, auth, security and root path
ant1fr Nov 14, 2026
252a712
chore(docker): add Dockerfile, docker-compose and .env.example
ant1fr Nov 14, 2026
4d5940d
chore(ci): add lint/test workflow and multi-arch release workflow
ant1fr Nov 14, 2026
b7c9e5f
Merge pull request #1 from ant1fr/feat/core-setup
ant1fr Nov 14, 2026
4ad92a7
refactor: extract atomic file writes and add queue directory
ant1fr Nov 14, 2026
85e2fdd
feat: add Spectra 6 palette with official tuned color metric
ant1fr Nov 14, 2026
6afe793
feat: add vectorized wavefront Atkinson and Floyd-Steinberg dithering
ant1fr Nov 14, 2026
b102e37
feat: add EL133UF1 and EL315 bin packing
ant1fr Nov 14, 2026
c81e6ad
feat: add fit modes, eInk enhancement and render pipeline
ant1fr Nov 14, 2026
c897166
feat: add current image cache store
ant1fr Nov 14, 2026
20d04ce
feat: add async Fraimic LAN client
ant1fr Nov 14, 2026
3ca9df2
feat: add delivery service with deepsleep queue and wakeup worker
ant1fr Nov 14, 2026
65e7eaa
fix: encode dithered preview as an indexed PNG
ant1fr Nov 14, 2026
bce259d
fix: refresh frame telemetry only on the periodic timer
ant1fr Nov 14, 2026
d305f5f
feat: add display upload, current image, fraimic and status endpoints
ant1fr Nov 14, 2026
f39d4ad
docs: document Fraimic endpoints, queue layout and Docker mDNS caveat
ant1fr Nov 14, 2026
cd6614b
fix: keep match_palette typed under NumPy 2.4 stubs
ant1fr Nov 14, 2026
be14c5f
Merge pull request #2 from ant1fr/feat/eink-fraimic
ant1fr Nov 14, 2026
34cc63a
fix: rotate before dithering so landscape matches the official converter
ant1fr Nov 14, 2026
06619aa
feat: add display.safe_margin_px inset for frame mats
ant1fr Nov 14, 2026
ef43b16
feat: add spread guard and padding for focus regions in smart_crop
ant1fr Nov 14, 2026
6bcf408
feat: add Immich accounts config with masked secrets
ant1fr Nov 14, 2026
580e53a
feat: decode HEIC/HEIF images via pillow-heif
ant1fr Nov 14, 2026
ee9312f
feat: add Immich provider with multi-account selection and face regions
ant1fr Nov 14, 2026
745c00a
feat: add Immich display, albums and people endpoints
ant1fr Nov 14, 2026
3ff77aa
docs: document Immich provider, accounts, aliases and safe margin
ant1fr Nov 14, 2026
6c10bb9
fix: reschedule the delivery worker after a failed attempt
ant1fr Nov 14, 2026
0abe855
feat: add eink.profile with a softer photo preset
ant1fr Nov 14, 2026
fe8b37e
Merge pull request #3 from ant1fr/feat/immich-core
ant1fr Nov 14, 2026
f3f4562
feat: persist taken_at in the history and detect bursts
ant1fr Nov 14, 2026
3eb39d7
feat: add photo quality gate rules with progressive relaxation
ant1fr Nov 14, 2026
179fb6a
feat: vet Immich photos with the quality gate and a burst cooldown
ant1fr Nov 14, 2026
5337e80
feat: give the burst cooldown its own memory (burst_cooldown_days)
ant1fr Nov 14, 2026
f5d5b52
Merge pull request #4 from ant1fr/feat/quality-gate
ant1fr Nov 14, 2026
3a29c8f
feat: add quiet-hours planning for the scheduler
ant1fr Nov 14, 2026
65cb3e1
feat: add scheduler options and quiet-hours env seeds
ant1fr Nov 14, 2026
9e1f425
feat: add scheduler service with persisted state and APScheduler timer
ant1fr Nov 14, 2026
758d80f
feat: add POST /api/refresh and record manual displays
ant1fr Nov 14, 2026
4526cd4
feat: expose scheduler state in /api/status
ant1fr Nov 14, 2026
ce3de2e
docs: document the scheduler, quiet hours and refresh
ant1fr Nov 14, 2026
4764b39
Merge pull request #5 from ant1fr/feat/scheduler
ant1fr Nov 15, 2026
078c274
feat: add date filters and on_this_day to Immich search
ant1fr Nov 15, 2026
7798fb8
feat: add context placeholders for source rules
ant1fr Nov 15, 2026
f75647b
feat: add smart_mix config section
ant1fr Nov 15, 2026
236eefe
feat: resolve weighted smart mix in scheduler with re-roll
ant1fr Nov 15, 2026
25c3186
feat: add ephemeral and hold to direct pushes
ant1fr Nov 15, 2026
3ccb3a2
feat: add smart-search and smart-mix context endpoints
ant1fr Nov 15, 2026
6003c36
docs: document smart mix and Home Assistant examples
ant1fr Nov 15, 2026
df40f62
Merge pull request #6 from ant1fr/feat/smart-mix
ant1fr Nov 15, 2026
1ae549c
feat: add typography and no-crop composition templates
ant1fr Nov 15, 2026
1a71c54
feat: add expiry and cancellation to the delivery queue
ant1fr Nov 15, 2026
810c399
feat: add base and preview image slots
ant1fr Nov 15, 2026
ceeca7b
feat: revert expired ephemeral images and add queue endpoints
ant1fr Nov 15, 2026
18cf860
feat: add TMDB provider with regional poster ranking
ant1fr Nov 15, 2026
4a0ac32
feat: add TMDB display endpoint and scheduler runner
ant1fr Nov 15, 2026
7881f80
feat: add Deezer and MusicBrainz artwork lookup
ant1fr Nov 15, 2026
ee68c50
feat: add now-playing display endpoint
ant1fr Nov 15, 2026
22655d2
fix: prefer studio album covers in MusicBrainz recording lookups
ant1fr Nov 15, 2026
9b01896
docs: document ephemeral queue, templates, TMDB and now-playing
ant1fr Nov 15, 2026
904df25
Merge pull request #7 from ant1fr/feat/ephemeral-templates
ant1fr Nov 15, 2026
8625fb4
fix: match album covers more reliably
ant1fr Nov 15, 2026
fff4cc9
fix: keep the vinyl record visible on dark backgrounds
ant1fr Nov 15, 2026
4c6b802
Merge pull request #8 from ant1fr/fix/artwork-matching
ant1fr Nov 15, 2026
d80e9e6
fix: skip edge sharpening on enlarged artwork
ant1fr Nov 15, 2026
f212123
fix: download TMDB posters at the resolution the frame needs
ant1fr Nov 15, 2026
03974d5
fix: request album covers at full quality for their on-panel size
ant1fr Nov 15, 2026
1432546
chore: add a template sample rendering script
ant1fr Nov 15, 2026
e958d42
Merge pull request #9 from ant1fr/fix/high-res-artwork
ant1fr Nov 15, 2026
412e687
chore: add a four-frame preview gallery script
ant1fr Nov 15, 2026
067d161
Merge pull request #10 from ant1fr/chore/preview-gallery
ant1fr Nov 15, 2026
58010af
feat: choose the eInk profile and dithering automatically
ant1fr Nov 15, 2026
8684943
feat: verify every .bin against the panel specification
ant1fr Nov 15, 2026
a060afd
docs: add the A/B script, prewarm numba and document the automatic look
ant1fr Nov 15, 2026
91107f1
fix: tune the automatic profile rules after the A/B review
ant1fr Nov 15, 2026
a73738c
Merge pull request #12 from ant1fr/feat/spectra-image-quality
ant1fr Nov 15, 2026
e212e89
fix: prefer the studio album over a single with the same title on Mus…
ant1fr Nov 15, 2026
c41c242
Merge pull request #13 from ant1fr/fix/musicbrainz-album-over-single
ant1fr Nov 15, 2026
ef22fa6
feat: add an admin login, session cookies and API key management
ant1fr Nov 15, 2026
bb58d31
docs: document the admin login, API key handling and port 8080
ant1fr Nov 15, 2026
a361765
Merge pull request #14 from ant1fr/feat/web-ui-auth
ant1fr Nov 15, 2026
b542cee
feat: add the web UI dashboard, playground and settings
ant1fr Nov 15, 2026
f039b34
Merge pull request #15 from ant1fr/feat/web-ui
ant1fr Nov 15, 2026
8f9d561
feat: add Family Mode, Random Discovery, ambient context and Zeroconf
ant1fr Nov 15, 2026
b0a9b6f
Merge pull request #16 from ant1fr/feat/ambient-context
ant1fr Nov 15, 2026
c1517b4
chore: add a Portainer stack file with host port, data path and user …
ant1fr Nov 15, 2026
bdfb108
Merge pull request #17 from ant1fr/chore/portainer-stack
ant1fr Nov 15, 2026
72ed576
fix: probe the frame on first dashboard load and add a Check now button
ant1fr Nov 15, 2026
833ae73
fix: stop buttons rendering disabled before their first use
ant1fr Nov 15, 2026
da15ff9
Merge pull request #18 from ant1fr/fix/frame-check
ant1fr Nov 15, 2026
fc62ca5
Merge pull request #19 from ant1fr/fix/disabled-buttons
ant1fr Nov 15, 2026
1a4b7b9
feat: make the track title optional on now-playing covers
ant1fr Nov 18, 2026
4915967
fix: stop the web UI from scrolling horizontally on phones
ant1fr Nov 18, 2026
7f420c1
Merge pull request #20 from ant1fr/feat/music-album-dedup
ant1fr Nov 18, 2026
111070f
Merge pull request #21 from ant1fr/fix/mobile-overflow
ant1fr Nov 18, 2026
0e5f253
chore: add the release pipeline, production compose, community files …
ant1fr Nov 18, 2026
29ae0b8
docs: credit the Stillroom converter to its actual author
ant1fr Nov 18, 2026
0c0fd5b
docs: point the roadmap to the GitHub Project board
ant1fr Nov 18, 2026
582d5d0
Merge pull request #22 from ant1fr/chore/release-pipeline
ant1fr Nov 18, 2026
0b3c03f
fix: derive the session signing key without a bare password hash
ant1fr Nov 18, 2026
a411ffe
Merge pull request #35 from ant1fr/fix/session-key-derivation
ant1fr Nov 18, 2026
218ecb1
fix: derive the session signing key with a cached PBKDF2
ant1fr Nov 18, 2026
b512b34
Merge pull request #36 from ant1fr/fix/session-key-kdf
ant1fr Nov 18, 2026
8cbc24b
feat: add the API compatibility contract and capability discovery
ant1fr Nov 19, 2026
8a0b6e0
Merge pull request #37 from ant1fr/feat/api-compatibility-contract
ant1fr Nov 19, 2026
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
26 changes: 26 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
.git
.github
.gitignore
.gitattributes
.dockerignore
.env
.env.*
.venv
venv
data
fraimic-docs
tests
**/__pycache__
**/*.py[cod]
*.egg-info
build
dist
.pytest_cache
.ruff_cache
.mypy_cache
.coverage
.idea
.vscode
docker-compose.yml
Dockerfile
CLAUDE.md
112 changes: 112 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# =============================================================================
# Smart Frame Engine - environment configuration
# Copy to `.env` and adjust. Never commit your real `.env`.
#
# Runtime settings (Immich, TMDB, Fraimic, display, eInk, scheduler) can also be
# edited from the web UI / `PUT /api/config`. Values saved there are stored in
# /data/config.json and take precedence over this file. Use
# `POST /api/config/reset` to fall back to the values below again.
# =============================================================================

# --- Docker Compose (host side) ----------------------------------------------
# Read by docker-compose.yml itself, not by the app. In Portainer / Synology Container
# Manager, define them as stack environment variables instead of using this file.
# Host port published by Compose (the container always listens on 8080 inside).
HOST_PORT=8080
# Where the persistent /data lives: a host folder (bind mount, e.g. /volume1/docker/smart-frame
# on a Synology NAS) or a Docker volume name (default: smart-frame-data). Create a host folder
# first and give it to PUID:PGID. The container itself always uses /data.
DATA_DIR=smart-frame-data
# Owner of a bind-mounted DATA_DIR (run `id -u` / `id -g` on the host).
PUID=1000
PGID=1000

# --- Security ----------------------------------------------------------------
# Password of the "admin" web UI login. When set, every route except /api/health, the
# login and the public images needs a login session or the API key, and an API key is
# generated into /data/secrets.json if APP_API_KEY is empty (shown in the UI).
# Leave empty (with APP_API_KEY empty too) for pure LAN usage without authentication.
ADMIN_PASSWORD=
# API key for Home Assistant and other clients: X-API-Key header,
# "Authorization: Bearer <key>" or ?api_key=. Optional when ADMIN_PASSWORD is set (a key is
# generated and can be regenerated from the UI); setting it here pins it.
# Without ADMIN_PASSWORD, all POST/PUT/DELETE routes and /api/config require it.
# Generate one with: openssl rand -hex 32
APP_API_KEY=
# Lifetime of a web UI login, in hours (default one week).
SESSION_TTL_HOURS=168
# Optional key signing the login cookies (generated into /data/secrets.json if empty).
SESSION_SECRET=
# Keep /api/current.jpg, /api/current.bin and /api/preview.jpg readable without a key
# (needed by Home Assistant Generic Camera). Set to false to require ?api_key=.
PUBLIC_IMAGE_ENDPOINTS=true
# Advertise _smartframe._tcp.local. over mDNS (Docker needs network_mode: host for it).
ZEROCONF_ENABLED=true
# Max size of uploaded/downloaded images, in MB.
MAX_UPLOAD_MB=20
# Reject external image URLs (posters, album covers, Home Assistant pictures) resolving to
# private/loopback/link-local addresses; every redirect target is checked too.
BLOCK_PRIVATE_URLS=false
# Comma-separated hosts or CIDRs allowed even when BLOCK_PRIVATE_URLS=true,
# e.g. homeassistant.local,192.168.1.0/24
URL_ALLOWLIST=

# --- Reverse proxy -----------------------------------------------------------
# Sub-path when served behind a proxy, e.g. /fraimic (empty = served at /).
ROOT_PATH=
# Comma-separated allowed CORS origins (* = any).
CORS_ORIGINS=*
# Proxy IPs trusted for X-Forwarded-Proto / X-Forwarded-For (* = any).
FORWARDED_ALLOW_IPS=*

# --- Server ------------------------------------------------------------------
LOG_LEVEL=INFO
# Container-internal port; change HOST_PORT instead when using Docker Compose
# (only needed with network_mode: host, where the engine listens on it directly).
# PORT=8080

# --- Immich (runtime default) ------------------------------------------------
# Seeds one Immich account named "default". Add more accounts (a partner, a shared
# library) under immich.accounts in the settings / PUT /api/config.
# A LAN address needs URL_ALLOWLIST when BLOCK_PRIVATE_URLS=true.
IMMICH_URL=http://immich.local:2283
IMMICH_API_KEY=

# --- TMDB movie & TV posters (runtime default) -------------------------------
# A v3 API key or a v4 read access token (https://www.themoviedb.org/settings/api).
# Without it, POST /api/display/tmdb falls back to the Home Assistant picture, to
# /data/assets/tmdb_fallback.png, then to a title card.
TMDB_API_KEY=
# Poster language and region, e.g. fr-FR or en-US: regional posters are preferred, then
# the same language, textless artwork and English.
TMDB_LANGUAGE=fr-FR

# --- Fraimic frame (runtime default) -----------------------------------------
# Hostname, IP or base URL of the frame (see fraimic.local/info for its IP).
# Inside Docker, .local (mDNS) names usually do NOT resolve on the default bridge
# network: use the frame's IP address and give it a DHCP reservation.
FRAIMIC_HOST=fraimic.local
# continuous = mains powered, always reachable
# deepsleep = battery powered, uploads are queued until the frame wakes up
FRAIMIC_POWER_MODE=continuous
# 133 = 13.3" (1200x1600), 315 = 31.5" (1440x2560)
FRAIMIC_PANEL=133
# portrait | landscape
ORIENTATION=portrait

# --- Smart Mix (runtime default) ---------------------------------------------
# Weighted playlist of source rules for scheduled refreshes (entries are configured in
# smart_mix.entries via the API/UI). A pinned scheduler.source_rule still takes precedence.
SMART_MIX_ENABLED=false

# --- Scheduler (runtime default) ---------------------------------------------
# Replays the active source rule (the pinned scheduler.source_rule, else the last
# manual display) every REFRESH_INTERVAL_HOURS hours. Any display resets the timer.
SCHEDULER_ENABLED=false
REFRESH_INTERVAL_HOURS=6
# Optional no-refresh window in local time (24h HH:MM, may cross midnight). A refresh
# that falls inside runs when the window ends. Leave both empty to disable.
QUIET_HOURS_START=
QUIET_HOURS_END=
# IANA timezone of the quiet hours, e.g. Europe/Paris (containers run in UTC otherwise)
TZ=UTC
12 changes: 12 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Normalize text files to LF in the repository and in Linux containers.
* text=auto eol=lf

# Binary assets
*.png binary
*.jpg binary
*.jpeg binary
*.webp binary
*.gif binary
*.bin binary
*.ttf binary
*.otf binary
46 changes: 46 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Bug report
description: Something does not work as expected
labels: [bug]
body:
- type: markdown
attributes:
value: Thanks for taking the time! Please do not paste API keys, passwords or private IPs.
- type: textarea
id: what
attributes:
label: What happened?
description: What you did, what you expected, what you got (screenshots welcome).
validations:
required: true
- type: textarea
id: repro
attributes:
label: Steps to reproduce
placeholder: "1. Open Settings > Immich ...\n2. ..."
- type: input
id: version
attributes:
label: Smart Frame Engine version
description: Shown in GET /api/status, or the image tag.
validations:
required: true
- type: dropdown
id: install
attributes:
label: How do you run it?
options: [Docker Compose, Portainer, Synology Container Manager, Python (from source), Other]
- type: dropdown
id: power
attributes:
label: Frame power mode
options: [continuous, deepsleep, Not sure / not relevant]
- type: input
id: immich
attributes:
label: Immich version (if relevant)
- type: textarea
id: logs
attributes:
label: Logs
description: "docker logs smart-frame-engine (keys are masked, but check before pasting)."
render: text
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Questions and ideas
url: https://github.com/ant1fr/Smart-Frame-Engine/discussions
about: Ask for help or share a setup in Discussions.
- name: Security vulnerability
url: https://github.com/ant1fr/Smart-Frame-Engine/security/advisories/new
about: Report it privately, not in a public issue.
30 changes: 30 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: Feature request
description: Suggest an idea, a new image source or a new template
labels: [enhancement]
body:
- type: textarea
id: problem
attributes:
label: What are you trying to do?
description: The problem or use case, not only the solution.
validations:
required: true
- type: textarea
id: idea
attributes:
label: What would you like to see?
- type: dropdown
id: area
attributes:
label: Area
options: [Image source (new provider), Template / layout, eInk rendering, Web UI, REST API, Home Assistant, Deployment / Docker, Other]
- type: textarea
id: alternatives
attributes:
label: Alternatives you considered
- type: checkboxes
id: help
attributes:
label: Contribution
options:
- label: I would be happy to help build or test this
12 changes: 12 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
## What and why

<!-- A few lines. Link the issue: "Closes #123". -->

## Checklist

- [ ] Based on `develop`, targeting `develop`
- [ ] The title starts with a Conventional Commit prefix (`feat:`, `fix:`, `docs:`, `chore:`...): it categorizes the release notes
- [ ] `ruff check .`, `ruff format --check .`, `mypy app` and `pytest` pass
- [ ] Tests added or updated
- [ ] Docs updated (README / wiki) when behaviour or settings change
- [ ] No secrets, personal IPs or photos committed
26 changes: 26 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
version: 2
updates:
- package-ecosystem: pip
directory: /
target-branch: develop
schedule:
interval: weekly
groups:
python-dependencies:
patterns: ["*"]
labels: [dependencies]
- package-ecosystem: docker
directory: /
target-branch: develop
schedule:
interval: weekly
labels: [dependencies]
- package-ecosystem: github-actions
directory: /
target-branch: develop
schedule:
interval: weekly
groups:
github-actions:
patterns: ["*"]
labels: [dependencies]
20 changes: 20 additions & 0 deletions .github/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Categories of the auto-generated release notes (gh release create --generate-notes).
# Pull requests are sorted by label; the Conventional Commit prefix of the title is
# mapped to a label by the PR template checklist.
changelog:
exclude:
labels:
- skip-changelog
authors:
- dependabot
categories:
- title: "✨ Features"
labels: [enhancement, feature, feat]
- title: "🐛 Fixes"
labels: [bug, fix]
- title: "📚 Documentation"
labels: [documentation, docs]
- title: "🔧 Maintenance"
labels: [chore, maintenance, dependencies, ci, refactor]
- title: "Other changes"
labels: ["*"]
Loading