Stillness 🖼️

Stillness is a lightweight Node.js service designed to breathe life into e-paper displays. It fetches images from a Google Photos Shared Album, processes them with high-quality dithering, and serves them as 1-bit PNGs optimized for 7-inch Waveshare (and similar) e-ink screens.

When development on Stillness started, I could not find any easy way to get photos from Google Photos shown on the fantastic TRMNL (however, there are recipes now!), hence this project. However, as I see it this project brings three main benefits:

• Privacy: While you do need to set up a public shared album, the album URL is not shared with anyone and if you self-host the service, nothing ends up in the cloud.
• Performance: Other solutions and BYOS for TRMNL rely on headless browsers taking screenshots, which can be very resource heavy. Stillness just fetches and processes image files, which makes it more suitable to run on a Raspberry Pi or NAS.
• Photos first: No complicated authentication with Google, just photos adapted in size and quality for e-paper displays. If you want text and dashboards, there are other projects for that.

✨ Features

• Google Photos integration: Automatically fetches and cycles through images from any public shared album.
• High-quality dithering: Uses the Floyd-Steinberg algorithm for superior 1-bit image quality
• Auto-filtering: Smartly ignores portrait and square images to ensure a perfect landscape fit
• Optimized for e-ink: Serves 1-bit indexed PNGs (800x480 by default) to minimize transfer time and display processing
• Efficient caching: Caches album URLs to reduce API calls and improve responsiveness
• Docker ready: Comes with a slim Docker configuration for easy deployment on home servers or Raspberry Pis

🚀 Quick Start

Prerequisites

• Node.js 24 (LTS) or Docker
• A public Google Photos Shared Album URL
• An e-ink display that can fetch and display images from a URL, for example:
  • Seeed Studio TRMNL 7.5" OG DIY Kit

Docker

1. Clone the repository

   git clone https://github.com/oscarb/stillness.git
   cd stillness

2. Create a .env file and set SHARED_ALBUM_URL to your public album URL

   cp .env.sample .env

3. Spin it up

   docker compose up -d --build

Your service should now be running at http://localhost:3000/image.

Node

1. Install dependencies:

   npm install

2. Create a .env file and set SHARED_ALBUM_URL to your public album URL

   cp .env.sample .env

3. Start the server:

   npm start
   # or for development with auto-reload:
   npm run dev

🛠️ Configuration

The service is configured via environment variables:

Variable	Description	Default
SHARED_ALBUM_URL	Required. The URL of your public Google Photos shared album.	-
PORT	The port the server will listen on.	3000

📡 API Reference

GET /image

Returns a random landscape image from the configured album, dithered and formatted for e-paper displays

---

Made with 🤖 by oscarb and Antigravity