Difference between revisions of "Smart playlists"

From Official Kodi Wiki
Jump to: navigation, search
(Grouping)
m
(136 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{see also|Playlists}}
+
{{mininav|[[Playlists]] }}
<section begin="intro"/>XBMC supports "Smart" playlists for all types of media (excluding pictures), which essentially use a set of rules to limit the results from the databases. They can be created either by using the built-in GUI Smart Playlist Editor accessible from the Playlist section, or by creating an xml file with the extension .xsp (XBMC Smart Playlist).<section end="intro"/>
+
{{outdated|This page or section has not been updated in a long time and may not be reliable.<br>Please consider updating it. }}
  
==Creating a smart playlist in the GUI==
 
{{incomplete}}
 
  
== Format of a Smart Playlist File ==
+
<section begin="intro"/>Kodi supports '''smart playlists''' for all types of media (excluding pictures), which essentially use a set of rules to limit the results from the [[databases]]. This means that to be able to create a smart playlist in the GUI, music/video ''must'' first be added to the libraries using a [[Scrapers|scraper]] [[Add-ons|addon]] or by creating [[NFO files]]. Smart playlist can be created either by using the built-in GUI smart playlist editor accessible from the [[Playlists]] section, or by creating an [[w:XML|XML]] file with the extension XSP ('''X'''BMC '''S'''mart '''P'''laylist).<section end="intro"/>
Smart playlists are plain text files that can be parsed by an xml reader. Any text editor can be used to create them. They should be saved with the extension .xsp (XBMC Smart Playlist) and placed in your [[Userdata]] directory (smart playlist xsp files cannot be read off of remote shares at present).
+
 
 +
== Creating a smart playlist in the GUI ==
 +
=== Smart playlist for music ===
 +
{{highlight|Music -> Playlists -> New smart playlist|bordered=yes}}
 +
 
 +
<gallery widths=600px heights=340px>
 +
Image:Musicxsp1.png|{{big|'''Step 1:'''}} Select "Music" on main menu.
 +
Image:Musicxsp2.png|{{big|'''Step 2:'''}} Select "Playlists" from the options.
 +
Image:Musicxsp3.png|{{big|'''Step 3:'''}} Select "New smart playlist" from the options.
 +
Image:Musicxsp4.png|{{big|'''Step 4:'''}} Fill in with the desired options and when done press OK.
 +
</gallery>
 +
 
 +
=== Smart playlist for video ===
 +
{{highlight|Video -> Playlists -> New smart playlist|bordered=yes}}
 +
 
 +
<gallery widths=600px heights=340px>
 +
Image:Videoxsp1.png|{{big|'''Step 1:'''}} Select "Videos" on main menu.
 +
Image:Videoxsp2.png|{{big|'''Step 2:'''}} Select "Playlists" from the options.
 +
Image:Videoxsp3.png|{{big|'''Step 3:'''}} Select "New smart playlist" from the options.
 +
Image:Videoxsp4.png|{{big|'''Step 4:'''}} Fill in with the desired options and when done press OK.
 +
</gallery>
 +
 
 +
== Party Mode playlists ==
 +
{{see|Party Mode}}
 +
 
 +
== Format of a smart playlist file ==
 +
Smart playlists are plain text files that can be parsed by an XML reader (e.g. [[w:Visual_studio|Visual Studio]] and [[w:Notepad%2B%2B|Notepad++]]). Any text editor can be used to create them. They should be saved with the extension XSP and placed in your [[userdata]] directory, as there is only limited support for smart playlists saved outside of the userdata folder.
  
 
The format is as follows:
 
The format is as follows:
<source lang="xml">
+
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0"?>
+
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 
<smartplaylist type="songs">
 
<smartplaylist type="songs">
  <name>All U2 from after 1990</name>
+
    <name>All U2 from after 1990</name>
  <match>all</match>
+
    <match>all</match>
  <rule field="artist" operator="is">U2</rule>
+
    <rule field="artist" operator="is">
  <rule field="year" operator="greaterthan">1990</rule>
+
        <value>U2</value>
  <limit>50</limit>
+
    </rule>
  <order direction="descending">playcount</order>
+
    <rule field="year" operator="greaterthan">
 +
        <value>1990</value>
 +
    </rule>
 +
    <limit>50</limit>
 +
    <order direction="descending">playcount</order>
 
</smartplaylist>
 
</smartplaylist>
</source>
+
</syntaxhighlight>
  
 
=== Types ===
 
=== Types ===
Line 30: Line 58:
 
* musicvideos
 
* musicvideos
 
* mixed (audio and music videos)
 
* mixed (audio and music videos)
 +
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<smartplaylist type="songs">
 +
</syntaxhighlight>
  
 
=== Name and Match ===
 
=== Name and Match ===
Basically there are 2 header tags, <code><name></code> and <code><match></code> and then a set of <code><rule></code> tags that define the rules to use, along with an <code><order></code> tag to allow sorting and a <code><limit></code> tag to limit the returned results. Note that the tags and attributes are all case-sensitive. The <code><name></code> tag is the name of the playlist and the <code><match></code> tag indicates how the <code><rule></code> tags should be matched. If <code><match>all</match></code> like in the above example, then only songs which satisfy all the <code><rule></code>'s will be included. If <code><match>one</match></code> is specified, then songs that satisfy any one (or more) of the <code><rule></code>'s will be included.
+
Basically there are two header tags, <code><name></code> and <code><match></code> and then a set of <code><rule></code> tags that define the rules to use, along with an <code><order></code> tag to allow sorting and a <code><limit></code> tag to limit the returned results.  
 +
{{Note|that the tags and attributes are all case-sensitive.}}
 +
The <code><name></code> tag is the name of the playlist and the <code><match></code> tag indicates how the <code><rule></code> tags should be matched. If <code><match>all</match></code> like in the above example, then only songs which satisfy all the <code><rule></code>'s will be included. If <code><match>one</match></code> is specified, then songs that satisfy any one (or more) of the <code><rule></code>'s will be included.
 +
 
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<name>All U2 from after 1990</name>
 +
<match>all</match>
 +
</syntaxhighlight>
  
 
=== Rules ===
 
=== Rules ===
The <code><rule></code> tags, of which there can be as many as you wish, have 2 attributes (<code>field</code> and <code>operator</code>) and a value.
+
The <code><rule></code> tags, of which there can be as many as you wish, have two attributes (<code>field</code> and <code>operator</code>) and a <code><value></code> tag.
 +
 
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<rule field="artist" operator="is">
 +
    <value>U2</value>
 +
</rule>
 +
</syntaxhighlight>
  
 
==== Fields ====
 
==== Fields ====
Depending on the type of the Smart Playlist different <code>field</code>s are available:
+
Depending on the type of the smart playlist different <code>field</code>s are available:
{| class="wikitable" style="margin-right: 0;"
+
{| class="prettytable" style="margin-right: 0;"
 
!colspan="2"|<code>field</code>
 
!colspan="2"|<code>field</code>
 
!colspan="3"|music
 
!colspan="3"|music
 
!colspan="4"|video
 
!colspan="4"|video
!colspan="1"|
+
!colspan="1"|type
 
|-
 
|-
 
!style="padding-left: 5px; padding-right: 10px;"|Name
 
!style="padding-left: 5px; padding-right: 10px;"|Name
Line 169: Line 214:
 
|number
 
|number
 
|{{yes}}
 
|{{yes}}
|{{no}}
+
|{{yes}}
 
|{{no}}
 
|{{no}}
 
|{{yes}}
 
|{{yes}}
Line 194: Line 239:
 
|{{no}}
 
|{{no}}
 
|{{yes}}
 
|{{yes}}
|{{no}}
+
|{{yes}}
 
|{{yes}}
 
|{{yes}}
 
|{{no}}
 
|{{no}}
Line 208: Line 253:
 
|{{yes}}
 
|{{yes}}
 
|{{no}}
 
|{{no}}
 +
|{{yes}}
 +
|-
 +
|style="padding-left: 5px;"|userrating
 +
|number
 +
|{{yes}}
 +
|{{yes}}
 +
|{{no}}
 +
|{{yes}}
 +
|{{yes}}
 +
|{{yes}}
 +
|{{yes}}
 
|{{yes}}
 
|{{yes}}
 
|-
 
|-
Line 226: Line 282:
 
|{{no}}
 
|{{no}}
 
|{{no}}
 
|{{no}}
|{{no}}
+
|{{yes}}
 
|{{no}}
 
|{{no}}
 
|{{no}}
 
|{{no}}
Line 564: Line 620:
 
|style="padding-left: 5px;"|audiolanguage
 
|style="padding-left: 5px;"|audiolanguage
 
|string
 
|string
 +
|{{no}}
 +
|{{no}}
 +
|{{no}}
 +
|{{yes}}
 +
|{{no}}
 +
|{{yes}}
 +
|{{yes}}
 +
|{{yes}}
 +
|-
 +
|style="padding-left: 5px;"|audiotrackcount<ref>added in v17</ref>
 +
|number
 
|{{no}}
 
|{{no}}
 
|{{no}}
 
|{{no}}
Line 575: Line 642:
 
|style="padding-left: 5px;"|subtitlelanguage
 
|style="padding-left: 5px;"|subtitlelanguage
 
|string
 
|string
 +
|{{no}}
 +
|{{no}}
 +
|{{no}}
 +
|{{yes}}
 +
|{{no}}
 +
|{{yes}}
 +
|{{yes}}
 +
|{{yes}}
 +
|-
 +
|style="padding-left: 5px;"|subtitletrackcount<ref>added in v17</ref>
 +
|number
 
|{{no}}
 
|{{no}}
 
|{{no}}
 
|{{no}}
Line 613: Line 691:
 
|{{yes}}
 
|{{yes}}
 
|{{yes}}
 
|{{yes}}
|{{no}}
+
|{{yes}}<ref>added in v15</ref>
 
|{{yes}}
 
|{{yes}}
 
|{{yes}}
 
|{{yes}}
Line 693: Line 771:
 
|{{yes}}
 
|{{yes}}
 
|{{yes}}
 
|{{yes}}
 +
|-
 +
|}
 +
 +
===== Field values =====
 +
{| class="prettytable" style="margin-right: 0;"
 +
! <code>field</code>
 +
! value description
 +
 +
|-
 +
| audiolanguage
 +
| A three letter [http://en.wikipedia.org/w/index.php?title=List_of_ISO_639-2_codes ISO 639-2/'''B''']  value in ''lowercase'' (usually the first three letters of the language name in English). An uppercase value will be ''ignored'' and produce an empty playlist.
 +
|-
 +
| lastplayed
 +
| operator: inthelast/notinthelast<br />  value: X days/weeks/months (X being a number)
 +
|-
 +
|-
 +
| mpaarating
 +
| Uses the [https://en.wikipedia.org/wiki/Motion_Picture_Association_of_America_film_rating_system#MPAA_film_ratings MPAA ratings] in the format: Rated G, Rated PG, Rated PG-13, Rated, Rated R
 +
|-
 +
| subtitlelanguage
 +
| A three letter [http://en.wikipedia.org/w/index.php?title=List_of_ISO_639-2_codes ISO 639-2/'''B'''] value in ''lowercase'' (usually the first three letters of the language name in English). An uppercase value will be ''ignored'' and produce an empty playlist.
 +
|-
 +
| videoaspect
 +
| The value is the [http://en.wikipedia.org/wiki/Aspect_ratio_(image) aspect ratio] in the dot format without the :1, e.g. 1.85<br /> Even though "videoaspect is X" is possible to create, it '''won't''' work and will return an empty list. You ''have to'' use "less than" and/or "greater than".<br />
 +
{{note| This is useless if you have a lot of video files with the black bars in its video (e.g. DVD/BD and remuxes). That'll lead to e.g. 4:3 and 2.35:1 videos also being recognized as 16:9. Even if you set the correct aspect ratio in the movie's [[NFO_files/Movies|NFO file]] (<streamdetails><aspect>) it won't help because the software will always overwrite this data when it plays back the video file (see [https://github.com/xbmc/xbmc/pull/3701 GitHub] about this issue). For now the only solution is to do it manually using [[Video_library_tags|tags]].'' }}
 
|-
 
|-
 
|}
 
|}
Line 698: Line 801:
 
==== Operators ====
 
==== Operators ====
 
The <code>operator</code> attribute specifies the rule that should be used to match the parameter to the <code>field</code>. All matching is done case-insensitive. The allowed <code>operator</code>s are:
 
The <code>operator</code> attribute specifies the rule that should be used to match the parameter to the <code>field</code>. All matching is done case-insensitive. The allowed <code>operator</code>s are:
; contains : True if the field contains the parameter as a substring  
+
 
; doesnotcontain : True if the field does not contain the parameter as a substring  
+
{| class="prettytable" style="margin-right: 0;"
; is : True if the field matches the parameter exactly
+
! <code>operator</code>
; isnot : True if the field does not match the parameter exactly
+
! Definition
; startswith : True if the start of the field matches the parameter  
+
|-
; endswith : True if the end of the field matches the parameter  
+
| contains
; lessthan : True if the content of the field is less than the parameter  
+
| True if the field contains the parameter as a substring  
; greaterthan : True if the content of the field is greater than the parameter
+
|-
; after : True if the content of the field comes after the parameter
+
| doesnotcontain
; before : True if the content of the field comes before the parameter
+
| True if the field does not contain the parameter as a substring  
; inthelast : True if the field falls in the last range specified by the parameter. Only applicable for a date field.
+
|-
; notinthelast : True if the field does not fall in the last range specified by the parameter. Only applicable for a date field.
+
| is
 +
| True if the field matches the parameter exactly
 +
|-
 +
| isnot  
 +
| True if the field does not match the parameter exactly
 +
|-
 +
| startswith  
 +
| True if the start of the field matches the parameter  
 +
|-
 +
| endswith
 +
| True if the end of the field matches the parameter  
 +
|-
 +
| lessthan  
 +
| True if the content of the field is less than the parameter
 +
|-
 +
| greaterthan  
 +
| True if the content of the field is greater than the parameter
 +
|-
 +
| after  
 +
| True if the content of the field comes after the parameter
 +
|-
 +
| before  
 +
| True if the content of the field comes before the parameter
 +
|-
 +
| inthelast  
 +
| True if the field falls in the last range specified by the parameter. Only applicable for a date field.
 +
|-
 +
| notinthelast
 +
| True if the field does not fall in the last range specified by the parameter. Only applicable for a date field.
 +
|}
  
 
=== Limit and Order ===
 
=== Limit and Order ===
Line 715: Line 847:
  
 
The above example, therefore selects all songs whose artist field is U2 and whose year field is greater than 1990, orders them by the number of times they've been played (most played first) then limits it to just 50. Thus, the top 50 songs you've played from all U2 songs published after 1990.
 
The above example, therefore selects all songs whose artist field is U2 and whose year field is greater than 1990, orders them by the number of times they've been played (most played first) then limits it to just 50. Thus, the top 50 songs you've played from all U2 songs published after 1990.
 +
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<limit>50</limit>
 +
<order direction="descending">playcount</order>
 +
</syntaxhighlight>
  
 
=== Grouping ===
 
=== Grouping ===
 +
Grouping was added in v13. The <code><group></code> tag allows to group the resulting list of media items by a specific category. The final list will consist of folder nodes containing matching media items. Depending on the type of the Smart Playlist the following grouping categories exist:
  
{{Gotham}}
+
{| class="prettytable" style="margin-right: 0;"
 
 
The <code><group></code> tag allows to group the resulting list of media items by a specific category. The final list will consist of folder nodes containing matching media items. Depending on the type of the Smart Playlist the following grouping categories exist:
 
 
 
{| class="wikitable" style="margin-right: 0;"
 
 
!colspan="2"|<code>field</code>
 
!colspan="2"|<code>field</code>
 
!colspan="3"|music
 
!colspan="3"|music
Line 810: Line 944:
 
|{{no}}
 
|{{no}}
 
|{{no}}
 
|{{no}}
|{{no}}
+
|{{yes}}
 
|{{no}}
 
|{{no}}
 
|{{yes}}
 
|{{yes}}
Line 868: Line 1,002:
 
For the '''sets''' grouping category there is support for additional so called mixed grouping. The difference to normal grouping is that the resulting list will not just be a list of grouped folders but a mix of media items and grouped folders. Mixed grouping can be controlled using the '''mixed''' attribute in the <code><group></code> tag with a boolean value (''true'' or ''false'').
 
For the '''sets''' grouping category there is support for additional so called mixed grouping. The difference to normal grouping is that the resulting list will not just be a list of grouped folders but a mix of media items and grouped folders. Mixed grouping can be controlled using the '''mixed''' attribute in the <code><group></code> tag with a boolean value (''true'' or ''false'').
  
== Combining Playlists ==
+
== Combining playlists ==
 
The <code>playlist</code> <code>field</code> can be used to combine several playlists together. When playlists are combined, the <code><limit></code> and <code><order></code> tags of the included playlists are ignored; only the <code><order></code> and <code><limit></code> of the final playlist are used.
 
The <code>playlist</code> <code>field</code> can be used to combine several playlists together. When playlists are combined, the <code><limit></code> and <code><order></code> tags of the included playlists are ignored; only the <code><order></code> and <code><limit></code> of the final playlist are used.
  
Line 874: Line 1,008:
  
 
'''Recently played rock tracks from the 1970s'''
 
'''Recently played rock tracks from the 1970s'''
<source lang="xml">
+
<syntaxhighlight lang="xml" enclose="div">
 
<?xml version="1.0"?>
 
<?xml version="1.0"?>
 
<smartplaylist type="songs">
 
<smartplaylist type="songs">
Line 882: Line 1,016:
 
   <rule field="playlist" operator="is">Recently Played Songs</rule>
 
   <rule field="playlist" operator="is">Recently Played Songs</rule>
 
</smartplaylist>
 
</smartplaylist>
</source>
+
</syntaxhighlight>
  
 
Using this system allows very complex queries to be built. Note that in a single playlist, you can only match ALL of the rules, or ONE (or more) of the rules. This is basically either ANDing the conditions together, or ORing them together. You cannot mix AND with OR in a single playlist. To build up a playlist with both AND and OR operations on the rules, you use multiple playlists to group the AND operations and the OR operations, then combine them as above.
 
Using this system allows very complex queries to be built. Note that in a single playlist, you can only match ALL of the rules, or ONE (or more) of the rules. This is basically either ANDing the conditions together, or ORing them together. You cannot mix AND with OR in a single playlist. To build up a playlist with both AND and OR operations on the rules, you use multiple playlists to group the AND operations and the OR operations, then combine them as above.
  
 
== Examples ==
 
== Examples ==
=== Recently played songs ===
+
=== Movie examples ===
<source lang="xml">
+
====In progress movies====
<?xml version="1.0"?>
+
Moives that are still ''in progress'' ordered by ''last played''.
 +
<syntaxhighlight lang=xml>
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="movies">
 +
    <name>In progress movies</name>
 +
    <match>all</match>
 +
    <rule field="inprogress" operator="true" />
 +
    <order direction="descending">lastplayed</order>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
====Last played movies (history)====
 +
Not ''in progress'' movies with a ''play count'' bigger than 0 ordered by ''last played''.
 +
<syntaxhighlight lang=xml>
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="movies">
 +
    <name>Last played movies (history)</name>
 +
    <match>all</match>
 +
    <rule field="inprogress" operator="false" />
 +
    <rule field="playcount" operator="greaterthan">
 +
        <value>0</value>
 +
    </rule>
 +
    <order direction="descending">lastplayed</order>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
==== One random movie ====
 +
Only ''one'' movie is added to the playlist. This isn't possible to create in the GUI because the lower limit is 10 (or at least the limit needs to be edited afterward).<br />
 +
Even though the limit is only ''one'' you still need to set ''random'' order.
 +
 
 +
Though the difference between a playlist containing the GUI minimum 10 or edited to contain only 1 isn't significant. Pressing play on both of them will play a random movie. The "benefit" with a playlist only containing one movie is that you'll only be presented with one if you open the playlist.
 +
 
 +
<syntaxhighlight lang=xml>
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="movies">
 +
    <name>Random movie</name>
 +
    <match>all</match>
 +
    <rule field="playcount" operator="is">
 +
        <value>0</value>
 +
    </rule>
 +
    <limit>1</limit>
 +
    <order direction="ascending">random</order>
 +
</smartplaylist>
 +
</syntaxhighlight><br />
 +
 
 +
==== Movies with a specific subtitle language ====
 +
Movies that contain Swedish (swe) internal subtitles.
 +
<syntaxhighlight lang=xml>
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="movies">
 +
    <name>Movies with Swedish subs</name>
 +
    <match>all</match>
 +
    <rule field="subtitlelanguage" operator="is">
 +
        <value>swe</value>
 +
    </rule>
 +
    <group>none</group>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
=== Music examples ===
 +
==== Recently played songs ====
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 
<smartplaylist type="songs">
 
<smartplaylist type="songs">
  <name>Recently Played Songs</name>
+
    <name>Recently Played Songs</name>
  <match>all</match>
+
    <match>all</match>
  <rule field="lastplayed" operator="inthelast">2 weeks</rule>
+
    <rule field="lastplayed" operator="inthelast">
  <order direction="descending">lastplayed</order>
+
        <value>2 weeks</value>
 +
    </rule>
 +
    <order direction="descending">lastplayed</order>
 
</smartplaylist>
 
</smartplaylist>
</source>
+
</syntaxhighlight>
  
=== Top 100 songs ===
+
==== Top 100 songs ====
<source lang="xml">
+
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0"?>
+
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 
<smartplaylist type="songs">
 
<smartplaylist type="songs">
  <name>Top 100 Songs</name>
+
    <name>Top 100 Songs</name>
  <match>all</match>
+
    <match>all</match>
  <rule field="playcount" operator="greaterthan">0</rule>
+
    <rule field="playcount" operator="greaterthan">
  <order direction="descending">playcount</order>
+
        <value>0</value>
  <limit>100</limit>
+
    </rule>
 +
    <order direction="descending">playcount</order>
 +
    <limit>100</limit>
 
</smartplaylist>
 
</smartplaylist>
</source>
+
</syntaxhighlight>
  
=== Rock music from the 1970s ===
+
==== Rock music from the 1970s ====
<source lang="xml">
+
<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0"?>
+
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 
<smartplaylist type="songs">
 
<smartplaylist type="songs">
  <name>Rock Music from the 1970s</name>
+
    <name>Rock Music from the 1970s</name>
  <match>all</match>
+
    <match>all</match>
  <rule field="genre" operator="is">Rock</rule>
+
    <rule field="genre" operator="is">
  <rule field="year" operator="greaterthan">1969</rule>
+
        <value>Rock</value>
  <rule field="year" operator="lessthan">1980</rule>
+
    </rule>
 +
    <rule field="year" operator="greaterthan">
 +
        <value>1969</value>
 +
    </rule>
 +
    <rule field="year" operator="lessthan">
 +
        <value>1980</value>
 +
    </rule>
 +
</smartplaylist>
 +
</syntaxhighlight><br />
 +
 
 +
=== TV show examples ===
 +
==== Last played episodes (history) ====
 +
Not ''in progress'' episodes and with a ''play count'' bigger than 0 from the last ''6 months'' ordered by ''last played''.
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="episodes">
 +
    <name>Last played episodes (history)</name>
 +
    <match>all</match>
 +
    <rule field="lastplayed" operator="inthelast">
 +
        <value>6 months</value>
 +
    </rule>
 +
    <rule field="inprogress" operator="false" />
 +
    <rule field="playcount" operator="greaterthan">
 +
        <value>0</value>
 +
    </rule>
 +
    <order direction="descending">lastplayed</order>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
==== In progress episodes ====
 +
Episodes that are still ''in progress'' from the last ''2 weeks'' ordered by ''last played''.
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="episodes">
 +
    <name>In progress episodes</name>
 +
    <match>all</match>
 +
    <rule field="lastplayed" operator="inthelast">
 +
        <value>2 weeks</value>
 +
    </rule>
 +
    <rule field="inprogress" operator="true" />
 +
    <order direction="descending">lastplayed</order>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
==== Last played TV shows ====
 +
TV shows that've been played in the last ''3 months'' ordered by ''last played'' with ''play count 0''.
 +
 
 +
The ''play count'' setting makes it so if all episodes have been watched it doesn't show up, but as soon new unplayed episodes or seasons are scraped the TV Show will show up again in the playlist.
 +
 
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="tvshows">
 +
    <name>Last played TV shows</name>
 +
    <match>all</match>
 +
    <rule field="lastplayed" operator="inthelast">
 +
        <value>3 months</value>
 +
    </rule>
 +
    <rule field="playcount" operator="is">
 +
        <value>0</value>
 +
    </rule>
 +
    <order direction="descending">lastplayed</order>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
==== TV show with specific episode names ====
 +
A playlist with The Simpsons' ''Treehouse'' of Terror episodes.
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="episodes">
 +
    <name>The Simpsons - Treehouse of Horror</name>
 +
    <match>all</match>
 +
    <rule field="title" operator="contains">
 +
        <value>Treehouse</value>
 +
    </rule>
 +
    <rule field="tvshow" operator="is">
 +
        <value>The Simpsons</value>
 +
    </rule>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
==== Random unplayed episodes from a TV show ====
 +
''10 random'' episodes with a ''play count of 0'' from ''The Simpsons''.
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="episodes">
 +
    <name>Random episodes - The Simpsons</name>
 +
    <match>all</match>
 +
    <rule field="tvshow" operator="is">
 +
        <value>The Simpsons</value>
 +
    </rule>
 +
    <rule field="playcount" operator="is">
 +
        <value>0</value>
 +
    </rule>
 +
    <limit>10</limit>
 +
    <order direction="ascending">random</order>
 +
</smartplaylist>
 +
</syntaxhighlight>
 +
 
 +
==== Random unplayed episodes from several TV shows ====
 +
''10 random'' episodes with a ''play count of 0'' (i.e. unplayed) from six different shows. Though as it's random this can create a list with two to ten episodes of the same show in a row.
 +
 
 +
If you specifically want to watch 6 random episodes from 6 different shows you could create playlists that are limited to 1 episode and 1 show (see [[Smart_playlists#One_random_movie|One random movie]] example). Then you queue the 6 playlists.
 +
<syntaxhighlight lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
 +
<smartplaylist type="episodes">
 +
    <name>Random episodes - AAFFSS</name>
 +
    <match>all</match>
 +
    <rule field="tvshow" operator="is">
 +
        <value>American Dad</value>
 +
        <value>Archer</value>
 +
        <value>Family Guy</value>
 +
        <value>Futurama</value>
 +
        <value>South Park</value>
 +
        <value>The Simpsons</value>
 +
    </rule>
 +
    <rule field="playcount" operator="is">
 +
        <value>0</value>
 +
    </rule>
 +
    <limit>10</limit>
 +
    <order direction="ascending">random</order>
 
</smartplaylist>
 
</smartplaylist>
</source>
+
</syntaxhighlight>
 +
 
 +
== Notes ==
 +
<references/>
  
 +
{{Helix updated}}
  
[[Category:Video Library]]
+
[[Category:Video library]]
[[Category:Music Library]]
+
[[Category:Music library]]
 +
[[Category:Manual]]

Revision as of 22:58, 20 July 2020

Home icon grey.png   ▶ Playlists ▶ Smart playlists
Time.png THIS PAGE IS OUTDATED:

This page or section has not been updated in a long time and may not be reliable.
Please consider updating it.


Kodi supports smart playlists for all types of media (excluding pictures), which essentially use a set of rules to limit the results from the databases. This means that to be able to create a smart playlist in the GUI, music/video must first be added to the libraries using a scraper addon or by creating NFO files. Smart playlist can be created either by using the built-in GUI smart playlist editor accessible from the Playlists section, or by creating an XML file with the extension XSP (XBMC Smart Playlist).

1 Creating a smart playlist in the GUI

1.1 Smart playlist for music

Music -> Playlists -> New smart playlist

1.2 Smart playlist for video

Video -> Playlists -> New smart playlist

2 Party Mode playlists

See: Party Mode

3 Format of a smart playlist file

Smart playlists are plain text files that can be parsed by an XML reader (e.g. Visual Studio and Notepad++). Any text editor can be used to create them. They should be saved with the extension XSP and placed in your userdata directory, as there is only limited support for smart playlists saved outside of the userdata folder.

The format is as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="songs">
    <name>All U2 from after 1990</name>
    <match>all</match>
    <rule field="artist" operator="is">
        <value>U2</value>
    </rule>
    <rule field="year" operator="greaterthan">
        <value>1990</value>
    </rule>
    <limit>50</limit>
    <order direction="descending">playcount</order>
</smartplaylist>

3.1 Types

Smart playlists can be of one of the following types:

  • songs (default)
  • albums
  • movies
  • tvshows
  • episodes
  • musicvideos
  • mixed (audio and music videos)
<smartplaylist type="songs">

3.2 Name and Match

Basically there are two header tags, <name> and <match> and then a set of <rule> tags that define the rules to use, along with an <order> tag to allow sorting and a <limit> tag to limit the returned results. Note: that the tags and attributes are all case-sensitive. The <name> tag is the name of the playlist and the <match> tag indicates how the <rule> tags should be matched. If <match>all</match> like in the above example, then only songs which satisfy all the <rule>'s will be included. If <match>one</match> is specified, then songs that satisfy any one (or more) of the <rule>'s will be included.

<name>All U2 from after 1990</name>
<match>all</match>

3.3 Rules

The <rule> tags, of which there can be as many as you wish, have two attributes (field and operator) and a <value> tag.

<rule field="artist" operator="is">
    <value>U2</value>
</rule>

3.3.1 Fields

Depending on the type of the smart playlist different fields are available:

field music video type
Name Data type songs albums artists movies tvshows episodes musicvideos mixed
genre string Yes Yes Yes Yes Yes Yes Yes Yes
album string Yes Yes No No No No Yes Yes
artist string Yes Yes Yes No No No Yes Yes
albumartist string Yes Yes No No No No Yes Yes
title string Yes No No Yes No No Yes Yes
year number Yes Yes No Yes Yes Yes Yes Yes
time number Yes No No Yes No Yes Yes Yes
tracknumber number Yes No No No No No No Yes
filename string Yes No No Yes No Yes Yes Yes
path string Yes No No Yes Yes Yes Yes Yes
playcount number Yes Yes No Yes Yes Yes Yes Yes
lastplayed date Yes No No Yes No Yes Yes Yes
inprogress boolean No No No Yes Yes Yes No Yes
rating number Yes Yes No Yes Yes Yes No Yes
userrating number Yes Yes No Yes Yes Yes Yes Yes
comment string Yes No No No No No No Yes
dateadded date No No No Yes No No No No
plot string No No No Yes Yes Yes Yes Yes
plotoutline string No No No Yes No No No Yes
tagline string No No No Yes No No No Yes
mpaarating string No No No Yes Yes Yes No Yes
top250 number No No No Yes No No No Yes
status string No No No No Yes No No Yes
votes number No No No Yes Yes Yes No Yes
director string No No No Yes Yes Yes Yes Yes
actor string No No No Yes Yes Yes No Yes
studio string No No No Yes Yes Yes Yes Yes
country string No No No Yes No No No Yes
numepisodes number No No No No Yes No No Yes
numwatched number No No No No Yes No No Yes
writers string No No No Yes No Yes No Yes
airdate date No No No No No Yes No Yes
episode number No No No No No Yes No Yes
season number No No No No No Yes No Yes
tvshow string No No No No Yes Yes No Yes
episodetitle string No No No No No Yes No Yes
review string No Yes No No No No No Yes
themes string No Yes No No No No No Yes
moods string No Yes Yes No No No No Yes
styles string No Yes Yes No No No No Yes
type string No Yes No No No No No Yes
label string No Yes No No No No No Yes
hastrailer boolean No No No Yes No No No Yes
videoresolution number No No No Yes No Yes Yes Yes
audiochannels number No No No Yes No Yes Yes Yes
videocodec string No No No Yes No Yes Yes Yes
audiocodec string No No No Yes No Yes Yes Yes
audiolanguage string No No No Yes No Yes Yes Yes
audiotrackcount[1] number No No No Yes No Yes Yes Yes
subtitlelanguage string No No No Yes No Yes Yes Yes
subtitletrackcount[2] number No No No Yes No Yes Yes Yes
videoaspect number No No No Yes No Yes Yes Yes
set string No No No Yes No No No Yes
tag string No No No Yes Yes Yes[3] Yes Yes
instruments string No No Yes No No No No No
biography string No No Yes No No No No No
born string No No Yes No No No No No
band formed string No No Yes No No No No No
disbanded string No No Yes No No No No No
died string No No Yes No No No No No
playlist string Yes Yes Yes Yes Yes Yes Yes Yes
3.3.1.1 Field values
field value description
audiolanguage A three letter ISO 639-2/B value in lowercase (usually the first three letters of the language name in English). An uppercase value will be ignored and produce an empty playlist.
lastplayed operator: inthelast/notinthelast
value: X days/weeks/months (X being a number)
mpaarating Uses the MPAA ratings in the format: Rated G, Rated PG, Rated PG-13, Rated, Rated R
subtitlelanguage A three letter ISO 639-2/B value in lowercase (usually the first three letters of the language name in English). An uppercase value will be ignored and produce an empty playlist.
videoaspect The value is the aspect ratio in the dot format without the :1, e.g. 1.85
Even though "videoaspect is X" is possible to create, it won't work and will return an empty list. You have to use "less than" and/or "greater than".

Note: This is useless if you have a lot of video files with the black bars in its video (e.g. DVD/BD and remuxes). That'll lead to e.g. 4:3 and 2.35:1 videos also being recognized as 16:9. Even if you set the correct aspect ratio in the movie's NFO file (<streamdetails><aspect>) it won't help because the software will always overwrite this data when it plays back the video file (see GitHub about this issue). For now the only solution is to do it manually using tags.

3.3.2 Operators

The operator attribute specifies the rule that should be used to match the parameter to the field. All matching is done case-insensitive. The allowed operators are:

operator Definition
contains True if the field contains the parameter as a substring
doesnotcontain True if the field does not contain the parameter as a substring
is True if the field matches the parameter exactly
isnot True if the field does not match the parameter exactly
startswith True if the start of the field matches the parameter
endswith True if the end of the field matches the parameter
lessthan True if the content of the field is less than the parameter
greaterthan True if the content of the field is greater than the parameter
after True if the content of the field comes after the parameter
before True if the content of the field comes before the parameter
inthelast True if the field falls in the last range specified by the parameter. Only applicable for a date field.
notinthelast True if the field does not fall in the last range specified by the parameter. Only applicable for a date field.

3.4 Limit and Order

The <limit> tag simply takes a number of songs as it's limit. A missing limit tag, or <limit>0</limit> will retrieve all matching songs. The <order> tag has a direction attribute, the values of which can be ascending or descending, and it's value is a field as above, or can be <order>random</order> if you want a random ordering returned. Note that random should be used with care - it is quite slow if the returned results from the <rule> sets is large (more than 500 items).

The above example, therefore selects all songs whose artist field is U2 and whose year field is greater than 1990, orders them by the number of times they've been played (most played first) then limits it to just 50. Thus, the top 50 songs you've played from all U2 songs published after 1990.

<limit>50</limit>
<order direction="descending">playcount</order>

3.5 Grouping

Grouping was added in v13. The <group> tag allows to group the resulting list of media items by a specific category. The final list will consist of folder nodes containing matching media items. Depending on the type of the Smart Playlist the following grouping categories exist:

field music video
Name Data type songs albums artists movies tvshows episodes musicvideos mixed
none string No No No Yes No No No No
genres string No No Yes Yes Yes No Yes Yes
years string No Yes No Yes Yes No Yes Yes
actors string No No No Yes Yes Yes No No
artists string No No No No No No Yes Yes
directors string No No No Yes Yes Yes Yes Yes
writers string No No No Yes No Yes No No
studios string No No No Yes Yes No Yes Yes
countries string No No No Yes No No No No
sets string No No No Yes No No No No
tags string No No No Yes Yes No Yes Yes
Emblem-important-yellow.png NOTICE:
There's an important difference between not providing a <group> tag (or providing an empty <group> tag) and setting the value of the <group> tag to none: The latter will overrule any mixed grouping that would be applied by default to a list of media items (specifically for a mixed list of movies and movie sets if the setting Group movies into sets is enabled).

3.5.1 Mixed grouping

For the sets grouping category there is support for additional so called mixed grouping. The difference to normal grouping is that the resulting list will not just be a list of grouped folders but a mix of media items and grouped folders. Mixed grouping can be controlled using the mixed attribute in the <group> tag with a boolean value (true or false).

4 Combining playlists

The playlist field can be used to combine several playlists together. When playlists are combined, the <limit> and <order> tags of the included playlists are ignored; only the <order> and <limit> of the final playlist are used.

As a simple example, lets create a new playlist combining the "Rock Music from the 1970s" and "Recently Played Songs" playlists above, to produce a playlist with the recently played rock songs from the 1970s.

Recently played rock tracks from the 1970s

<?xml version="1.0"?>
<smartplaylist type="songs">
  <name>Recently played  Rock Tracks from the 1970s</name>
  <match>all</match>
  <rule field="playlist" operator="is">Rock Music from the 1970s</rule>
  <rule field="playlist" operator="is">Recently Played Songs</rule>
</smartplaylist>

Using this system allows very complex queries to be built. Note that in a single playlist, you can only match ALL of the rules, or ONE (or more) of the rules. This is basically either ANDing the conditions together, or ORing them together. You cannot mix AND with OR in a single playlist. To build up a playlist with both AND and OR operations on the rules, you use multiple playlists to group the AND operations and the OR operations, then combine them as above.

5 Examples

5.1 Movie examples

5.1.1 In progress movies

Moives that are still in progress ordered by last played.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="movies">
    <name>In progress movies</name>
    <match>all</match>
    <rule field="inprogress" operator="true" />
    <order direction="descending">lastplayed</order>
</smartplaylist>

5.1.2 Last played movies (history)

Not in progress movies with a play count bigger than 0 ordered by last played.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="movies">
    <name>Last played movies (history)</name>
    <match>all</match>
    <rule field="inprogress" operator="false" />
    <rule field="playcount" operator="greaterthan">
        <value>0</value>
    </rule>
    <order direction="descending">lastplayed</order>
</smartplaylist>

5.1.3 One random movie

Only one movie is added to the playlist. This isn't possible to create in the GUI because the lower limit is 10 (or at least the limit needs to be edited afterward).
Even though the limit is only one you still need to set random order.

Though the difference between a playlist containing the GUI minimum 10 or edited to contain only 1 isn't significant. Pressing play on both of them will play a random movie. The "benefit" with a playlist only containing one movie is that you'll only be presented with one if you open the playlist.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="movies">
    <name>Random movie</name>
    <match>all</match>
    <rule field="playcount" operator="is">
        <value>0</value>
    </rule>
    <limit>1</limit>
    <order direction="ascending">random</order>
</smartplaylist>

5.1.4 Movies with a specific subtitle language

Movies that contain Swedish (swe) internal subtitles.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="movies">
    <name>Movies with Swedish subs</name>
    <match>all</match>
    <rule field="subtitlelanguage" operator="is">
        <value>swe</value>
    </rule>
    <group>none</group>
</smartplaylist>

5.2 Music examples

5.2.1 Recently played songs

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="songs">
    <name>Recently Played Songs</name>
    <match>all</match>
    <rule field="lastplayed" operator="inthelast">
        <value>2 weeks</value>
    </rule>
    <order direction="descending">lastplayed</order>
</smartplaylist>

5.2.2 Top 100 songs

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="songs">
    <name>Top 100 Songs</name>
    <match>all</match>
    <rule field="playcount" operator="greaterthan">
        <value>0</value>
    </rule>
    <order direction="descending">playcount</order>
    <limit>100</limit>
</smartplaylist>

5.2.3 Rock music from the 1970s

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="songs">
    <name>Rock Music from the 1970s</name>
    <match>all</match>
    <rule field="genre" operator="is">
        <value>Rock</value>
    </rule>
    <rule field="year" operator="greaterthan">
        <value>1969</value>
    </rule>
    <rule field="year" operator="lessthan">
        <value>1980</value>
    </rule>
</smartplaylist>

5.3 TV show examples

5.3.1 Last played episodes (history)

Not in progress episodes and with a play count bigger than 0 from the last 6 months ordered by last played.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="episodes">
    <name>Last played episodes (history)</name>
    <match>all</match>
    <rule field="lastplayed" operator="inthelast">
        <value>6 months</value>
    </rule>
    <rule field="inprogress" operator="false" />
    <rule field="playcount" operator="greaterthan">
        <value>0</value>
    </rule>
    <order direction="descending">lastplayed</order>
</smartplaylist>

5.3.2 In progress episodes

Episodes that are still in progress from the last 2 weeks ordered by last played.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="episodes">
    <name>In progress episodes</name>
    <match>all</match>
    <rule field="lastplayed" operator="inthelast">
        <value>2 weeks</value>
    </rule>
    <rule field="inprogress" operator="true" />
    <order direction="descending">lastplayed</order>
</smartplaylist>

5.3.3 Last played TV shows

TV shows that've been played in the last 3 months ordered by last played with play count 0.

The play count setting makes it so if all episodes have been watched it doesn't show up, but as soon new unplayed episodes or seasons are scraped the TV Show will show up again in the playlist.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="tvshows">
    <name>Last played TV shows</name>
    <match>all</match>
    <rule field="lastplayed" operator="inthelast">
        <value>3 months</value>
    </rule>
    <rule field="playcount" operator="is">
        <value>0</value>
    </rule>
    <order direction="descending">lastplayed</order>
</smartplaylist>

5.3.4 TV show with specific episode names

A playlist with The Simpsons' Treehouse of Terror episodes.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="episodes">
    <name>The Simpsons - Treehouse of Horror</name>
    <match>all</match>
    <rule field="title" operator="contains">
        <value>Treehouse</value>
    </rule>
    <rule field="tvshow" operator="is">
        <value>The Simpsons</value>
    </rule>
</smartplaylist>

5.3.5 Random unplayed episodes from a TV show

10 random episodes with a play count of 0 from The Simpsons.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="episodes">
    <name>Random episodes - The Simpsons</name>
    <match>all</match>
    <rule field="tvshow" operator="is">
        <value>The Simpsons</value>
    </rule>
    <rule field="playcount" operator="is">
        <value>0</value>
    </rule>
    <limit>10</limit>
    <order direction="ascending">random</order>
</smartplaylist>

5.3.6 Random unplayed episodes from several TV shows

10 random episodes with a play count of 0 (i.e. unplayed) from six different shows. Though as it's random this can create a list with two to ten episodes of the same show in a row.

If you specifically want to watch 6 random episodes from 6 different shows you could create playlists that are limited to 1 episode and 1 show (see One random movie example). Then you queue the 6 playlists.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="episodes">
    <name>Random episodes - AAFFSS</name>
    <match>all</match>
    <rule field="tvshow" operator="is">
        <value>American Dad</value>
        <value>Archer</value>
        <value>Family Guy</value>
        <value>Futurama</value>
        <value>South Park</value>
        <value>The Simpsons</value>
    </rule>
    <rule field="playcount" operator="is">
        <value>0</value>
    </rule>
    <limit>10</limit>
    <order direction="ascending">random</order>
</smartplaylist>

6 Notes

  1. added in v17
  2. added in v17
  3. added in v15