> For the complete documentation index, see [llms.txt](https://docs.xibosignage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xibosignage.com/layouts/layouts_editor_playlists.md).

# Playlists

Playlists are used to show a sequence of media items, such as an image slideshow.

There are two ways to create a Playlist:

* Add Playlists directly to a Layout from the Layout Editor. Local Playlists can be converted to be saved for re-use as a global Playlist. Saved Playlists will be shown in the Layout Editor to add to Layouts.
* Create Playlists independently to a Layout. Global Playlists can be scheduled to Displays without the creation of a Layout. Playlists created outside of the Layout Editor are still shown for selection from the Add Playlist function from the Layout Editor.

## Add Playlists

Create new or select existing Playlists to use from the **Layout editor** to create a timeline of content to show on a Layout.

## Feature Overview:

* Create and configure directly on a Layout.
* Convert a Playlist created on a Layout to a Global Playlist to save for future use.
* Easily display a 'slide-show' of content held in one or more Playlists.
* Sync with Playlists on other Layouts which are part of a Synchronised Event.
* Combine content from a variety of Playlists to be shown.
* Set the maximum number of items to be shown from a Playlist.
* Control how long each item on a Playlist should show before moving onto the next item.
* Set Expiry Dates for media items added to a Playlist.
* Play one item per cycle for a specified Play Count.
* Select a Random Widget to play at each cycle.
* Cycle through items contained on a Playlist in the viewer to easily see the sequence.

## Adding Playlists to a Layout

* From the Layout Editor, click on **Add Playlists** from the **Toolbox**:

![Add Playlists](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-6830621f616a1a4adb0dc899f9124a1f810564ca%2Fv4.1_layouts_editor_add_playlists.png?alt=media)

* Click to Add or drag on a **New Playlist** or a named Playlist which has already been created.
* Resize and position:

![Content Synchronisation Key](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-25023330ef13eeef88f544652756a5a946b7e287%2Fv4.1_layouts_editor_synchronisation_key.png?alt=media)

From the **Properties Panel**, use the **Content Synchronisation Key** to sync with Playlists on other Layouts. Playlists with the same key will be synchronised when the Layout is scheduled as a Synchronised Event.

 **Scenario:**

You have a Synchronised Event with 3 Displays and 3 different Layouts. Each Layout has some Text at the top and a Playlist in the middle which all 3 need to play in sync.

You could also set two different Playlists to sync differently which you could set to `sync_1` and `sync-2` for example. {/tip}

* Optionally set **Transitions** for items on a Playlist from the Properties Panel.

{% hint style="info" %}
When default Transitions have been applied, the properties panel will be blank. Only manually entered Transitions will show on forms. Defaults can be overridden by unticking the **Automatically apply Transitions** check box from the Properties Panel for the Layout.
{% endhint %}

* Click the icon in the right hand corner of the Playlist to open the Playlist Editor to add and configure content.

{% hint style="info" %}
The Playlist Editor includes **Spacer** and **Rich Text** Widgets that are only available for use with Playlists.\
Media added to a Playlist can also have Start and End times using Expiry Dates.
{% endhint %}

{% hint style="warning" %}
 If you add a named Playlist which has already been created, any edits made to the Playlist will be applied everywhere the Playlist is being currently used!
{% endhint %}

* Click the **Back** button at the top to exit the Playlist Editor and return to the Layout Editor.

View all the content that has been added to the Timeline of the Playlist by using the arrows in the bottom right of the Playlist on the Layout.

* Cycle through the order of content:

![Preview Timeline Content](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-29303aa6541eaab3bff98e555f1d0d7a84a2e7eb%2Fv4.1_layouts_editor_playlists_preview_content.png?alt=media)

## Convert Playlist

If you add a **New Playlist** to the Layout you can opt to convert this into a saved Playlist. Converted Playlists will be shown for Playlist selection in the Layout Editor and from the Playlists grid.

* Click the Playlist on the Layout to select and give it a **Name** from the **General** tab of the **Properties Panel**.
* Right click and select **Convert Playlist** from the menu.

![Convert Playlist](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-44be470f095417fd964af06a46b4717c86a6a1a9%2Fv4.1_layouts_editor_convert_playlist.png?alt=media)

You will see a pop up message at the bottom of the Layout Editor to say that the Playlist has been saved as a Global Playlist.

{% hint style="success" %}
Click the **Show more** button to see your Playlist added to the list of available Playlists! 
{% endhint %}

Converted Playlists will be saved to the Playlists Grid.

## Add to Playlist

If you have a **New Playlist** on a Layout, you can add a new or global Playlist to the Timeline to open further options in the Properties Panel for configuration:

![Playlist Spots](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-c925989239a2c0c93bc2f099d5bd217e2aef4146%2Fv4.1_layouts_editor_playlist_spots.png?alt=media)

* Select Playlists, Spot Options and Playlist Ordering, when selecting more than one Playlist to Embed from the Properties Panel.

Adding a **Playlist** to a **New Playlist** on a Layout has additional Cycle Based Playback options which includes a Random Widget feature.

{% hint style="info" %}
If you want to add more than one Playlist to combine the play order, we recommend that you should only add one Playlist to the Timeline and then use the options in the Properties Panel to select the additional Playlists and configure.
{% endhint %}

* ### Cycle Based Playback

Once enabled all Playlists selected will be treated as one "list" and will only show one Widget each time the Layout is played, cycling through the content from all Playlists added:

* Tick Enable cycle based playback from the Properties Panel.
* Provide a **Play Count** to determine how many plays each Widget on the Playlist should have before moving onto the next Widget in the timeline.

![Cycle Playback](https://2811002782-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fj0uXhtBdyPyW40TfKTZd%2Fuploads%2Fgit-blob-c4b130b7584e497b6f39dfcdb4d9f6690e025ed8%2Fv4.1_layouts_editor_playlist_cycle_playback.png?alt=media)

Using the **Random Widget each cycle** option will play a Widget from the timeline at random for each cycle.

{% hint style="warning" %}
These additional options are **not** available when adding one or more Playlists to a Global Playlist timeline, which has been added directly to the Layout! 
{% endhint %}

{% hint style="success" %}
Did you know [Playlists](https://github.com/xibosignage/xibo-manual/tree/master/source/en/media_playlists.html) created and managed independently to Layouts do not require further user access rights to Layouts or the Layout Editor to add and manage content!
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.xibosignage.com/layouts/layouts_editor_playlists.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.