Frequently Asked Questions

Common questions and troubleshooting for TheiaCast

Showing all questions

Table of Contents

  1. General Questions
  2. Installation and Setup
  3. Device Connectivity
  4. Content and Playlists
  5. Remote Control
  6. Broadcasting
  7. Performance
  8. Security
  9. Licensing
  10. Troubleshooting

General Questions

What is TheiaCast?

TheiaCast is a web-based digital signage solution that allows you to manage and control multiple display devices from a central dashboard. It supports web content, videos, images, and presentations with advanced scheduling and remote control capabilities.

What platforms are supported?

  • Server: Any platform with Docker support (Linux, Windows, macOS)
  • Clients: Windows 10/11, Raspberry Pi OS (Debian-based Linux), Android / Fire TV (native WebView)
  • Admin Dashboard: Any modern web browser (Chrome, Firefox, Safari, Edge)

Is TheiaCast free?

Yes, TheiaCast offers a free tier that supports:

  • Up to 3 devices
  • All core features (playlists, scheduling, broadcasting, remote control, MFA, SSO, API keys, Webhooks, Device Groups, and more)

Paid tiers offer additional devices and Custom Branding — those are the only two things a licence unlocks.

What are the hardware requirements?

Server:

  • 2GB RAM minimum (4GB recommended)
  • 10GB storage minimum (more for video content)
  • 2 CPU cores minimum

Display Devices:

  • Windows: 2GB RAM, any modern CPU
  • Raspberry Pi: Raspberry Pi 4 with 2GB RAM (4GB recommended)

How is the TheiaCast server installed?

The server is deployed with Docker Compose. This is the only supported installation method — the backend, frontend, and PostgreSQL database run as containers defined in docker-compose.yml. All you need on the host is:

  • A 64-bit Linux host (or any machine that can run Docker)
  • Docker Engine and the Docker Compose plugin
  • A reverse proxy (nginx or similar) if you want to terminate HTTPS in front of it

See the Installation Guide for the full walkthrough.

Is my data secure?

Yes. TheiaCast uses:

  • JWT authentication for admin users
  • Secure token-based authentication for devices
  • Password hashing with BCrypt
  • HTTPS support for encrypted connections
  • Optional multi-factor authentication (MFA)

Installation and Setup

How do I install TheiaCast?

Follow the Quick Start Guide for a 5-minute setup.

Quick summary:

  1. Install Docker and Docker Compose
  2. Create docker-compose.yml file
  3. Run docker-compose up -d
  4. Access dashboard at http://localhost

The dashboard won't load. What should I check?

1. Check if services are running:

docker-compose ps

All services should show "Up" status.

2. Check backend logs:

docker-compose logs backend

Look for "Application started" message.

3. Check if port 80 is available:

# Windows
netstat -ano | findstr :80

# Linux
sudo netstat -tulpn | grep :80

If another service is using port 80, change frontend port in docker-compose.yml:

frontend:
  ports:
    - "8080:80"  # Use port 8080 instead

4. Try accessing backend directly:

curl http://localhost:5001/health

Should return: Healthy (plain text, HTTP 200)

How do I change the default passwords?

Database Password:

  1. Edit docker-compose.yml
  2. Change POSTGRES_PASSWORD in both postgres and backend services
  3. Run docker-compose down && docker-compose up -d

Admin Password:

  1. Log into dashboard
  2. Go to Settings → Account
  3. Enter current and new password

Can I use an external PostgreSQL database?

Yes. Change the connection string in docker-compose.yml:

backend:
  environment:
    - ConnectionStrings__Default=Host=your-db-server;Port=5432;Database=theiacast;Username=your-user;Password=your-password

Remove the postgres service if you don't need the bundled database.

How do I enable HTTPS?

Quick method (with reverse proxy):

  1. Install nginx or Caddy on host
  2. Configure reverse proxy with SSL termination
  3. Forward requests to TheiaCast containers

Device Connectivity

My device shows as offline even though it's running

Troubleshooting steps:

1. Check device client logs:

# Windows
Get-Content "C:\Program Files\TheiaCast\logs\client.log" -Tail 50

# Raspberry Pi
sudo journalctl -u theiacast-client -f

2. Verify device token:

  • Check .env file on device has correct DEVICE_TOKEN
  • Compare with token shown in dashboard (flip device card → click token icon)

3. Verify server URL:

  • .env should have SERVER_URL=http://your-server-ip:5001
  • Should NOT include /ws path
  • Use server's IP address, not localhost

4. Check network connectivity:

# From device, test HTTP curl http://your-server-ip:5001/health

5. Check firewall:

  • Server firewall should allow port 5001 (backend)
  • Client device should allow outbound connections

6. Restart device client:

# Windows
Restart-Service TheiaCastClient

# Raspberry Pi
sudo systemctl restart theiacast-client

Device keeps disconnecting and reconnecting

Possible causes:

1. Network instability:

  • Check WiFi signal strength
  • Use wired Ethernet connection if possible
  • Check router logs for connection drops

2. WebSocket timeout:

  • Check for aggressive firewall/proxy WebSocket idle timeouts and increase them if possible

3. Device resource issues:

  • Check device health metrics (CPU, memory, disk)
  • If CPU >90% or Memory >90%, device may be overwhelmed

4. Server restarts:

  • Check backend logs for crashes or restarts
  • Device will automatically reconnect when server is back

Can I connect devices over the internet (not LAN)?

Yes, but you need to:

1. Expose server to internet:

  • Configure port forwarding on router (ports 80, 443, 5001)
  • Or use a VPN tunnel
  • Or use reverse proxy with public IP/domain

2. Update device client:

  • Set SERVER_URL=http://your-public-ip:5001 or https://your-domain.com

3. Security considerations:

  • Use HTTPS/SSL for encrypted connections
  • Use strong passwords and MFA
  • Consider VPN for additional security
  • Regularly rotate device tokens

How do I move a device to a different server?

1. On new server:

  • Create device with same Device ID
  • Note the new device token

2. On device:

  • Edit .env file
  • Update SERVER_URL to new server
  • Update DEVICE_TOKEN to new token
  • Restart client

3. On old server:

  • Delete old device (optional)

Content and Playlists

Why isn't my playlist playing on the device?

Troubleshooting checklist:

1. Is playlist assigned to device?

  • Dashboard → Devices → Flip card
  • Should show active playlist name
  • If not, click "Assign Playlist" and select playlist

2. Does playlist have items?

  • Dashboard → Playlists → Click playlist
  • Should show at least one content item
  • If empty, add content items

3. Is device online?

  • Device must be online to receive playlist updates
  • Green indicator = online, gray = offline

4. Are time windows blocking content?

  • Check playlist item time windows
  • If current time is outside all time windows, nothing will display

5. Check device client logs:

  • Look for "Loaded playlist" message
  • Look for "No valid items in time window" warning

Can I show different content on different days of the week?

Yes! Use the Days of Week filter when adding playlist items:

  1. Create playlist
  2. Add item
  3. Select specific days (e.g., Monday, Wednesday, Friday)
  4. Add another item for other days

How do I make content show permanently (no rotation)?

Set Display Duration to 0 seconds when adding the playlist item:

  1. Playlists → Select playlist → "Add Item"
  2. Select content
  3. Set "Display Duration" to 0
  4. Click "Add"

The device will show this content permanently until you change the playlist.

What video formats are supported?

Recommended: MP4 with H.264 video codec and AAC audio

Upload formats accepted:

  • MP4
  • WebM
  • MKV
  • MOV

Any codec is accepted — if it isn't H.264, TheiaCast automatically transcodes it to H.264 in the background before it plays on devices.

Performance tips:

  • H.264 is best for Raspberry Pi (hardware decoding)
  • Keep resolution ≤1080p for smooth playback
  • Bitrate ≤10 Mbps for reliable streaming

What image formats are supported?

  • JPEG/JPG
  • PNG (transparency supported)
  • GIF (animation supported)
  • WebP
  • SVG

Recommended: JPEG for photos, PNG for graphics with transparency

Can I show PowerPoint presentations?

Yes! Upload .pptx files as content items. TheiaCast converts them to web-based slideshows.

Limitations:

  • Animations may not play exactly as in PowerPoint
  • Embedded videos are not supported
  • Complex transitions may render differently

Recommendation: Test presentation on a device before deploying to all screens.

How do I show a website that requires login?

Use Auto-Login:

  1. Open (or create) a content item with the website URL, then toggle on "Automatically log in when this page loads"
  2. Click "Set up visually" — this opens a live view of the actual login page; click and type on it exactly like using a real browser, then click "Done" to capture the session
  3. If the visual setup can't reach the page, expand "Advanced: enter details manually" and enter CSS selectors for the username, password, and submit fields plus the credentials instead

Platform support: currently the Android / Fire TV client only — Raspberry Pi and Windows clients don't act on these fields yet, even though they can be configured for any content item.

Are auto-authentication credentials encrypted?

Yes — auto-login passwords are encrypted at rest using ASP.NET Core's Data Protection API before being stored in the database.

Can I show local files (not URLs)?

Not directly. TheiaCast is designed for web content and uploaded media.

Workarounds:

  1. Upload media files to TheiaCast (Content → Add Content → Upload File)
  2. Host files on a local web server and use URL
  3. Use network share with web server (e.g., nginx serving local directory)

Remote Control

Live Remote isn't working - I just see a black screen

Troubleshooting:

1. Is device online?

Check device status indicator (green = online)

2. Check WebSocket connection:

  • Open browser developer console (F12)
  • Look for WebSocket errors
  • Try refreshing the dashboard

3. Is Chromium running on device?

  • Check device client logs
  • Should see "Browser launched" message

4. Try Visual Remote instead:

  • Uses screenshots instead of live stream
  • Works if live streaming has issues

5. Check network bandwidth:

  • Live streaming requires ~2-5 Mbps
  • High latency >200ms may cause issues

Keyboard input in Live Remote isn't working

Troubleshooting:

1. Click the canvas to focus:

  • Canvas must be focused to receive keyboard events
  • You should see "KEYBOARD ACTIVE" indicator

2. Check browser permissions:

  • Some keys (F11, Ctrl+W) are reserved by browser
  • Use on-screen keyboard controls instead

3. Try typing in text input instead:

  • Enter text in the sidebar text box
  • Click "Type Text" button

Clicks aren't registering in the right location

Issue: Coordinates may be off if device resolution doesn't match display.

Solution:

  1. Check device resolution in screencast metadata
  2. Ensure device client is running in full-screen kiosk mode
  3. Restart device client if resolution changed recently

Can I control multiple devices at once?

Not directly. Remote control works on one device at a time.

For multiple devices:

  • Use Broadcasting to send messages/content to all devices
  • Use Playlists to synchronize content across devices

Broadcasting

Broadcast message isn't showing on device

Troubleshooting:

1. Is device online?

  • Broadcast only works on online devices
  • Check device status indicator

2. Is device selected?

  • In broadcast modal, check target devices
  • "All Devices" should be selected, or specific device checked

3. Is broadcast duration set?

  • Default: 30 seconds
  • If set to 0, broadcast shows permanently (until manually dismissed)

4. Check device client logs:

  • Should see "Received broadcast" message

How long does a broadcast last?

Duration is configurable when creating broadcast:

  • Default: 30 seconds
  • Set to 0 for permanent (until dismissed or new content)

After duration expires, device returns to normal playlist content.

Can I broadcast to specific devices?

Yes! In the broadcast modal:

  1. Uncheck "All Devices"
  2. Select individual devices to target
  3. Click "Start Broadcast"

Can I broadcast images and videos?

Yes! In broadcast modal:

  1. Select "Image" or "Video" type
  2. Click "Select Media"
  3. Choose from uploaded content
  4. Configure duration
  5. Click "Start Broadcast"

How do I stop an active broadcast?

Two methods:

1. Stop Broadcast button:

  • Broadcast Control panel shows active broadcasts
  • Click "Stop Broadcast" button

2. Automatic expiration:

  • Broadcasts with duration >0 automatically stop after duration

Performance

Dashboard is slow to load

Possible causes:

1. Too many devices:

  • Each device card loads latest screenshot
  • With many devices, this can be slow
  • Solution: Use filtering to show fewer devices

2. Large screenshots:

  • Screenshots are base64-encoded in API response
  • Solution: Reduce screenshot quality or resolution in Settings

3. Slow network:

  • Test network speed from your location to server
  • Solution: Use CDN or closer server location

4. Server overload:

  • Check server CPU/memory usage
  • Solution: Upgrade server resources or reduce load (increase intervals)

Video playback is choppy on Raspberry Pi

Solutions:

1. Use H.264 codec:

  • Hardware-accelerated on Raspberry Pi
  • Avoid VP9, AV1 (no hardware support)

2. Reduce resolution:

  • 1080p maximum for Raspberry Pi 4
  • 720p for Raspberry Pi 3

3. Reduce bitrate:

  • Keep video bitrate ≤5 Mbps
  • Use handbrake or ffmpeg to re-encode:
ffmpeg -i input.mp4 -c:v libx264 -preset slow -crf 22 -maxrate 5M -bufsize 10M -c:a aac output.mp4

4. Check Raspberry Pi temperature:

  • Overheating causes throttling
  • Ensure adequate cooling (heatsink, fan)

5. Use wired Ethernet:

  • WiFi may introduce buffering
  • Wired connection is more stable

Device client is using too much memory

Solutions:

1. Restart device client periodically:

  • Memory leaks in Chromium can build up
  • Set up daily restart (cron or scheduled task)

2. Reduce screenshot frequency:

  • Edit SCREENSHOT_INTERVAL in the device's .env file and restart the client
  • Increase from 5 min to 10 min

3. Disable unused features:

  • If not using live remote, screenshots can be less frequent

4. Upgrade device RAM:

  • Raspberry Pi 4 with 4GB RAM recommended
  • Windows devices: 4GB minimum

Live streaming is laggy (low FPS)

Possible causes:

1. Network bandwidth:

  • Live streaming requires ~2-5 Mbps
  • Test network speed between server and admin

2. Server CPU:

  • Forwarding frames uses CPU
  • Check server load during live streaming

3. Device CPU:

  • Capturing frames uses CPU
  • Check device health metrics

Solutions:

  • Use wired network connections
  • Close other applications on device
  • Upgrade server/device hardware

Security

How do I enable HTTPS?

Quick method:

  1. Use Let's Encrypt with reverse proxy (nginx, Caddy)
  2. Forward HTTPS traffic to TheiaCast containers

Should I change the default database password?

Yes, absolutely! The default password in the example docker-compose.yml is for demonstration only.

Change it before deploying to production:

  1. Edit docker-compose.yml
  2. Change POSTGRES_PASSWORD in both services
  3. Redeploy

How do I enable multi-factor authentication (MFA)?

Quick steps:

  1. Go to Settings → Account
  2. Enable MFA
  3. Scan the QR code with your authenticator app
  4. Enter the 6-digit code to confirm

How often should I rotate device tokens?

Recommendation: Every 90 days for production environments.

To rotate:

  1. Dashboard → Devices → Flip card → "Rotate Token"
  2. Update .env on device
  3. Restart device client

Future: Automatic token rotation is planned.

Can I restrict device connections by IP address?

Not currently supported in the web UI.

Workaround: Use firewall rules on server:

# Example: Only allow specific IP range
sudo iptables -A INPUT -p tcp --dport 5001 -s 192.168.1.0/24 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 5001 -j DROP

Licensing

What features are included in the free tier?

Free tier includes:

  • Up to 3 devices
  • Every other feature: playlists and scheduling, content management, broadcasting, remote control, health monitoring, screenshots, MFA, SSO, API keys, Webhooks, Device Groups, Floor Map, Canvas Designer, and Backup/Restore

A paid licence only unlocks more than 3 devices and Custom Branding — those are the only two gated things.

How do I upgrade my license?

  1. Go to the License page in the admin sidebar
  2. Purchase a licence key for the tier you need
  3. Click "Activate Licence" and paste the key
  4. Click "Activate"

What happens if my license expires?

When a licence expires or you go over its device limit:

  • New device registrations are blocked
  • Custom Branding re-locks
  • Existing devices, content, playlists, and configuration are not deleted or deactivated

Grace period: 7 days over the device limit before new registrations are blocked — existing devices keep working throughout

Can I transfer my license to a different server?

Yes. On the old server's License page, click "Revoke" on the key, then contact [email protected] with your licence key and the new server's Installation Key to get it rebound.

Do I need a license for development/testing?

No. Free tier (3 devices, 1 user) is sufficient for development and testing.

For larger test environments, contact sales for evaluation licenses.

Troubleshooting

Error: "Failed to connect to database"

Cause: Backend cannot reach PostgreSQL database.

Solutions:

1. Check PostgreSQL is running:

docker-compose ps postgres

Should show "Up" status.

2. Check connection string:

  • docker-compose.yml → backend → environment
  • Verify ConnectionStrings__Default matches PostgreSQL service

3. Check PostgreSQL logs:

docker-compose logs postgres

Look for startup errors.

4. Reset database:

docker-compose down -v  # WARNING: Deletes all data! docker-compose up -d

Error: "Device token is invalid or has expired"

Cause: Device token doesn't match server records.

Solutions:

1. Get correct token:

  • Dashboard → Devices → Flip card → Click token icon
  • Copy token

2. Update device .env:

DEVICE_TOKEN=paste-correct-token-here

3. Restart device client:

# Windows
Restart-Service TheiaCastClient

# Raspberry Pi
sudo systemctl restart theiacast-client

4. If token still doesn't work, rotate it:

  • Dashboard → Devices → Flip card → "Rotate Token"
  • Update .env with new token
  • Restart client

Error: "WebSocket connection failed"

Cause: Client cannot establish WebSocket connection to server.

Solutions:

1. Check server URL:

  • Should be http://server-ip:5001 (NOT http://server-ip:5001/ws)

2. Check firewall:

  • Port 5001 must be open on server
  • Outbound connections allowed on client

3. Check reverse proxy:

  • If using nginx/Caddy, ensure WebSocket upgrade headers are configured

4. Test WebSocket endpoint:

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://server-ip:5001/ws

Should return 101 Switching Protocols.

"Page is blank" or "White screen" on device

Cause: Web page failed to load or JavaScript error.

Solutions:

1. Check device client logs:

  • Look for console errors or navigation failures

2. Check URL is accessible:

  • Try opening URL in browser manually
  • Verify URL is correct (no typos)

3. Site blocks embedding (X-Frame-Options / frame-ancestors):

  • iframe-based clients (webOS, Tizen, the admin preview) fetch such pages through the backend /proxy automatically, which strips frame-blocking headers - this should just work
  • If it still fails, the site likely needs its own cookies/session; try the URL in a fresh incognito window and use one that works there, or host a copy yourself

4. Restart browser:

  • Device → Remote Control → "Refresh Page"
  • Or restart device client

Playlist item doesn't show - "No valid items in time window"

Cause: All playlist items have time windows that exclude current time/day.

Solutions:

1. Check time windows:

  • Dashboard → Playlists → Select playlist
  • Verify time windows include current time

2. Check days of week:

  • Verify current day is selected in "Days of Week" filter

3. Remove time restrictions:

  • Edit playlist item
  • Clear "Time Window Start" and "Time Window End"
  • Clear "Days of Week" selection
  • Save

4. Check server time:

  • Verify the backend container/host's system time zone is correct (TheiaCast has no in-app time zone setting)

Device shows "Offline" but client is running

Cause: WebSocket connection is broken.

Solutions:

1. Restart device client:

# Windows
Restart-Service TheiaCastClient

# Raspberry Pi
sudo systemctl restart theiacast-client

2. Check network connectivity:

curl http://server-ip:5001/health

3. Check device token:

  • Compare .env token with dashboard token

4. Check server logs:

docker-compose logs backend

Look for WebSocket connection errors

Screenshots not updating

Cause: Screenshot upload is failing or disabled.

Solutions:

1. Check screenshot interval:

  • Edit SCREENSHOT_INTERVAL in the device's .env file and restart the client
  • Should be >0 (0 disables screenshots)

2. Check device client logs:

  • Look for "Screenshot captured" messages
  • Look for upload errors

3. Request manual screenshot:

  • Dashboard → Devices → Flip card → "Screenshot"
  • Check if this works

4. Check database size:

  • Large database may slow screenshot storage

Fire TV shows “Are you still watching?” and interrupts the display

Cause: This is a Fire OS platform feature, not a TheiaCast setting — it fires after roughly four hours when an app is on screen and awake with no remote input, which is exactly what a signage player looks like. Apps cannot suppress it in code (Amazon reserves that for the platform), and Fire OS also blocks the third-party accessibility services that could otherwise simulate input.

Solutions:

1. Let the app do it (recommended for fleets):

Grant it WRITE_SECURE_SETTINGS once over adb and it disables the screensaver and sleep/inactivity timeouts itself on every launch:

adb connect <fire-tv-ip>:5555
adb shell pm grant com.theiacast.client android.permission.WRITE_SECURE_SETTINGS

2. On the device:

  • Open Settings → Display & Sounds → Screensaver and set it to Never

3. Permanent fix:

  • Amazon exempts signage apps from the prompt by package name — contact [email protected] and we can raise the exemption request with Amazon Developer Support

4. Self-recovery either way:

  • If the prompt goes unacknowledged and Fire OS sends the app to the home screen, TheiaCast relaunches itself within a couple of seconds

Can't upload large video files

Cause: File size exceeds upload limit.

Solutions:

1. Check for a reverse-proxy body-size limit:

  • TheiaCast's backend has no upload size limit of its own
  • If you run TheiaCast behind nginx or another reverse proxy, raise its request body size limit (e.g. nginx's client_max_body_size)

2. Use external hosting:

  • Upload video to YouTube, Vimeo, or CDN
  • Use URL in content item instead of uploading

3. Compress video:

  • Reduce bitrate/resolution with ffmpeg

Still Need Help?

If your question isn't answered here:

1. Check other documentation:

2. Email support:

[email protected] — our team answers setup questions, licensing queries, and technical issues.

3. Report a bug or request a feature:

Email [email protected]

Include logs, screenshots, and steps to reproduce