Kometa: the manifest says 2.4.7, the newest release says 2.5.1

Metadata lives outside the server, and that is the whole design

The argument the README makes is short and it is the reason to use this tool. Because your metadata is managed outside your libraries, you never have to worry about losing your customisations if the media server's database is lost; you simply reapply them. And it is easy to move your customisations between servers if you need to. Everything else in the project follows from that: metadata is expressed in files you keep, the script reconciles the server against those files, and the server's own database is treated as derived state. That also explains the collection examples in the README, which are the kind you would otherwise build by hand, grouped by networks, studios, genres, actors, decades, streaming service and what's trending, each driven by a query against one of the external metadata services.

The manifest is behind the newest release, and two beta branches exist

The version numbers do not agree. The project manifest declares 2.4.7 while the release record's newest tag is 2.5.1, preceded by 2.5.0 and 2.4.8, so the manifest is four increments behind what has actually shipped. That gap matters because the manifest is what a package installer reads. The release cadence underneath it is brisk: three releases in about six weeks. Alongside the stable branch there are two more, named develop and nightly, which the README describes as beta versions updated more frequently than the stable one, and both appear as badges at the top of the file next to the release page and the container registry. So there are three moving targets to choose between, and the one whose number the tooling reads is the oldest of them.

Twenty-six dependencies and exactly one range

The dependency list is the most disciplined part of the project and the most unusual. Twenty-six entries, and twenty-five of them are pinned to an exact version, down to the post-release suffix on a date utility and a conditional entry for Windows that is skipped on other platforms. The single ranged dependency is a notification library, which is a strange one to leave loose. Two others deserve a second look. One is a scraper-avoidance library, which tells you what the metadata fetching has to cope with, and one is a profiler, which is a development tool installed as a runtime dependency. The entry that will surprise you most is a library installed directly from a source repository at a fixed commit hash, under another organisation's account, rather than from a package index.

The requirements file is generated, and it is fully transitive

There is a second dependency file at the root, and its first lines say what it is: it was written by an export command from the environment manager, with the flags spelled out, and the options include omitting hashes, omitting development packages and omitting the project itself. What follows is a flat list with exact pins and a comment under each entry saying which package pulled it in, including a chain that runs from a letterboxd client through a fast-fingertips package to a markdown parser. That file is the one to ship, because it is the resolved closure rather than the intent. Two details are worth knowing: the export omits development packages, so a contributor installing from it gets the runtime and nothing else, and the omission of hashes means the file is reproducible by version but not by content.

The type checker runs on a ratchet instead of at zero errors

The manifest carries a block of configuration with a paragraph of explanation, and the paragraph is the interesting part. It says the static checker replaces an earlier one, that the strategy is a ratcheting baseline, that the project does not require zero errors, and that it requires instead that the error count does not go up on a change. Then it names the three pieces of machinery that enforce it: a file holding the currently accepted error count, a script containing the gate logic, and a workflow that runs the gate. That is a defensible way to introduce a checker into a large codebase without stopping every change, and it is the part of this repository a maintainer of any similar project should copy. The rest of the tooling is conventional, with one exception: the formatter and import sorter are configured to a line length of 256 characters.

The container builds from the project's own published image

The recipe is ten lines and the first instruction after the syntax directive takes a build argument for a tag, then builds from the project's own image on the container registry with that tag. So this is a bootstrap image: it layers the source of one branch on top of an already published image of the project, with the branch name passed in as a build argument and an environment variable set to tell the code it is running in a container. A comment above it records an open blocker in the project's own words, naming a workflow file, a change intended to unblock nightly image builds, and the change request number. The runtime bits are the ones you would expect: a volume for the configuration directory and an entry point that runs a small init shim before the main script.

Two documentation systems and a schema directory

The homepage is a wiki on its own domain, and the documentation links all point at that wiki rather than at a documentation site generated from the repository. Meanwhile the tree contains a documentation configuration, a documentation source directory and a set of documentation outputs, so there is a second documentation system that is built from files in the repository and published elsewhere. Add to that a translations site, a separate site listing features, and a separate repository for user-submitted configuration files, and you have four external destinations plus one built documentation set. The root also contains a JSON schema directory, which is the quiet detail that matters most: it means the configuration files are validated against a schema rather than discovered by trial and error.

A stray file named PART sits beside the fonts

The top level is a working directory for a project that ships data as well as code, and two entries explain that. There is a defaults directory holding the team's own pre-made collection and overlay definitions, which is why the README can promise modular files that take the work out of defining each collection by hand. And there is a fonts directory, which exists because overlays draw text onto artwork and need a font to draw it with. Neither is mentioned in the README's own instructions, which move straight from installing to creating a configuration file to creating a collection file, so both are things you discover by opening the container. Between them sits a file with a four letter name and no extension, which is not a build output and is not referenced anywhere in the documentation.

Editorial conclusion

This is the tool for a Plex library you have already curated by hand and do not want to re-curate, because it treats your metadata as input rather than as state, which means a rebuilt server database is a rerun rather than a recovery. Three things to check before you point it at a real library. The manifest version trails the newest release by four increments, so read the changelog rather than the manifest to know what you have. The dependency list is almost entirely exact pins including one installed straight from a source repository at a commit, so upgrading means regenerating it rather than relaxing a range. And the overlays need fonts, which is why there is a fonts directory at the root and a step most people forget.

Frequently asked questions

Official sources

1. Kometa-Team/Kometa on GitHub
2. License: MIT
3. Project website
4. README
5. Releases