This guide was originally written for the Kodi 18 "Leia" release on Android, most also applies to other platforms.\\ <color red>**Updated 28<sup>th</sup> July 2021 for Kodi 19.1 (Matrix)\\ Updated 9<sup>th</sup> May 2023 for Kodi v20.1 (Nexus)\\ Updated 26<sup>th</sup> March 2024 for Kodi v21 (Omage)**</color>
====== Kodi v21 (Omega) ======
  * [[kodi:estuary21|Estuary Skin (mod)]]

====== Kodi 20 (Nexus) ======

===== Setup =====
===== Kodi Setup =====
==== General Setup ====
  - Install [[https://play.google.com/store/apps/details?id=org.xbmc.kodi&hl=en&gl=US|Kodi]]
  - Install addons:
    - //Program Addons -> Keymap Editor//
    - //Music -> Radio// addon
    - //Weather -> Gismeteo Weather// addon
    - Missing Movies
  - Install custom version of Estuary skin as explained in the next section.
  - Set Screensaver to //Dim//.
  - 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.
  - Add file paths through main menu //Videos//, then //Files/Add videos.../Browse/Add network location...//, and add the samba path to the folder.
  - Add file path for (example) **Concerts**, then create movie set //concerts//, then add all movies to the movie set.
  - Select the movie set, then select //Add to favorites// through the context menu.
  - Repeat for other movie types you want to group into it's own menu item, for example **Billiard** and **Foreign movies**.
  - Add file path for **Music**, go to //Settings// first and enable additional scrapers for Artist and Album information.
  - Add photos file path and make the path a favorite.
  - Optional: Zattoo Box addon

  - Setup
    - General setup
    - Customizing UI
    - Network sources
    - Addons
  - Storage setup
  - Backup and cloning
  - Subtitles
  - Scraping
    - Artwork
    - 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 ====
  - Similar to [[#setup_on_external_storage_android|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)
  - To move the ''Thumbnails'' folder to a network drive put the following lines into file ''advancedsettings.xml'' within the Kodi userdata folder:<code>
<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>
</code>
  - 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.
  - 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.
  - 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 ===
  - Starting with Android version 10 it is not possible to access another app's user data due to the tightened security policy
  - 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)
  - Alternatively you can copy or move ''dvancedsettings.xml'' to Android's ''Main Storage'' root folder, which can be written to by any app
  - Modify ''advancedsettings.xml'' as described in the steps above
  - Copy or move ''advancedsettings.xml'' back to Kodi's userdata folder with Kodi's built in file manager
  - Do this before setting up the Kodi media library, e.g. before scraping videos and music
  - 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

=== Links ===
  * [[https://kodi.wiki/view/Archive:Reduce_disk_space_usage|Archive:Reduce disk space usage]]
  * [[https://kodi.wiki/view/Userdata|Kodi:Userdata]]
  * [[https://kodi.wiki/view/Path_substitution|Path substitution]]
  * [[https://forum.kodi.tv/showthread.php?tid=201788|Path substitution on android xbmc]]
  * [[https://kodi.wiki/view/HOW-TO:Change_data_location_for_Android|Change data location for Android]]

==== Setup on external storage (Android) ====
  - Similar to [[#setup_on_devices_with_limited_storage_capacity|Setup on devices with limited storage capacity]], but move the entire user data to an external device (USB drive, SD card, or network drive)
  - Choose an external device with a decent transfer speed
  - 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.
  - 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.
  - 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|Skin]] for details.
  - 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.
  - 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:<code>xbmc.data=/storage/<volume_id>/Kodi</code>
  - 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.
  - Since the Kodi configuration files now are on an external device you can replace or update files simply by modifying files in a PC.
  - 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 ===
  * [[https://kodi.wiki/view/HOW-TO:Change_data_location_for_Android|Change data location for Android]]
  * [[https://www.aftvnews.com/how-to-partially-or-entirely-move-kodi-data-to-external-usb-storage/#:~:text=You%20cannot%20move%20an%20apps,it%20stores%20its%20data%20files.|How to move all Kodi data to External Storage]]
===== 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:
  - simple but effective full Kodi backup
  - clone the Kodi setup from one client to multiple clients in the same network
  - 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)
  - clone the Kodi setup to a different network in a different location

==== Backup ====
  - Exit Kodi
  - 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.
  - If you have Android 10 or newer you need to use the File Manager in Kodi.
  - If you moved your "Thumbnails" folder to another storage space as explained in [[#setup_on_devices_with_limited_storage_capacity|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.
  - To restore, follow the steps lined out in the following section.
==== Clone Kodi setup in the same network ====
  - Make sure Kodi is installed and was run at least one time (this will create links to Kodi's user data)
  - 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|Backup]])
  - If you moved your "Thumbnails" folder to another storage space as explained in [[#setup_on_devices_with_limited_storage_capacity|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:<code>
<advancedsettings>
    <hosts>
        <entry name="hostname">192.168.1.12</entry>
    </hosts>
</advancedsettings>
</code>
  * 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|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.
  - Unzip the {{ :media:kodi-batch.zip |Batch files}} to a folder of your choice, for example ~/batch/
  - Change directory to folder //userdata/Database// of your Kodi installation, which you have backed up before
  - Check the databases with:<code>~/batch/checkdb <database> <pattern></code>"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//.
  - This will return the number of patterns (search pattern is the hostname) found in the tables of the database, output similar to:<code>$ ~/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</code>
  - Check the tables with:<code>~/batch/checktable <database> <table> <pattern></code>//table// is the name of the table as returned in the previous command. Do this for all tables of each database.
  - This will return the number of patterns found in the fields of the tables of the database, output similar to:<code>$ ~/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</code>
  - To be sure you can also verify the pattern with:<code>~/batch/checkpattern <database> <table> <pattern></code>
  - 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).
  - Check the xml files with:<code>~/batch/checkxml <file> <pattern></code>Do this for all xml files in folder //userdata//.
  - 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.
  - Make sure you are in folder //userdata//, then patch with:<code>~/batch/updateall <search_pattern> <replace_pattern></code>"replace_pattern" is the new host name of your media server, or the new ip address to be used by Kodi.

=== Links ===
  * [[https://stackoverflow.com/questions/10586153/split-string-into-an-array-in-bash|Split string into an array in Bash]]
  * [[https://sqlite.org/lang_update.html|SQLite - UPDATE]]
  * [[https://kodi.wiki/view/Databases|Databases]]
  * [[https://sqlite.org/index.html|SQLite]]
  * [[https://www.tutorialspoint.com/sqlite/index.htm|SQLite Tutorial]]


===== 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:<code>cd \movieset\folder
for /r %a in (poster.jpg) do C:\PortableCustom\ImageMagick\convert.exe -resize 500x750! -depth 8 -quality 80% "%a" "%a"</code>

===== 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|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 =====
  - Download [[https://freefontsdownload.net/free-arial-unicode-ms-font-36926.htm|Arial Unicode MS]]
  - Create folder "Fonts" in /Main Storage/Android/data/org.xbmc.kodi/files/.kodi/media/
  - Copy ArialUni.ttf to /Main Storage/Android/data/org.xbmc.kodi/files/.kodi/media/Fonts/
  - Enable ArialUni in Kodi, Player -> Language -> Font to use for text subtitles

==== Thai Subtitles ====
  - Find [[http://www.thaisubtitle.com|Thai subtitles]]
  - Find movie, then select the Thai flag to the right, and download
  - Check timing of subtitles against movie and adjust if necessary
  - Add the subtitle file to the mkv movie file or as a separate file in the movie folder
  - Consider the following for the different formats:
    - srt: no change necessary
    - ssa: change encoding to Thai
    - ass: change font name in the style definition to Arial Unicode MS
====== Kodi Setup ======

===== Skin =====
  * [[kodi:estuary19|Customized Estuary 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 ====
  * see [[https://kodi.wiki/view/NFO_files|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.
  - Login to your box (for Android use //SSHelper//) and copy the entire skin directory with TotalCommander or the following command:<code>; 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</code>
  - 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
  - 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:<code>; 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</code>
  - Fix directory and file permissions
  - Reboot Kodi, first enable the new skin in Addons, then set the new skin in Interface
  - 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.
  - Note the ActivateWindow command including the parameters in between the (brackets) in favorites.xml, this will be the command to open your custom menu.<code>; Android: /storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/userdata/favorites.xml
; LibreELEC: ~/.kodi/userdata/favorites.xml</code>
  - Modify all custom menu entries and menu icons in Home.xml:<code>; 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</code>
  - For that, choose a menu item you do not use, for example "Games", find the string "ActivateWindow(Games)" in Home.xml
  - Rename the entry within <label>, and replace the png file within <thumb>, for example with movies.png
  - Remove visibility check within <visible> except !Skin.HasSetting, with which you can enable/disable all custom menu items
  - 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):<code>; 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</code>
  - 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..."
  - 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
  - Reorder your menu items to your liking and reboot Kodi
  - Optionally, change the splash screen by replacing splash.jpg in the kodi install folder, or by placing splash.png into the user folder:<code>; Android:
/data/data/org.xbmc.kodi/cache/apk/assets/media
/storage/emulated/0/Android/data/org.xbmc.kodi/files/.kodi/media</code>

Refer to the example file {{ :kodi:home.zip |}} which contains custom menu items replacing the games entry. Note id 52 below, which is the id of the favorite selected.<code><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></code>
In my setup, it is Concerts(1), Billiard(2), Thai movies (8), 3D(53).

==== Links ====
  * [[https://forum.kodi.tv/showthread.php?tid=319520|Want to add a custom menu item...]]
  * [[https://kodi.wiki/view/Estuary_Modification#Renaming_and_Reordering_Main_Menu_Items|Renaming and Reordering Main Menu Items]]
  * [[https://forum.libreelec.tv/thread/11249-how-to-change-files-on-read-only-file-system/|LibreELEC: How to change files on Read-only file system]]
  * [[https://discourse.coreelec.org/t/missing-kodi-splash-screen/3641|Missing Kodi Splash screen]]
  * [[https://kodi.wiki/view/Movie_sets_artwork|Movie sets artwork]]

===== 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.<code>$ 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-/}"' \;</code>

In addition, you need to create file //advancedsettings.xml// in the userdata folder with the following content<code><advancedsettings>
	<videolibrary>
		<moviesetextraart>
			<arttype>poster</arttype>
			<arttype>fanart</arttype>
		</moviesetextraart>
	</videolibrary>
</advancedsettings></code>

==== Links ====
  * [[https://kodi.wiki/view/Movie_sets_artwork|Movie sets artwork]]
  * [[https://kodi.wiki/view/HOW-TO:Use_your_computer_to_edit_XBMC%27s_(SQL)_database-files|Update SQL databases when files move]]