Overview
Sub-playlists let you control how media groups rotate inside a main playlist. Using Max Items, Max Time, and the Repeat Items option, you can precisely define how long each sub-playlist plays before the player moves on to the next one.
This article walks you through five practical examples, starting from the simplest setup (no limits at all) and building up to more advanced combinations. Each example uses the same data, so you can clearly see how each new setting changes what plays on screen.
Glossary
- Max Items: The maximum number of media items the player will show from a sub-playlist before switching to the next one.
- Max Time: The maximum total playback time allowed for a sub-playlist before the player switches.
- Repeat Items: When enabled, the sub-playlist loops its content from the beginning if it finishes all items before reaching a configured limit.
Playback Rules — Quick Reference
Before jumping into the examples, keep these rules in mind. They apply to every scenario below.
- The player evaluates Max Items and Max Time independently. Whichever limit is reached first triggers the switch.
- When a limit is reached, the player switches back to the main playlist and moves to the next sub-playlist.
- When the player returns to a sub-playlist, it resumes from where it left off and not from the beginning. The only exception is when Repeat Items is enabled, and the sub-playlist finishes all its content without hitting any limit, in which case it starts over.
- The player never partially plays a media item. If the remaining allowed time can’t fit the next item in full, that item is skipped entirely.
- The Repeat Items option only activates when a sub-playlist finishes all its content before reaching any configured limit.
Quick Cheat Sheet
Use this as a quick reference when deciding how to configure your sub-playlists.
| Configuration | Best For | What Happens |
|---|---|---|
| No limits | Simple alternation | Each sub-playlist plays all its items, then switches. Every loop is identical. |
| Max Items only | Controlling item exposure per rotation | Switches after N items, regardless of how long they take. |
| Max Time only | Equal screen time per group | Switches after the time cap; items that don’t fit the remaining time are skipped. |
| Max Items + Max Time | Precise control over both count and duration | Whichever limit is reached first triggers the switch. |
| Repeat Items enabled | Filling a time slot without gaps | Loops content from the beginning until the time limit is reached. |
ℹ️ When Repeat Items activates: The sub-playlist finishes all its items → no limit has been reached yet → Repeat Items is ON → playlist restarts. If a limit has already been reached, the Repeat Items is ignored.
Example 1: Two Sub-Playlists, No Limits
The simplest setup. Use this when you want two groups of content to alternate without any time or item constraints, for example, rotating between global marketing content and local announcements. With no limits set, both sub-playlists play all their items in full before switching. Every loop is identical.
Example 2: Two Sub-Playlists With Max Items Limits
Now we add a Max Items limit to each sub-playlist. This is useful when you want to control exactly how many items from each group play per rotation, for example, show 1 featured promo, then 2 informational slides, then repeat. The player switches as soon as the item count is reached, regardless of how long those items took.
Example 3: Two Sub-Playlists With Max Time Limits
Max Time controls how long each sub-playlist plays, not how many items it shows. This example uses a 25-second budget on both sub-playlists. Pay close attention to two things: what happens when the next asset doesn’t fit in the remaining time, and what happens to an asset that’s longer than the limit itself. It will never play.
Example 4: Two Sub-Playlists With Max Items and Max Time Combined
The most advanced limit setup has both Max Items and Max Time active on each sub-playlist, but with different values. The key principle here: whichever limit is reached first triggers the switch. The two limits compete on every visit, and the stricter one always wins. This gives you precise control over both the number of items and the time spent, but it also produces the most varied playback pattern across loops.
💡Note: Sub-Playlist B’s Max Time here is 30s, not 25s, which is why B3 can fit in Loop 3.
Example 5: Repeat Items Enabled With Max Time Limits
This is where the Repeat Items option comes into play. Use it when a sub-playlist has short assets that need to fill a longer time window without leaving gaps. Instead of switching back early once all items have played, the player loops the content from the beginning and keeps going until the time limit is reached. The result: the full screen time budget is always used.
Common Misconfigurations
These are the most common ways the player behaves differently from what you might expect. Click each one to see the explanation.
Expecting Repeat Items to always loop content
Repeat Items only activates when a sub-playlist finishes all its items before reaching a configured limit. If a limit (Max Items or Max Time) is reached first, the player switches immediately; therefore, the Repeat Items plays no role.
Expecting a long asset to play even when time is almost up
The player never partially plays a media item. If the next item’s full duration doesn’t fit within the remaining Max Time window, that item is skipped entirely, and the player switches. This prevents partial playback and blank frames, but it also means an asset that’s longer than the Max Time setting will never play in that sub-playlist.
Expecting a sub-playlist to restart from Asset 1 on every visit
When the player returns to a sub-playlist, it resumes from the next item and not from Asset 1. This is intentional: it ensures all your assets get screen time over time, rather than the first asset always playing and the last ones rarely showing up.
Setting Max Time without accounting for asset durations
If any of your assets are longer than your Max Time setting, they will never play. Always make sure your longest asset is shorter than your Max Time limit. If you want to guarantee a certain number of items always play, use Max Items instead because it’s more predictable when asset durations vary.
Important Playback Notes
No partial plays
The player never cuts a media item short. If it can’t play the next item in full, it skips it. This prevents blank frames and abrupt interruptions on screen.
Resume, don’t restart
Every time the player returns to a sub-playlist, it resumes from the next unplayed item and not from the beginning. This ensures all your content gets fair screen time across loops.
Nested sub-playlists
A sub-playlist can contain another sub-playlist. If a parent sub-playlist has Max Items = 1 and contains a nested sub-playlist, the player treats the entire nested sub-playlist as a single item. All the media inside it plays before the parent’s limit is applied.
Timing buffer tip
Small transition delays between media items can accumulate over time, reducing the effective available time within a Max Time window. If you’re using Max Time and need a predictable number of items to always play, add a small buffer to your time setting, roughly 1 extra second for every 5 media items expected to play per visit.
Need Help?
The Yodeck Support Team can help you out! Log in to your Yodeck account and send us a message from the bottom right corner!
