Getting Started with TheiaCast

Learn how to set up and configure TheiaCast for your digital signage needs

Overview

TheiaCast is a professional digital signage management system that allows you to:

  • Create and manage playlists for your displays
  • Upload videos and web content to devices
  • Control displays remotely with live streaming
  • Monitor device online/offline status and capture screenshots
  • Automate content rotation with duration-based scheduling
  • Support Windows PCs, Intel NUCs, and Raspberry Pi devices

Architecture

Backend:
ASP.NET Core 10 (C#) with PostgreSQL database
Frontend:
React 19 + TypeScript with Vite and Tailwind CSS
Pi Client:
Node.js 18+ with Puppeteer and Chromium
Windows Client:
.NET 10 with Playwright and bundled Chromium
Real-time:
Native WebSockets for live streaming and device control

Quick Start

1. Install the Server

Choose your deployment method:

Docker (Recommended):

git clone https://github.com/jimmyeao/TheiaCast.git
cd TheiaCast
docker-compose -f docker-compose.prod.yml up -d

Or use pre-built images:

docker pull ghcr.io/jimmyeao/theiacast-backend:latest
docker pull ghcr.io/jimmyeao/theiacast-frontend:latest

See our installation guide for manual installation options.

2. Access the Dashboard

After installation, access the admin dashboard at http://localhost:5173

Default Credentials:
Username: admin
Password: admin123
⚠️ Change these immediately in production!

TheiaCast Login Screen

Secure login interface with modern authentication

3. Two-Factor Authentication (Optional)

For enhanced security, enable two-factor authentication. TheiaCast supports TOTP-based 2FA for an additional layer of protection.

TheiaCast 2FA Screen

Two-factor authentication for enhanced account security

4. Install Client Devices

Install the client software on your display devices:

Windows Client

Download and run the installer:

TheiaCast-Client-Windows-v1.0.0-Setup.exe

Auto-starts via Task Scheduler

Linux / Raspberry Pi

Download and extract tarball:

sudo ./scripts/install.sh

Systemd service auto-start

See installation guide for detailed instructions.

5. Register Your Devices

In the admin dashboard, navigate to the Devices page and add your display devices:

  1. Click "Add Device" button
  2. Enter a unique Device ID (e.g., "lobby-display-1")
  3. Enter a friendly name for the device
  4. Copy the generated device token
  5. Configure the token on your client device

Important: Keep device tokens secure! They provide full access to device control.

6. Create Content

Add content that will be displayed on your devices:

  • URLs: Any website or web application
  • Videos: Video URLs (YouTube, Vimeo, direct video files)
  • Login Required Sites: Use live remote control to log in to websites that require authentication

Logging into Websites:

For websites requiring authentication, use the Live Remote Control feature to log in manually:

  1. Go to Devices page and click "Live Remote" on your device
  2. Wait for the live video stream to connect
  3. Click on the login fields and type credentials directly
  4. The browser maintains session cookies automatically
  5. Device will remain logged in across restarts

💡 Browser sessions persist using a local profile directory on each client device

7. Build Playlists

Create playlists to organize and schedule your content:

  1. Go to Playlists page and click "Create Playlist"
  2. Add content items to the playlist
  3. Set display duration for each item (seconds, or 0 for permanent)
  4. Configure optional time windows (e.g., 9:00 AM - 5:00 PM)
  5. Set day-of-week filters if needed
  6. Arrange items in the desired order

Duration Control:

  • 0 seconds: Static display (no rotation)
  • >0 seconds: Display for specified duration, then move to next item

8. Assign and Go Live

Assign playlists to devices and start displaying content:

  1. Go to Devices page
  2. Flip the device card to see controls
  3. Click "Assign Playlist"
  4. Select the playlist to display
  5. Content automatically pushed to device in real-time

✓ Real-time Updates: Changes to playlists are instantly pushed to connected devices via WebSocket.

Key Features

🎥 Live Remote Control

Stream live video from devices and interact remotely with click, type, and keyboard commands using Chrome DevTools Protocol

📋 Playlist Scheduling

Control when content displays with duration-based rotation, time windows, and day-of-week filtering

💊 Health Monitoring

Monitor device status (CPU, memory, disk) and capture screenshots remotely in real-time

🔐 Session Persistence

Client devices maintain persistent browser sessions across restarts - log in once via remote control and stay authenticated

🔄 Real-time Updates

Instant playlist and content updates via WebSocket connections - no device restart required

📱 Cross-Platform

Support for Windows PCs, Intel NUCs, and Raspberry Pi devices with unified management

Advanced Features

Remote Browser Control

Full remote interaction with device browsers via Puppeteer/Playwright automation. Click at specific coordinates, type text into fields, send keyboard commands, and scroll programmatically.

CDP Screencast Streaming

Real-time video streaming at 10-30 FPS using Chrome DevTools Protocol. See exactly what's on each device with low latency and interact directly with the live stream.

Persistent Browser Profiles

Chromium profiles persist sessions and cookies across device restarts. Once authenticated, websites remain logged in without repeated credential entry.

Need Help?

Check out our additional documentation, GitHub repository, or reach out to the community for support.

Installation GuideView on GitHubDownload Now