frameserver

lightweight, FastAPI-based server designed to power digital photo frames.

features

• slideshow photo with transitions and different format fits (letterboxed or fullscreen crop).
• drag'n'drop photo ordering in admin panel
• clock display, small customization and sync via websockets.
• photo captions
• optimized for android system webview 44

how 2 launch

prerequisites

• python 3.11+ (if running locally)
• docker and docker compose (if running on server, recommended)

running with docker

1. clone the repo:

   git clone https://github.com/ploff/frameserver
   cd frameserver

2. start the server:

   docker-compose up -d --build

3. access:

   • admin panel: http://localhost:8000/
   • photo frame view: http://localhost:8000/static/index.html

local installation

1. create a venv:

   python -m venv venv
   source venv/bin/activate

2. install dependencies:

   pip install -r requirements.txt

3. run:

   uvicorn app.main:app --host 0.0.0.0 --port 8000

API endpoints

API documentation is automatically generated and available at /docs:

• GET /api/v1/photos - get list of all photos.
• POST /api/v1/photos/upload - upload new images.
• PATCH /api/v1/photos/{id} - update photo caption.
• POST /api/v1/photos/reorder - update the display order.
• POST /api/v1/frame/reload - send reload signal to connected frame.