User Guide

Main Navigation

The left sidebar provides access to all features:

• 📊 Dashboard - Overview of your system
• 💻 Devices - Manage display devices
• 🗂️ Groups - Nest devices into groups with dynamic tag rules for bulk targeting
• 🗺️ Floor Map - Place devices on building floor plans
• 📈 Reports - Proof-of-play, screen uptime, and CSV export
• 📝 Logs - View system logs
• 🎬 Content - Upload and manage content
• 📅 Playlists - Create content schedules
• 🖼️ Canvas - Free-form designs with live zones and widgets
• ⬆️ Updates - Check for and deploy client software updates
• 👥 Users - Manage user accounts
• 🛡️ Roles - Manage custom roles and permissions
• 🔐 API Keys - Create and manage API keys
• 🔗 Webhooks - Configure outbound event callbacks
• 🔑 License - View license status
• ⚙️ Settings - Configure system settings

Quick Stats

The dashboard shows at-a-glance information:

• Total devices (online/offline)
• Total content items
• Total playlists
• Active broadcasts
• System health

Interface Language

The admin interface is available in several languages. Change it under Settings → Account & Security → Language. This is a per-browser preference (stored locally, like the dark / light theme) — each admin picks their own, and it does not change what anyone else sees.

Viewing Devices

Navigate to Devices in the sidebar.

Devices page showing multiple device cards

Each device card shows:

• Device name and status (Online/Offline)
• Group and tag chips - the device’s deepest containing group(s) and any tags, shown in a row above the thumbnail
• Live thumbnail - Latest screenshot
• Current playlist - What's currently assigned
• Playback controls - Pause, resume, next, previous
• Health status - Click card to flip and see details

Adding a New Device

1. Click + Add Device
2. Fill in the device details:
   • Device ID: Unique identifier (e.g., "lobby-display-01")
   • Name: Friendly name (e.g., "Main Lobby Display")
   • Description: Optional description
   • Location: Optional location info
   
3. Click Create
4. Important: Copy the device token shown in the popup
   • You'll need this to configure the client software
   • Store it securely - you can view it later if needed

   Screenshot pending for this step.

5. Install and configure the client software on your display device using this token (see Installation Guide)

Device Actions

Click on a device card to flip it and reveal actions:

Available actions:

• Assign Playlist - Choose which playlist to display
• Screenshot - Take immediate screenshot
• Live Remote - View and control display in real-time
• Visual Remote - Control using screenshot interface
• View Token - Show the device token
• Restart / Reboot - Restart the client app, or reboot the whole device
• Delete - Remove device (confirmation required)

Screen Power & Volume Control (HDMI-CEC)

Extra buttons on the device card — screen on (☀️), screen off (🌙), volume up, volume down, and mute — send a one-off command to the screen over HDMI-CEC. No restart needed. Mute is a single toggle; the same button un-mutes.

A per-device Power Schedule (flip the card → Configure Display → Power Schedule) can turn the screen on and off automatically at set times on chosen days.

CEC has no reliable way to read a TV’s true power or volume state, so TheiaCast only knows what it last sent — a change made with the TV’s own remote is invisible to it. Brightness control is not available— it isn’t part of the HDMI-CEC standard.

Filtering Devices by Tags

Use tags to organize devices by location, department, or purpose:

1. Click Manage Tags to create tags
2. Assign tags to devices
3. Use the tag filter buttons to show only specific groups

Device Groups

Groups are a separate, nested-folder way to organize devices — a building, a floor, a region — distinct from the flat Tags system above. They sit alongside tags rather than replacing them: a group can hold devices directly, or automatically via a dynamic tag rule (any device carrying every tag in the rule joins the group without being added by hand).

1. Go to Groups (under Monitor in the sidebar)
2. Click New group for a top-level group, or select a group and Add sub-group to nest one underneath it — nesting can go as deep as you like, e.g. Site → Building A → Floor 2
3. Add devices directly from the group’s detail panel, and/or attach a dynamic tag rule

A group’s effective device count rolls up its own direct members, its own tag-rule matches, and every sub-group’s devices recursively, so a device several levels deep still counts toward the top-level group. Use a group to broadcast to, or push a playlist across, everything under it at once instead of picking devices one at a time — and use the Groups filter chip row on the Devices and Updates pages (next to the Tags row) to narrow either page down to a group’s members. Device Groups is available on every tier. See the Monitoring Guide for the full reference.

Teams Relay

Re-broadcasts a live Microsoft Teams meeting or Town Hall to selected — or all — screens, full-screen, overriding whatever those screens are currently showing until stopped. Uses Teams’ own RTMP-Out (“Custom Streaming”) feature — TheiaCast never joins the meeting itself.

1. Click Teams Relay on the Devices page
2. Target devices with the same tag/group selector used for Broadcast (leave both empty for every device), optionally give the session a label, then Start Relay
3. TheiaCast generates a one-time RTMP Server URL and Stream Key — hand these to whoever is running the Teams meeting, who adds the Custom Streaming app in Teams and pastes them in
4. Once Teams starts streaming, targeted screens switch over automatically; the status pill goes from Waiting for Teams to connect to Live

Normal playlist rotation is paused, not lost, and resumes exactly where it left off when you click Stop Relay. A Microsoft 365 admin needs to enable Teams live streaming for your tenant once before first use, and the organizer needs an Enterprise-tier (E3+) Microsoft 365 licence — a Business Premium-only tenant can see “You don’t have streaming permissions” even with Live Streaming turned on. Teams Relay is available on every tier. See the Teams Relay guide for the full reference and troubleshooting.

Playback Controls

Control playlist playback directly from the device card:

• ▶️ Play/⏸️ Pause - Resume or pause playlist rotation
• ⏮️ Previous - Go to previous playlist item
• ⏭️ Next - Skip to next playlist item
• Status indicator - Shows playing (green), paused (yellow), or broadcasting (purple)
• Item counter - Shows current item position (e.g., "2/5")

Viewing Device Details

Click the thumbnail to see:

• Full-size screenshot
• Current URL
• Health metrics (CPU, memory, disk usage)
• Connection status
• Last screenshot timestamp

Viewing Content

Navigate to Content in the sidebar.

Content page with grid view

View Modes

Toggle between two viewing modes:

• Grid view (📱) - Thumbnail previews
• List view (☰) - Detailed list

Your preference is saved automatically.

Content Types

TheiaCast supports several content types:

1. 🌐 Web Pages - Any website URL
2. 🎬 Videos - MP4 files uploaded or from URL
3. 🖼️ Images - JPG, PNG files
4. 📊 Presentations - PowerPoint (.pptx) and PDF files (converted to a slideshow)
5. 🎨 Templates - A ready-made, form-configured design — no external design tool needed. See Template Library below

Adding Web Content

1. Click + Add Content
2. Enter details:
   • Name: Descriptive name
   • URL: Full website address (e.g., https://example.com)
   • Description: Optional notes
   
3. Click Save

Uploading Videos

1. Click the Upload Video button
2. Fill in the form:
   • Name: Video title
   • File: Choose your MP4 file (up to 32GB)
   • Upload progress will show
   
3. Click Upload

The video will be:

• Uploaded to the server
• Cached on display devices
• Available for playlists immediately

Uploading Images

1. Click Upload Image
2. Enter name and select image file (JPG or PNG)
3. Click Upload

Images display full-screen on devices.

Uploading Presentations

1. Click Upload Presentation
2. Enter details:
   • Name: Presentation title
   • File: PowerPoint (.pptx) or PDF file
   • Duration per slide: Seconds to show each slide (default: 10)

   Screenshot pending for this step.

3. Click Upload

The presentation will be converted to individual slides.

Auto-Authentication for Websites

Some internal tools require a login. TheiaCast can fill in credentials automatically when a device navigates to that URL, or — once a session has been captured — sign the device in with a saved session instead of sending the password at all.

Only a simple single-page login form is supported (one username field, one password field, one submit button). Multi-step sign-in flows, two-factor authentication, and CAPTCHA-protected logins aren’t supported.

Recommended: Visual Setup

Open (or create) a content item — it must already be saved, since the visual setup needs a real URL to load — toggle on Automatically log in when this page loads, then click Set up visually. This opens a full-screen live view of the actual login page, streamed from a real headless browser running on the server:

1. Click anywhere on the page just like using a real browser — the click lands on the real page.
2. Type in the text box below the live view and press Send to type into whatever field is currently focused, or use the Enter / Backspace / Tab buttons for keys that aren’t plain text.
3. Repeat until you’re actually logged in and looking at the real destination page.
4. Click Done — this captures whatever session now exists (cookies and/or the site’s own login token) and saves it.

This also works from a phone or tablet. If Done reports it found no session, the site didn’t yield to this approach — the manual method below won’t help either, since both ultimately depend on the same login page.

Advanced Fallback: Manual CSS Selectors

If the visual setup can’t reach the page (for example, a login page only reachable from a device’s own network, not the server’s), expand Advanced: enter details manually and fill in the fields directly:

• Username Selector: CSS selector for the username field (e.g., #username)
• Password Selector: CSS selector for the password field (e.g., #password)
• Submit Selector: CSS selector for the submit button (e.g., button[type="submit"])
• Username: Login username
• Password: Login password (never shown again after saving — re-enter it to change it, leave blank to keep the existing one)

Finding CSS Selectors: Open the login page in Chrome/Edge → right-click the field → Inspect → note the id or name attribute → use #id for IDs or [name="fieldname"] for names.

Use Capture session now to test the configuration immediately. A successful capture logs in once, server-side, and saves the resulting session; from then on, the device signs in using that saved session and TheiaCast stops sending the password to the device at all.

Template Library

Click Templates on the Content page to build a piece of content from a ready-made design — no external design tool needed. Pick a template, fill in a form, save. A live preview updates as you type; click and drag the text in the preview to move it anywhere on the screen, and use Reset position to snap it back to centre.

Every template also has a Background Style picker (Flowing / Geometric / Particles) and an Orientation switch (Landscape / Portrait) — pick whichever matches the physical screen. Afterwards a template behaves like any other content item: add it to a playlist, assign a duration, and re-edit it any time (the same form reopens pre-filled, including its saved text position, style, and orientation).

AI-Enabled Signage

Once an admin connects an AI provider (Settings → AI — OpenAI, Anthropic, or any OpenAI-compatible endpoint), a handful of AI-assisted buttons appear across the Content page: Write with AI / Improve with AI next to any template text field, Generate with AI for template background images, Suggest with AI for an image’s alt text on upload, and an AI Starter Playlist button that turns a one-line description of your business into a small ready-made playlist. Every suggestion is reviewable and editable before it’s applied — nothing AI writes is ever saved automatically. These buttons are completely absent until a provider is configured. See the AI-Enabled Signage guide for the full reference.

Content Approval Workflow (optional)

Off by default. Turn it on under Settings → Content & Retention → Content Approval Workflow if you want a review step before anything new goes live. When enabled:

1. New content (uploaded or added by URL) starts as Draft.
2. The creator clicks Submit for review on the content card.
3. Any Operator or Admin clicks Approve or Reject (with an optional reason). The creator is emailed either way.
4. Only Approved content can be added to a playlist. A Draft, Pending, or Rejected item stays in the library with a status badge but cannot reach a device.

A Pending review filter chip appears above the library grid whenever something is awaiting submission or review. Rejected content can be edited and re-submitted.

Editing Content

1. Click the edit button (✏️) on any content item
2. Modify the details
3. Click Save

Deleting Content

1. Click the delete button (🗑️)
2. Confirm deletion
3. Note: Content used in playlists will be removed from those playlists

Searching Content

Use the search box to find content by name or URL:

Storage Management

View storage usage at the bottom of the Content page:

Shows:

• Total space available
• Space used by videos, images, presentations
• Percentage used

Viewing Playlists

Navigate to Playlists in the sidebar.

Playlists page with 2-column grid layout

Filtering Playlists

Use the filter tools at the top:

• Search box: Find playlists by name or description
• Tag filters: Click tags to filter by category
• Results counter: Shows how many playlists match

Creating a Playlist

1. Click + Create Playlist
2. Enter details:
   • Name: Playlist name (e.g., "Reception Area - Weekdays")
   • Description: Optional notes
   • Active: Check to enable immediately
   
3. Click Create

Adding Items to Playlist

1. Find your playlist and click Add Item
2. Configure the item:
   • Content: Select from your content library
   • Display Duration: Seconds to show (0 = permanent/static)
   • Order: Position in playlist (auto-assigned)
   
3. Click Save

Advanced Scheduling

Restrict when content displays using time windows and days of week.

Time Windows

Show content only during specific hours:

1. When adding/editing a playlist item, expand Time Window
2. Set Start Time and End Time (24-hour format)
   • Example: 09:00 to 17:00 (9 AM to 5 PM)
   
3. Content only displays between these times

Date Ranges

Run an item only between two calendar dates:

1. When adding/editing a playlist item, expand Date Range
2. Set a Start Date and/or End Date (both inclusive)
   • Example: 1 December to 14 December for a two-week campaign
   • Leave one side blank for an open-ended range
3. Dates are evaluated in the device’s time zone (see Scheduling and Time Zones)

Clearing a date field removes that bound. An unparseable date is rejected rather than silently cleared, so a saved date is never lost by mistake.

Days of Week

Show content only on specific days:

1. In the playlist item editor, expand Days of Week
2. Check the days when content should display
   • Example: Monday-Friday only
   
3. Content only displays on selected days

Monthly Recurrence

Repeat an item on a monthly pattern instead of specific weekdays — “the 1st Monday of every month” or “the 15th of every month”.

1. In the playlist item editor, expand Monthly Recurrence.
2. Choose either an nth weekday (e.g. 3rd Friday) or a day of the month (1–31, or Last day of month).

Combined Scheduling Example

Show "Lunch Menu" only Monday-Friday, 11:30 AM - 1:30 PM:

• Time Window: 11:30 - 13:30
• Days: Mon, Tue, Wed, Thu, Fri checked

Item Transitions & Preview

Each playlist can animate the change between items. The control lives in the playlist’s detail header — a dropdown next to the Apply to group, Rename, and Preview buttons. Changes save immediately and are pushed to assigned devices straight away.

For non-cut types, the chevron next to the dropdown opens the options: Duration (ms) (0–10000, default 600) plus the direction/axis/angle controls relevant to that type. Transitions apply between playlist items only — the first item shown, broadcasts, and Teams Relay sessions still appear instantly. A missing or unrecognised transition behaves as a cut, so older clients keep working.

The Preview button in the detail header opens a popup that plays the playlist exactly as a device would — real item durations, the configured transition, and video lifecycle handling. Use it to check order, durations, and transitions before assigning. Keyboard: ←/→ skip items, Space pauses the rotation clock, Esc closes the popup.

Reordering Playlist Items

Drag and drop items to change their order:

1. Click and hold the drag handle (≡) on an item
2. Drag to new position
3. Release

The order saves automatically.

Editing Playlist Items

1. Click Edit on any playlist item
2. Modify settings
3. Click Save

Changes take effect immediately on all assigned devices.

Removing Items from Playlist

1. Click Remove on the item
2. Confirm deletion

The item is removed from this playlist but remains in your content library.

Assigning Playlists to Devices

1. Go to Devices page
2. Click a device card to flip it
3. Click Assign Playlist
4. Select the playlist
5. Click Assign

The device will immediately start playing the playlist.

Playlist Tags

Organize playlists with tags:

1. Edit a playlist
2. Select tags or create new ones
3. Save

Use tag filters on the Playlists page to find related playlists.

Setting a Device Time Zone

1. Go to Devices and edit a device
2. Choose a Time Zone (IANA name, e.g. Europe/London or America/New_York)
3. Save — the setting is pushed to the device immediately

Content Publish and Expiry

Set a go-live and retire date on a content item itself, so it applies everywhere that content is used, across every playlist:

1. Edit a content item
2. Set Publish At and/or Expires At (both inclusive)
3. Before the publish date and after the expiry date, the content is skipped on every device

Where both a content window and a playlist item’s date range apply, the tighter of the two wins.

“What’s Scheduled” Preview

The device page has a What’s scheduled panel that explains, for each item in the assigned playlist, whether it is allowed to play right now — and if not, the exact constraint blocking it (outside its time window, wrong day, before publish date, expired, and so on).

• It reports eligibility, not the live rotation order — use it to answer “why isn’t this showing?”
• Each eligible item shows the last minute it stays eligible (its window is inclusive).
• The preview looks ahead 14 days.

Live Widgets

Add a zone element in the canvas editor and pick a widget type. Each has a live preview on the editor canvas:

• Clock — digital or analogue, with its own time zone, optional label, and toggles for seconds, date, and 12/24-hour format, plus colour controls.
• Countdown — counts down to a target date and time in a chosen zone, correct across daylight-saving changes.
• Weather — current conditions for a location, no API key required. If the weather service can’t be reached it shows an “Unavailable” placeholder rather than a blank zone.
• Calendar — upcoming events from an ICS/iCal feed (Google Calendar, Outlook/Microsoft 365, or any calendar app that can publish one). Choose between four views — List, Month grid, Week, or Day — plus a time zone, refresh interval, and appearance settings. If the feed can’t be reached or parsed, the zone shows “Calendar unavailable” rather than going blank.

Per-Zone Audio for Video

Video in a zone element is muted by default. Tick Enable Audio on a zone to let its video play with sound. Only the zone currently on screen is unmuted; others are paused and rewound, so multiple video zones don’t talk over each other.

Publishing Changes

There’s no separate “push to devices” step. Click Save, and any screen already showing that design picks it up the next time it reloads that content — the same as editing an image or a web URL content item.

Selecting Overlapping Elements

Clicking the canvas only selects the topmost element at that point. Use the Layerspanel to pick any element by name — it lists every element top-first with its type, and selects it directly regardless of what’s stacked on top. Reorder layers there, or set an exact Z-Index in the element’s Position & Size tab.

Starting a Broadcast

1. At the top of the Dashboard page, click Start Broadcast to All Devices
   

   Broadcast button on dashboard

2. Choose broadcast type:
   • Message: Text message with custom background
   • URL: Navigate all displays to a website
   • Image: Show an image file
   • Video: Play a video file
   

Message Broadcast

Display a formatted text message:

1. Select Message type
2. Enter your message text
3. Click Start Broadcast

All devices will immediately show your message in a styled card.

URL Broadcast

Send all displays to a specific website:

1. Select URL type
2. Enter the full URL
3. Click Start Broadcast

Image/Video Broadcast

1. Select Image or Video type
2. Upload the file (or select from library if available)
3. Click Start Broadcast

Targeting Specific Devices

Filter which devices receive the broadcast:

1. In the broadcast modal, expand Target Devices
2. Select tags to filter devices
3. The counter shows how many devices will receive it
4. Click Start Broadcast

Ending a Broadcast

1. The Active Broadcast banner shows at top of Dashboard
2. Click End Broadcast
3. Devices return to their assigned playlists

Screenshot pending for this step.

Live Remote Control

The most powerful way to interact with displays:

1. Go to Devices
2. Click device card → Live Remote
3. A modal opens showing live video stream from the device
   

   Live remote control modal with stream

Features:

• Live video at 10-30 FPS
• Click anywhere on the stream to interact
• Type directly when focused (click the video first)
• FPS counter shows stream performance
• Connection status indicator

Keyboard Control:

1. Click the video to focus it
2. "KEYBOARD ACTIVE" indicator appears
3. Type normally - keystrokes go to the device
4. Perfect for entering passwords or filling forms

Visual Remote Control

Screenshot-based interaction with auto-refresh:

1. Click Visual Remote on a device
2. Screenshot-based interface loads
3. Enable Auto-refresh for continuous updates (every 2 seconds)

Screenshot pending for this step.

Features:

• Click on screenshot to interact at that position
• Keyboard controls sidebar with common keys
• Type text with optional CSS selector targeting
• Refresh page button
• Lower bandwidth than live remote

Basic Remote Control

Simple command interface:

1. Click Remote on a device
2. Use the control panel:
   • Type text: Enter text with optional CSS selector
   • Special keys: Enter, Tab, Escape, Arrow keys, F5
   • Click coordinates: Send click at X,Y position
   • Scroll: Scroll up/down/left/right

   Screenshot pending for this step.

Remote Control Use Cases

Creating Tags

1. Go to Devices page
2. Click Manage Tags
3. Click + Create Tag
4. Enter tag name and choose a color
5. Click Create

Assigning Tags to Devices

1. Edit a device
2. Select tags from the list
3. Save

Or use bulk tagging:

1. Select multiple devices (if feature available)
2. Apply tag to all

Assigning Tags to Playlists

1. Edit a playlist
2. Select tags
3. Save

Filtering by Tags

On Devices Page:

• Click tag buttons at top to show only tagged devices
• Click multiple tags to show devices matching any of the selected tags (not all of them) — this combines with the Groups filter and status filter, which each narrow the result further

On Playlists Page:

• Use tag filter buttons in the filter card
• Combine with search for powerful filtering

Tag Organization Examples

Device Health Monitoring

View real-time health metrics for each device:

1. Go to Devices
2. Click a device card to flip it
3. View health indicators:
   • CPU Usage: Percentage of CPU in use
   • Memory Usage: RAM utilization
   • Disk Usage: Storage space used
   • Status: Online/Offline
   • Last Seen: Time of last connection
   

Viewing Screenshots

See what's currently displayed:

1. Device card shows latest thumbnail
2. Click thumbnail for full-size view
3. Click Screenshot button for immediate refresh

Screenshot pending for this step.

Automatic screenshots:

• Single-item playlists: Every 30 seconds
• Multi-item playlists: On each rotation
• On-demand: Click Screenshot button

System Logs

View system activity and troubleshoot issues:

1. Go to Logs in the sidebar
2. Filter by:
   • Device
   • Log level (Info, Warning, Error)
   • Date range
   
3. Each log entry shows:
   • Timestamp
   • Device name
   • Message
   • Level/severity

Device Logs

View logs specific to a device:

1. Go to Devices
2. Click View Logs on a device
3. Logs filtered to that device appear

Useful for troubleshooting connection or playback issues.

How It Works

• A background check watches how long each device has been silent. Once it passes the offline threshold you set, you get one alert email.
• The threshold acts as a debounce — a display that briefly drops and reconnects won’t trigger an alert.
• A device that loses power is caught too: the alert is driven by missed check-ins, not by a clean disconnect.

Turning It On

Alerting and the email connection are configured under Settings → Notifications & Alerts. See the Administrator Guide for recipient addresses, the offline threshold, and choosing a send method (SMTP, OAuth 2.0, or Microsoft Graph).