Framez

A desktop "smart photo frame" app built with Flutter. Pick a folder and the app enters presentation mode, showing photos at random for 10 seconds each.

Live Demo →

Installation

Pre-built binaries are available on the Releases page for every version tag.

macOS

1. Download Framez-macos-x64.dmg from the latest release.
2. Open the .dmg file.
3. Drag Framez.app into the Applications folder.
4. On first launch, right-click the app and select Open to bypass Gatekeeper (the app is unsigned).

Linux (Debian/Ubuntu)

1. Install runtime dependencies:

   sudo apt-get update
   sudo apt-get install ffmpeg libheif-examples libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
     gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav

2. Download Framez-linux-x64.deb from the latest release.
3. Install the package:

   sudo dpkg -i Framez-linux-x64.deb

4. Launch from the terminal or your system app menu:

   framez

   To uninstall:

   sudo dpkg -r framez

---

Supported platforms

• macOS
• Linux (Requires ffmpeg for .mov playback and heif-convert for HEIC support)
• Web (browser-native playback; no server-side conversion)

Supported formats

• Images: JPEG, PNG, HEIC/HEIF (auto-converted on macOS & Linux; browser-native on web), GIF, WebP
• Videos: MP4, MOV (auto-converted on Linux; browser-native on web), WebM

Running from source

1. Install Flutter and ensure desktop support is enabled.

2. From the project root:

   flutter pub get
   flutter run -d macos   # or windows, linux, chrome

3. Use Choose folder to select a directory. The app scans it (and subfolders) for supported images.

4. Tap Start presentation to enter full-screen presentation mode.

5. In presentation mode, tap anywhere or press Escape to exit.

Web (Docker + nginx)

Build a self-contained nginx image that serves the Flutter web app as static content:

docker build -f web.Dockerfile -t framez-web .

Run the container (served on http://localhost:8080):

docker run --rm -p 8080:80 framez-web

Then open http://localhost:8080 in your browser.

Note: The initial docker build clones Flutter (beta channel) and compiles the app, which takes several minutes on the first run. Subsequent builds reuse the Docker layer cache where possible.

GitHub Pages

The app is automatically built and deployed to https://neuman968.github.io/flutter_framez/ on every push to main via the deploy-web.yml workflow.

One-time repo setup: go to Settings → Pages → Build and deployment → Source and select GitHub Actions.

Running docker compose

The docker-compose-rpi.yml file in this directory runs the application as well as a Sambda server that can be configured so that a Raspberry pi, or any other linux device hooked up to a display can be turned into smart photo frame. Wayland is required when running with docker compose.

Features

• Directory selection — Native folder picker on macOS, Windows, Linux, and web browsers (webkitdirectory).
• Recursive scan — Finds images in the chosen folder and all subfolders.
• Random order — Order is shuffled when you start a presentation.
• HEIC on Linux — HEIC/HEIF files are converted to JPEG for display on Linux.
• MOV on Linux — .mov files are automatically converted to .mp4 for playback on Linux using ffmpeg.
• Default Directory — Set a default scan directory via the FRAMEZ_PHOTO_DIR environment variable.
• Audio Toggle — Choose to play or mute video audio from the landing page.
• Pinch/pan — Optional zoom and pan via InteractiveViewer while a photo is shown.