This guide is intended only as a more in depth instruction for manipulating file paths either for broken links or performance modification. For other applications of path substitution you can consult Kodi’s wiki on the subject.
At its core, path substitution is a simple concept. You are simply adding <from> and <to> tags to an advancedsettings.xml file that specify a part of a file path that will get replaced, and the new path that will be replacing it. Kodi will use this whenever it is trying to access a file or folder. This redirection is done on the fly and does not change how the file paths are stored in your database, nor does it modify your sources. This is a method you would use INSTEAD of modifying your sources and re-scraping.
To try to clarify exactly the behavior that happens let’s look at a hypothetical situation. Say you have a file in your library with the path
smb://old_nas/movies/Zone Troopers (1985)/Zone Troopers.mkv
and that stopped working when you upgraded to a new NAS that has all your movies located at
smb://new_nas/new_movies/
If we add a path substitution replacing
<from>smb://old_nas/movies/</from>
<to>smb://new_nas/new_movies/</to>
then when Kodi tries to access that file it substitute’s the specified text so it will then look for the file in
smb://new_nas/new_movies/Zone Troopers (1985)/Zone Troopers.mkv
It is important to understand that this is only happening when Kodi attempts to access a file path. This substitution does not modify anything in your database, nor does it use this substitution when it stores information when it scrapes new files. For example if you add a new file in the new NAS in our example above located at
smb://new_nas/new_movies/Airplane (1980)/Airplane.mkv
and you update your library it gets stored in your database as being located at
smb://old_nas/movies/Airplane (1980)/Airplane.mkv
because your source is still configured to the original location.
If you’re going to use path substitution it is important that you DO NOT update your source paths, or add new ones that point to the new location. If you want to do that, do not use path substitution. If we take the example above and change our source to point to our new network location, when we update the library we will have stored in the database four movies at the following locations
smb://old_nas/movies/Zone Troopers (1985)/Zone Troopers.mkv
smb://old_nas/movies/Airplane (1980)/Airplane.mkv
smb://new_nas/ new_movies/Zone Troopers (1985)/Zone Troopers.mkv
smb://new_nas/ new_movies/Airplane (1980)/Airplane.mkv
This is particularly bad as with the file substitution active all four file paths are valid and the duplicates cannot be automatically removed by running a “clean library” as that only removes entries without valid paths. To fix this without manually deleting each item you would have to remove the path substitution so the old paths no longer work, and then run “clean library”. At this point you might as well have deleted your library and started over from scratch to start with.
The obvious benefit to this is that by changing one file your library is instantly fixed. If you ever need to change your path again all you need to do is change the path you have set as <to>. This requires no re-scraping of your library, and incurs no performance hit.
To make a file substitution from the terminal you can type in
nano ~/.kodi/userdata/advancedsettings.xml
And the text you would need would look like this
<advancedsettings>
<pathsubstitution>
<substitute>
<from>old</from>
<to>new</to>
</substitute>
</pathsubstitution>
</advancedsettings>
Replacing the “old” and “new” with the file paths you need to change. To save your edits and close the text editor you can press ctrl-x, then y, then press enter.
EXAMPLES
Converting from Kodi network paths to system mounts
<advancedsettings>
<pathsubstitution>
<substitute>
<from>smb://192.168.0.10/</from>
<to>/mnt/server/</to>
</substitute>
</pathsubstitution>
</advancedsettings>
Converting from using SMB to NFS
<advancedsettings>
<pathsubstitution>
<substitute>
<from>smb://192.168.0.10/</from>
<to>nfs://192.168.0.10/</to>
</substitute>
</pathsubstitution>
</advancedsettings>
Replaced USB drive and file path changed
<advancedsettings>
<pathsubstitution>
<substitute>
<from>/media/MyBook/movie/</from>
<to>/media/Elements/Movies/</to>
</substitute>
<substitute>
<from>/media/MyBook/tv/</from>
<to>/media/Elements/TV Shows/</to>
</substitute>
</pathsubstitution>
</advancedsettings>
Your network location changed
<advancedsettings>
<pathsubstitution>
<substitute>
<from>smb://192.168.0.10/</from>
<to>smb://192.168.1.55/</to>
</substitute>
</pathsubstitution>
</advancedsettings>
What this file may look like when you’re using other setting
<?xml version="1.0" encoding="utf-8"?>
<advancedsettings>
<videodatabase>
<type>mysql</type>
<host>192.168.0.201</host>
<port>3306</port>
<user>xbmc</user>
<pass>xbmc</pass>
</videodatabase>
<musicdatabase>
<type>mysql</type>
<host>192.168.0.201</host>
<port>3306</port>
<user>xbmc</user>
<pass>xbmc</pass>
</musicdatabase>
<imageres>720</imageres>
<fanartres>1080</fanartres>
<videolibrary>
<importwatchedstate>true</importwatchedstate>
</videolibrary>
<slideshow>
<blackbarcompensation>0</blackbarcompensation>
</slideshow>
<pathsubstitution>
<substitute>
<from>smb://192.168.0.201/videos/</from>
<to>/mnt/videos/</to>
</substitute>
</pathsubstitution>
</advancedsettings>
Some notes about using this with a MySQL database
When you are sharing a database between clients it is required that you keep the file paths in your sources common to all your clients. Ideally you should copy your sources.xml and passwords.xml files to all clients so they are exactly the same. For the sake of simplicity and ease of installation I would recommend using a Kodi file path such as smb://ip_address/share/ as this works on all platforms Kodi can run on. Unfortunately this may not be optimal for all of your devices. Fortunately you can use different path substitutions on different devices and not cause any issue with a shared database as it only changes how the individual machines access the network share and does not impact how it is stored in the database. You can safely path sub to a system mount on a Vero for example and not impact a Windows install using a Kodi file path.