Skip to content

About

Self-hosted engine that turns Immich photos, movie posters and album covers into Spectra 6 e-ink pictures for Fraimic frames, with Home Assistant support.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Smart Frame Engine

CI Docker image Latest release License: MIT

Your best photos, movie posters and album covers on a color e-ink frame, automatically.


What is it?

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.

The dashboard: the composition and the exact 6-color result

Get it running in 3 minutes

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
  1. Open http://localhost:8080 (or http://<your-server>:8080).
  2. Settings → Frame: enter the frame's IP address (give it a fixed IP on your router).
  3. Settings → Immich: add your server and API key, tick the people or albums you like.
  4. 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, PUID and PGID in .env or 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.

A quick tour

Playground
Playground: try posters, album covers and title cards, and compare Spectra 6 renderings side by side before anything reaches the frame.
Family Mode
Family Mode: show only your family, hide private people and albums, and let Home Assistant switch it on when guests are over.

A Fraimic frame on the wall
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.

Learn more

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

Feedback, issues & roadmap

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.

Credits

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.

License

MIT

About

Self-hosted engine that turns Immich photos, movie posters and album covers into Spectra 6 e-ink pictures for Fraimic frames, with Home Assistant support.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages