How screenly/anthias works
1. Purpose and deployment shape
Anthias is a self-hosted digital-signage appliance for Raspberry Pi, generic ARM64 SBCs, and PCs. It manages a local asset library and schedules images, videos, and web content for a directly attached display. The deployable stack is container-oriented and supports balena fleets; native installation provisions hosts with Ansible.
• docker-compose.yml.tmpl
• balena.yml
• ansible/site.yml
2. Runtime entry points
Three Python processes form the device runtime: a Django server/control plane, a display viewer, and a host agent. Container startup wrappers select and launch these roles.
• Server: src/anthias_server/manage.py, bin/start_server.sh
• Viewer: src/anthias_viewer/__main__.py, bin/start_viewer.sh
• Host agent: src/anthias_host_agent/__main__.py, ansible/roles/anthias/templates/anthias-host-agent.service
3. Server: control plane and persistence
The Django application owns asset, schedule, and application-domain state, exposes the management UI and versioned REST APIs, and serves files/UI assets. ASGI routing supports realtime connections; model migrations define persistent schema evolution.
• src/anthias_server/app/models.py
• src/anthias_server/app/views.py
• src/anthias_server/api/urls/v2.py
• src/anthias_server/django_project/asgi.py
4. Asset ingestion, processing, and integrations
Assets enter through dashboard/API upload and import/migration workflows. Server-side processing prepares or validates media; integrations use common ingestion abstractions to import external signage content. Remote-video, YouTube, and HTTP handling live in shared modules.
• src/anthias_server/processing.py
• src/anthias_server/lib/integrations/ingest.py
• src/anthias_server/lib/integrations/registry.py
• src/anthias_server/lib/screenly_migration.py
• src/anthias_common/remote_video.py
5. Scheduling and playback pipeline
The viewer consumes server-provided asset state, applies scheduling, and dispatches each selected asset to media or web rendering. Playback includes a GStreamer framebuffer path; supported web content is rendered by a separate Qt WebView executable. This is the principal boundary between management state and physical display output.
• src/anthias_viewer/scheduling.py
• src/anthias_viewer/playback.py
• src/anthias_viewer/media_player.py
• src/anthias_viewer/gst_fbdev_player.py
• src/anthias_webview/src/main.cpp
6. Device operations and hardware boundary
The host agent and server libraries inspect device/network characteristics and control or monitor attached hardware: HDMI-CEC/display power, storage health, and undervoltage. These isolate Linux/device-specific behavior from Django views and viewer policy.
• src/anthias_host_agent/ifaddrs.py
• src/anthias_server/lib/display_power.py
• src/anthias_server/lib/cec_client.py
• src/anthias_server/lib/storage_watcher.py
• src/anthias_common/undervoltage.py
7. Background, infrastructure, and packaging
Celery handles deferred server work, with Redis supplied as an infrastructure service. Docker images encapsulate server, viewer, Redis, and specialized Qt build stages. Balena deployment and Ansible provisioning provide alternative operational boundaries; GitHub Actions build images, test, generate OpenAPI, and deploy artifacts.
• src/anthias_server/celery_tasks.py
• docker/Dockerfile.server.j2
• docker/Dockerfile.viewer.j2
• docker/Dockerfile.redis.j2
• docker-compose.balena.yml.tmpl
Main entry points: manage.py Django server · docker-compose.yml.tmpl Container stack · playback.py Playback dispatch · models.py Assets and schedules
Components 19
Deployment
- Container stack · Defines the appliance service stack.
docker-compose.yml.tmpl - Balena fleet
balena.yml - Native provisioning
ansible/site.yml
Control plane
- Django server · Owns management, APIs, and application state.
src/anthias_server/manage.py - Management UI and v2 API
src/anthias_server/api/urls/v2.py - Assets and schedules
src/anthias_server/app/models.py - ASGI realtime routing
src/anthias_server/django_project/asgi.py - Asset ingestion · Imports uploads and external signage content.
src/anthias_server/lib/integrations/ingest.py - Media processing
src/anthias_server/processing.py - Deferred tasks
src/anthias_server/celery_tasks.py - Redis
docker/Dockerfile.redis.j2
Playback
- Display viewer · Turns server state into display output.
src/anthias_viewer/__main__.py - Schedule selection
src/anthias_viewer/scheduling.py - Playback dispatch
src/anthias_viewer/playback.py - GStreamer framebuffer
src/anthias_viewer/gst_fbdev_player.py - Qt WebView
src/anthias_webview/src/main.cpp
Device operations
- Attached display
- Host agent · Inspects host and network characteristics.
src/anthias_host_agent/__main__.py - Display and health control · Controls display power and monitors device health.
src/anthias_server/lib/display_power.py
Connections 23
- Container stack → Django server: runs
- Container stack → Display viewer: runs
- Container stack → Redis: runs
- Balena fleet → Container stack: deploys stack
- Native provisioning → Host agent: provisions service
- Django server → Management UI and v2 API: serves
- Django server → Assets and schedules: owns
- Django server → ASGI realtime routing: exposes
- Management UI and v2 API → Asset ingestion: accepts assets
- Asset ingestion → Media processing: prepares media
- Media processing → Assets and schedules: stores asset state
- Django server → Deferred tasks: queues deferred work
- Deferred tasks → Redis: uses
- Assets and schedules → Display viewer: provides asset state
- Display viewer → Schedule selection: applies
- Schedule selection → Playback dispatch: selects asset
- Playback dispatch → GStreamer framebuffer: media content
- Playback dispatch → Qt WebView: web content
- GStreamer framebuffer → Attached display: framebuffer output
- Qt WebView → Attached display: rendered output
- Host agent → Django server: reports host state
- Django server → Display and health control: requests device control
- Display and health control → Attached display: CEC and power control