+ *
+ * The VLC playlist system has a tree structure. This allows advanced
+ * categorization, like for SAP streams (which are grouped by "sap groups").
+ *
+ * The base structure for all playlist operations is the input_item_t. This
+ * contains all information needed to play a stream and get info, ie, mostly,
+ * mrl and metadata. This structure contains a unique i_id field. ids are
+ * not recycled when an item is destroyed.
+ *
+ * Input items are not used directly, but through playlist items.
+ * The playlist items are themselves in a tree structure. They only contain
+ * a link to the input item, a unique id and a few flags. the playlist
+ * item id is NOT the same as the input item id.
+ * Several playlist items can be attached to a single input item. The input
+ * item is refcounted and is automatically destroyed when it is not used
+ * anymore.
+ *
+ * The top-level items are the main media sources and include:
+ * playlist, media library, SAP, Shoutcast, devices, ...
+ *
+ * It is envisioned that a third tree will appear: VLM, but it's not done yet
+ *
+ * The playlist also stores, for utility purposes, an array of all input
+ * items, an array of all playlist items and an array of all playlist items
+ * and nodes (both are represented by the same structure).
+ *
+ * So, here is an example:
+ * \verbatim
+ * Inputs array
+ * - input 1 -> name = foo 1 uri = ...
+ * - input 2 -> name = foo 2 uri = ...
+ *
+ * Playlist items tree
+ * - playlist (id 1)
+ * - category 1 (id 2)
+ * - foo 2 (id 6 - input 2)
+ * - media library (id 2)
+ * - foo 1 (id 5 - input 1)
+ * \endverbatim
+ *
+ * Sometimes, an item creates subitems. This happens for the directory access
+ * for example. In that case, if the item is under the "playlist" top-level item
+ * and playlist is configured to be flat then the item will be deleted and
+ * replaced with new subitems. If the item is under another top-level item, it
+ * will be transformed to a node and removed from the list of all items without
+ * nodes.
+ *
+ * For "standard" item addition, you can use playlist_Add, playlist_AddExt
+ * (more options) or playlist_AddInput if you already created your input
+ * item. This will add the item at the root of "Playlist" or of "Media library"
+ * in each of the two trees.
+ *
+ * You can create nodes with playlist_NodeCreate and can create items from
+ * existing input items to be placed under any node with playlist_NodeAddInput.
+ *
+ * To delete an item, use playlist_DeleteFromInput( p_item ) which will
+ * remove all occurrences of the input.
+ *
+ *
+ * The playlist defines the following event variables:
+ *
+ * - "item-change": It will contain the input_item_t->i_id of a changed input
+ * item monitored by the playlist.
+ * - "item-current": It will contain a input_item_t->i_id of the current
+ * item being played.
+ *
+ * - "playlist-item-append": It will contain a pointer to a playlist_add_t.
+ * - "playlist-item-deleted": It will contain the playlist_item_t->i_id of a
+ * deleted playlist_item_t.
+ *
+ * - "leaf-to-parent": Set when an item gets subitems and is transformed to a
+ * node. It will contain a pointer to the input_item_t bound to the transformed
+ * playlist item.
+ *
+ *
+ * XXX Be really carefull, playlist_item_t->i_id and input_item_t->i_id are not
+ * the same. Yes, the situation is pretty bad.
+ *