[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.

4 Likes
Freezing on high bandwidth 4k content
Some subfolders on a mounted share inaccessible
OSMC's June update is here with Kodi v18.7 - OSMC
File sharing with a NAS, media server, windows share or other device
Cannot access NAS after IP address change
Moving Thumbnails to SD card
Vero4k+ stop playing movies after a few seconds
Buffering issues playing UHD Movies
Buffering issues
Buffering issues
Vero 4k Freezing when cleaning video library
[TESTING] Linux 4.9 kernel and improved video stack for Vero 4K / 4K +
Kodi hangs on playback start
Navigation is very slow, and 4K playback frequently buffering
NFS and SMB, Neither work well!
NFS and SMB, Neither work well!
Can't get through a movie
Strange situation with "ghost" Movies
Vero4k not handling symlinks?
4K Video becomes jerky before freezing
New Router (Fritzbox) - NFS Problem
Vero 4K+ Insufficient space for Update to proceed. Free some storage and try again later
How Do I upgrade my media drive
Vero 4K+: 4K films not playing / Potential SMB issue
Suddenly videos takes a minute to start
Windows and Linux......playing together
Change Hard Drive Name
Library scan does not find any content on USB mounted drive
Change NFS source (IP address)
Corrupt Video after 30 seconds
New bug in NFS? Almost nothing playing from my NFS share, started like four days ago
Is it possible to revert to an older kernel?
NAS drive for Vero 4k not accessible
Change NFS source (IP address)
Choppy and noisy audio playback after full reinstall and new raspberry pi NAS nfs share
Removing old source and creating new one
New network woes
PI4 buffering
Issue playing videos from a Macbook shared folders to my Vero 4K+
Vero 4k+ bandwidth limited after kodi v19 upgrade
No MySQL data being written or read?
Pi4 with 19.1 stutters after playing for about 15-30 minutes
Artwork not showing, only black screen where art should be, but NAME-poster.jpg and/or poster.jpg in folder
Kodi 19 trouble
SMB not working again?
To MySQL or not to MySQL?
Reset media library
Vero 4K+ v19 - Many Problems
Duplicating media sources
Issue with Vero4k and raw 4K MTS files?

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.