A Fraimic frame uses a Spectra 6 e-ink panel: paper-like, no glare, no backlight, zero power while it shows a picture. But the panel only has six colors (black, white, yellow, red, blue, green), so a photo sent as-is looks muddy.
Smart Frame Engine is the missing piece. It runs quietly on your home server, picks pictures for you, prepares them so they look their best on those six colors, and sends them to the frame:
- 📸 Your Immich photos, chosen for you: favorite people, albums, "on this day"... with a quality filter that skips screenshots, blurry shots, documents and blank frames.
- 🎬 Movie and TV posters in HD (from TMDB) when you start a film, shown whole, never cropped.
- 🎵 Album covers for the music that is playing, with the artist and album underneath.
- 🧠 A smarter eInk pipeline: it chooses the right color profile and dithering per picture, so skin tones, skies and album art all look right.
- 🏠 Home Assistant friendly: show the right thing when you press play, when guests arrive, or when it rains. Or ignore Home Assistant entirely: it also works on its own, on a timer.
- 🔒 Yours alone: self-hosted, no cloud, optional password. Private albums and the Immich Locked Folder never appear on the wall.
You need Docker and the address of your frame. (Immich and TMDB are optional and can be added later, in the web UI.)
mkdir smart-frame && cd smart-frame
curl -fsSLO https://raw.githubusercontent.com/ant1fr/Smart-Frame-Engine/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/ant1fr/Smart-Frame-Engine/main/.env.example -o .env
docker compose up -d- Open http://localhost:8080 (or
http://<your-server>:8080). - Settings → Frame: enter the frame's IP address (give it a fixed IP on your router).
- Settings → Immich: add your server and API key, tick the people or albums you like.
- Press Next photo on the dashboard. 🎉
Want it to refresh by itself? Turn on the scheduler in Settings → Frame & schedule.
Using a NAS or Portainer? Set
DATA_DIR(a host folder),HOST_PORT,PUIDandPGIDin.envor in the stack variables. Step-by-step guides are in the wiki. Building from source:docker compose -f docker-compose.build.yml up -d --build.
Your frame, on the wall. (A real photo is coming.)
- 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 moment the frame wakes up.
- Temporary pictures: a poster or album cover shows for the length of the film or song, then your slideshow comes back.
The full documentation lives in the GitHub Wiki:
| Installation and Deployment | Docker, Synology, Portainer, reverse proxy, host networking |
| Configuration Reference | Every setting, Smart Mix, Family Mode, Spectra 6 dithering |
| Immich and TMDB Setup | API keys, pickers, the Locked Folder rule |
| API Reference | Authentication and every endpoint (also live at /docs) |
| Home Assistant Integration | Automations, discovery |
This is a young project and it gets better with your help. 💙
- 🐛 Found a bug? Open an issue: the template asks only for what helps.
- 💡 Have an idea or a new image source in mind? Open a feature request, or start a discussion.
- 🗺️ Curious what is next? Follow the roadmap board (summary): editorial templates (quotes, weather, agenda, collages), more engines and generative art are on the way.
- 🛠️ Want to contribute? See CONTRIBUTING.md. Small fixes are welcome too.
- 🔐 Security issue? Please report it privately: see SECURITY.md.
Show me your wall: a photo of your frame in the discussions makes my day.
The Spectra 6 palette, color metric, Atkinson kernel and .bin layouts follow the official
Fraimic Bin Converter (MIT), which builds on
Toon-nooT's PhotoPainter Spectra 6 converter.
The soft / vivid curves and dithering kernels are adapted from the MIT-licensed
Stillroom converter by WillCroPoint (not a Fraimic project).
Templates use the Inter typeface (SIL OFL 1.1).
This product uses the TMDB API but is not endorsed or certified by TMDB. Album covers come from the Deezer API, MusicBrainz and the Cover Art Archive. Not affiliated with Fraimic or Immich.

