Smart playlists/XSP Method

From Official Kodi Wiki
< Smart playlists
Revision as of 23:02, 12 February 2023 by Karellen (talk | contribs) (Updated for v20)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
Smart Playlists Contents

Home icon grey.png   ▶ Playlists ▶ Smart playlists ▶ XSP Method

Location of XSP Files

The XSP (XBMC Smart Playlist) files are located in the userdata/playlists folder. The location of this folder for each platform is shown in the table below.

Within the /playlists/ folder are three subfolders - mixed, music and video. Playlists must be saved in the correct subfolder.

After saving a XSP file, there is normally no need to restart Kodi, but if the Smart Playlist Manager is active, you may need to exit out and re-enter to display the new XSP files.

The Userdata folder is a subfolder of the Kodi Data Folder and is located as shown in the table below.

Operating system Userdata Folder
Android Android/data/org.xbmc.kodi/files/.kodi/userdata/ (see note)
iOS /private/var/mobile/Library/Preferences/Kodi/userdata/
LibreELEC /storage/.kodi/userdata/
Linux ~/.kodi/userdata/
macOS /Users/<your_user_name>/Library/Application Support/Kodi/userdata/
Nvidia Shield (SMB) smb://<nvidiashieldurl>/internal/Android/data/org.xbmc.kodi/files/.kodi/userdata
OSMC /home/osmc/.kodi/userdata/
tvOS /private/var/mobile/Library/Preferences/Kodi/userdata/
webOS /media/developer/apps/usr/palm/applications/org.xbmc.kodi/.kodi/userdata/
Windows %APPDATA%\Kodi\userdata
Windows Portable <Install location chosen by you>\portable_data\userdata\
Windows via Microsoft Store %LOCALAPPDATA%\Packages\XBMCFoundation.Kodi_4n2hpmxwrvr6p\LocalCache\Roaming\Kodi\
Windows Xbox %LOCALAPPDATA%\Packages\XBMCFoundation.Kodi_4n2hpmxwrvr6p\LocalCache\Roaming\Kodi\
Note: In some Android setups the path may be slightly different to the one stated above.

Editing XSP Files

Smart playlists are plain text files that any text editor can create, but we recommend using an editor that can parse XML such as Visual Studio Code or Notepad++.

Breakdown of XSP File

The XSP file consists of the following:

  • Two header tags, <name> and <match>
  • One or more <rule> tags that define the rules to use
  • A <limit> tag to limit the returned results
  • A <group> tag to allow grouping of results
  • An <order> tag to sort the display of the results

Note: All tags and attributes are case-sensitive.

The following example is used to explain each component of the code.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<smartplaylist type="movies">
    <name>SciFi by Year</name>
    <rule field="genre" operator="is">
        <value>Science Fiction</value>
    <order direction="descending">lastplayed</order>

XML Declaration

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

Must be the first line of the XSP file and there are no variations.

Top Level Tags

<smartplaylist type="movies">

Top level parent tag which also defines the media type. Only one type can be used and different types of media cannot be mixed into a single playlist.

Available types:

  • Songs
  • Albums
  • Artists
  • Movies
  • TV shows
  • Episodes
  • Music Videos
  • Mixed - used to combine Music and Music Videos.


    <name>SciFi by Year</name>

The name of the playlist. The name you enter here will be displayed in Kodi.



If two or more rules have been created add the appropriate rule matching method. If only one rule, use the default all

  • all - an item must match all rules for it to be displayed in the list
  • one - an item needs to match only one of the rules for it to be displayed in the list


    <rule field="genre" operator="is">
        <value>Science Fiction</value>

The rule determines how your titles are filtered and added to the smart playlist.

A rule can have multiple <value> entries. Multiple rules can be used in a single smart playlist.

The tag has two attributes:

  • field - Determines which field in the database the rule is applied to
  • operator - Specifies how rule is to be applied. All matching is done case-insensitive. See the Available Rules page for available operators

The <value> tag provides the string to be matched.

For a list of available fields and operators see... Rules & Groupings



Adds grouping to the results. The displayed list will consist of folder nodes containing matching media items.

eg Selecting group by genre will open a list of all the genres that are used by the titles that match the rules. Then select a genre to see the title list.

The mixed operator can only be used when Sets is chosen as the value. It allows combining of what is considered two classes of media - a set/collection and a movie

  • Disabled - Will only list the collection for movies that belong to a Set. Enter a collection to see the individual movie(s) that match the rule(s).
  • Enabled - Will show the collection that the matching movies belong to as well as the individual movies that do not belong to a set/collection.

For a list of available groupings see... Rules & Groupings



Used to limit the number of matches in the list. You may want to display all matches or limit to the first 100 matches, for example.

To display all items, omit the tag.


    <order direction="descending">lastplayed</order>

The order tag will determine the order of the items in the list.

The <order> tag has a direction attribute which can be ascending or descending.

The value can be any value that is used in the Rule field.

For random order use <order>random</order>. Random should be used with care as it can be slow on large libraries.


  • The rule fields and rule operators can change between Kodi versions. If unsure of available fields and operators, use the GUI method to create the start of your playlist to pre-fill in the unknown fields and operators.

Return to top