Release v2.15.2

docs/user/guide-web.md

@@ -199,19 +199,80 @@ A playlist is the sequence a screen plays. It controls which slides appear, the
 
 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:
+#### Building 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.
+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 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.
+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.