This guide was originally written for the Kodi 18 “Leia” release on Android, most also applies to other platforms.
Updated 28th July 2021 for Kodi 19.1 (Matrix)
Updated 9th May 2023 for Kodi v20.1 (Nexus)
Updated 26th March 2024 for Kodi v21 (Omage)

Kodi v21 (Omega)

Kodi 20 (Nexus)

Setup

Kodi Setup

General Setup

  1. Install Kodi
  2. Install addons:
    1. Program Addons → Keymap Editor
    2. Music → Radio addon
    3. Weather → Gismeteo Weather addon
    4. Missing Movies
  3. Install custom version of Estuary skin as explained in the next section.
  4. Set Screensaver to Dim.
  5. Enable Show movie sets in Settings/Media/Videos. You might want to enable Include sets containing a single movie before setting up the library, and disable it afterwards.
  6. Add file paths through main menu Videos, then Files/Add videos…/Browse/Add network location…, and add the samba path to the folder.
  7. Add file path for (example) Concerts, then create movie set concerts, then add all movies to the movie set.
  8. Select the movie set, then select Add to favorites through the context menu.
  9. Repeat for other movie types you want to group into it's own menu item, for example Billiard and Foreign movies.
  10. Add file path for Music, go to Settings first and enable additional scrapers for Artist and Album information.
  11. Add photos file path and make the path a favorite.
  12. Optional: Zattoo Box addon
  1. Setup
    1. General setup
    2. Customizing UI
    3. Network sources
    4. Addons
  2. Storage setup
  3. Backup and cloning
  4. Subtitles
  5. Scraping
    1. Artwork
    2. Naming conventions

Setup

On a device with limited storage capacity, for example the Mi Box S which is an Android Box with only 8GB storage capacity (5.4GB available to apps), you will likely run into capacity problems when your Kodi library grows. You can either format a USB drive (or SD card if your device has a slot) as device storage and then move the entire Kodi app data, or just the Thumbnails folder, to that drive or to an external (network) drive. If you are on a wired LAN there is a good chance that the Box can access a network drive faster than an attached USB drive, and it does not need to deal with encryption which is a good thing for a weak CPU.

Starting with Android version 10 it is not possible to access another app's user data due to the tightened security policy. Also, access to the device using SSH (e.g. starting an SSH server on the device) requires root access. If you like to modify a skin, or update the Kodi databases, then you need to move Kodi's configuration files to a storage space which you can modify.

There are 2 method's to deal with both on a Android platform.

Setup on devices with limited storage capacity

  1. Similar to Setup on external storage (Android), but move only the Thumbnails folder within Kodi's data space to an external device (USB drive, SD card, or network drive)
  2. To move the Thumbnails folder to a network drive put the following lines into file advancedsettings.xml within the Kodi userdata folder:
    <advancedsettings>
        <pathsubstitution>
            <substitute>
                <from>special://profile/Thumbnails/</from> <!-- keep this exactly like this -->
                <to>smb://nas/media/kodi/machine/Thumbnails/</to> <!-- adjust to your file path on your NAS or server -->
            </substitute>
        </pathsubstitution>
    </advancedsettings>
  3. Then move the Thumbnails folder itself from the Box to the network location. This folder by far takes the biggest amount of Kodi's storage requirements, and in most cases is sufficient to give the device plenty of storage space back.
  4. Note that the the Texture Cache consists of two interlinked data stores - the Thumbnails folder and the SQLite database TexturesXX.db. Do not share the Thumbnails folder between different Kodi clients, as this will eventually take the clients where the SQLite database lives out of sync with the Thumbnails folder.
  5. Remember to restore database and folder at the same time from the same backup if you keep a backup of your Kodi installation and later restore it to either the same client or a different client. If you restore to a different client, create a separate folder in your external network drive.

Devices running Android / AndroidTV version 10 or newer

  1. Starting with Android version 10 it is not possible to access another app's user data due to the tightened security policy
  2. Copy or move advancedsettings.xml to external storage with Kodi's built in file manager, for example a USB drive (if the file exists in Kodi's userdata folder)
  3. Alternatively you can copy or move dvancedsettings.xml to Android's Main Storage root folder, which can be written to by any app
  4. Modify advancedsettings.xml as described in the steps above
  5. Copy or move advancedsettings.xml back to Kodi's userdata folder with Kodi's built in file manager
  6. Do this before setting up the Kodi media library, e.g. before scraping videos and music
  7. If you already have a Kodi media library in place you need to copy the entire Thumbnails folder to the location you entered in advancedsettings.xml with Kodi's built in file manager

Setup on external storage (Android)

  1. Similar to Setup on devices with limited storage capacity, but move the entire user data to an external device (USB drive, SD card, or network drive)
  2. Choose an external device with a decent transfer speed
  3. If you choose a SD card, format the card on the device as external (portable) storage, not as device storage. On Samsung and other devices with KNOX technology SD cards cannot be formatted as device storage anyway.
  4. Create folder Kodi in the root of an SD card, or anywhere an another external device. Do not use the app's default location on the SD card as this path is not accessible as the kodi samba user since Android 11.
  5. Use FX File Explorer (Android 9 or older) or Kodi's built in file manager (Android 10 or newer) to move your existing .kodi folder from /storage/emulated/0/Android/data/org.xbmc.kodi/files (you may find /storage/emulated/0/ also as Main Storage) to the newly created Kodi folder on the external device. If you have created or downloaded a customized skin it will also be copied, as it resides in .kodi/addons. Refer to Skin for details.
  6. If you have Android 10 or newer you need to use Kodi's built in file manager to access data within the Kodi data space. For Android 9 you can still use any Android File Manager.
  7. Create and copy a text file named xbmc_env.properties into the root directory of your internal (device) storage. This storage is writeable by FX File Explorer (Android). Create the file with the following line to tell Kodi where to find it's configuration folder:
    xbmc.data=/storage/<volume_id>/Kodi
  8. This is how the Android OS accesses the storage. The path might start with /storage/ as on my Samsung devices, but might be different on other devices. You can find the correct path by using a file explorer, like “File Browser” or “Root Explorer” to determine the proper path. The specified path must be a local Android file path and not a network path, as you would not be able to mount a network path without being root. <volume_id> is the volume ID (aka volume serial number) given to a USB drive or SD card, you can check it by inserting into your PC and then running “vol” on the drive from the command line.
  9. Since the Kodi configuration files now are on an external device you can replace or update files simply by modifying files in a PC.
  10. Kodi's UI will load a little slower, but it has no impact on movie load times and performance, as those are not stored on internal device storage anyway.

Links

Backup and clone

Setting up and maintaining a well tagged video and music library with Kodi can be a lot of effort, particularly if you want to have it perfectly done, and the library grows big. I highly recommend to take a full Kodi backup after having completed the setup. The backup can then be used to restore or clone a Kodi installation. More advanced techniques are also discussed in my guide:

  1. simple but effective full Kodi backup
  2. clone the Kodi setup from one client to multiple clients in the same network
  3. clone the Kodi setup from a client to another client on a different subnet (for example, if you maintain different subnets for LAN and WLAN)
  4. clone the Kodi setup to a different network in a different location

Backup

  1. Exit Kodi
  2. Use a FX File Explorer (or any File Manager) or LAN drive - SAMBA Server & Client to copy folder .kodi from “/storage/emulated/0/Android/data/org.xbmc.kodi/files” (you may find “/storage/emulated/0/” also as “Main Storage”) to backup storage. This applies for Android version up to Android 9.
  3. If you have Android 10 or newer you need to use the File Manager in Kodi.
  4. If you moved your “Thumbnails” folder to another storage space as explained in Setup on devices with limited storage capacity, then you also need to backup the Thumbnails folder. Do not start Kodi until you have backed up both, and store the Thumbnails folder together with the app storage backup.
  5. To restore, follow the steps lined out in the following section.

Clone Kodi setup in the same network

  1. Make sure Kodi is installed and was run at least one time (this will create links to Kodi's user data)
  2. Remove folder .kodi in “/storage/emulated/0/Android/data/org.xbmc.kodi/files”, then restore the backup of folder .kodi taken before to the same location (see Backup)
  3. If you moved your “Thumbnails” folder to another storage space as explained in Setup on devices with limited storage capacity, then you need to restore the Thumbnails folder to that chosen location, not to device storage. Do not start Kodi until you have restored both.

Clone Kodi setup for different subnets

If you use different subnets in your LAN/WAN setup, then you might need to modify Kodi databases and xml setting files prior to restore (clone) a Kodi installation, under certain conditions:

  • the cloned device lives on a different subnet than the Kodi master installation, for example a mobile device where the WLAN lives on a different subnet than the LAN
  • you have used host names rather than host ip addresses when setting up the Kodi master
  • If your NAS or server have a fixed IP address you can add a hosts entry to file “advancedsettings.xml” in folder userdata, which takes precedence over name resolution:
    <advancedsettings>
        <hosts>
            <entry name="hostname">192.168.1.12</entry>
        </hosts>
    </advancedsettings>
  • If you have Android 10 or newer you need to move the advancedsettings.xml with the File Manager in Kodi. For Android 9 you can still use any Android File Manager.

For a permanent change of the host name(s), refer to the following section Clone Kodi setup for different networks for a walk through. The steps required are identical, except that you must make sure all references to host names of the media servers (e.g. NetBIOS names) are replaced by ip addresses. This is necessary because the Samba client relies on broadcast and WINS which do not propagate host names across subnets.

Clone Kodi setup for different networks

Media server(s) on a different network almost certainly have different host names and are assigned different ip addresses within the network. To be able to clone a Kodi installation to a client on a different network all references to the media servers must be updated.

I have written a few batch files to automate the process, which are explained below. They work under “Bash” which is a linux command shell, and can be run on a Linux machine or under a Linux installation in “Windows Subsystem for Linux”. The following guide is for advanced users who know their way around Linux just enough to be able to run batch files under Linux.

  1. Unzip the Batch files to a folder of your choice, for example ~/batch/
  2. Change directory to folder userdata/Database of your Kodi installation, which you have backed up before
  3. Check the databases with:
    ~/batch/checkdb <database> <pattern>

    “pattern” is the name of the host or the ip address of your media server. Do this for all databases in folder .kodi/userdata/Database.

  4. This will return the number of patterns (search pattern is the hostname) found in the tables of the database, output similar to:
    $ ~/batch/checkdb MyMusic82.db hostname
    tables in db "MyMusic82.db", search "hostname" (pattern "/hostname/|@hostname/|%2fhostname%2f|%40hostname%2f")
    path: 1264 found
    source: 1 found
    source_path: 1 found
    art: 990 found
  5. Check the tables with:
    ~/batch/checktable <database> <table> <pattern>

    table is the name of the table as returned in the previous command. Do this for all tables of each database.

  6. This will return the number of patterns found in the fields of the tables of the database, output similar to:
    $ ~/batch/checktable MyMusic82.db path hostname
    fields in db "MyMusic82.db", table "path", search "hostname" (pattern "/hostname/|@hostname/|%2fhostname%2f|%40hostname%2f")
    strPath: 1264 found
  7. To be sure you can also verify the pattern with:
    ~/batch/checkpattern <database> <table> <pattern>
  8. This will return the number of patterns found in the fields of the tables of the database, and also return a line with the number of patterns found which were not identified through the regex expression containing the pattern. If the number of patterns found are different for the two lines you need to adjust the regex pattern in all batch files (variable PATTERN, and also variable REPLACE which is used in the update batch files).
  9. Check the xml files with:
    ~/batch/checkxml <file> <pattern>

    Do this for all xml files in folder userdata.

  10. All returned tables and field names need to have an update line in file “updateall”. If all matches you are ready to do the patch.
  11. Make sure you are in folder userdata, then patch with:
    ~/batch/updateall <search_pattern> <replace_pattern>

    “replace_pattern” is the new host name of your media server, or the new ip address to be used by Kodi.

Links

Scraping

  • Prepare an artwork folder for movie sets. You can also first scrape the movies in Kodi and then replace the movie set artwork where necessary by saving set artwork into the artwork folder, then selecting Manage… –> Choose art through the context menu in Kodi on the movie set to change.
  • Change resolution of all images in movieset:
    cd \movieset\folder
    for /r %a in (poster.jpg) do C:\PortableCustom\ImageMagick\convert.exe -resize 500x750! -depth 8 -quality 80% "%a" "%a"

Change Kodi User Name and/or Password

  • Exit Kodi and make sure the app is not running.
  • Add new user kodi to your NAS or server as member of the same group as the user you use to store media files (in a Synology NAS this would be group users).
  • Check that all files in your media folder on the NAS or server have group set to the same group (e.g. users).
  • Modify samba user credentials in files passwords.xml, mediasources.xml, favourites.xml, and guisettings.xml in kodi's userdata folder.
  • Update the databases the same way as explained in Clone Kodi setup for different networks, but instead of batch files checkdb, checktables, and updatetables, use pwd_checkdb, pwd_checktables, and pwd_updatetables. Instead of using <pattern>, <search_pattern> and <replace_pattern>, use <username:password>, <search_username:password> and <replace_username:password>.
  • Start Kodi, then go to Settings –> File manager and create a new source. This will trigger samba to update user and password in it's internal cache.
  • Verify that the thumbnails are loading and video and audio files can be played back. Afterwards you can remove the source created in Settings –> File manager.

Enable Thai subtitles for srt, ssa and ass subtitle files

  1. Create folder “Fonts” in /Main Storage/Android/data/org.xbmc.kodi/files/.kodi/media/
  2. Copy ArialUni.ttf to /Main Storage/Android/data/org.xbmc.kodi/files/.kodi/media/Fonts/
  3. Enable ArialUni in Kodi, Player → Language → Font to use for text subtitles

Thai Subtitles

  1. Find movie, then select the Thai flag to the right, and download
  2. Check timing of subtitles against movie and adjust if necessary
  3. Add the subtitle file to the mkv movie file or as a separate file in the movie folder
  4. Consider the following for the different formats:
    1. srt: no change necessary
    2. ssa: change encoding to Thai
    3. ass: change font name in the style definition to Arial Unicode MS

Kodi Setup

Skin

Add-ons

Music add-ons

  • Radio

Program add-ons

  • Keymap Editor
  • Log Viewer for Kodi

Video add-ons

  • Embuary Info
  • Missing Movies

Weather

  • Multi Weather

nfo Files

Kodi 18 with Estuary skin

Modify Menu Entries

The new default skin “Estuary” is very good, not too heavy, and well maintained. However, it lacks the ability to customize the home screen. However, it is possible to customize the home menu items manually. With SSH access to your Kodi box, you can create custom menu entries. You need to be root to copy from the apk directory. Alternatively, you can copy from a rooted device, or a PC install, and then copy from USB to your media player, if the media player is not rooted.

  1. Login to your box (for Android use SSHelper) and copy the entire skin directory with TotalCommander or the following command:
    ; Android:
    su
    cp -R /data/data/org.xbmc.kodi/cache/apk/assets/addons/skin.estuary /storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/addons
    ; LibreELEC:
    cp -R /usr/share/kodi/addons/skin.estuary ~/.kodi/addons
  2. Instead of /storage/emulated, you can also use path /data/media, which points to the same “0” directory, but the latter can be accessed only when root
  3. Rename the copied directory to skin.estuary.mod, then rename the skin id and name to “estuary.mod” in the 2nd line of addon.xml:
    ; Android: /storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/addons/skin.estuary.mod/addon.xml
    ; LibreELEC: ~/.kodi/addons/skin.estuary.mod/addon.xml
  4. Fix directory and file permissions
  5. Reboot Kodi, first enable the new skin in Addons, then set the new skin in Interface
  6. Make the desired views a favorite, for example you want to have a menu item for foreign language movies, so add all foreign language movies into the same movie set and make it a favorite.
  7. Note the ActivateWindow command including the parameters in between the (brackets) in favorites.xml, this will be the command to open your custom menu.
    ; Android: /storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/userdata/favorites.xml
    ; LibreELEC: ~/.kodi/userdata/favorites.xml
  8. Modify all custom menu entries and menu icons in Home.xml:
    ; Android: /storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/addons/skin.estuary.mod/xml/Home.xml
    ; LibreELEC: ~/.kodi/addons/skin.estuary.mod/xml/Home.xml
  9. For that, choose a menu item you do not use, for example “Games”, find the string “ActivateWindow(Games)” in Home.xml
  10. Rename the entry within <label>, and replace the png file within <thumb>, for example with movies.png
  11. Remove visibility check within <visible> except !Skin.HasSetting, with which you can enable/disable all custom menu items
  12. If you want to remove the text when moving to your new menu item, first open file strings.po and find the string id (for “Games”, this is id 31162 as per Kodi 9.0.1):
    ; Android: /storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/addons/skin.estuary.mod/language/resource.language.en_us
    ; LibreELEC: ~/.kodi/addons/skin.estuary.mod/language/resource.language.en_us
  13. Open Home.xml again and find id 31162, comment out from <include content=“ImageWidget”> to </include>, this will disable the text “Play your personal games…”
  14. To create more than one extra menu item, copy the new menu item and rename the <label> and <onclick> directives, but keep property name (menu_id and id) the same as for the original games menu item
  15. Reorder your menu items to your liking and reboot Kodi
  16. Optionally, change the splash screen by replacing splash.jpg in the kodi install folder, or by placing splash.png into the user folder:
    ; Android:
    /data/data/org.xbmc.kodi/cache/apk/assets/media
    /storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/media

Refer to the example file home.zip which contains custom menu items replacing the games entry. Note id 52 below, which is the id of the favorite selected.

<item>
  <label>$LOCALIZE[20389]</label>
  <property name="menu_id">$NUMBER[17000]</property>
  <onclick>ActivateWindow(10025,&quot;videodb://movies/sets/52/?setid=52&quot;,return)</onclick>
  <thumb>icons/sidemenu/musicvideos.png</thumb>
  <property name="id">games</property>
  <visible>!Skin.HasSetting(HomeMenuNoGamesButton)</visible>
</item>

In my setup, it is Concerts(1), Billiard(2), Thai movies (8), 3D(53).

Links

Movie sets and media files

Movie set artwork

Kodi 19 introduces a central movie set artwork folder. Prior to that, movie sets got their artwork from one of their movie members, but this does not work anymore in Kodi 19 beta2. I use tmm (tiny media manager) to create artwork, which also adds movieset artwork. This is how to extract the movieset-poster.jpg and movieset-fanart.jpg files from the movie folder and move them to a central artwork folder.

$ cd /your/movies/root/folder
$ find . -name 'movieset-poster.jpg' -exec cp --parents \{\} /path/to/moviesetart \;
$ find . -name 'movieset-fanart.jpg' -exec cp --parents \{\} /path/to/moviesetart \;
$ cd /path/to/moviesetart
find . -name '*.jpg' -exec bash -c 'filename="{}"; mv "$filename" "${filename//movieset-/}"' \;

In addition, you need to create file advancedsettings.xml in the userdata folder with the following content

<advancedsettings>
	<videolibrary>
		<moviesetextraart>
			<arttype>poster</arttype>
			<arttype>fanart</arttype>
		</moviesetextraart>
	</videolibrary>
</advancedsettings>

Links