Kodi Media Library Setup: Organising a Video Collection
How Kodi's scraper and library database actually work, and the naming conventions that decide whether your own media files get identified correctly.
Kodi is an open-source media player, maintained by the non-profit XBMC Foundation, designed to turn a collection of video and music files into a browsable library with artwork, metadata, and playback resume. It ships with no content of any kind. What it does is index files you already have (ripped discs, home video, recordings you made, media you bought and downloaded) and present them well.
The part people struggle with is the library system. Kodi does not simply list your folders; it builds a database, and that database is populated by matching your filenames against online metadata sources. If the matching fails, you get a library full of unidentified entries, and the cause is nearly always the naming convention rather than Kodi itself.
How the Library Works
Three things happen when you add a source:
1. Scanning. Kodi walks the directory and finds video files.
2. Scraping. For each file, it parses the filename to guess a title and year, queries a metadata provider, and retrieves details and artwork.
3. Storage. Results go into a local SQLite database. Subsequent browsing reads the database, not the filesystem.
That third step explains a common confusion: adding a file to a folder does not make it appear in the library until a scan runs. Kodi is browsing its database, not your disk.
The scraper is assigned per-source, and the source's content type determines which scraper runs. Setting a folder of films to "TV shows" produces uniformly wrong results, and it is a surprisingly easy mistake when adding several sources at once.
Naming Conventions
This is where the real work is, and getting it right eliminates most library problems before they occur.
One folder per film, named with the title and year, containing a video file named the same way:
The year is the important part. It disambiguates remakes and films sharing a title, and without it the scraper is guessing. Parenthesised four-digit years are the convention Kodi's parser expects.
For films split across multiple files, append -part1, -part2 and Kodi will treat them as one item with continuous playback.
Extras go in an extras/ subfolder or carry a recognised suffix such as -trailer, which keeps them out of the main library listing.
One folder per series, with season subfolders, and episode files carrying explicit season and episode numbers:
The S01E01 pattern is the one to use. Kodi recognises several alternatives (1x01, s01.e01) but the standard form is the most reliably parsed, particularly by third-party tools you might add later.
Specials go in Season 00 or a Specials folder, numbered as S00E01 onward.
Two cases cause most misidentification:
Series with the same name. Several shows share a title across different years and countries. Adding the year to the folder (Detectorists (2014)) resolves it.
Anthology and split-season shows. Where the metadata provider's season numbering differs from the release's, no naming convention fixes it. Set the correct ID manually per series.
When automatic matching fails, you can force the correct result rather than fight the filename. Kodi supports NFO files, small XML sidecars alongside the media file. The minimal useful form contains just a URL or an ID pointing at the correct metadata entry:
Kodi reads the NFO in preference to guessing. Full NFO files can contain complete metadata, which is the approach to take if you want your library to survive without depending on an online provider at all.
Sharing a Library Across Devices
Running Kodi on several devices with independent databases means watched status and resume points diverge immediately, you stop an episode in the living room and the bedroom device has no idea.
Kodi supports a shared MySQL or MariaDB backend for exactly this. Point every installation at one database server and they share library contents, watched state, and resume positions.
The setup requires a advancedsettings.xml on each client naming the database host and credentials, and a database server that is always on, typically the same machine holding the media. The paths to media must also be identical across clients, which in practice means network paths rather than local ones.
It is more setup than most single-device users need. For a household with three or more Kodi installations it is clearly worth it.
The Add-on Question
Kodi's reputation is complicated by third-party add-ons, and it is worth being precise about the distinction.
Kodi is extensible, and the XBMC Foundation maintains an official add-on repository containing skins, subtitle providers, metadata scrapers, and clients for legitimate services. That is the ecosystem the project supports.
Because the platform is open, unaffiliated developers have also distributed add-ons through third-party repositories over the years, some of which existed to access content their users had no rights to. The XBMC Foundation has been consistently and publicly opposed to these, has pursued trademark action against vendors selling preloaded devices, and does not permit them in the official repository.
The practical guidance is straightforward: install from the official repository. Third-party repositories carry no code review, and beyond the legal question, unreviewed add-ons running with full application permissions on a device on your home network is a security proposition worth declining on its own merits.
Alternatives Worth Knowing
Kodi is a player that manages a library on the device it runs on. If your goal is one library served to many devices, a media server is a better architectural fit, Jellyfin, Plex, or Emby index the collection centrally and stream to clients, including transcoding for devices that cannot decode the source format.
The two approaches can coexist. Running Jellyfin as the server and Kodi as a client on a capable device gives you the central library with Kodi's playback and interface, which for a large collection is often the best of both.