# Web Guide

Pulse Signage brings content creation, publishing, screen management, and live operations into one web application. This guide explains what each area is for, how the areas work together, and when to use each one.

## Overview

### Dashboard

The dashboard is the starting point for everyday work. It summarizes the parts of the system that matter most when you are publishing or checking displays, including screens, playlists, slides, templates, and active clients.

Use the dashboard to:

- See whether the system has content ready to publish.
- Move quickly to the content or screen area that needs attention.
- Check high-level counts and current activity.
- Identify whether a display problem is likely to be content-related or connection-related.

The dashboard is an overview rather than a replacement for the detailed pages. Use the dedicated feature pages when you need to edit content or investigate a specific connection.

## Screens and Players

### Screens

A screen represents a display destination in Pulse Signage. It gives a playlist somewhere to play and provides the link between your content and a physical display.

When setting up a screen, choose a clear name and stable slug so other people can recognize it. Assign the playlist that should normally play there, then associate the screen with the appropriate player during setup.

Use the screen area when you need to:

- Add a new display destination.
- Change the playlist shown on a display.
- Review which player is associated with a screen.
- Update screen details after a display is moved or renamed.
- Remove a display that is no longer part of the signage setup.

If a screen exists but is not showing the expected content, first check its assigned playlist, then check the player and client status.

Keep screen names specific to their physical location or purpose. The screen assignment is the publishing boundary: changing the playlist changes what that destination plays, while reusing a playlist lets several screens share the same experience.

### Connected Clients

A connected client is an active browser or player connection reporting to a screen. A single screen can have more than one connection over time as players restart, browsers reconnect, or replacement devices come online.

The clients page helps you distinguish content problems from runtime problems. It shows information such as:

- The client name and screen group.
- The current slide title, when one is available.
- The client viewport size.
- When the connection was established or last updated.
- Whether the client is paused or blacked out.

From this page, available controls can reload a client, move to the previous or next slide, pause playback, or toggle blackout. Commands apply to the selected connection, so confirm the client and screen before sending one.

If a client is missing, check that the player is running and connected before changing the playlist. If the client is present but showing the wrong content, check the screen's playlist and the playlist order.

Use client information to separate three common problems:

- A missing client usually indicates a player, network, bridge, or pairing problem.
- A connected client showing the wrong slide usually indicates a screen assignment or playlist problem.
- A connected client showing a broken region usually indicates a slide value, asset, source, or external stream problem.

### Client Pairing and Remote Players

Pairing connects a player device to a screen or screen group. The web application pairing workflow uses the player's six-character PIN and a client name.

A typical setup is:

1. Start the web application, database, and player bridge.
2. Open the pairing workflow from the web application.
3. Read the six-character PIN shown by the player, or scan its QR code.
4. Enter a name that identifies the physical player, such as `Lobby player`.
5. Select the screen the player should display.
6. Connect the player and wait for the pairing confirmation.
7. Confirm the player appears among connected clients.
8. Assign or verify the playlist for the selected screen.

Use a new client name when pairing a replacement device so the client list remains understandable. If the PIN is rejected or expires, return to the player and start the pairing display again before retrying.

A local player can run alongside the main application, while a remote player connects back to the player bridge from another location. Remote players need a working connection to the bridge and the web service.

If a remote player does not appear:

- Check the bridge address and shared connection settings.
- Confirm firewall rules allow the required traffic.
- Confirm WebSocket traffic is allowed through any reverse proxy.
- Check that the player can resolve and reach the service from its network.
- Check the connected clients page after the player reconnects.

The web application remains the main control source. Screen assignments, player commands, media synchronization, fonts, and access updates are delivered to players through the service connections. A player being offline does not make it an independent administration surface; it receives the current state when it reconnects.

## Content

### Slide Templates

A slide template is a reusable design definition. It sets the canvas, background, regions, layout, and animation defaults that editors use when creating slides. A template defines the visual structure; a slide fills that structure with a particular message or set of values.

Templates are useful when you want consistency. For example, an event announcement template can give every editor the same title, date, image, and background fields without asking them to rebuild the layout each time.

#### Template Details and Canvas

When creating or editing a template:

- Give the template a descriptive name based on its purpose.
- Choose the canvas size that matches the target display orientation and resolution.
- Use a landscape canvas for wide screens, a portrait canvas for vertical displays, and a custom size when the hardware needs one.
- Treat the canvas as the coordinate system for every region. A layout made for one aspect ratio may need a separate template for another.
- Preview the template at the canvas size where it will be used before publishing it.

Existing templates may lock their canvas size after slides have been created from them. If the design needs a different aspect ratio, create a separate template rather than distorting a template that is already in use.

#### Backgrounds

The template background is behind every region. It can be built from:

- A solid background colour.
- An uploaded background image.
- A linear gradient with an adjustable angle and multiple colour stops.

Use an image for a branded or photographic background, a colour for a simple consistent surface, and a gradient when the design needs depth without another media asset. Keep important details away from region boundaries and check text contrast against the final background. Removing a background image does not remove the regions placed above it.

#### Regions and Layout

A region is a named area of the canvas that provides one content slot on a slide. Add a region, choose its type, give it a stable name, and place it on the canvas. Regions can overlap; the Z-Index determines which region is drawn in front when they do.

Each region has layout controls for:

- **X and Y:** the region's position on the canvas.
- **Width and Height:** the region's size.
- **Lock ratio:** an optional ratio such as `16:9` that keeps the shape consistent while resizing.
- **Z-Index:** the stacking order for overlapping regions.
- **Region name:** the stable field name used to identify the content slot.

Use names such as `headline`, `hero_image`, `event_time`, or `room_schedule` instead of generic names. Stable names make slides easier to edit and make template changes easier to understand. Keep regions large enough for their longest expected value; a region that fits a short title may clip a longer announcement.

#### Region Types

The available region types cover fixed content, uploaded media, live data, and external content:

- **Text:** rich text content with font family, font size, font colour, and normal editorial formatting. Use it for headings, labels, paragraphs, and other copy that editors change per slide.
- **Image:** an uploaded image in the media library. The editor supports PNG, JPG, GIF, WebP, and SVG images, with cropping to the region ratio when needed.
- **Video:** an uploaded MP4, WebM, or Ogg video. Videos preview in the region and loop during playback.
- **HTML:** HTML content rendered inside a sandboxed preview. Use it for controlled custom markup when an ordinary text region cannot express the design.
- **Webpage:** a URL displayed in an embedded webpage region. Use it for a page that should be shown inside the slide, and verify that the destination permits embedding.
- **QR Code:** a generated QR code with configurable code content and visual styling. Use it for links, tickets, instructions, or other information that viewers can scan.
- **RSS:** a selected RSS feed item. Choose the feed and item, then map the available feed fields into the region.
- **API:** a value from a configured API source. Select the source, identify the item or path when required, and use the returned value in the slide.
- **Timetable:** schedule information from configured timetable groups and entries. Use it for room bookings, events, departures, or other structured schedules.
- **Weather:** current or forecast weather for a configured location. Select the location and forecast mode, then format the region to leave room for changing values.
- **Time / Date:** a clock or date display using a chosen timezone. Use it for local time, event dates, or location-specific schedules.
- **RTMP:** a live RTMP stream URL. Use it for a live video source and check that the player can reach the stream from its network.

Live region types depend on their configured source. Configure the RSS feed, API source, timetable, weather location, or other source before trying to use it in a slide.

#### Region Animations

Animations are configured per region and are saved with the template. They have three independent phases:

- **Intro:** how the region enters when the slide starts.
- **Outro:** how the region leaves when the slide ends.
- **Attention seekers:** a repeating animation while the slide is visible, useful for drawing attention to a status, alert, or call to action.

The basic choices include fades, slides, zooms, and attention effects such as pulse, flash, bounce, shake, swing, and heartbeat. Choose **None** when movement would distract from the content. Use the advanced animation settings when the basic choices do not provide the required direction, speed, delay, duration, or repeat behaviour. The template preview can play the intro, outro, or attention animation so you can check the result before saving.

Avoid animating every region at once. Staggered or limited motion is easier to read, especially for information-heavy slides and live data.

When working with templates:

- Keep fields focused on the content an editor is expected to change.
- Consider existing slides before changing a template, because layout changes can affect every slide built from it.
- Create a separate template when two designs are conceptually different instead of forcing one template to handle unrelated layouts.
- Use the preview controls to check backgrounds, overlapping regions, text wrapping, media cropping, and animations together.

Templates provide structure; they do not decide which slides play or which screen receives them.

### Slides

A slide is an individual piece of signage content. It is normally created from a template, filled with content, previewed, and then placed into one or more playlists.

Slides can contain ordinary editorial content such as text, images, video, HTML, QR codes, and webpages, as well as content that changes over time through announcements or data sources. This lets a playlist remain stable while the information inside a slide stays current.

When filling a slide, work through each region in the template rather than trying to redesign the layout in the slide editor. Enter text in text regions, upload or select media in media regions, and choose configured sources in live-data regions. The template's region names and layout remain the reference for how the slide is intended to look.

For media regions, check the crop and aspect ratio before saving. For text and live data, check the longest likely value, line wrapping, font size, and contrast. For webpages and streams, confirm the player network can reach the external address.

A useful slide workflow is:

1. Select the template that matches the intended design.
2. Fill in the visible content and any optional fields.
3. Preview the slide at the target canvas size.
4. Check text wrapping, image cropping, animation, and contrast.
5. Save the slide and add it to a playlist.
6. Recheck the live client after publishing.

If a slide is reused in multiple playlists, an edit can affect every place where it appears. Create a separate slide when the content needs to vary between destinations.

### Playlists

A playlist is the sequence a screen plays. It controls which slides appear, the order in which they appear, how long they remain visible, and how transitions behave.

Use playlists to organize content by destination, audience, or purpose. A lobby playlist, for example, may combine welcome messages, schedules, announcements, and a repeating information slide without changing the underlying templates.

When editing a playlist:

- Add only the slides that belong to that display experience.
- Reorder slides to establish the intended viewing sequence.
- Review each slide's duration and the overall rhythm of the sequence.
- Configure transitions where a change in visual pacing is useful.
- Decide how unavailable streams should be handled if the playlist uses live media.
- Save the playlist before checking the player.

The order is significant: viewers see slides from top to bottom and then return to the beginning. Use longer durations for slides with more text or live data, and use shorter durations for simple notices. A transition changes how one slide gives way to the next; it does not change the region animations inside either slide.

A playlist change affects the screens using that playlist. A slide change can affect every playlist that includes that slide, so choose the object that matches the scope of the change you intend to make.

### Canvas Sizes

Canvas sizes describe the dimensions or aspect ratios a design is meant to use. They help templates and slides stay predictable when a display has a known resolution or orientation.

Create a canvas size when your organization has a recurring display format, such as a landscape lobby screen, a portrait information board, or a wide event display. Use a consistent name that makes the intended hardware obvious.

Before publishing a design, preview it at the target canvas size. A slide designed for a wide screen may need different spacing, font sizes, or image treatment on a portrait display.

## Data and Live Content

### Announcements

Announcements are messages that can be sent to selected screens without rebuilding a regular playlist. They are useful for temporary information such as room changes, service notices, event reminders, alerts, or time-sensitive instructions.

An announcement normally includes:

- The message or content to display.
- How long it should remain visible.
- Its visual treatment, such as color or icon.
- The screens that should receive it.

Use an announcement when the message is temporary or targeted. Use a playlist slide when the content is part of the normal repeating experience.

After changing an announcement, connected players receive a refresh and update their displayed state. If a target screen is offline, it will receive the current state when it reconnects and refreshes its content.

Before sending an announcement, verify the target screens and the expiry or display duration. A broad target selection can interrupt many displays at once. Keep urgent messages short enough to read in the available time and use the visual treatment consistently so viewers can distinguish an announcement from normal scheduled content.

### Data Sources

See the [Data Sources guide](guide-data-sources.md) for supported source types, refresh behavior, and troubleshooting.

## Media

Media is added where it is needed in a template or slide. Image and video regions provide their own upload controls, while template backgrounds are uploaded from the template options. An upload in one slide or template is not automatically a reusable selection in every other slide, so add the file to each region or template where it is required.

### Images

Images can be used as template backgrounds or as content in image regions. Supported image formats are PNG, JPG, GIF, WebP, and SVG, subject to the deployment's upload policy.

When adding an image:

- Choose a file that suits the target canvas size and region shape.
- Keep important subjects away from the edges when the region may crop the image.
- Check the crop and scaling in the slide preview before publishing.
- Use a transparent PNG or SVG when the design needs the background to show through.
- Remember that animated image formats may be altered if they are cropped or transformed.

### Videos

Videos can be uploaded into video regions and used in playlists that support live media. The editor accepts MP4, WebM, and Ogg video formats, subject to the deployment's upload policy. Videos preview in their region and loop during playback.

Use a video that the target players can decode reliably, keep the file size appropriate for the available network, and check the first and last frames in the slide preview. If a video is unavailable during playback, review the playlist behavior for unavailable media and the player's connection.

### Template Backgrounds

Template backgrounds are separate from image-region content. A background can be a solid colour, an uploaded image, or a linear gradient. A background image belongs to the template, while an image region belongs to the slide content placed in that region.

### Uploads and Synchronization

Upload limits and allowed image or video types are controlled in [Administration settings](guide-admin.md#media-uploads). A file uploaded in one slide or template is referenced by that content; it is not automatically copied into other slides.

Players receive referenced media through the service synchronization process. A newly uploaded or changed file may need a short time to reach every player, especially when a player is offline. Check the player after synchronization before treating a missing file as a slide-design problem. Remove or replace media only after checking which templates or slides still reference it.

## Operations

### Background Updates

Pulse Signage performs routine work in the background so the web application does not need to wait for every refresh or cleanup operation. This includes refreshing data sources, synchronizing media and fonts, removing expired information, and keeping player state current.

Most background work happens automatically. If content appears stale, use the relevant feature page to check the source or player state first. A player that is offline cannot receive new media, fonts, slides, or commands until it reconnects.

When investigating stale content, check in this order:

1. Confirm the connected client is online and reporting the expected screen.
2. Confirm the screen points to the intended playlist.
3. Confirm the playlist contains the current slide in the expected order.
4. Check the source or asset used by the affected region.
5. Allow time for the player to refresh or synchronize after the change.

The task and system pages can help administrators investigate work that is delayed or failed.

### System Settings and Activity

System settings provide defaults and integrations used across the application. Depending on the deployment, they can include player behavior, announcement defaults, data-source refresh settings, email templates, and external service providers.

Activity history records important account and system changes. It is useful when you need to understand when a setting changed, investigate an unexpected update, or review recent administrative activity.

Change system-wide settings carefully because they can affect multiple screens, users, sources, or players. Use activity history to confirm what changed and when, especially after a display or synchronization problem begins.