E-paper photo frames

Everlock turns any album into the picture source for a battery-powered e-paper photo frame. The frame wakes up on its schedule, asks your instance for one picture, shows it, and goes back to sleep — no cloud account and no extra server. Months of battery life, and the photos never leave your own machine.

The frame

Everlock speaks the protocol of the open-source esp32-photoframe project: an ESP32 driving a color (Spectra 6) or grayscale e-paper panel, available as a DIY build with off-the-shelf parts. Firmware, hardware notes, and a web-based installer live in the project's repository.

How it works

Each time the frame checks in, Everlock picks a random photo from the album — never the one currently on display — and renders it for that exact panel: resized and cropped to the panel's dimensions and orientation, dithered against the panel's real measured colors, and delivered in the display's native format so the frame doesn't have to do any image processing of its own. That is what keeps the battery alive: the device downloads, blits, and sleeps. If nothing new is available, the answer is "nothing changed" and the panel doesn't even refresh.

HEIC photos from an iPhone, camera JPEGs, PNGs — anything in the album works; conversion happens on the server. Opening the frame's URL in a browser shows the picture the frame would get.

Setup

Create an album and put photos in it — the frame follows the album from then on, so adding pictures later just works.
Share the album (read access). The share link contains a key of the form evapi_… — this is the frame's credential. It can see this one album and nothing else, and you can revoke it at any time.

In the frame's settings, set the image source:

image url:    https://photos.example.org/album/<album-id>/photoframe
access token: evapi_<key from the share link>

That's all. The rotation interval, orientation, and image tuning (tone curve, saturation, dithering) are configured on the frame itself — Everlock picks the device's settings up automatically with every fetch.

Captions

A frame can ask for a caption drawn into the picture: the X-Subtitle-Template request header carries a Handlebars template, and Everlock renders the resulting text into the bottom-left corner of every served frame — with a drop shadow, and text colors picked for contrast against the photo behind it, so the caption stays readable on light and dark pictures alike.

X-Subtitle-Template: {{year}} {{location}}

The template renders against the photo being served:

Variable	Value
`{{year}}` `{{month}}` `{{day}}`	The capture date, in the photo's local timezone
`{{date}}`	The capture date as `YYYY-MM-DD`
`{{location}}`	The photo's location, as filled in by AI enrichment
`{{description}}`	The photo's description
`{{name}}`	The original file name

Absent values render as empty text, and a caption that comes out empty leaves the picture untouched — a photo without a location under the template above simply shows its year. The caption scales with the panel and is dithered along with the photo, so it renders crisply on color and grayscale panels alike.