# Playlist core

## Concepts

### Overview

VLC's playlist now features a tree system, with a notion of several views. Each view comes with a new tree. Items can be shared between views. Items can become internal nodes.

### Views

The predefined views are :

- The "simple" view which only contains the "manually added" items (either added through command line, either through command line). It can contain a hierarchy.

- The "category" view contains a "General" node that is exactly like the "simple" view. It can also contains several types of items (generally, "autodiscovered". Examples are:

  - SAP items

  - Audio CD if detected

  - imported playlists

- The "all items" flat view contains all items without any hierarchy

- Sorted views (Sorted by author, with a node per author, ...)

### Who uses this ?

#### Services discovery modules

A new type of modules has been created, the services_discovery modules. Their goal is to add items to the playlist (SAP listener, HAL (Hardware Abstraction Layer), ...).

## How does the playlist work

### Process overview

On startup, a playlist thread is started. It starts an infinite loop, always searching for something to do.

- If a request is triggered by an action on the playlist, stop the current item and process the request

- If the current item has finished, stop it and go to next item

### Data structures

#### View

Each view is identified by an identifier. It also contains a pointer to the root item.

#### Item

An item can be either a leaf node (which can be played) or an internal node of the tree (can not be played directly, but contains children).

You can know if an item is a leaf or internal node by looking at i_children. If i_children is -1, then it is a leaf node, else it contains the number of children, available in pp_children.

As items can be common to several views, we need to remember for each the parent in each view. That's why each item includes the pp_parents array. Each one is an `item_parent_t` structure that contains the view identifier, and the parent _in this view_.

The `i_flags` is a bit array used to know whether an item is to be saved, whether the playlist can continue after playing this item (which is generally not the desired behaviour for SAP items, fe), whether it is enabled, and whether it must be deleted after being played.

The `i_serial` field is increased on each change of the children, if the item is an internal node. The goal is to allow interfaces to update in a clever way, by only rebuilding nodes that have changed.

### Controlling the playlist

The playlist can be controlled using playlist_Control. It takes a query identifier, and a variable number of arguments.

When a control is made, the "request" field of the playlist is set to true, which causes the current item to be stopped. If needed, a new item is then selected.

### Selecting an item

Different rules apply for selection of items, if a request has been made or if it is an "automatic" change, after an item has finished.

If there a request, the item is always selected if possible (if you selected a node, it will play the first available child), else, some more rules will apply (play-and-stop, random, repeat, ...).

All item selection is made in `src/playlist/playlist.c`, function NextItem.

The playlist object contains two fields dedicated to this, status and request.

This process uses tree walking functions in `src/playlist/view.c`.