> For the complete documentation index, see [llms.txt](https://unknown-56-works.gitbook.io/luigiscreen/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unknown-56-works.gitbook.io/luigiscreen/control-studio/events-automation.md).

# Events, Groups and Schedules

## Creating an event in Web Studio

Open **Events** in Web Studio.

Fast path:

1. Press **Create event**.
2. Open the event card.
3. Add steps on the right side of the builder.
4. Pick a target screen under **Run this event**.
5. Press **Start event**.

An event is a temporary takeover. It interrupts the target screen, plays its timeline in order, and then returns the screen to its normal playlist or direct source.

## Event builder

The Web Studio event builder is intentionally direct:

| Control              | What it does                                                                  |
| -------------------- | ----------------------------------------------------------------------------- |
| **Add step**         | Immediately writes a new step into the event                                  |
| **Save step**        | Updates the selected step type, media value, text, duration and enabled state |
| **Delete** on a step | Removes that step immediately                                                 |
| **Duplicate**        | Copies the whole event before experimenting                                   |
| **Delete event**     | Removes the event from configuration                                          |
| **Start event**      | Plays the event on the selected screen                                        |
| **Stop event**       | Ends the active event on the selected screen                                  |

Adding a step does not use the global draft/publish flow. The builder saves the step immediately so new users do not have to understand YAML or staging before they can test an event.

Click an existing step to open the inspector. The top **Edit step** block saves common changes directly: switch between media, text, countdown and wait/hold, change the selected media value, edit the text, change duration or enable and disable the step.

Advanced step fields such as conditions are still available lower in the inspector through the Stage/Publish flow.

The default starter event still contains a short text announcement and an operator wait. Delete those steps if you want to start from a blank timeline.

## Event priority

```yaml
events:
  normal_announcement:
    priority: 30
  emergency_message:
    priority: 100
```

A higher-priority event may interrupt a lower-priority event. A lower-priority event is rejected while a higher-priority event controls that screen. The reason appears in playback history.

## Step types

Media types `rtmp`, `mjpeg`, `video`, `image`, `url-image`, `gif`, `folder`, `text` and `countdown` work in event sequences.

Control step types:

| Type           | Fields                                 | Behavior                                       |
| -------------- | -------------------------------------- | ---------------------------------------------- |
| `wait`         | `duration`                             | keep current visual and wait                   |
| `wait-manual`  | `text`                                 | hold until an operator presses Resume/Next     |
| `wait-viewers` | conditions                             | retry until viewer conditions pass             |
| `wait-stream`  | none                                   | retry until the selected screen source is live |
| `command`      | `command`                              | run one command as console                     |
| `broadcast`    | `message` or `text`                    | send a server broadcast                        |
| `sound`        | `sound`                                | play a Bukkit sound to online players          |
| `title`        | `text`                                 | show a title to online players                 |
| `group`        | `target`, `action`, `value`            | control a screen group                         |
| `branch`       | `then-event`, `else-event`, conditions | jump to another event                          |

Example:

```yaml
events:
  update_reveal:
    priority: 80
    sequence:
      countdown:
        type: countdown
        text: "Update starts soon"
        duration: 10s
      wait_for_obs:
        type: wait-stream
        duration: 1s
      live:
        type: rtmp
        value: "rtmp://127.0.0.1:55556/screen"
        duration: 5m
      operator:
        type: wait-manual
        text: "Waiting for operator"
        duration: 1s
      finish:
        type: broadcast
        message: "The reveal has finished."
        duration: 1s
```

## Branching

```yaml
      choose_path:
        type: branch
        conditions:
          min-viewers: 10
          tps-above: 18
        then-event: crowded_live
        else-event: backup_trailer
```

The branch starts the target event from its first step. Missing target events are recorded in the playback reason instead of crashing the scheduler.

Avoid branches that loop forever without a wait or finite media step.

## Screen groups

Click **Create Screen Group** and answer:

```
arena arena_left,arena_center,arena_right
```

The group page can start, stop or return all members to their own automation. Group event/source steps execute in the same server tick, which provides practical synchronization. Screens using the exact same source also share one loader.

Group step example:

```yaml
      global_return:
        type: group
        target: arena
        action: return
        duration: 1s
```

Supported group actions are `start`, `stop`, `return`, `playlist` and `event`.

## Automation builder

Open **Automations** in Web Studio when you want LuigiScreen to do something at a server time without typing YAML.

Fast path:

1. Press **Create rule**.
2. Open the new automation card.
3. Set **WHEN** to the server time.
4. Pick a target screen or screen group.
5. Pick the **THEN** action.
6. Press **Save rule**.

An automation rule is intentionally written like a small sentence:

```
WHEN 20:00
IF every configured day
THEN event cinema_night on cinema
```

Supported actions:

| Action     | Value       | Behavior                                |
| ---------- | ----------- | --------------------------------------- |
| `event`    | event id    | starts a temporary event takeover       |
| `playlist` | playlist id | assigns and starts a playlist           |
| `start`    | none        | starts the target screen                |
| `stop`     | none        | stops the target screen                 |
| `return`   | none        | returns the target to normal automation |

The builder has direct controls:

| Control         | What it does                                                 |
| --------------- | ------------------------------------------------------------ |
| **Save rule**   | Writes the selected time, target, action and conflict policy |
| **Run now**     | Executes the rule immediately, ignoring the clock            |
| **Duplicate**   | Copies the rule before experimenting                         |
| **Delete rule** | Removes the rule from configuration                          |

Creating, saving, duplicating and deleting automations does not use the global draft/publish flow. It writes directly so new operators can test a rule without learning the raw config first.

While a rule is open, unsaved changes are kept in a local browser draft. Live Studio refreshes can still update the rest of the page, but they should not reset the time, target, action or value you are editing. The dropdown fields use the bundled Choices.js picker, so long screen, group, event or playlist lists are searchable. When a picker is open, moving the mouse over choices pauses visual rerenders briefly so the dropdown does not disappear before you click an option.

Rules created in Web Studio run every day by default. Edit `days` in `studio.yml` when a narrower recurring calendar is needed.

```yaml
schedules:
  friday_cinema:
    enabled: true
    days: [FRIDAY]
    time: "20:00"
    target: cinema
    action: event
    value: cinema_night
    priority: 50
    conflict: priority
```

Automations sharing time, target and at least one day are marked as conflicts. At runtime the highest priority wins. A lower automation is skipped unless its `conflict` policy is `allow`.

## Audience voting

Live Control can start a 60-second vote using up to three valid media files.

Players vote with:

```
/screen vote <screen> <option>
```

Operators can also use:

```
/screen vote start <screen> [option1 option2 ...]
/screen vote status <screen>
/screen vote end <screen>
```

One vote is stored per player. Changing a vote subtracts the previous choice. The voter needs `luigiscreen.vote`, must be in the screen world and must be within `voting.distance` from the screen. The winner is queued when voting ends.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://unknown-56-works.gitbook.io/luigiscreen/control-studio/events-automation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.