<?sphp $this->text('pagetitle') ?>
 
Home of the Squeezebox™ & Transporter® network music players.

Custom Browse

From SqueezeboxWiki

(Redirected from Custom Browse plugin)
Jump to: navigation, search

This is a plugin for Squeezebox Server (SBS, formerly known as SqueezeCenter or SlimServer) that makes it possible to create your own custom browse menus on the Squeezebox. The standard SBS menus aren't very configurable although there are some options regarding how different types of artists shall be shown. The Custom Browse menu provides a way to extend this so you can configure any menu you like. There is a lot of different menus available with the Custom Browse installation, you can modify this or define completely new ones. With the predefined menu types available with the installation there is an easy to use web interface for creating new menus and changing options on the existing ones. You can also choose to customize the configuration for a menu and edit the menu configuration XML text manually.

Some example of menus that are delivered with the plugin:

  • New Artists, New Albums
  • Decades
  • Statistics (using TrackStat plugin)
  • Dynamic Playlists (using DynamicPlayList plugin)

For more information about available menus see the section about available menu types below.

The Custom Browse menu can be used in a number of different senarios:

  • You are satisfied with the standard SBS browse menus but you would like to add a few more way of browsing your music
  • You are satisfied with most of the standard SBS browse menus but you would like to replace one of them so it works a bit different.
  • You like to totally replace the standard SBS browse menus with a completely different browse menu structure

Contents

Screenshots

Here are some screenshots that shows how some things looks like in Custom Browse

CustomBrowseImage1.jpg CustomBrowseImage2.jpg

Installation

  1. Remove any previous version of Custom Browse from the SBS Plugins directory if you have manually installed it earlier (this is not needed if you have installed it through Extension Downloader)
  2. Goto SBS Settings/Plugins and select to install Custom Browse. You might need to check the Show all 3rd party plugins checkbox to see it in the list. If you don't want to install it through SBS Settings/Plugins, you can also download it from the download page and manually unzip the new version in the SqueezeCenter Plugins directory
    • Please note that earlier versions of this plugin will require you to also install the License Manager plugin.
    • Please note that earlier versions of this plugin will require you to purchase a license.
  3. Optionally Install other plugins that extends Custom Browse with more functionality
  4. When you have installed everything you might also want to look at

Note!

  • More information about how to purchase and activate the commercial license can be found through the License Manager plugin

If you are using SlimServer 6.5 or earlier, you may want to use the old guide instead.

Bugs and new features

The current list of known bugs and wishes for new features can be found here:

If you want to encourage future development of this plugin you should also consider making a donation or purchasing a license

http://license.isaksson.info

Navigation

The Custom Browse menus are navigated in similar way as the standard browse menus

  • Arrow keys navigates in the menu structure
  • Number keys can be used to goto a specific letter or position with a few click, for example stepping down to artists starting with T
  • A single push on play will start playing the selected item
  • A single push on add will add the selected item at the end of the current playlist
  • Holding add down a while will insert the selected item in the current playlist directly after the currently playing song
  • In some menus you will get a M icon in the upper right corner, here it is possible to hold play down to execute a mixer. See the section about mixers for more information regarding this.

Manage menus

You can create, delete or modify Custom Browse menus by going to the "Custom Browse" section of the "SqueezeCenter Settings" section of the web interface and select:

  • Manage menus: To create, delete or modify browse menus
  • Manage header/footer items: To create, delete or modify header or footer items shown in the web interface and also to create, delete or modify the song information menu/page and "Browse by selected" mixers.

To create a new menu, hit the "Create new menu" link, select the desired menu type, enter its parameters and save the menu. See the following section for a more detailed description of the available menu types.

To delete a menu, hit the "Delete" or "Hide" link to the right of the menu item.

To modify a menu, click the menu name, change its parameters and save the menu.

The setup examples listed in the installation section gives you a few step by step instructions how to create different kind of menus.

Available menu types

The menu types listed below are those available with the Custom Browse plugin, additional menu types can also be provided by installing other plugins, as an example this happens if you install the Custom Scan plugin which provides a number of menus based on custom tags not normally handled by SqueezeCenter.

Albums Albums menu that works the same way as the standard SqueezeCenter albums menu
Albums/Compilations Albums menu that is divided into artist albums and compilation albums.
Artists Artists menu that works the same way as the standard SqueezeCenter artists menu
Artists by letter Menu that browses artists but it has an extra level where you have to select the first letter of the artist before you can browse artists for the selected letter
Bands Menu similar to the standard SqueezeCenter artists menu but it only show bands
Bitrates Bitrates menu that make it possible to browse music by bitrate or lossless/not lossless
Compilations Compilations menu that only shows compilation albums
Composers Menu similar to the standard SqueezeCenter artists menu but it only show composers
Conductors Menu similar to the standard SqueezeCenter artists menu but it only show conductors
Decades Menu to browse music by decades
Dynamic playlists Menu that puts the standard Dynamic Playlists menu below Custom Browse menu.
Filtered Albums Albums menu that makes it possible to browse albums limited to a specific included/excluded genres and comment
Filtered Artists Artists menu that makes it possible to browse artists limited to a specific included/excluded genres
Filtered Artists by letter Menu that browses artists but it has an extra level where you have to select the first letter of the artist before you can browse artists for the selected letter, the included artists is limited to included/excluded genres and comment
Filtered Genres Genres menu that makes it possible to browse genres limited to a specific included/excluded genres
Filtered Singles Singles menu that lists singles. It detect all tracks with a specific COMMENT tag or a specific genre as a single.
Genre Albums Genres menu that works the same way as the standard SqueezeCenter albums menu but is a bit more shallow by moving directly from genres to albums instead of requesting the user to select artists before albums
Genre Libraries Libraries menu that makes it possible to browse artist, genre, album limited to a specific included/excluded genres.
Note! If you are thinking about using the Genre Libraries menu you should probably also look at the Multi Library plugin.
Genres Genres menu that works the same way as the standard SqueezeCenter genres menu
Genres by letter Genres menu to browse genres, but it adds an extra level after you have selected the genre where you also have to select the first letter of the artist before you can browse artists for the selected letter
Genres/Sub Genres Menu that shows genres and sub genres in two levels, it only show tracks that matches both selected genres
Libraries Libraries menu that makes it possible to browse artist, genre, album limited to a specific directory tree in your music folder.
Note! If you are thinking about using the Libraries menu you should probably also look at the Multi Library plugin.
Library Statistics Shows different statistics about your library, not useful for playing tracks
Music folders Menu that puts the standards Music Folders browse menu below the Custom Browse menu
New Albums New Albums menu that works the same way as the standard SqueezeCenter New Music menu, but can use statistics from the TrackStat plugin
New Artists New Artists menu that works the same way as the standard SqueezeCenter albums New Music menu but instead of listing albums it lists the artists on the new albums
Playlists Playlists menu that works the same way as the standard SqueezeCenter playlists menu
Random Albums Random Albums menu that lists 20 random albums from your library
Ratings Menu that makes it possible to browse music by track ratings
Singles Singles menu that lists singles. It detect all tracks without any ALBUM tag as a single.
Singles by letter Singles menu browses singles but also adds an extra level where you will have to select the first letter of the artists before you can browse singles for the selected artist
SlimServer Albums Standard SqueezeCenter Albums menu
SlimServer Artists Standard SqueezeCenter Artists menu
SlimServer Genres Standard SqueezeCenter Genres menu
SlimServer New Music Standard SqueezeCenter New Music menu
SlimServer Playlists Standard SqueezeCenter Playlists menu
SlimServer Years Standard SqueezeCenter Years menu
Statistics Menu that just puts the standard TrackStat menu below the Custom Browse menu
Years Years menu that works the same way as the standard SqueezeCenter years menu
Year Songs Years menu that lists all songs for a year directly without the intermediate albums level

Available context menu/header/footer types

The menu types listed below are those available for usage as "Browse by selected" mixer or header/footer information in the web interface with the Custom Browse plugin, additional menu types can also be provided by installating other plugins, as an example this happens if you install the Custom Scan plugin which provides a number of menus based on custom tags not normally handled by SqueezeCenter.

All the context menu/header/footer information types have an important parameter Object type that can have the following values

albumheader Show the item as header on the album page in the web interface
artistheader Show the item as header on the artist page in the web interface
genreheader Show the item as header on the genre page in the web interface
playlistheader Show the item as header on the playlist page in the web interface
yearheader Show the item as header on the album page in the web interface
trackheader Show the item as header on the song page in the web interface
albumfooter Show the item as footer on the album page in the web interface
artistfooter Show the item as footer on the artist page in the web interface
genrefooter Show the item as footer on the genre page in the web interface
playlistfooter Show the item as footer on the playlist page in the web interface
yearfooter Show the item as footer on the album page in the web interface
trackfooter Show the item as footer on the song page in the web interface
album Show the item when selecting "Browse by selected" mixer and as body on the album page in the web interface
artist Show the item when selecting "Browse by selected" mixer and as body on the artist page in the web interface
genre Show the item when selecting "Browse by selected" mixer and as body on the genre page in the web interface
playlist Show the item when selecting "Browse by selected" mixer and as body on the playlist page in the web interface
year Show the item when selecting "Browse by selected" mixer and as body on the year page in the web interface
track Show the item when selecting "Browse by selected" mixer and as body on the song page in the web interface. This is also the items shown when right clicking in the Now Playing menu on the Squeezebox/Transporter

The following tables shows the available context menu/footer/header types.

Information about album

Album comment links Links from comment tags for the selected album
Album cover Album cover for the selected album
Album details Various information for selected album
Album images Images for the selected album, stored in same directory as album music files
Album image Image for selected album, images are collected from the specified sub directory within "Cache directory for images" specified in Custom Browse settings in Server Settings/Plugins
Album information files Links to information files for a selected album
Album play links Play, add, insert links to play the selected album
Album title Clickable album title
Artists for album Artists, composers, conductors or bands for a selected album
Genres for album Genres for the selected album
Search for album Links to search for selected album on various internet sites
Songs for album Songs on selected album
Years for album Years for songs on the selected album

Information about artist

Albums for artist Albums for selected artist
Artist comment links Show links from comment tags for the selected artist
Artist details Various information about selected artist
Artist image Image for selected artist, images are collected from the specified sub directory within "Cache directory for images" specified in Custom Browse settings in Server Settings/Plugins
Artist name Name of the selected artist
Artist play link Show link to play the selected artist
Genres for artist Genres for the selected artist
Search for artist Links to search for selected artist on various internet sites
Years for artist Years for songs by the selected artist

Information about genre

Albums for genre Albums for the selected genre
Artists for genre Artists, composers, conductors or bands for a selected genre
Genre details Various information about selected genre
Genre image Image for selected genre, images are collected from the specified sub directory within "Cache directory for images" specified in Custom Browse settings in Server Settings/Plugins
Genre name Name of selected genre
Years for genre Years for a selected genre

Information about playlist

Albums for playlist Albums for a selected playlist
Artists for playlist Artists, composers, conductors or bands for a selected playlist
Genres for playlist Genres for a selected playlist
Playlist details Various information about the selected playlist
Playlist image Image for selected playlist, images are collected from the specified sub directory within "Cache directory for images" specified in Custom Browse settings in Server Settings/Plugins
Playlist title Title of selected playlist

Information about song

Albums for song Albums for a selected song
Artists for song Artists, composers, conductors or bands for a selected song
Genres for song Genres for a selected song
Search for song Search for the selected song on internet
SlimServer song information The standard SqueezeCenter song information menu
Song album cover Album cover for the selected song
Song comment links Show links from comment tags for the selected song
Song comments Comment tags for the selected song
Song details Various information about the selected song
Song path Path for the selected song
Song play link Show link to play the selected song
Song lyrics Lyrics for the selected song
Years for song Years for a selected song

Information about year

Albums for year Albums for a selected year
Artists for year Artists, composers, conductors or bands for a selected year
Genres for year Genres for a selected year
Year details Various information about selected year
Year image Image for selected year, images are collected from the specified sub directory within "Cache directory for images" specified in Custom Browse settings in Server Settings/Plugins
Year name Name of the selected year

Available mixers

The mixer listed below are those available with the Custom Browse plugin, additional mixers can also be provided by installating other plugins, as an example this happens if you install the Custom Skip plugin which provides a mixer for making it easy to add a object such as a track or artist to a skip filter. A mixer is available in the web interface as an icon beside the play/add buttons or accessible by holding play down for a while when browsing the SqueezeBox/Transporter.

Browse by selected Mixer that just moves to a separate browse menu with the selected item as context. This is also a way to move out of the context, for example if you browse down to a menu like Genres/Pop/Whitney Houston/The BodyGuard and this is a compilation album you will only see the Pop songs by Whitney Houston on this album. If you when standing on The Bodyguard in this situation launch this mixer you will be able to see all songs on this album, not just those that belong to the Pop genre with artist Whitney Houston.
MusicMagic Start a MusicIP based mix, requires the MusicMagic plugin included with SqueezeCenter to be configured and also requires that the MusicIP server is running. This is the same mixer as the one available in the standard SqueezeCenter browse menus when the MusicMagic plugin is used.
Random Play 20 songs for the selected element in random order, for example playing 20 Country songs when standing on the Country genre and executing this mixer. In the settings section for Custom Browse in Server Settings/Plugins there is a mixsize parameter that can be changed if you want this mix to contain more tracks.

Downloading and sharing menus

Custom Browse provides a way to download and share menu definitions with other users, this is used in a number of different ways:

  • The latest version of the builtin menu type are always available for download, this means that instead of waiting for a new official release of Custom Browse you can download a new menu directly after it has been corrected by the developer.
  • A user can choose to publish/share a menu he has made himself, after publishing this menu will be available for download for all other users

When publishing/sharing a menu you have the following options

  • You can choose to register, the advantage with this is that other users will see that you are the author for the menu so you will get some credit for it. It is also a way to make sure that no one else can modify your shared menu. You register by selecting on of the "Publish" links and then selecting "Register & Login" in the Custom Browse web interface in your SqueezeCenter.
  • You can choose to publish a menu anonymously, this way you don't need to provide any information about yourself but it also means that other persons can update and modify the shared menu.

The recommendation is that you register when publishing menus but its still better that you publish a menu anonymously than not publish it at all.

Hide/Show menus

When you have created the menus you like there is a number of ways to choose which menus that actually shall be visible, as described below

  • You can use the "Enabled menus", "Enabled header/footer items" or "Enabled mixers" section in the "Custom Browse" section of "SqueezeCenter Settings" in the web interface to completely hide a menu
    • The "Show in browse and home menu" checkbox specifies if the menu shall be visible directly in the top menu of the SqueezeBox/Transporter
    • The "Select enabled menus" checkbox specifies if the menu shall be visible inside the "Custom Browse" menu
  • You can use the "SqueezeCenter menus" section in the "Custom Browse" section of "SqueezeCenter Settings" in the web interface to replace a standard SqueezeCenter menu with a Custom Browse based menu
  • In the menu configuration of a specific menu you can use the "Only include on these players" and "Exclude from these players" settings to enter on which SqueezeBox/Transporter units the menu shall be visible. You can specify several players separated with a comma.
  • If you have installed the Multi Library plugin you can in the menu configuration of a specific menu use the "Only include when these libraries are active" and "Exclude when these libraries are active" settings to specify on which sub library defined in the Multi Library that has to be active for the menu to be visible.

Menu structure

By default a new menu is placed directly inside the "Browse/Custom Browse" menu, for example:

Browse
    Custom Browse
        New Albums 

If you like a deeper menu structure you can choose to edit the menu configuration and specify a value in the "Menu group" setting, for example specifying "Other/New Music" in menu group would instead show the menu as:

Browse
    Custom Browse
        Other
            New Music
                New Albums

If you like the menu to be available directly in the "Browse" menu or directly in the top menu you shall use the "Show in browse and home menu" as described in the "Hide/Show menus" section above. Doing this makes it possible to show the menu as:

New Albums

Or

Browse
    New Albums

Or

Browse
    Other
        New Music
            New Albums

Menu configuration format

Menu example

When you choose to customize a menu configuration and edit the raw XML configuration it is important that you use the correct format. The following sample shows a simple albums menu configuration.

<?xml version="1.0" encoding="utf-8"?>
<custombrowse>
        <menu>
                <menuname>Albums</menuname>
                <menuorder>50</menuorder>
                <menu>
                        <id>album</id>
                        <menuname>Songs</menuname>
                        <itemtype>album</itemtype>
                        <itemformat>album</itemformat>
                        <menutype>sql</menutype>
                        <menulinks>alpha</menulinks>
                        <option>
                                <id>bytitle</id>
                                <name>Sort by title</name>
                                <menulinks>alpha</menulinks>
                                <keyword name="orderby" value="albums.titlesort asc"/>
                        </option>
                        <option>
                                <id>byyear</id>
                                <name>Sort by year</name>
                                <menulinks>number</menulinks>
                                <keyword name="orderby" value="albums.year desc, albums.titlesort asc"/>
                        </option>
                        <menudata>
                                select albums.id,albums.title,left(albums.titlesort,1) from tracks,albums
                                where
                                        tracks.audio=1 and
                                        albums.id=tracks.album
                                group by albums.id
                                order by {orderby}
                        </menudata>
                        <menu>
                                <id>track</id>
                                <itemtype>track</itemtype>
                                <itemformat>track</itemformat>
                                <menutype>sql</menutype>
                                <menudata>
                                        select tracks.id,tracks.title from tracks
                                        where
                                                tracks.audio=1 and
                                                tracks.album={album}
                                        order by tracks.tracknum,tracks.titlesort asc
                                </menudata>
                                <menu>
                                        <id>trackdetails</id>
                                        <menutype>trackdetails</menutype>
                                        <menudata>track</menudata>
                                </menu>
                        </menu>
                </menu>
        </menu>
</custombrowse>

Element descriptions

A description of the different elements follows below

menu Defines a new sub menu
id Identification for a specific menu, must be uniqe on the same level.
The id element is mandatory for all menus besides the top menu. The top menu will allways get id equal to the filename.
includedclients A comma separated list of players that the menu shall be included on.
This element is optional and if not specified the menu will be included on all players, see also excludedclients element below.
excludedclients A comma separated list of players that the menu shall be excluded from.
This element is optional and if not specified the menu will be included on all players, see also includedclients element above.
enabledcheck A main element which contains sub elements for each check that shall be done to verify if a menu should be visible or not. It contains a sub structure like this for all checks
<item>
	<type>function</type>
	<data>Plugins::CustomBrowse::Plugin|isuPNPDeviceAvailable|device=[% deviceudn %]</data>
</item>
  • type
The only allowed value today is: function
  • data
  • If type = function:
    Object|function|parameter1=value|parameter2=value
    The called function should take two parameters $client and $params, where $params is a hash with all specified parameters as key/value pairs. See the isuPNPDeviceAvailable function in Custom Browse/Plugin.pm for a sample.
menugroup Group in which the menu should be placed, a / separated string, for example "Group1/SubGroup1" (without quotation marks. Optional parameter that only should be specified if you want to place the menu in a group.
menuname Title of the menu, this element is required on the top menu level, its never used for dynamic menus in the player interface. In the web interface this value is used for the navigation links at the top. The menuname element is mandatory for static menus with no menutype element.
menuorder The sort number of the menu, a number between 1 and 100, default is 50. Lower numbers will be sorted before higher numbers
menuprefix Optional element that if specified will result in that this text is added to the beginning of all the text of all items in the menu. Useful in header/footer menu types where you like to have the item text contain both a name and a value. With this element the raw data returned from the SQL could contain the value part and the menuprefix element contains the name part.
itemtype Type of items in the menu, should only be available if the menu items represents a single unique database object. The following values are allowed:
  • album
  • artist
  • genre
  • year
  • playlist
  • track

Only elements with one of these item types can be played with the play button. The itemtype element is optional, its basically used to indicate if the item should be possible to play/add or not. Note that its important that the item really represent the item type set.

itemseparator The text that shall act as separator when separating the text value of the item into several values. This is used in most of the builtin context menus where the item text value is separated into a "attribute name" and "attribute value". This is an optional element and doesn't have to be specified.
itemplacement Optional element that is used in the header/footer menus to indicate if the element should be placed in the left or right column, by default all elements are placed in the right column. Allowed values are "left" and "right".
itemformat The formatting type that should be applied to the menu item. Currently the following are supported.
  • track - Format the item as a track, the SqueezeCenter standard track formatting settings is used
  • trackconcat - Format the item as a track, but add the value from the menu after the formatted track
  • album - Format the item as an album, the SqueezeCenter standard album formatting settings is used
  • albumconcat - Format the item as an album, but add the value from the menu after the formatted album
  • titleformat - Format the item according to a title format. The title format needs to be specified in a itemformatdata element
  • titleformatconcat - Format the item according to a title format, but add the value from the menu after the formatted text
  • function - Format the item by calling a callback function, the function needs to be specified in an itemformatdata element
  • functionconcat - Format the item by calling a callback function, but add the value from the menu after the formatted text
  • internetimage - The text value of the item is expected to be an url to the image, this item will not be shown in the player and CLI interface, on the web interface it will be shown as an image. If two values are specified by separating the item text with the itemseparator element, the first value will be url to the link when the image is clicked on and the second value will be the url to the image displayed directly in the page.
  • slimserverimage - The text value of the item is exepected to be an internal SqueezeCenter url to an image, this item will not be shown in the player and CLI interface, on the web interface it will be shown as an image. If two values are specified by separating the item text with the itemseparator element, the first value will be url to the link when the image is clicked on and the second value will be the url to the image displayed directly in the page.
  • interneturl - The text value of the item is exepected to be an url, this item will not be shown in the player and CLI interface, on the web interface it till be displayed as a standard internet link pointing at the specified url.
  • slimserverurl - The text value of the item is exepected to be an internal SqueezeCenter url, this item will not be shown in the player and CLI interface, on the web interface it till be displayed as a standard link pointing at the specified url within SqueezeCenter.

The itemformat element is optional. If item format "album" is specified this will enable the gallery view button in the web interface.

itemformatdata Extra information required for the selected itemformat, see the itemformat element for more information about for which itemformat values this element is required.
itemformatascii Optional element that only has meaning when itemformat is one of the url or image types. The result is that if this element exist and has the value 1, the url is converted to ascii characters. As an example: http://www.google.se/search?q=Céline Dion would be converted to http://www.google.se/search?q=Celine Dion, as you see the é character is converted to an e.
itemformaturlnewwindow Optional element that only has meaning when itemformat is one of the url types. The result is that if this element exist and has the value 1, the url opened in a new web browser window
itemformatimagewidth Optional element that only has meaning when itemformat is one of the image types. The result is that if this element exist, the image will be rescaled in the web browse to the width in pixels specified in this element when displayed.
menutype Type of menu. This element defines how items should be retrieved for dynamic menus. The menutype element is mandatory for dynamic menus, its currently not used for static menus. The following values are currently supported.
  • sql
Retrieves menu items by executing a SQL statement. The SQL statement is defined in the menudata element.
  • trackdetails
Enter track details mode for the selected track, the menudata element contains the id of the menu where the track identifier can be found.
  • mode
Enters this mode. Modes are typically implemented by all plugins and represent their plugin menu. But modes are also available for a number of internal SqueezeCenter menus.
  • folder
Lists all sub directories as a menu item, the parent directory is defined in the menudata element.
  • function
Calls a function that returns the menu items that shall be available. The function to call is defined in the menudata element.
menulinks Defines the type of navigation links that should be available in the web interface. Currently the only allowed value is "alpha" and "number". Not specifying this element is the same as setting it to "number".
  • number
Standard positional navigation using numeric buttons on SqueezeBox and page number links in web interface.
  • alpha
If this element exist for a menytype=sql the SQL statement must contain a third column that contains the navigation letter for each row. The menulinks element also affects the SqueezeBox navigation in the way that this will enable navigation by letters using numeric buttons.
menuurl Defines the url that shall be used as link in web interface for menus with menutype=mode.
menudata Defines parameters needed for retrieval of dynamic menu data. This element contains different information dependent on the value of the menutype element. The menudata element is mandatory for dynamic menus, its currently not used for static menus.
menytype menudata
  • sql
One or several SQL statements which should return two or tree columns. The first column will be used as id internally and the second column is the text that is displayed. The third column is optional and is only required if menulinks=alpha has been defined. The first column should typically be the id column in the table, for example tracks.id. Text within {} will be replaced by looking up the selected item in the parent menu with the id specified within {}. Keywords will be replaced in this field. The third column is optional and when it exists it shall contain the letter which the item shall be linked to, typically the first letter in the sort column in the database.
  • trackdetails
The id of the parent menu that contains the track that should be displayed.
  • mode
The name of the mode that should be entered. For plugins the mode are typically: "PLUGIN.xxx" where xxx is the name of the *.pm file which contains the plugin code. For example TrackStat mode is: PLUGIN.TrackStat::Plugin And DynamicPlayList mode is: PLUGIN.DynamicPlayList
  • folder
The directory where sub folders shall be read. This value can also contain keywords which will be replaced.
  • function
The name of the function that should be called and additional parameters. Specified as: <function>|parameter1=value1|parameter2=value2, for example: Plugins::CustomBrowse::Plugin::albumImages|excludedimages=cover.jpg. The function called takes the following parameters:
  • $class - The class where the function is defined
  • $client - The client
  • $keywords - A hash with all values defined, both the values for each menu level but also the values specified in menudata definition
  • $context - The context hash, contains itemid and itemtype

The function should return an array of hash elements where each element contains the keys id and name

keyword Defines a keyword that can be used in SQL statements and will be replaced before actually executing the SQL. Keywords can be defined on all levels in the menu structure. If the same keyword exist both in a the current menu and the parent menu the value of the keyword in the current menu will be used. You can also define keywords in option element and then this will override keywords defined directly in the menu element or in one of the parent menus. The keyword element requires two attributes:
  • name - The name of the keyword, this name should be used when using the keyword
  • value - The value of the keyword, the keyword will be replaced by this text if it is used in a SQL statement.


defaultoption Specifies the id of the option element that shall be the default. The default option is the one shown first and is also the only one available in player and CLI interfaces.
option Makes a drop list available in the web user interface where its possible to select one of the options defined for the menu. Typically the option element is used to make it possible to select different sort order for the menu items. The option element is optional and is not required if you don't want any drop list in the user interface. The option element must have the following sub elements:
  • id - A unique id of the option
  • name - The text that should be displayed to the user

The option can also optionally contain the following elements which then will override the same elements directly inside menu.

  • menulinks
  • menudata
  • keyword
playtype The playtype element indicates what should happen if you press play on an item in the menu. The playtype element is optional and if not specified the logic will be:
  1. Play the selected item if its itemtype is supported
  2. Play all items in the sub menu if the itemtype is not supported

The supported values of the playtype element are:

  • all - Play all items in the current menu instead of just playing the selected, this is useful for makeing play on a track play all tracks on that album.
  • sql - Play the tracks with the ids returned from the SQL statement in the playdata element.
  • none - Nothing shall happend when play/add is pressed
playdata Contains custom data for the playtype element. This element is optional and is only required for some of the different play types.
playtype playdata
  • all
Not used
  • sql
A SQL statement that returns the track identifiers of the tracks that should be played. The SQL statement should return two columns the track identifier and the track title.
mix A main element for a mix definition, can contain sub elemetnts: mixid, mixtype, mixdata, mixcategory, mixchecktype, mixcheckdata
mixid A unique identifier of the mixer
mixtype Type of mix, allowed values:
  • allforcategory - All globaly defined mixes for the category specified in mixdata shall be included here
  • sql - Mix is defined by a SQL statement
  • mode - Mix is defined by a mode
  • function - Mix is defined by a function
mixcategory Only valid for globaly defined mixes. Defines the category of the mix, menu items without any local defined mix elements will include the categories with the value of itemtype. This also means that its preferable if the mixcategory element is set to one of:
  • album
  • artist
  • playlist
  • year
  • track
  • genre
mixdata Contains custom data for the mixtype element. The allowed values are:
mixtype mixdata
  • allforcategory
The name of the category to include global mixes for
  • sql
An SQL statement returning one column with the id of the object to include in the mix
  • mode
The name of the mode to enter when mix is launched
  • function
The complete name of the function to execute when the mix is launched. The following parameters will be sent to the function:
  • $client - The client from where the mix was started
  • $item - The object which were selected when the mix was started
  • $addOnly - 1 if add was pressed, else 0
mixchecktype Type of method to check if mix should be available, can be one of:
  • sql
An SQL statement is execuced and if it returns any rows the mix is enabled. The SQL is defined by mixcheckdata element or by mixdata if mixcheckdata does not exist.
  • function
A function is executed and if it returns non 0 the mix is enabled
mixcheckdata Contains custom data for the mixchecktype element. The allowed values are:
mixchecktype mixcheckdata
  • sql
An SQL statement returning a single column, it it returns one or several rows the mix is enabled.
  • function
The complete name of the function to execute, if it returns non 0 the mix is enabled. The following parameters will be sent to the function:
  • $class - The class in which the function exists
  • $item - The object which were selected when the mix requested

Keyword replacement

In some of the elements keywords can be used, these keywords are replaced with real values before the element value is used. Currently the following keywords are supported in those element that supports keyword replacment.

  • {custombrowse.audiodir} - The music directory
  • {custombrowse.audiodirurl} - The url of the music directory
  • {property.xxx} - The value of the xxx configuration parameter, see Prefs/server.prefs in your SqueezeCenter installation for exact name.
  • {clientproperty.xxx} - The value of the xxx configuration parameter for the current player, see Prefs/server.prefs in your SqueezeCenter installation for exact name.
  • {context.itemid} - The value of the contextid parameter, this is set based on the identifier off the currently selected item. This is typically used as key in the context menus, see included built-in menus for a sample.
  • {context.itemtype} - The value of the contexttype parameter, this is set based on the itemtype off the currently selected item. This is normally not used in the menu configuration.
  • {context.itemname} - The value of the contextname parameter, this is set based on the name off the currently selected item. This is normally not used in the menu configuration.
  • {xxx} - The value of the keyword with name xxx or the id of the selected item in the menu with id xxx

Keywords can also be defined as a keyword element in the xml file, this is useful for example to change keyword values in different option element, but might also be usefull if you want to define some part of a SQL statement in one place instead of repeating it in every statement.

Templates

It is possible to configure a template directory in the settings page for Custom Browse in the web interface. By doing this you can add your own menu templates. Templates are use full if you start to customize the menu configuration in several similar menus, in that situation you can instead choose to create a template with some parameters, where each menu just have different values on the parameters.

A menu template consists of two files:

xxx.template The menu configuration which can contain [% yyy %] keywords that will be replaced with real values when the menu is created.
xxx.xml A description of the template and a definition of the parameterse that the user shall enter. See the templates in the CustomBrowse/Templates directory for some samples.

NOTE! The templates can contain a downloadidentifier element, you shall NOT include this element if you create a new template you should also remove it if you modify an existing template. The purpose of the downloadidentifier element is to make the download function work, it will automatically be added to the template if you choose to publish it.

CLI interface

The Custom Browse plugin offers a CLI interfase with the following commands.

Browse query command

The browse query command is used for browsing the menus, the syntax is:

<player> custombrowse browse <start> <noOfItems> <hierarchy> <additional parameters>

For example browsing down to the Artists/Artist42 menu where Artists42 as identifier 1 and listing the first 10 items is done as follows:

00:04:20:06:22:b3 custombrowse browse 0 10 hierarchy:artists,artist artists:artists artist:1

The hierarchy parameter is always a comma separated list of the level values for each menu level in the hierarchy to browse into.

The response to the browse query command has the following syntax:

<player> custombrowse browse <start> <noOfItems> <hierarchy> <additional parameters> count:<noOfResults> level:<level> itemid:<id> itemname:<name> itemplayable:<playable> itemmixable:<mixable>

The response for browse query command browsing into the Artists/Artist42 menu would look something like:

00:04:20:06:22:b3 custombrowse browse 0 10 hierarchy:artists,artist artists:artists artist:1 count:2 level:album itemid:1 itemname:Album1 itemplayable:1 itemmixable:0 level:album itemid:2 itemname:Album2 itemplayable:1 itemmixable:1

The parameters in the result is:

  • count - Number of items in the result
  • itemid - The identifier of an item
  • itemname - The name of the item that should be displayed to the user
  • itemplayable - Indicates if it is possible to play the item, see the play and add commands for more information.
  • itemmixable - Indicates if one or more mixers exists on the item, see the mix and mixes query command for more information.
  • itemtype - The type of the item, see description for itemtype in the menu configuration section of this documentation for more information.
  • level - The level of this item. This is used when browsing into the next sub menu by adding this to the hierarchy parameter value.

If we like use the response to browse down into a sub menu, the important stuff is the level and itemid parameters. The level parameter should be added to the hierarchy parameter and it shall also be specified as a separate parameter with the itemid as value, for example like album:2

If we like to browse down into the Artists/Artist42/Album2 the query command based on the response would be:

00:04:20:06:22:b3 custombrowse browse 0 10 hierarchy:artists,artist,album artists:artists artist:1 album:2

Play command

The play command is used for playing an item in the menu, the syntax is:

<player> custombrowse play <hierarchy> <additional parameters>

See the browse query command for more details of each parameter, if we like to play the Artists/Artist42/Album2 album from the sample in the browse query command we should execute:

00:04:20:06:22:b3 custombrowse play hierarchy:artists,artist,album artists:artists artist:1 album:2

Add command

The add command is used for adding an item in the menu to the end of the current playlist, the syntax is:

<player> custombrowse add <hierarchy> <additional parameters>

See the browse query command for more details of each parameter, if we like to add the Artists/Artist42/Album2 album from the sample in the browse query command to the end of the playlist we should execute:

00:04:20:06:22:b3 custombrowse add hierarchy:artists,artist,album artists:artists artist:1 album:2

Mixes query command

The mixes query command is used for getting the available mixers on an item in the menu, the syntax is:

<player> custombrowse mixes <hierarchy> <additional parameters>

See the browse query command for more details of each parameter, if we like get the mixes for the Artists/Artist42/Album2 album from the sample in the browse query command we should execute:

00:04:20:06:22:b3 custombrowse mixes hierarchy:artists,artist,album artists:artists artist:1 album:2

The response to the mixes query command has the syntax:

<player> custombrowse mixes <hierarchy> <additional parameters> count:<noOfResults> mixid:<id> mixname:<name>

As an example the query command above would result in a response like:

00:04:20:06:22:b3 custombrowse mixes hierarchy:artists,artist,album artists:artists artist:1 album:2 count:2 mixid:musicmagic mixname:MusicMagic mixid:random mixname:RandomAlbum

The parameters in the response are:

  • count - Number of mixers returned in response
  • mixid - The identifier of a mixer, shall be used in the mix command when executing the mixer
  • mixname - The name of the mixer to display for the user

Mix command

The mix command is used for executing a mixer on an item in the menu, the syntax is:

<player> custombrowse mix <mixid> <hierarchy> <additional parameters>

See the browse query command for more details of each parameter, if we like to execute the RandomAlbum mixer on the Artists/Artist42/Album2 album from the sample in the browse and mixes query command we should execute:

00:04:20:06:22:b3 custombrowse mix 2 hierarchy:artists,artist,album artists:artists artist:1 album:2

Installation Hints

Sometimes selecting CustomBrowse from SqueezeCenter Settings/Plugins after enabling it results in an error:

 404 Not Found: settings/plugins/CustomBrowse/settings/basic.html 

Deleting plugin-data.yaml from the cache directory might help. See this forum thread for more details.