[HowTo] Repairing File Paths with Path Substitution

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.

5 Likes

thank you so much, i will get on it and report back

FYI - I noticed that when using Yatsee on an android device, with the local playback (on the android device) extension, it will not be able to playback movies nor music on it - because Yatsee does not translate the paths somehow. Don’ t know what this is due to.

1 Like

That is an interesting find. I would guess that Kodi is probably just passing along the file path that is stored in the database and not checking to see if there is a path substitution that it should be applying. I would think that this is a Kodi bug and not an issue with Yatsee.

Whatever bug that is - it is time I “redo” my kodi configuration anyway. I have been migrating it for 10 years now (from xbmc or so) and it is a real mess :} yet it works.