LibreSignage

LibreSignage is an open-source digital signage web application built with Flask. The project uses Flask's application factory pattern and blueprints so features can be developed and tested independently.

Requirements

• Python 3.10 or newer
• Node.js 20 or newer
• uv (recommended) or another Python package installer

Development

Clone the repository, install the locked development environment, and start Flask:

uv sync --dev
npm install
npm run build
uv run flask --app libresignage run --debug

Then open http://127.0.0.1:5000.

The content library at http://127.0.0.1:5000/content/ accepts images, video, PDFs, text, QR codes, clocks, web pages, and RSS or Atom feed URLs. Each item has a default display duration. QR codes can encode a validated website or a vCard assembled from contact name, organization, phone, email, and website fields plus an optional structured street, city, state/region, postal code, and country address. LibreSignage generates high-error-correction SVG codes locally without a third-party QR service, and caches them for offline players. Clock widgets use an IANA timezone and continue updating without a network connection. Feed widgets render safe, readable headline cards, refresh every five minutes, and retain the last successful response when the upstream provider fails. Feed downloads reject redirects, oversized responses, private-network targets, invalid XML, and unsafe link schemes. Web-page widgets remain available for sites that permit iframe embedding.

Use http://127.0.0.1:5000/content/playlists to arrange reusable content into ordered playlists, override an entry's duration, choose transitions, and configure continuous looping or one-time playback. Players skip failed media and continue through the sequence. Metadata and cached feed responses are stored in src/instance/libresignage.sqlite and uploaded files in src/instance/uploads/ by default. Deployments can set the DATABASE, UPLOAD_FOLDER, and MAX_CONTENT_LENGTH Flask configuration values to change those locations and the upload-size limit.

Uploaded videos are automatically normalized to muted WebM/VP9 so the same asset plays in browser and Linux Qt screen clients. Install ffmpeg on the LibreSignage server before accepting video uploads. Conversion runs in a background worker: the library shows its status, refreshes while work is in progress, and excludes unfinished videos from playback. Conversion behavior, the FFmpeg executable, and the 30-minute conversion timeout can be changed with LIBRESIGNAGE_VIDEO_TRANSCODING_ENABLED, LIBRESIGNAGE_FFMPEG_BINARY, and LIBRESIGNAGE_VIDEO_TRANSCODE_TIMEOUT.

The library supports case-insensitive search across titles, text or URLs, folders, and tags, plus exact folder filtering. Assets can have a folder, up to ten normalized tags, and an optional expiry date. Expired assets remain visible for auditing and cleanup but are automatically skipped during playlist, scheduled, layout, preview, and managed-screen playback. Usage badges identify every referencing playlist; deleting an in-use asset requires explicit confirmation. Edit / replace updates metadata or replaces the underlying file, text, URL, feed, QR payload, or clock timezone without changing the asset ID or its playlist positions. SHA-256 checksums reject duplicate uploaded files, and successful replacement removes the superseded managed file.

Use http://127.0.0.1:5000/content/schedules to assign playlists to date ranges, recurring weekdays, and local-time dayparts. Overnight windows are supported, and the highest-priority active schedule wins when rules overlap. The scheduled player checks for schedule changes every 30 seconds while continuing its current playback if the server is temporarily unavailable.

The centralized CMS at http://127.0.0.1:5000/dashboard/ summarizes content, playlists, schedules, and registered screens. Each screen receives a permanent player URL and can use either the scheduled channel or a directly assigned playlist. Assignment changes remain staged until an operator publishes them. Connected players check for new published revisions every two seconds and atomically reload the new content. Failed checks back off to 15 seconds while players continue the last available revision. Every publish is recorded as a fleet batch on the dashboard.

Administrators can activate a full-screen emergency override from the CMS dashboard for selected screens, a reusable screen group, or the entire fleet. Critical, warning, and information styles use large high-contrast messaging and interrupt playback within the normal two-second player polling interval. The override is cached as the screen's current offline revision. The explicit Restore published playback action clears it without changing the screen's playlist, schedule, or multi-zone assignment.

Every managed screen has a Preview draft action on the CMS dashboard. Preview renders the staged playlist, currently active scheduled channel, or multi-zone layout with the same templates used by the player, without publishing, advancing its revision, or recording device contact. Operators can inspect Full HD landscape, Full HD portrait, 4K landscape, and HD landscape canvases; each uses its actual logical resolution and scales to fit the browser. External web content may block iframe previews through its own security policy.

Managed players also prepare the complete published playlist for offline use with a per-screen service worker. Local images, video, PDFs, text, and player assets are stored in revisioned browser caches with no application expiry; failed cache updates retain the last complete revision. Cached video supports byte-range playback. Live web and RSS content is intentionally excluded and shows an explicit offline message until connectivity returns. Browser storage quotas and device-level cache eviction still apply. See Reboot-safe offline player for provisioning, cold-start verification, and kiosk browser-profile requirements.

LibreSignage includes a standalone PyWebView screen client for native kiosk deployment. It stores an end-user-provided server base URL and registered screen slug, runs the resulting managed-player URL fullscreen, and uses a persistent browser profile so service workers and offline revisions survive client and system restarts. See PyWebView screen client for installation, configuration, diagnostics, renderer selection, and graphical-session autostart.

Managed players report a health heartbeat every 5 seconds with their cache revision, service-worker state, browser storage usage, network state, and last cache error. The dashboard classifies screens as online, degraded, offline, or never connected and opens persistent offline alerts after LIBRESIGNAGE_DEVICE_OFFLINE_AFTER_SECONDS (90 seconds by default). Operators can remotely restart the browser player, request Sync now, or clear its LibreSignage caches. Operating-system reboot requires a native player or device agent and is not available to the browser player.

The screen inventory at http://127.0.0.1:5000/dashboard/screens stores each display's stable identity, location, operator notes, and reusable group membership. Operators can stage a scheduled channel or direct playlist for explicitly selected screens, one group, or the complete fleet. Bulk targeting resolves to concrete screen IDs when staged; the existing publish action then delivers those assignments to players.

Each inventory record also stores a logical display profile: width, height, derived landscape or portrait orientation, and media scaling. Common Full HD, 4K, and HD presets are available alongside custom dimensions from 320 to 7,680 pixels. Fit with letterboxing preserves the whole image, Fill and crop covers the display, and Stretch to fill matches its bounds. Managed playback exposes this metadata, applies the chosen image/video scaling, and rearranges split multi-zone layouts vertically for portrait screens. Draft preview starts with the saved profile and can temporarily compare other resolutions and scaling modes.

Multi-zone layouts at http://127.0.0.1:5000/content/layouts use fixed, predictable templates: 70/30 split, main with ticker, and 70/30 split with ticker. Each zone owns an independent playlist, duration loop, transition, and failure-recovery cycle. Layouts can be staged to individual screens, groups, or the full fleet and their complete local media set is included in offline caching.

Accessible content templates at http://127.0.0.1:5000/content/templates provide announcement, promotion, and information-notice starting points. Operators substitute labeled text fields, brand and text colors, and an optional image—no design software is required. LibreSignage enforces WCAG AA 4.5:1 text contrast, requires descriptive alternative text for uploaded template images, and safely limits text lengths. Created designs become normal library items, so they can be reused in playlists, schedules, and multi-zone layouts and are included in managed-player offline caches.

The CMS requires an individual user account. On a new installation, visit http://127.0.0.1:5000/auth/setup once to create the first administrator. Administrators manage accounts at http://127.0.0.1:5000/auth/users. Passwords must contain at least 12 characters and are stored as salted hashes. The built-in roles are:

• Admin: manage users, devices, groups, remote commands, and publishing.
• Editor: create and update content, playlists, layouts, schedules, and staged screen assignments, but cannot publish or administer users/devices.
• Viewer: inspect the CMS without making changes.

Managed player URLs, media delivery, offline assets, status checks, and heartbeats remain available without an interactive login so kiosk devices can recover after a reboot. Other CMS routes require authentication, and state-changing browser requests use CSRF protection. Production startup fails unless LIBRESIGNAGE_SECRET_KEY is explicitly configured.

Configuration profiles live in src/libresignage/config.py. LibreSignage uses the development profile by default; set LIBRESIGNAGE_CONFIG to development, testing, or production, or pass config_name to the factory:

app = create_app(config_name="production")

The shared configuration also reads LIBRESIGNAGE_SECRET_KEY, LIBRESIGNAGE_DATABASE, LIBRESIGNAGE_UPLOAD_FOLDER, and LIBRESIGNAGE_MAX_CONTENT_LENGTH from the environment. LIBRESIGNAGE_TIMEZONE sets the default IANA timezone shown when creating a schedule. LIBRESIGNAGE_DEVICE_OFFLINE_AFTER_SECONDS controls the device heartbeat timeout. Copy .env.example to .env for local development, replace the sample secret, and start Flask from the project root. LibreSignage automatically loads that file; variables already exported by the operating system take precedence.

cp .env.example .env

Local CI verification

Before pushing, run the same locked dependency, test, lint, and package checks used by GitHub Actions with one command:

./scripts/check-ci.sh

The script stops at the first failure and builds packages in a temporary directory that it removes automatically. To run or troubleshoot individual checks:

uv lock --check
uv sync --locked --dev
uv run --locked pytest
uv run --locked ruff check .
uv build --out-dir /tmp/libresignage-dist
uv run --locked twine check /tmp/libresignage-dist/*

If uv lock --check reports that the lockfile needs to be updated after a dependency or project-version change, run uv lock, review and commit the resulting uv.lock change, then repeat the verification commands.

Frontend styles live in src/libresignage/static/scss/app.scss. It imports Bootstrap's Sass source so Bootstrap variables can be overridden before the import. Run npm run watch:css while editing styles, or npm run build to compile the production CSS and copy Bootstrap's bundled JavaScript.

The package also exposes libresignage:create_app for WSGI servers:

from libresignage import create_app

app = create_app()

Building and publishing

Build both distribution formats with uv build. GitHub Actions validates every push and pull request. Creating a GitHub release triggers the PyPI publishing workflow, which uses PyPI Trusted Publishing and a protected pypi GitHub environment.

License

LibreSignage is distributed under the MIT License. See LICENSE.