# Who plays when: customers and the loop

How loop length, slots, customers and caps decide the turns in a screen's loop, what a gap is, house content, sharing a loop between house, direct and programmatic time, order, and the Loop report that shows it before it plays.

A screen plays its bookings in a loop. Each play of a booking in the loop is a **turn**. A booking asks for a number of turns (its **slots**), and the loop's **length** is how long the whole round takes. By default Mestra plays the bookings as booked, one after another, and nothing here changes that.

If you set rules, Mestra builds each screen's loop from them on the server, before it plays, and sends the screen the finished order. The screen only plays the next turn. It doesn't count or decide anything. You can see the result for any screen in its **Loop report**.

## The four levels

Rules can be set at four levels. Every field starts **Unset**, which means no rule.

| Level                    | Where                                                      | What it sets                                                                                                                                                                                                               |
| ------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Organisation**         | **Settings** > **Loop defaults** (owners)                  | Loop length, default slot length, longest loop, shortest slot, the most any one customer may have, order.                                                                                                                  |
| **Site**                 | **Sites** > **Loop** (owners)                              | The same settings, for the screens at one site.                                                                                                                                                                            |
| **Screen**               | The screen's page > **Loop settings** (editors and owners) | The same settings, for one screen.                                                                                                                                                                                         |
| **Customer and booking** | **Customers**, and the booking                             | A customer's share of the loop, plays an hour, plays a day, and keeping its own ads apart. A booking's own cap, and whether it is house content. A campaign can set a customer, a cap and a daily window for its bookings. |

The first three levels set the same six fields: **Loop length**, **Default slot length**, **Longest loop**, **Shortest slot**, **Most any one customer may have** and **Order**. A screen's own value wins over its site's, and its site's over the organisation's. The screen's page shows where each value came from.

## The rule: screen limits are hard, the most specific wins

- **Longest loop**, **Shortest slot** and **Most any one customer may have** are **hard limits**. Mestra never builds a loop that breaks them, whatever a customer or booking asks for. A booking shorter than the shortest slot is left out (house content is the exception: it is kept), and a customer's total is held to the share limit.
- For a share or a number of plays, the **most specific rule wins**: a booking's own cap, then its campaign's, then its customer's. The screen's share limit is applied on top.
- A customer's category keeps competitors apart: ads of the same category never play back to back.

Nothing is refused when you book because of these rules. A booking shorter than a screen's shortest slot (unless it is house content) can't play on that screen, and the booking dialog says so for each screen. Everything else is worked out when the loop is built, and the Loop report says what it did.

## How a cap becomes turns

Caps are shares of time, and a loop is made of turns, so Mestra turns each cap into a number of turns in the loop.

- A **share of loop** of 50% on a 60 second loop is 30 seconds, so a customer with 10 second ads gets at most 3 turns.
- **Plays an hour** is turns a loop. A loop of 100 seconds plays 36 times an hour, so "at most 60 plays an hour" allows one turn of that ad per loop.
- **Plays a day** is worked out over the longest day the ad is live.

### An example

A screen has a 60 second loop. **Acme** has a share of 50% and keeps its own ads apart. Acme's **A1** (10 seconds) asks for 3 turns and **A2** (10 seconds) asks for 2. **Bolt**, with no cap, books **B1** (10 seconds) for 1 turn.

1. The bookings ask for 60 seconds. Acme's five turns are 50 seconds, which is 83%, over its 50%.
2. Mestra cuts Acme's turns one at a time, from the booking with the most turns, until Acme has 30 seconds, which is 50%: **A1** gets 1 turn and **A2** gets 2.
3. That leaves 20 seconds of the loop to fill. Acme is at its cap, but Bolt has none, so Mestra gives Bolt's **B1** two more turns.
4. Acme's ads are kept apart, so none plays next to another.

The loop, 60 seconds:

<svg viewBox="0 0 624 72" role="img" aria-label="The loop, 60 seconds, six turns of 10 seconds: A2, B1, A1, B1, A2, B1. Acme (A1 and A2) has three turns, none next to another. Bolt (B1) has three." style="width:100%;max-width:640px;height:auto;display:block;margin:1rem 0"><rect x="1" y="1" width="100" height="46" rx="5" fill="currentColor" fill-opacity="0.32" stroke="currentColor" stroke-opacity="0.55"/><text x="51.0" y="29" text-anchor="middle" font-size="15" fill="currentColor" font-family="inherit">A2</text><text x="51.0" y="64" text-anchor="middle" font-size="11" fill="currentColor" fill-opacity="0.7" font-family="inherit">10 s</text><rect x="105" y="1" width="100" height="46" rx="5" fill="currentColor" fill-opacity="0.12" stroke="currentColor" stroke-opacity="0.55"/><text x="155.0" y="29" text-anchor="middle" font-size="15" fill="currentColor" font-family="inherit">B1</text><text x="155.0" y="64" text-anchor="middle" font-size="11" fill="currentColor" fill-opacity="0.7" font-family="inherit">10 s</text><rect x="209" y="1" width="100" height="46" rx="5" fill="currentColor" fill-opacity="0.32" stroke="currentColor" stroke-opacity="0.55"/><text x="259.0" y="29" text-anchor="middle" font-size="15" fill="currentColor" font-family="inherit">A1</text><text x="259.0" y="64" text-anchor="middle" font-size="11" fill="currentColor" fill-opacity="0.7" font-family="inherit">10 s</text><rect x="313" y="1" width="100" height="46" rx="5" fill="currentColor" fill-opacity="0.12" stroke="currentColor" stroke-opacity="0.55"/><text x="363.0" y="29" text-anchor="middle" font-size="15" fill="currentColor" font-family="inherit">B1</text><text x="363.0" y="64" text-anchor="middle" font-size="11" fill="currentColor" fill-opacity="0.7" font-family="inherit">10 s</text><rect x="417" y="1" width="100" height="46" rx="5" fill="currentColor" fill-opacity="0.32" stroke="currentColor" stroke-opacity="0.55"/><text x="467.0" y="29" text-anchor="middle" font-size="15" fill="currentColor" font-family="inherit">A2</text><text x="467.0" y="64" text-anchor="middle" font-size="11" fill="currentColor" fill-opacity="0.7" font-family="inherit">10 s</text><rect x="521" y="1" width="100" height="46" rx="5" fill="currentColor" fill-opacity="0.12" stroke="currentColor" stroke-opacity="0.55"/><text x="571.0" y="29" text-anchor="middle" font-size="15" fill="currentColor" font-family="inherit">B1</text><text x="571.0" y="64" text-anchor="middle" font-size="11" fill="currentColor" fill-opacity="0.7" font-family="inherit">10 s</text></svg>

The darker turns are Acme's, the lighter ones Bolt's.

Acme has 30 seconds (50%) and its ads are never next to each other, including from the end of one loop to the start of the next. The Loop report says: A1 asked for 3 turns and got 1, "Held to 50% by Acme's cap"; B1 asked for 1 and got 3, "Filled 2 turns".

## Filling a short loop

When the loop is shorter than its length, or a cut leaves a hole, Mestra fills it in this order and never relaxes a rule to do so:

1. **Another paid booking** that can take one more turn without breaking any of its caps, the screen's limits or the keeping apart. It picks the one furthest under its cap. A booking with no cap anywhere counts as having the whole loop to spare.
2. **House content**, turn about.
3. **A gap**, only when nothing else may play.

If you set no loop length, nothing is added to reach a length. A paid ad that on one turn still breaks a cap lengthens the loop with house content, then gaps, rather than being left out. If you set a loop length, that ad is left out instead, and the Loop report says so.

## What a gap is

A gap is a turn that shows the screen's stop show for the length of a slot. It is the loop saying that nothing was allowed to play. You can fill gaps by booking more content, adding house content, or loosening a cap. The Loop report counts every gap and says why it is there.

## House content

House content is your own content, such as a menu or a brand film, that fills what paid bookings leave. Book it like any other file and choose **House** instead of **Paid**. A house booking has no customer and no cap. If the loop is over-booked, house turns go first, before any paid turn is cut.

## Order

**Order** is how the turns of a loop are arranged. Unset, the loop plays as booked: each booking's turns together, in booking order.

| Order          | What it does                                                                            |
| -------------- | --------------------------------------------------------------------------------------- |
| **As booked**  | Each booking's turns together, as today.                                                |
| **Spread out** | Each booking's turns are spaced as evenly as the loop allows.                           |
| **Shuffled**   | A mixed order that is the same on every machine, and changes from one loop to the next. |

Caps and keeping apart hold in every order, and across the end of one loop and the start of the next. Mestra picks no order for you.

## A campaign's dates and window

A campaign's dates and daily window clamp its bookings when they play. Nothing is refused at booking time. A booking that falls outside its campaign's hours says **Outside its campaign's hours** on the **Bookings** page.

## Sharing a loop between house, direct and programmatic

A **loop split** says how the time of every loop is shared between three kinds of content, as whole percentages that add up to 100:

- **House**: your own content, as above.
- **Direct**: the bookings, under every rule on this page.
- **Programmatic**: time kept for programmatic buying.

The programmatic share also has an **auction share**: the percentage of it sold at [auction](https://withmestra.com/docs/network/budget-campaigns/#auction) rather than at your fixed programmatic price. It is 0 until you set it.

An owner or admin sets the split for the whole network on Mestra Network's **Settings** page, and can give a single site its own split on that site's page. A site's own split wins over the network's. Each share is a share of time, so a split needs a **loop length** on the screen: without one, the split can't apply and the screen's loop is built as if there were no split.

### Unsold direct time

Time in the direct share that no booking fills goes where the network chooses:

- **Programmatic**: it joins the programmatic share.
- **House content**: house content plays in it.
- **The bookings already playing (smart fill)**: extra turns go to bookings that can take them, as smart fill does without a split. This is also what a site with its own split uses when the network has none.

### What plays in each share

- **Direct** time is bookings. Every cap, limit and keeping-apart rule still holds, and a booking never gets more turns than smart fill allows inside the direct share.
- **Programmatic** time is made of turns that each last the site's **default slot length**. Mestra decides which ad plays in each one, just before it plays (see [Ad turns](https://withmestra.com/docs/player/ads/)). With no ad, a programmatic turn shows the site's house **images** in turn, each held for the slot length, or the stop show for the slot length if the site has no house image. House videos don't play in programmatic turns.
- **House** time is filled with house content as usual.

The three shares are spread through the loop, not played in blocks, so each programmatic turn lands about where an even share would put it. The auction share is spread the same way through the programmatic turns, so a share of 30 gives about three auction turns in every ten.

### The auction share

Set **Sold at auction (% of programmatic time)** with the other shares, for the whole network or for a single site. A site with its own split has its own auction share, and one that starts its own split begins with the network's. A change starts when you save it or from the time you pick, never changes plays already made, and shows in the list of changes waiting to start. An older form or an assistant that leaves the auction share out keeps what is set. A share of 0 is no auction, and 100 is auction only. See [Auction](https://withmestra.com/docs/network/budget-campaigns/#auction).

### When a split starts, and when it waits

- A split starts from the moment it is saved, and plays already made are never changed. You can also pick a time to start from, and see and cancel a change that has not started yet. It takes effect on the screens when that time arrives.
- A split **never takes a turn away from a booking**. If a screen's bookings already take more time than the direct share, the split waits on that screen: the loop is built as it would be without a split, the Loop report says "The loop split waits here" with the seconds booked and the seconds in the share, and the split starts once the bookings fit. The site's page in Mestra Network lists those screens, and the Settings page lists the sites where it waits.
- With **no slot length** set, there are no programmatic turns, and that time is house content. The site's page says so.
- Screens on **Doohly or Broadsign** aren't planned by Mestra yet. A split saved for their site is kept, but isn't applied there, and the site's page says so.

A guaranteed campaign also holds turns in the direct share, which count as booked time like any booking (they never push one out). Mestra decides those the same way. Each screen needs Mestra Player 1.4.0 or later to play decided ads; an older screen plays house content in programmatic turns.

## The Loop report

Open a screen and select **The loop**. It shows what the loop will do for the next 7 days, built the same way the screen builds it, so you can check it before anything plays. For each set of bookings that are live together it shows:

- when that set is live, and the loop length, gaps included;
- the order of turns, with a gap marked **Gap**, a programmatic turn marked **Programmatic** and a held turn marked **Held for** its campaign;
- for each booking: its customer, the turns it asked for, the turns it got, and why they differ;
- the notes: what was cut, what was left out, what was filled and what was added;
- when a loop split is in force: where it came from (the site or the network), the time each share takes, and whether it is held or waiting.

If a screen has no rules and no customers, the report says the screen loops its bookings in order. If there is more than one order, the report shows the first and lets you page through the rest. **Plan live at** shows the plan that is live at a chosen time.

A loop so long that its plan cannot be sent to a screen (a 24-hour loop of one-second ads, say) is not planned: the screen shows its stopped picture for that set, and the report says "This loop is too long to plan: shorten the loop length or use longer slots". A screen that is in a group plays the group's loop, so its settings are the group's, set on the group's page.

The report shows the current build. A change to a rule or booking reaches the screens the way any booking does.

## Who can do what

- **Reviewers** read the Loop report and the customers. They can't read the loop settings.
- **Editors** set a screen's own loop settings, make and change customers, and set a booking's customer, priority and cap.
- **Owners** also set the organisation's and sites' loop settings.

## Do the same from an assistant or the API

An assistant connected with a Screens permission can read customers, set a customer's rules, read the loop settings and the Loop report, and set loop settings. See [Mestra Player tools](https://withmestra.com/docs/mcp/tools/#mestra-player-screens). The routes are in the [Loop API](https://withmestra.com/docs/api/loop/) and the [Customers API](https://withmestra.com/docs/api/screen-customers/).
