pulse-signage/docs/user/guide-web.md

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.

Use Edit default content to set a region's starting content with the same type-specific editor used on slides, including the rich-text editor for text. Slides use these defaults until a slide-specific value is saved. Select Read-only on slides for fixed content such as a logo, footer, or branded label; it remains visible in previews and playback but is omitted from the slide editor and ignores saved slide overrides. Read-only regions can still be changed in the template editor.

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: a reusable image in the media library. The editor supports PNG, JPG, GIF, WebP, and SVG images, with optional crop, rotate, flip, and zoom tools that leave the original unchanged.
• 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. 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 provide the starting design.

Choose Adjust layout beside the preview to open the large layout modal and adjust this slide only. Select a region on the canvas or in the region dropdown, drag its edges, or enter exact X, Y, width, and height values in canvas pixels. Set Z-Index to change stacking order and Lock ratio to constrain resizing. Arrow keys move the selected region by one pixel; Shift plus an arrow moves it by ten.

The slide and template editors share position, size, stacking, and ratio controls, along with matching region outlines and labels. Choose Adjust animations for a separate animation popup with the template's presets and advanced duration, delay, and repeat settings. Use Intro, Outro, and Attention to preview those animations on the slide canvas. Reset region animations to template resets the selected region; Reset all animations to template clears every slide animation override. Apply to this slide keeps changes in the slide draft; Cancel discards them. Users with template-edit permission can choose Save animations to shared template from the adjacent save menu. That action confirms the number of affected slides, updates shared template animations, and clears animation overrides from the current slide so it inherits the template again. Other slides' explicit animation overrides and unsaved slide content are preserved. Existing animation settings are also preserved when adjusting placement. Region names and types are defined by the template.

Both layout editors offer Snap to guides for alignment with the canvas edges, centers, and other regions. Hold Alt while dragging to bypass snapping. The slide workspace also provides undo and redo. Reset region to template and Reset all to template remove local overrides so those regions follow the template again. Apply to this slide keeps adjustments in the slide draft; save the slide to publish them. Cancel discards changes made during that layout session.

Users with template editing permission can choose Save layout to shared template from the arrow beside Apply to this slide. Confirmation shows how many slides use the template. This saves the current position, size, stacking order, and ratio settings immediately without saving unsaved slide content or changing template animations. The current slide's geometry overrides are cleared so it inherits the saved layout, while explicit animation overrides are retained. Other slides keep their own overrides. Saving an existing slide's layout this way also requires slide editing permission.

If the shared template changed while the layout editor was open, the shared save is rejected and the draft remains available. Reload the slide after preserving any unsaved content before trying again. A failed save or cancelled confirmation leaves the current layout draft unchanged.

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.

Building a Playlist

1. Choose the playlist's canvas size and give the playlist a recognizable name.
2. Choose Add slide in the Playlist items header, select the slides, and add them. Slides must match the playlist's canvas size. The same slide can only be assigned once to a playlist; use a Repeat group when it needs to play multiple times.
3. Use the drag handle or up/down arrows to arrange the slides. You can also organize slides into groups as described below.
4. Review each slide's duration, audio settings, and schedule.
5. Configure transitions and the handling of unavailable live streams where appropriate.
6. Save the playlist before checking the player. Unsaved editor changes do not affect playback.

The player works through the playlist from top to bottom, then starts another playthrough. Groups stay in their assigned position; their mode determines which members play at that position.

Slide Playback Controls

• Duration: enter the time in seconds. Numeric values can include fractional seconds, such as 8.341. Use longer durations for text-heavy slides and shorter durations for simple notices.
• Video duration: on supported video slides, the camera icon toggles using the video's duration instead of a manually entered duration.
• Audio: use the speaker/mute button to enable or disable the slide's audio.
• Schedule: configure when that playlist slide is eligible to play. A slide without schedule rules is always eligible unless its group schedule restricts it.

A transition changes how one slide gives way to the next; it does not change the region animations inside either slide.

Creating and Organizing Groups

Choose New group, to the left of Add slide, to create a group. Enter its name and drag slides into the blank, colour-matched area beneath the header. The empty area disappears when the group has members and returns if its last slide is moved out. Add at least one slide before saving if you want to retain the group; empty groups are not saved.

Group headers and their members share a colour, with alternating shading between member rows. The colours help distinguish groups and do not affect playback.

Use a group's drag handle or arrows to move the whole group, including its members. Drag individual slides to reorder them within a group, move them to another group, or move them outside groups. Removing a group leaves its member slides in the playlist as standalone slides.

The Order column numbers groups as top-level playlist entries. For example, group 8 contains slides 8.1, 8.2, and so on; the next standalone slide or group is 9. These labels update automatically when you move items.

Pick and Repeat Modes

The Pick / Repeat selector sits immediately after the group name. The Playback column shows the controls for the selected mode. Switching modes remembers the settings for both modes.

Pick selects a specified number of eligible members on each playlist playthrough:

• Set Pick from 1 to the number of slides in the group. The maximum updates as slides are added or removed. The input is disabled while the group is empty.
• With the double-chevron button shown, selection follows the group's editor order and wraps around to the beginning when needed.
• Toggle that button to shuffle arrows for shuffled selection and playback order. A selection stays fixed for the current playthrough; the next playthrough makes another selection. A slide can be selected on consecutive playthroughs, but it is not selected twice within the same group's selection on one playthrough.
• The player fills the Pick count whenever enough members are schedule-eligible. If fewer are eligible, only those available members play; unavailable slides are not used to fill the count.

For three eligible members in editor order A, B, C:

Settings	First playthrough	Second playthrough	Third playthrough
Pick 1, ordered	A	B	C
Pick 2, ordered	A, B	C, A	B, C
Pick 2, shuffled	For example: C, A	For example: A, B	For example: C, A

Shuffled results are illustrative, not a guaranteed sequence or a promise that every member will play before another repeats. Selection is calculated by the player; restarting it or applying a playlist update resets its playthrough tracking. Changes in schedule eligibility can also change which members are selected.

Repeat plays the entire eligible group in editor order, a specified number of times, before continuing to the next playlist entry:

• Set Repeat from 1 to 100. This is the total number of passes through the group, not a count of additional repeats.
• Pick and shuffle controls are hidden and do not affect Repeat playback.
• For A, B, C with Repeat 2, playback is A, B, C, A, B, C, then the next playlist entry.
• Repeat 1 plays the whole eligible group once per playlist playthrough.

Group and Slide Schedules

Use Schedule on a group header to restrict the whole group. Use Schedule on a member row to restrict that slide independently.

A grouped slide must satisfy both its own schedule and its group's schedule. Within either schedule, multiple rules are alternatives: matching any rule is enough. Within one rule, all configured conditions must match, including any date range, time window, and selected days.

For example, a group scheduled for weekdays from 09:00 to 17:00 and a member scheduled from 12:00 to 14:00 can only show that member on weekdays between 12:00 and 14:00. Pick and Repeat both respect these restrictions.

When a member's schedule has no overlap with the group schedule, the editor shows a Never shown warning. Adjust the slide or group rules so they overlap. If no members are eligible, the group contributes no slides to playback at that time.

Publishing Playlist Changes

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.

After saving, check a screen using the playlist and confirm the intended order, duration, group mode, and schedules. Saved updates are applied by the player at a slide transition rather than interrupting the slide currently playing.

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 for supported source types, refresh behavior, and troubleshooting.

Media

Media is added where it is needed in a template or slide, or directly through the Media Library. Image and video regions provide their own upload controls, while template backgrounds are uploaded from the template options. Use the shared media picker to reuse an uploaded asset in another region or template without uploading another copy.

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.
• Uploads retain the full original, including SVG vectors and animated images. Applying a crop creates a separate image copy for that placement; SVG and animated GIF crops become PNGs, while the original vectors or animation remain available.

Images are uploaded in full. The crop editor opens automatically after an image upload completes or an existing image is selected from the library. It offers a crop box, ratio presets (including Region), rotation, flip, and zoom controls. Choose Edit crop on an image region to reopen it later. Apply crop remembers the original and crop settings; applying an untouched full-image selection keeps it uncropped. Cancel discards a newly selected image and cleans up a new upload if nothing saved uses it. Existing library images are not deleted. When reopening an already applied image, Cancel leaves that previous selection unchanged. Save the slide to retain the changes. Different slides can crop the same original independently. Previously cropped files remain usable, but their missing content can only be recovered by uploading the original again.

Playback images fit the region's pixel dimensions and slide canvas, preserving aspect ratio without enlarging small images. An uncropped original that already fits is used directly, without creating a duplicate file. Larger originals and cropped images get appropriately sized playback copies. Uncropped GIF and WebP copies retain their animation. Saving a larger region or changing its shared template regenerates the copy from the full original when needed. The original file remains unchanged.

Uploaded media synchronization is scoped to each player's client screen assignments and playlists, including last-known assignments for offline clients. Players receive the playback image, not its editing original, unless the original is itself the playback file. This works for direct players and players reached through the bridge. Obsolete player copies are removed when no longer needed by that player; files shared with web storage are retained while the web still needs them. Managed fonts and weather icons keep their separate synchronization rules.

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.

Media Library

The Media Library stores image and video files for reuse across slides, templates, and player content. Search by filename, filter by media type or usage, and sort by name, date, or file size. Results load in batches; use Load more to browse a larger library.

The image, video, and template background editors use the same media picker, so you can select an existing asset instead of uploading another copy. In the Media Library, use selection mode to choose multiple assets for deletion. Assets referenced by slides or templates are marked as in use and cannot be deleted.

Uploads and Synchronization

Upload limits and allowed image or video types are controlled in Administration settings. 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.