Skip to content

DPL playlist format

Jump to bottom
AF-1 edited this page May 17, 2022 · 18 revisions

Dynamic playlists are based on the former SQLPlayList format. The following guide applies to built-in and custom dynamic playlists (user-provided and used directly in DPL) but not necessarily to those provided by other plugins.

  • The first part contains parameters: general parameters like the playlist name, group or category and user input parameters that present users with some options to choose from before starting the playlist.
  • The second part contains the actual SQLite statement LMS uses to fetch the tracks.

Here's a simple dynamic playlist example: 
-- PlaylistName:Songs - random
-- PlaylistGroups:Christmas/Songs
-- PlaylistCategory:songs
-- PlaylistVirtualLibraryID1:UCTI_FAMILY_LIBRARY
-- PlaylistParameter1:list:Limit to PLAYED songs:0:all songs,1:unplayed songs,2:played songs

select distinct tracks.url from tracks
    join library_track on
        library_track.track = tracks.id and library_track.library = 'PlaylistVirtualLibraryID1'
    join comments on
        comments.track = tracks.id and comments.value like '%%Christmas%%'
    join tracks_persistent on
        tracks_persistent.urlmd5 = tracks.urlmd5
left join dynamicplaylist_history on
        dynamicplaylist_history.id=tracks.id and dynamicplaylist_history.client='PlaylistPlayer'
    where
        audio=1
        and tracks.secs >= 'PlaylistTrackMinDuration'
        and dynamicplaylist_history.id is null
        and
            case
                when 'PlaylistParameter1'=1 then (tracks_persistent.playCount = 0 or tracks_persistent.playCount is null)
                when 'PlaylistParameter1'=2 then tracks_persistent.playCount > 0
                else 1
            end
    order by random()
    limit 'PlaylistLimit';

Playlist Parameters

Parameters always start with -- Playlist.

General Parameters

You should definitely set the -- PlaylistName.

With -- PlaylistGroups you can sort your dynamic playlist into any group in the DPL home menu. You don't have to use one of the built-in groups. You can name it anything you want. And groups can have subgroups. The dynamic playlist example creates a group called "Christmas" with a subgroup called "Songs". Groups and subgroups are separated by a slash /
PlaylistGroups is an optional parameter.

-- PlaylistCategory is used to sort playlist by playlist type on the DPL settings page. It's always lower case and it can have any of these values:
songs, artists, albums, genres, years, playlists.
PlaylistCategory is an optional parameter.

If you want to create a context menu dynamic playlist (context menu for artist, album, genre, years or playlist) you have to add this line:
-- PlaylistMenuListType:contextmenu
Otherwise it will show up as a normal (stand-alone) dynamic playlist.

The -- PlaylistLimitOption:unlimited parameter tells DPL to add an 'unlimited' number of tracks to the playlist. To prevent faulty playlist definitions from adding complete libraries unlimited actually means max. 2000 tracks.

The sqlite statements of many (built-in) dynamic playlists use random sorting. Regardless, DPL additionally tries to increase randomness by shuffling tracks before adding them. If you want to use custom dynamic playlists and disable extra shuffling just add the -- PlaylistTrackOrder:ordered parameter.
Example: Custom dynamic playlists adding complete albums should use the -- PlaylistLimitOption:unlimited and the -- PlaylistTrackOrder:ordered parameter.

Virtual libraries:
You can always ask the user to choose a virtual library (see user input parameters below). But if you want a one-click custom dynamic playlist without user interaction and you know which virtual library to use already here's how to do it:

LMS virtual libraries have a name (displayed in menus), a unique (configurable) id and a 'realID' which is what LMS uses internally. Since realIDs can change across rescans it's safer to use the name of the virtual library, even better the unique ID (because unlike names it has to be unique).
Just use the -- PlaylistVirtualLibraryID or the -- PlaylistVirtualLibraryName followed by a number.

Using the dynamic playlist example from above that would be -- PlaylistVirtualLibraryID1:UCTI_FAMILY_LIBRARY
or maybe -- PlaylistVirtualLibraryName1:Family Christmas Songs.

Then you can use PlaylistVirtualLibraryID1 or PlaylistVirtualLibraryName1 in your sqlite statement and DPL will replace these values with the virtual library's realID. The ID/numbering starts with 1 and increases by 1 with each additional PlaylistVirtualLibrary parameter.

Action/CLI parameters:
The PlaylistStartAction and PlaylistStopAction parameters allow you to execute a CLI command when a dynamic playlist is started or stopped.
Their main use is to enable or disable a secondary CustomSkip filter set to filter tracks at playtime. Choosing a Customkip filter set in the SQPlayList plugin does the exact same thing: add these 2 parameters.

Example:

-- PlaylistStartAction1:cli:customskip setsecondaryfilter TEST.cs.xml
-- PlaylistStopAction1:cli:customskip clearsecondaryfilter

Important:

  • Use the complete file name (incl. file extension).
  • The file name is case-sensitive. Using the example above: CustomSkip would consider TEST.cs.xml and test.cs.xml two different filter sets.
  • The PlaylistStopAction parameter will disable the secondary CustomSkip filter set as soon as Dynamic Playlists stops (adding new songs). So if DPL can't find more tracks matching your search criteria it stops being 'active' and disables the secondary filter on exiting. The remaining unplayed songs in your client playlist will no longer be filtered by the secondary CustomSkip filter set because DPL disabled it on exiting. If that happens a lot to you I recommend setting the max. number of unplayed tracks DPL adds to a low number so DPL doesn't stop and disable the secondary CS filter too soon.

The ID starts with 1 and increases by 1 with each additional PlaylistAction parameter.
For more information on CustomSkip filters please visit the CustomSkip wiki.

User Input Parameters

And then there are parameters requesting input from the user that is used in the SQLite statement.
Their ID starts with 1 and increases by 1 with each additional PlaylistParameter: -- PlaylistParameter1, -- PlaylistParameter2 and so on.
In other words: the -- PlaylistParameter1 part asks the user for input which can then process in your SQLite statement using placeholders like 'PlaylistParameter1' (wrapped in single quotes).

You can choose from predefined parameters or create a custom parameter:

  • Predefined parameters are available for artist, album, genre, multiplegenres, year, multipleyears, multipledecades, playlist, multiplestaticplaylists and virtuallibrary.
    They will present the user with a list of artists, albums, genres, years, decades, static playlists or virtual libraries to choose from. They follow the same pattern as this example for artists: -- PlaylistParameter1:artist:Select artist: or multiple genres: -- PlaylistParameter1:multiplegenres:Select genres:
  • list parameter: the dynamic playlist example above shows another kind of parameter, the list parameter, that lets users choose from custom list items with custom values:
    -- PlaylistParameter1:list:Limit to PLAYED songs:0:all songs,1:unplayed songs,2:played songs
  • And finally you can create your own custom parameter, sort of a list parameter using SQLite query results. Requesting users to choose a (single) decade is one example:
    -- PlaylistParameter1:customdecade:Select decade:select cast(((tracks.year/10)*10) as int),case when tracks.year>0 then cast(((tracks.year/10)*10) as int)||'s' else 'Unknown' end from tracks where tracks.audio=1 group by cast(((tracks.year/10)*10) as int) order by tracks.year desc.
    Custom parameters must always be prefixed with custom (customdecade in this example).
  • The PlaylistPreselectedArtists and PlaylistPreselectedAlbums are special cases. They don't request user input when you start your dynamic playlist. Instead you add artists/albums to a list (preselecting them from the context menu) while browsing your music library. When you start a dynamic playlist with these playlist parameters DPL will provide the necessary artist/album IDs. All you have to do is add one or two lines to your SQLite statement and DPL will take care of the rest. Here are examples for
    preselected artists:
    join contributor_track on contributor_track.track=tracks.id and contributor_track.role in (1,4,5,6) and contributor_track.contributor in ('PlaylistPreselectedArtists')
    and preselected albums:
    tracks.album in ('PlaylistPreselectedAlbums')


SQLite statement

This is what LMS uses to fetch the tracks.
You can use 2 kinds of playlist parameters in your SQLite statement that DPL will replace with actual values:

  • the user input playlist parameters mentioned above and
  • a set of playlist parameters that DPL will fill in automatically.

DPL will automatically replace these (non-configurable) parameters with current values:

  • 'PlaylistPlayer' => client MAC address
  • 'PlaylistCurrentVirtualLibraryForClient' => if there's a virtual library enabled for the client other than the complete library
  • 'PlaylistVariousArtistsString' => your (localized) string for Various Artists if you want to filter for that
  • 'PlaylistVariousArtistsID' => contributor.id for Various Artists if you want to filter for that

You can change the value of these parameters on the DPL settings page:

  • 'PlaylistLimit' => limit the max. number of tracks added to your playlist. No limit if you add the -- PlaylistLimitOption:unlimited.
  • 'PlaylistTrackMinDuration' => minimum track length
  • 'PlaylistTopRatedMinRating' => minimum rating for tracks to be considered top rated
  • 'PlaylistPeriodPlayedLongAgo' => time period for tracks to be considered played long ago
  • 'PlaylistExcludedGenres' => list of genres to exclude from results
  • 'PlaylistMinArtistTracks' => ignore artists with less tracks
  • 'PlaylistMinAlbumTracks' => ignore albums with less tracks

All parameters have to be wrapped in single quotes as shown above.

I highly recommend taking a look at the dynamic playlists that come with the plugin. It's a good starting point for your own dynamic playlists and might save you some time.

Clone this wiki locally