foo. bar. baz. quux.

Foobar2000:Playlist Tree:Tutorial

From WikiBazQuux

Jump to: navigation, search



Image:Playlist tree cropped.png
A cropped picture of playlist tree in action
As of May 2009, I'm taking down all foobar2000 related files.
As of May 2008, I will no longer be developing foobar2000 components.

I no longer wish to contribute my time to a closed source, single platform app.
Also, certain actions by the foobar2000 developers have lead to my no longer wishing to contribute. These include removing features utilized by developers and users because they dislike they way they are being used and allowing only an elite few access to new API features.
Thank you to loyal users over the past years.
If you are a developer and are interested in taking over development of one of my components, please email me at chris SQUIGGLE bowron SLAM us.

foo_playlist_tree is a powerful tree based media library plugin for foobar2000 that is highly customizable. Playlist Tree allows you to create static hierarchical playlists as well as automatic playlists that can be generated from a large variety of conditions. It also includes an embedded scheme interpreter for playlist generation and scripting.

Known Bugs

  • autorefreshed @playlists queries dont autorefresh the individual playlists
  • rearranging playlists does not refresh @playlists queries
  • Issues with %<tagz>% processing (use the new @scheme feature for complicated multi-value tags)
  • panels can get reordered by modifying layout.
  • Sorting not working correctly for unicode characters
  • Unicode issues in edit dialog
  • @node<> uses display - having sizes in format can cause issues with using @node queries

Not Bugs

  • If you click on the +/- of a node, and no node in the tree has been selected, it will select that node
  • If you have hide lines enabled, the top level nodes will not have +/- buttons. (you can use the left/right arrow keys to expand and contract the nodes)

Feature Requests

  • reimplement @browse_as<>
  • send album art panel selected item
  • ignore nested playlists in drops
  • dropping a file to a @drop'ed playlist adds the file to the actual playlist file too
  • auto refresh @node queries
  • allow criteria in @playlists query (i.e. only playlists with PT: in the name or something) (use a fancy @scheme query)
  • remove duplicates option for sending to library playlist operations
  • reorder queue/playlist by @queue and @playlist query drag and drop reorder
  • refresh @database queries on tag changes
  • global setting to ignore "The" and "a" when sorting
  • option to always have the box checked for 'sort by display name' when creating a new query
  • option to disable drag and drop
  • allow drag and drop to other apps
  • vertical padding options
  • add "[local] menus" in "Selection Action" in main preference, so we would be able to automatically refresh queries when selecting them
  • be able to get the selected playlist items in scheme query

Unlikely Candidates

    • Inline label editting - I think having all editing done in the dialog makes things cleaner and you dont have to worry that what you meant as a double click be interepreted as a label edit.



Note that some of the documentation refers to older version of Playlist Tree.

If you know of a good playlist tree resource such as a tutorial in a language other than English, please post it in one of the above forums and I will add it to this list.

Frequently Asked Questions

How do I load a .col file?

You don't. The collection files that were available from my website are for previous versions of playlist tree. For examples of queries for the current version of playlist tree, please see the examples.

How do I access the playlist tree specific context menu?

By default, you can access the playlist tree menu by middle clicking on a node, or by holding SHIFT while you right click on a node. These can be configured under the mouse and keyboard options in playlist tree.

For Developers

Playlist tree supports notifying other components when the selected node is changed.

class callback_node
   virtual bool   get_entries( pfc::list_base_t<metadb_handle_ptr> & list ) const = 0;
   virtual bool   is_leaf() const     = 0;
   virtual bool   is_folder() const   = 0;
   virtual bool   is_query() const    = 0;
   virtual int    get_entry_count() const = 0;
   virtual void   get_name( pfc::string_base & out ) const = 0; 

class NOVTABLE node_select_callback : public service_base 
   virtual void on_node_select( const callback_node * node ) = 0;


const GUID node_select_callback::class_guid = 
{ 0x9c2ae3c3, 0xdc04, 0x4042, { 0xad, 0xf3, 0x88, 0x84, 0x11, 0x7b, 0x49, 0x55 } };

Embedded Scheme

Beginning with Playlist Tree 3.0.beta0 Playlist Tree contains an embedded Scheme Interpreter using MzScheme. This is intended for advanced users with programming experience. This allows you to build queries in a real programming language. To create a scheme based query, set the "Source" of the query to "@scheme" and the "Format" to the scheme code to evaluate.

The scheme console output functions such as display and write will be directed to the foobar2000 console.

Playlist Tree specific scheme primitives:

  • (for-each-db-entry fn [filter-string] [sort-string])
  • (add-node handle folder-list)
  • (now-playing)
  • (console-print [object1] [object2] ... [objectn])
  • (format-title handle title-format-string)
  • (meta-list handle tag)
  • (for-each-playlist fn)
  • (for-each-playlist-entry playlist-name fn) - first parameter can be playlist name or index
  • (get-subsong-index handle)
  • (get-path handle)
  • (get-length handle) => returns time in seconds
  • (get-file-size handle) => returns size in bytes
  • (for-each-queue-entry fn)
  • (for-each-node-entry node-name fn)
  • (add-query-node label source criteria format [population-order] [sortp] [max-n] [max-type]) => returns a tree-node which can be used in refresh-query, max-type can be one of tree-max-tracks, tree-max-minutes, tree-max-megs, tree-max-subfolders
  • (refresh-query query-node)
  • (handle-apply function path [subsong-index])
  • (file-creation filename) => retusn the file creation in seconds, same scale as the mzScheme (current-seconds) results. more info.
  • (file-last-access filename) => see file-creation
  • (file-last-write filename) => see file-creation
  • (in-library? handle)
  • (handle-test handle filter-string) - e.g. (handle-test handle "rating GREATER 3")
  • (mainmenu mainmenu-fun-string)
  • (playlist-contextmenu contextmenu-fn-string [playlist-index])
  • (contextmenu contextmenu-fn-string handle-list)
  • (playing-playlist)
  • (active-playlist)
  • (find-or-create-playlist name) => returns a playlist-index
  • (add-to-playlist handle [playlist-index] [item-index]) => if no playlist-index is specified, active playlist is assumed.
  • (clear-playlist [playlist-index])
  • (activate-playlist playlist-index)
  • (play-from-playlist [playlist-index] [item-index])
  • (prompt-user-string "foo") - prompts the user for input. Returns a string. "" for cancel.
  • (prompt-user-list "foo" ("option 1" "option 2" ... "option n")) - prompts the user to select from given options - returns zero-based index of selection. -1 for cancel.

See examples here.

For more information on foobar2000 in general or on Columns UI, refer to the official foobar2000 forum or the foobar2000 wiki

The Tree Window

Static Folders

A static folder is a simple recipient where you can store music files, static folders or dynamic folders. To create a static folder, right click on the root, choose New Folder and click Ok in the 'Edit New Folder' window. To add music files to a static folder, simply drag and drop the files from window explorer or from other programs or components.


You can also drag and drop files from other Playlist tree folders if 'Allow local drag and drop' option is enabled in the <Config> section of the Playlist tree preferences. To access the Playlist tree preferences, select Foobar2000/Preferences in the Main menu and choose 'Playlist tree' under 'Components' in the right pane of the Preferences window.

By right-clicking on the folder and choosing Edit..., you can edit the folder name, customize your music files display format (i.e. %artist% - %title%), specify the sort criteria, choose the icons, etc. In the <Folders> preferences, you can also customize the folder name display and the selected folder name display (i.e. %name% - %size%). Here you can use the standard title formatting tags and the playlist tree specific tags

Dynamic Folders

Dynamic folders are one of the main features of Playlist tree. To create a dynamic folder, choose Add Query from context menu. A new node will appear in the tree and a configuration window on the screen. You can always access the configuration window of a dynamic folder through the Edit... command in the context menu.

One of the most common way to use a dynamic folder is to create a database view. Here is a simple example:


The criteria field works as a filter to create a specific subset of your music database. You may include everything in your database by leaving the criteria blank or display only a portion of your music collection, i.e. the files with a valid %rating% field. In this case, insert NOT rating MISSING in the Query field.

Query strings use the syntax of the Playlist Generator plugin (i.e. Query=NOT rating MISSING, Query=title HAS blue). For a detailed description of the syntax rules, please refer to the documentation of the Playlist Generator plugin available in the official foobar2000 forum.


In the Format field, you must write a TAGZ string. For a quick reference of the TAGZ rules, select Display/Titleformatting in the foobar2000's preferences and click the help button. Playlist tree format strings are also backward compatible with Albumlist format strings. You may find many examples of Albumlist format strings in the official foobar2000 forum.

The Max field allows you to limit the number of tracks/minutes/megabites of your query results. For example, if you want to create a 700MB compilation of Pop music, you can set:


  • Determines what data is fed through the query see the appendix entry for more information.

Population Sort Order

  • order to fill the tree, sorts the tracks before adding to tree
  • useful for max criteria stuff
  • if no sorting needed, leave blank
  • @default will use query format as the sort criteria
  • Reverse checkbox allows to invert your sorting order (from higher to lower, from Z to A, etc.)

Refreshing Queries

Since the content of dynamic folders is subject to change, the tree needs to be refreshed periodically. The simplest way to manually refresh the whole tree is to choose Components/Playlist Tree/Root.../Refresh Queries from foobar2000's main menu. You can also assign a keyboard shortcut to this function in the Core/Keyboard Shortcuts section of the foobar2000 preferences.

Alternatively, if you want to refresh a folder and its subfolders, right-click on the folder and choose Refresh from context menu.

Automatic Refresh

Choosing the automatic refresh option on a query makes playlist tree refresh the query when necessary. The effect is different depending on the query type.

  • $playing query - Automatic refresh will refresh the query whenever a new track starts to play.
  • @playlist<> query - Automatic refresh will refresh the query when the playlist is modified.
  • @playlists<> query - Automatic refresh will refresh whenever a playlist is added or deleted.
  • @queue query - Automatic refresh will refresh whenever an item is added or removed from the playback queue.

When using automatic refresh with the @playlist or @queue queries, there is also another effect. Dropping an item onto a @queue query will add that item to the playback queue, then refresh the query so that the subfolder structure is maintained correctly. Dropping items onto a @playlist query, will add the items to the source playlist, then refresh the query so that the subfolder structure is maintained properly.

Save/Restore the Tree

As of version 2.2.beta2, playlist tree will automatically save and restore your trees. The following refers to older versions.

If you would like the playlist tree to be saved and restored the next time you start foobar2000, setup an automatic save/restore file. You can do this by right clicking on any empty area (not on any nodes or parts of the tree) of the playlist tree panel and choosing the "Select File..." option. This will tell playlist tree to save to that file the next time it exits. If you have already saved a file and wish to load it, and then continue to save and restore from that file, choose the "Select File And Load..." option.

Customizing the Tree

Once you created your static and dynamic folders, you can arrange them as you like by using the drag and drop feature ('Allow local drag and drop feature' in <Config> Preferences should be enabled). You can also insert, move, rename, delete folders and items by using context menu or main menu items

You may also find a number of options that modify the display of the tree in the <Appearance> Preferences. Every option is followed by a brief description. Some of the importangt options are listed in the Appendix

By using the 'Edit folder' window, accessible through the Edit... command in context menu, you can also change the icons for both static and dynamic folders. In the bottom-left corner of the 'Edit folder' window, there are two Set... buttons and a Reset button. The left and right Set... buttons are respectively used to select the closed folder icon and the open folder icon. The Reset button restores the default icons.

If you want to use a different icon set, you can go to <Bitmap> preferences, enable the Use External Bitmap option and set the path of your custom bitmap in the External Bitmap File field. Here is an example of a customized Playlist tree with G.A.N.T. icons:


You can find some examples of custom bitmaps here. If you don't want to use icons in the tree, uncheck the Use Bitmaps option in <Bitmaps> preferences.

Library Playlist

The Library Playlist is a special playlist in the main window that displays the content of the selected folder. To add the Library Playlist to the foobar2000 main window, choose the Send Selection to Library Playlist option in <Library> preferences. The Library Playlist option in 'Library' preferences lets you choose a name for the Library Playlist.


If you tick the 'Don't Browse' checkbox in a folder's edit window, its content will not be displayed in the Library Playlist.

The Search Feature

To enable the Playlist tree search feature add the "Playlist Tree Search" toolbar to your Columns UI layout.

Now you can type a search string in the textbox and start your search. Search criteria can be in playlistgen style query. (e.g. artist IS beck).

Press Enter to find the next matching track. If no matches are found the text will turn red. Otherwise the item will be selected in the tree. Pressing Enter will continue searching, pressing Escape will cancel the search and clear the search box text.


Playlist Tree Specific Tags

=== %_name% === name of the folder === %_displayname% === display name of folder (processes out @icon<> etc === %_size_abbr% === total file size (100 MB, 10 GB) === %_size_abb% === total file size (100 M, 10 G) === %_size% === total file size (100, 102400) === %_play_length% === play length

=== %_itemcount% === total number of files === %_foldercount% === number of subfolders === %_folderindex% === index of the item in the parent === %_overallindex% === index of the item in the whole tree === %_nestlevel% === nest level of folder === %_isquery% === 1 if the node is a query, undefined otherwise === %_isleaf% === 1 if the node is a leaf node, undefined otherwise === %_isfolder% === 1 if the node is a static folder, undefined otherwise

Special Functions


Works similarly to the album list component, but playlist tree allows multiple tags to be enumerated, using the syntax %<tag1,tag2,tag3>%.


Allows to evaluate a label or a Playlist Generator format query according to TAGZ rules.


Allows you to specify a different icon for a node.


Allows you to get tags from the currently playing item in your dynamic playlists.


Label=Same artist
Query=artist IS @format<$playing('%artist%')>


Allows you to find the average value over the files in a node.


Allows you to find the sum of values for the files in a node.


Quotes the text so that formatting will not effect it. (Allows special characters to make it through a @format<> call.


retrieve information about ancestor node. n is optional. Usage: $parent('%_displayname%') or $parent('%_displayname%',2)


allows nested queries. format and poporder are optional


Do not actually display the text inside the function




hides immediate children files



Allows you to specify the format for a @drop<> query should be that as if the file where actually dropped.

Specifying Sources

Source Directives


Query is performed against all entries in the database. This is the default if no source is specified.


It allows to add to a dynamic folder the files contained in a directory, archive, cue sheet, matroska file, playlist file (.m3u, .fpl), playlist tree file (.pts)

Note: if you specify @default in the format field files are displayed in the same order as in the original directory/archive/cue sheet/matroska file/etc.


Allows you to add to a dynamic folder the files contained in another folder. You can use this function to create nested queries.


If you specify @playlists as the source, it will create @playlist<> queries as children for every playlist you have open in foobar2000.


Specify a playlist that contains the files you want to appear in the results.

Combining Sources

You can use the following functions to combine sources:


@node<a> @and @node<c> finds all the files that are in BOTH node a and node c.


@node<a> @or @node<c> finds all the files that are in EITHER node a OR node c.


@node<a> @not @node<c> finds all files in node a that are NOT in node c.

Important Options

Playlist Tree

  • Hide leaves - Allows you to hide the last level of the tree, i.e. the music files. This function is useful if it is coupled with foo_browser or using a Selection Action to send the contents to the library playlist.
  • Hide root - Allows you to remove the 'Playlist Tree' root folder from the displayed tree.
  • Hide lines - Allows you to hide the lines shown in the tree.
  • Hide +/- - Hides the expand/collapse buttons in the tree.
  • Back color, Text color, Line color - Allows you to set colors for background, text and lines in Playlist tree main window.


Playlist Tree written by cwbowron. Many thanks to Peter Pawlowski and the foobar2000 crew. Many thanks to mattahan for the G.A.N.T. icons.

Wiki based on documentation written by marcomk and jkwarras.

Personal tools