README
¶
Picture Frame
A self-hosted digital picture frame for the Raspberry Pi.
Your photos beside the time, the weather, and the real temperature in your rooms. Motion-aware, private, and plugged into Home Assistant.
It runs as a single static binary that serves both the on-screen kiosk display and a browser admin interface, so you set everything up without re-flashing. It is light enough for a Raspberry Pi Zero W driving an HD screen, and written in Go and Svelte.
Highlights
- Smooth crossfades: fluid fade transitions between photos, even on hardware as modest as a Raspberry Pi Zero W driving an HD display.
- Motion-aware screen power: the panel blanks when the room is empty and wakes on motion. A manual on/off override persists across restarts.
- Your photos, your way: local uploads (cropped in the browser) or a synced Immich album.
- Two-way Home Assistant: publishes sensor and screen state over MQTT with auto-discovery, and lets Home Assistant control the frame.
- Live overlay: a localized clock and date, weather (OpenWeatherMap), and live Bluetooth or MQTT sensor readings, captioned in your own words.
- Built-in Wi-Fi management: including a self-hosted access-point fallback with a captive portal when no known network is in range.
- Local-first: runs entirely on your LAN with no cloud account. The only things that reach the internet are the optional weather feed and clock sync. Add an RTC module and it runs fully offline, even air-gapped.
- Highly customizable: every option is set from the admin interface and saved to a TOML file.
See it in action
https://github.com/user-attachments/assets/cee342a3-6438-43ce-9a11-cfcd60533817
Documentation
The full documentation lives at https://pictureframe.ekemate.hu. It covers installation, a guided tour of the admin interface, and every configuration option. For the engineering notes, see The story & the hard parts.
Install
On a fresh Raspberry Pi OS Trixie Lite, reachable over SSH:
curl -fsSL https://github.com/MateEke/picture-frame/releases/latest/download/install.sh | sudo bash
See the Install guide for the requirements, options, and first setup.
Development
make build # builds the SvelteKit UI and the static ARM binary into dist/
See CONTRIBUTING.md for the development environment and the checks a change
needs to pass, and deploy/README.md for the system-level details behind an
install.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
openapi
command
|
|
|
picture-frame
command
|
|
|
internal
|
|
|
auth
Package auth provides password hashing and signed session cookies for the admin UI.
|
Package auth provides password hashing and signed session cookies for the admin UI. |
|
kioskwatch
Package kioskwatch monitors heartbeats from the kiosk frontend.
|
Package kioskwatch monitors heartbeats from the kiosk frontend. |
|
library/adapter/immich
Package immich implements library.RemoteAlbum against an Immich shared link.
|
Package immich implements library.RemoteAlbum against an Immich shared link. |
|
licenses
Package licenses exposes the aggregated third-party dependency notices, embedded so they are served offline (the frame runs air-gapped).
|
Package licenses exposes the aggregated third-party dependency notices, embedded so they are served offline (the frame runs air-gapped). |
|
mqtt
Package mqtt bridges the state bus to MQTT with Home Assistant auto-discovery: it publishes BLE sensors, a screen intent switch plus a live-power binary_sensor, and routes screen commands back.
|
Package mqtt bridges the state bus to MQTT with Home Assistant auto-discovery: it publishes BLE sensors, a screen intent switch plus a live-power binary_sensor, and routes screen commands back. |
|
mqtt/adapter
Package adapter implements mqtt.Client over eclipse/paho.mqtt.golang.
|
Package adapter implements mqtt.Client over eclipse/paho.mqtt.golang. |
|
redact
Package redact scrubs sensitive details from strings shown in the admin UI.
|
Package redact scrubs sensitive details from strings shown in the admin UI. |
|
sensors/mqttsubscriber
Package mqttsubscriber implements sensors.Source over MQTT state topics.
|
Package mqttsubscriber implements sensors.Source over MQTT state topics. |
|
slideplan
Package slideplan groups an ordered image list into slides: solo images that crop nicely under object-cover, and side-by-side pairs of same-orientation outliers whose aspect is too far from the screen to crop well.
|
Package slideplan groups an ordered image list into slides: solo images that crop nicely under object-cover, and side-by-side pairs of same-orientation outliers whose aspect is too far from the screen to crop well. |
|
startup
Package startup holds the logic-bearing startup helpers extracted from the picture-frame command: config transforms and backend selection that are worth testing in isolation from the binary's process-level wiring.
|
Package startup holds the logic-bearing startup helpers extracted from the picture-frame command: config transforms and backend selection that are worth testing in isolation from the binary's process-level wiring. |
|
testutil
Package testutil provides shared test helpers.
|
Package testutil provides shared test helpers. |
|
updater
Package updater fetches, verifies, and applies signed GitHub release tarballs from the admin UI, with pre-flight and systemd-native rollback.
|
Package updater fetches, verifies, and applies signed GitHub release tarballs from the admin UI, with pre-flight and systemd-native rollback. |
|
updater/adapter
Package adapter holds the updater's external integrations (GitHub release source, HTTP downloader, exec pre-flight).
|
Package adapter holds the updater's external integrations (GitHub release source, HTTP downloader, exec pre-flight). |
|
updater/mock
Package mock simulates the self-updater for development and e2e.
|
Package mock simulates the self-updater for development and e2e. |
|
weather
Package weather polls a provider and publishes conditions to the state bus.
|
Package weather polls a provider and publishes conditions to the state bus. |
|
weather/adapter
Package adapter implements weather.Fetcher backends for external providers.
|
Package adapter implements weather.Fetcher backends for external providers. |
|
weather/mock
Package mock provides a static weather.Fetcher for development and tests.
|
Package mock provides a static weather.Fetcher for development and tests. |
|
wifi
Package wifi manages the WiFi connection and AP fallback for the picture frame.
|
Package wifi manages the WiFi connection and AP fallback for the picture frame. |
|
wifi/mock
Package mock is an in-memory wifi.Manager for development and UI testing: Connect/Forget/Configure mutate held state, touching no real networking.
|
Package mock is an in-memory wifi.Manager for development and UI testing: Connect/Forget/Configure mutate held state, touching no real networking. |
Click to show internal directories.
Click to hide internal directories.