DPL playlist format

DPL playlist format

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 like the playlist name, playlist group or playlist parameters users can 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
-- PlaylistParameter1:list:Limit to PLAYED songs:0:all songs,1:unplayed songs,2:played songs

select distinct tracks.url from tracks
    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';

Parameters

Parameters always start with -- Playlist.

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.

And then there are parameters requesting input from the user that is used in the SQLite statement.
They are simply numbered: -- PlaylistParameter1, -- PlaylistParameter2 and so on.

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

• Predefined parameters are available for artist, album, genre, years, playlist, and virtuallibrary. They will present the user with a list of artists, albums, genres, years, playlists or virtual libraries to choose from. They follow the same pattern as this example for artist: -- PlaylistParameter1:artist:Select artist:.
  
• 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 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).
  
  
  

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 playlist parameters with user input mentioned above (like 'PlaylistParameter1') and
• a set of playlist parameters that DPL will fill in automatically (according to the values you set in the DPL settings).
  
  

DPL offers these auto-replaced parameters:

• '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

You can set these on the DPL settings page:

• 'PlaylistLimit' => limit the max. number of tracks added to your playlist
• 'PlaylistTrackMinDuration' => minimum track length
• 'PlaylistTopRatedMinRating' => minimum rating for tracks to be considered top rated
• 'PlaylistPeriodRecentlyAdded' => time period for tracks to be considered recently added
• 'PlaylistPeriodRecentlyPlayed' => time period for tracks to be considered recently played
• 'PlaylistPeriodPlayedLongAgo' => time period for tracks to be considered played long ago
• 'PlaylistExcludedGenres' => list of genres to exclude from results

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

You can use the dynamic playlists that come with the plugin as a starting point for your own dynamic playlists.