+ *
+ * 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.
+ *
+ * In the playlist itself, there are two trees, that should always be kept
+ * in sync. The "category" tree contains the whole tree structure with
+ * several levels, while the onelevel tree contains only one level :), ie
+ * it only contains "real" items, not nodes
+ * For example, if you open a directory, you will have
+ *\verbatim
+ * Category tree: Onelevel tree:
+ * Playlist Playlist
+ * - Dir - item1
+ * - Subdir - item2
+ * - item1
+ * - item2
+ *\endverbatim
+ * The top-level items of both tree are the same, and they are reproduced
+ * in the left-part of the playlist GUIs, they are the "sources" from the
+ * source selectors. Top-level items 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 = ...
+ *
+ * Category tree Onelevel tree
+ * - playlist (id 1) - playlist (id 3)
+ * - category 1 (id 2) - foo 2 (id 8 - input 2)
+ * - foo 2 (id 6 - input 2) - media library (id 4)
+ * - media library (id 2) - foo 1 (id6 - input 1)
+ * - foo 1 (id 5 - input 1)
+ * \endverbatim
+ * Sometimes, an item must be transformed to a node. This happens for the
+ * directory access for example. In that case, the item is removed from
+ * the onelevel tree, as it is not a real item anymore.
+ *
+ * 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.
+ *
+ * If you want more control (like, adding the item as the child of a given
+ * node in the category tree, use playlist_BothAddInput. You'll have to provide
+ * the node in the category tree. The item will be added as a child of
+ * this node in the category tree, and as a child of the matching top-level
+ * node in the onelevel tree. (Nodes are created with playlist_NodeCreate)
+ *
+ * Generally speaking, playlist_NodeAddInput should not be used in newer code, it
+ * will maybe become useful again when we merge VLM;
+ *
+ * To delete an item, use playlist_DeleteFromInput( input_id ) which will
+ * remove all occurrences of the input in both trees
+ *