Skip to content

README.md

Latest commit

 

History

History
177 lines (115 loc) · 3.63 KB

README.md

File metadata and controls

177 lines (115 loc) · 3.63 KB
Raw

🖥️ Kiosk Rotation Engine

A lightweight, self-hosted digital signage engine for kiosk displays.

Drop files in a folder. Screens update automatically. No cloud. No accounts. No nonsense.

✨ Features

  • 📂 Folder-based rotation (images, videos, HTML)
  • 📥 Network upload support (via shared drop folder)
  • 🔄 Live updates — viewers refresh automatically
  • 🧠 Playlist versioning (safe, flicker-free updates)
  • 🖥️ Fullscreen kiosk player (browser-based)
  • 🛡️ Fault-tolerant (invalid files are ignored)
  • ⚙️ Simple YAML configuration
  • 🐧 Works on Linux, Windows, Raspberry Pi

🚀 Quick Start

git clone https://github.com/ProtoXCode/Kiosk-Rotation-Engine.git
cd kiosk-rotation-engine
pip install -r requirements.txt
python run.py

Open in a browser:

http://<host>:8080

(Use fullscreen / kiosk mode for production screens.)

📁 Content Workflow

This system uses a two-stage content pipeline:

Upload → Processing → Display

1. Upload (network share)

Files are dropped into an upload directory (e.g. via SMB/Samba):

/srv/uploads

This folder can be shared across the network so other machines can easily add content.

2. Processing (recommended)

A small processing step moves valid files into the live rotation directory:

/srv/display

Typical responsibilities:

  • ✅ Allow only supported file types
  • 🚫 Reject invalid or unsupported files
  • 📦 Optionally enforce file size limits
  • 🔄 Normalize or convert formats if needed

This prevents broken or unsupported files from reaching the display.

3. Display (app reads here)

The engine reads from the configured media directory:

rotation:
  media_directory: /srv/display

Only processed, valid content should live here.

📁 Supported Content

🖼️ Images

  • .jpg, .jpeg, .png, .webp
  • .heic, .heif (auto-converted to JPEG)

🎬 Video

  • .mp4, .webm

🌐 Web Content

  • .html (rendered via iframe)
  • .url (rendered via iframe — target site must allow embedding)

📄 Office Documents (optional)

  • .ppt, .pptx
  • .doc, .docx
  • .xls, .xlsx
  • .pdf

Office files are converted before display (e.g. to images or PDF pages).

⚠️ Requires LibreOffice to be installed on the host system for document conversion support.

⚙️ Configuration (config.yaml)

Example:

rotation:
  media_directory: /srv/display
  default_duration: 10
  image_duration: 10
  playlist_scan: 60
  video_mute: true
  • media_directory – Folder used for playback (post-processing)
  • default_duration – Fallback duration (seconds)
  • image_duration – Image display time
  • playlist_scan – Backend rescan interval (seconds)
  • video_mute – Start videos muted

🧠 How It Works (Short Version)

  • Backend scans the media directory on a fixed interval
  • Builds a versioned playlist
  • Viewers fetch the playlist and play it sequentially
  • Updates are applied cleanly on the next loop

No polling storms. No race conditions. No broken screens.

⚠️ Design Notes

  • No authentication (intended for trusted networks)
  • Upload directory should not be used directly as media source
  • Recommended to isolate upload and display directories
  • Not designed for public internet exposure

🧩 Typical Setup

  • Debian server running the engine
  • Network share (SMB via Samba) mapped to /srv/uploads
  • Background script or service processes uploads
  • Clean media served from /srv/display

📜 License

MIT License

Use it, break it, improve it — just don’t put it behind a paywall 😎