<chapter><title>Playlist core</title>

<sect1><title>Concepts</title>

<sect2><title>Overview</title>

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.

</sect2>

<sect2><title>Views</title>

The predefined views are :

<itemizedlist>

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

<listitem><para>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:</para>

<itemizedlist>

<listitem><para>SAP items</para></listitem>
<listitem><para>Audio CD if detected</para></listitem>
<listitem><para>imported playlists</para></listitem>

</itemizedlist>
</listitem>

<listitem><para>The "all items" flat view contains all items without any hierarchy</para></listitem>

<listitem><para>Sorted views (Sorted by author, with a node per author, ...)</para></listitem>

</itemizedlist>

</sect2>

<sect2><title>Who uses this ?</title>

<sect3><title>Services discovery modules</title>

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), ...).

</sect3>

</sect2>

</sect1>

<sect1><title>How does the playlist work</title>

<sect2><title>Process overview</title>

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

<itemizedlist>

<listitem><para>If a request is triggered by an action on the playlist,
stop the current item and process the request</para></listitem>

<listitem><para>If the current item has finished, stop it and go to next
item</para></listitem>

</itemizedlist>

</sect2>

<sect2><title>Data structures</title>

<sect3><title>View</title>

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

</sect3>

<sect3><title>Item</title>

<para>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).</para>

<para>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.</para>


<para>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 <code>item_parent_t</code> structure
that contains the view identifier, and the parent _in this view_.</para>

<para>The <code>i_flags</code> 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.</para>

<para>The <code>i_serial</code> 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.</para>

</sect3>

</sect2>

<sect2><title>Controlling the playlist</title>

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

<para>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.</para>

</sect2>

<sect2><title>Selecting an item</title>

<para>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.</para>

<para>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, ...).</para>

<para>All item selection is made in
<code>src/playlist/playlist.c</code>, function NextItem.</para>

<para>The playlist object contains two fields dedicated to this, status
and request.</para>

<para>This process uses tree walking functions in
<code>src/playlist/view.c</code>.</para>

</sect2>

</sect1>

</chapter>
