trakt-scrobbler: marking what you watch on VLC, Plex and MPV

A background service that watches your players

trakt-scrobbler is an application that runs in the background and monitors your media players for any new activity. When it detects a file being played, it determines the media info, such as the name of the movie or show and the episode number, and sends this to the trakt.tv servers, so that it can be marked as Currently Watching on your profile. No manual intervention is required.

Trakt itself is a website that keeps a history of everything you have watched, and this project is the bridge between the local playback and that history. The description calls it a trakt.tv scrobbler for your computer, and the supported players are VLC, Plex, MPC-HC and MPV.

The primary language is Python, the licence is GPL-2.0, and the project ships as a package with a command line entry point. The release history shows v1.7.2 in May 2025, v1.8.0 in January 2026 and v1.9.0b1 in February 2026, with the last push on 2026-05-28.

The audience is a desktop user with a local media library and a trakt.tv account, and the value is the same as for any scrobbler: the history is written by watching what you actually play, rather than by remembering to type it.

Two integration styles, and the player does not matter

The feature list makes one point explicitly: scrobbling is independent of the player or players where the media is played, and support for new players can thus be added easily. That is the architectural decision, and everything else follows from it.

The integrations fall into two groups in practice. VLC, and MPC-BE and MPC-HC, are monitored through their web interface. MPV is monitored through its IPC server. Plex is supported and, the readme notes, does not require Plex Pass, which removes a common stumbling block for users of the free tier.

So the component that watches for activity is per player, and the component that decides what the activity means and reports it to trakt.tv is shared. That is the same reason the acknowledgements section credits two separate projects: TraktForVLC as the inspiration, and mpv-trakt-sync-daemon, which was a huge help in making the mpv monitor. The mpv monitor did not exist for free, it was borrowed and adapted, and the readme is candid about it.

For a user, the practical consequence is that a library split across two players still produces one coherent history, because the identification and reporting happen above the player layer. For a developer, the consequence is that a new player is a new monitor rather than a new pipeline.

Guessit, folder whitelisting and the manual override

Three features decide how accurate the history is, and each one addresses a different failure.

The first is automatic media info extraction using guessit. Guessit is a library that guesses metadata from a filename, so the scrobbler can turn something like a file path into a show name, an episode number and a year without asking. The readme is careful about the limits: for cases when it misidentifies the files, you can specify a regex to manually extract the necessary details. So the tool has an escape hatch for exactly the case where the automatic path fails, and the escape hatch is a regular expression rather than a lookup table.

The second is folder whitelisting. Only media files from subdirectories of the listed folders are synced with trakt. That is a privacy and a noise control in one line: the service does not report everything the player opens, only what lives under the directories you named.

The third is the notification. Optionally you can receive a quick notification that the media start, pause and stop activity has been scrobbled, which is useful when you want to confirm that a report happened, and it is implemented with the desktop-notifier package, so it uses the notification mechanism of the platform rather than drawing its own window.

Proxy support is also listed, where you can optionally specify a proxy server to handle all communication with the trakt servers, and there is an optional socks extra for the cases where the proxy is a SOCKS one.

The trakts command and the shape of the configuration

The service is controlled by a command line interface, and the readme points at a CLI reference wiki page. The entry point is short enough to be worth quoting.

[project.scripts]
trakts = "trakt_scrobbler.cli.main:app"

The entry point is a typer application, and typer is also what makes the interface available as a subcommand, so trakts is the command you run to start, stop and query the service.

The configuration handling uses confuse, a library for layered configuration, with a config_default.yaml file that the source distribution includes, and the packaging configuration ships the trakt_scrobbler package and the completions directory, which holds shell completions for the command line tool. The URL matching that decides whether a path belongs to a whitelisted folder uses urlmatch, and the data models use pydantic.

The manifest also records the platform reality of the project. pywin32 is a dependency only on Windows, and the package classifiers describe the intended audience as End Users on the Desktop, with the operating system marked as independent. The Python range is 3.9 up to but not including 3.15, with tomli pulled in only below 3.11.

One optional dependency group is defined, socks, which pulls in pysocks, matching the proxy support described in the features.

Where the Trakt Scrobbler is the wrong tool

Four limits, and the first is the account dependency.

Everything this tool does ends in a call to trakt.tv, and a user without a trakt.tv account gets nothing from it. It is not a local watch history, not a media server integration, and not a way to get your library into a different tracker.

The second is that the detection depends on the local playback. The service watches players on the machine it runs on, so a library that is mostly streamed, or watched on a device where the scrobbler is not installed, produces gaps in the history. The readme also does not describe any backfill, so a gap stays a gap.

The third is identification, and it is the practical risk. The whole chain depends on guessit resolving a filename into a show and an episode, and the readme is explicit that it sometimes misidentifies files. When it does, the history gets a wrong entry, and the fix is the regex override, which means writing a rule per badly named file. The folder whitelisting is the practical mitigation for a user who has a mixed library, because it bounds how much can be misidentified at once.

The fourth is the state of the project itself. The most recent tag, v1.9.0b1, is a beta, and the version in the manifest is that same beta, so the current line is pre-release. The readme is short and points at the wiki for setup, which means the configuration details, including the Trakt API credentials, live outside the repository and you have to read the wiki to run it. The licence is GPL-2.0-only, which is fine for a personal tool and worth noting if you intend to bundle it.

Licence, releases and the state of the repository

The licence is GPL-2.0-only, declared in the packaging metadata, so the code can be used, modified and redistributed with the notice kept. That is a strong copyleft, and this is not legal advice, but for a tool that people run on their own desktop to talk to their own trakt.tv account, it is the conventional choice.

The release history is short and recent. Version 1.7.2 was published on 2025-05-25 as a minor update, 1.8.0 on 2026-01-09 and 1.9.0b1 on 2026-02-02, and the last push to the default branch was on 2026-05-28. The repository is not archived, and its releases, most recently v1.9.0b1 in February 2026, are the record of what changed.

The repository layout is small: the trakt_scrobbler package, a completions directory for the shell completions, a tests directory, a pyproject.toml, a uv.lock and a CONTRIBUTING.md. The contribution guidance is brief, asking for an issue for bugs and feature requests and for proper pull requests, and it points at the contributing file for the detail.

For a reader, the fastest way to understand the project is to look at the two integrations it inherited rather than reinvented, TraktForVLC and mpv-trakt-sync-daemon, and to read the CLI reference in the wiki, since the readme deliberately keeps the operational detail out of the repository. One thing the packaging does tell you is that the project is a desktop application with a shell command rather than a library, and that it is built with hatchling, type checked with pyright in basic mode and formatted with black at a line length of 88.

Editorial conclusion

trakt-scrobbler is the right tool for a trakt.tv user who watches on a desktop player and wants their history maintained without touching anything, and for anyone who moves between players and wants the same result in each. It is the wrong tool if you do not use trakt.tv, if you need your history synced from a service rather than a local file, or if the file names in your library are too inconsistent for guessit to resolve. Before adopting, run the trakts command against a folder of your own media and check the extracted titles, because that identification step is the one that decides whether the whole thing works, and use the folder whitelisting to keep it away from anything you do not want logged.

Frequently asked questions

Official sources

1. iamkroot/trakt-scrobbler on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases