Media Player Scrobbler

Cross-Platform Tracker for Windows, macOS, and Linux

Media Player Scrobbler is a community-developed, open-source tracker that connects your local media players to your Simkl account.

It detects what you’re watching in real time and updates your Simkl watch history automatically across all major operating systems.

Works on Windows, macOS, and Linux. Ideal for users who watch content on multiple platforms or want an open-source alternative to the Simkl TV Tracker.

Media player scrobble apps for SimklSimkl

GitHub - ByteTrix/Media-Player-Scrobbler-for-Simkl: A cross-platform application that automatically tracks media playback from your media player and synchronizes your progress with your SIMKL account.GitHub

Windows TV Tracker

What is Media Player Scrobbler?

Media Player Scrobbler (MPS) is a cross-platform application that automatically tracks what you watch on your media players and updates your Simkl profile in real time.

It works silently in the background, detecting playback from supported media players (VLC, MPV, PotPlayer, MPC-HC, MPC-BE, etc.), identifying the movie/episode based on filenames, tracking progress, and marking items as watched once you reach a set threshold (default: 70%).

MPS supports Movies, TV Shows, and Anime, provides offline support, and works on Windows, macOS, and Linux.

Key Features

• Supports all major players — VLC, PotPlayer, MPV, MPC-HC/BE, KMPlayer, SMPlayer, and more.

• Cross-platform — Works on Windows, macOS, and Linux.

• Smart filename parsing — Automatically identifies movies, shows, and anime from filenames.

• Accurate playback tracking — Marks as watched at 70% completion by default.

• Offline queueing — Saves progress offline and syncs when back online.

• Native experience — System tray, auto-start, and background updates (Windows).

• Full media coverage — Supports Movies + TV Shows + Anime.

Supported Platforms & Players

Operating Systems

OS	Status	Notes
🪟 Windows	✅ Stable	Native EXE installer, auto-start, tray app
🐧 Linux	✅ Stable	Install via pipx, tray app supported
🍏 macOS	⚠️ Experimental	pip installation, tray app (permissions required)

Supported Players

• VLC

• PotPlayer

• MPV

• MPC-HC / MPC-BE

• SMPlayer

• KMPlayer

• GNOME Videos

• Dragon Player

• iTunes (limited support)

• More added regularly…

Best results: VLC and MPV are recommended for best accuracy.

---

How Does It Work?

The Media Player Scrobbler runs quietly in the background and links your player activity to your Simkl profile.

Media Player → Player Title → Simkl Scrobbler → Parse Title → Identify Media → Track Progress → Simkl API → Mark as Watched → Simkl Profile

Step-by-step Breakdown:

1. Detect Playback MPS monitors supported players for active video playback.

2. Extract Metadata Uses the filename + player title to identify the media.

3. Identify Movie or Episode Matches filename data to Simkl’s database (e.g., Show.Name.S01E03.mkv).

4. Track Progress Tracks real-time playback progress using player controls.

5. Mark as Watched When you reach 70% completion (default), it sends the scrobble.

6. Sync to Simkl Updates appear instantly on your Simkl profile. Offline? No problem — MPS will sync everything once you're online.

---

Installation Guide

Quick Start

Platform	Install Method	Status
Windows	Use .exe installer → runs from tray	No commands needed
Linux	pipx install simkl-mps → tray app	Requires setup command
macOS	pip install simkl-mps[macos] → tray app	Experimental / untested

Tray Menu Overview

Tray Status Icons

Windows Installation Guide

Download & Setup

1. Download the latest installer from GitHub: Media Player Scrobbler for Simkl (Windows)

2. Right-click → Run as Administrator

3. Follow the setup wizard:

   • Accept the license

   • Choose install location

   • Enable Auto-start on login (recommended)

   • Enable Auto-update checking

After Installation

• The Scrobbler launches automatically.

• Log in with your Simkl account when prompted.

• A system tray icon appears — that means it’s active.

Related Links:

• Windows Installation & Configuration Guide

• Optimizing for Windows

---

Linux Installation Guide

Prerequisites

Ensure Python 3.9+ and pipx are installed:

sudo apt install python3 python3-pip pipx

Install the Scrobbler

pipx install simkl-mps

Run the Application

simkl-mps tray

• Authenticate with your Simkl account.

• The tray icon will appear — tracking is now live.

Optional Auto-start

Add this to Startup Applications:

simkl-mps tray --autostart

---

macOS Installation Guide

⚠️ macOS support is under testing; some features may behave differently.

Installation

pip install "simkl-mps[macos]"

or

pipx install "simkl-mps[macos]"

Run

simkl-mps tray

• Authenticate when prompted.

• Grant accessibility permissions if asked.

• Tray icon shows app status.

---

Media Player Configuration

After installation, configure your player for accurate detection.

VLC Player

1. Go to Tools → Preferences → Interface → Web.

2. Enable Web Interface.

3. Restart VLC.

MPV Player

Create or edit:

~/.config/mpv/scripts/simkl.lua

Paste the plugin script (from GitHub media-players guide).

MPC-HC / MPC-BE

1. Open Options

2. Go to Player → Web Interface

3. Enable

4. Set a password

5. Restart player

PotPlayer

No setup required — fully supported out of the box.

---

Local Watch History Viewer

Media Player Scrobbler includes a built-in Local History Viewer, allowing you to browse your watch history in your browser.

Analyze your locally tracked movies, TV shows, and anime directly in your browser.

Features

• Unified history for all media types

• Search, filter, and sort by type, title, or year

• Grid/List modes with dark/light toggle

• Episode and movie details with runtime breakdown

• Statistics via interactive charts

• Built with plain HTML, CSS, and JavaScript (no frameworks)

How to Access

1. Open the watch-history-viewer folder.

2. Open index.html in a browser.

3. The viewer loads from your local data.js history file.

4. Explore your watch history

---

Troubleshooting

Media Not Detected

• Use clean filenames: Movie.Title.2023.mkv Show.Name.S01E04.mp4

• Configure your player properly (see Media Player Configuration).

• Some players hide titles in fullscreen — disable fullscreen title hiding.

Tray Icon Missing

• Restart the app

• Check hidden system tray icons

• Ensure desktop environment supports tray apps (Linux/Mac)

VLC Not Connecting

• Enable VLC Web Interface

• Ensure the password matches the configuration file

Common Issues

Issue	Solution
Authentication failed	Run simkl-mps init --force
No movie detected	Ensure proper filename: Movie.Title.(Year).ext
App won’t start	Run as admin (Windows) or check simkl_mps.log
Offline sync delay	Wait until reconnect; queued scrobbles will upload

Log Locations

Platform	Path
Windows	%USERPROFILE%\simkl-mps\simkl_mps.log
macOS	~/kavin/simkl-mps/simkl_mps.log
Linux	~/.kavin/simkl-mps/simkl_mps.log

Run debug mode:

simkl-mps tray --debug

---

Conclusion

Media Player Scrobbler is the most flexible and powerful tracking solution for Simkl users who want:

• automatic scrobbling

• full media support (movies, TV, anime)

• cross-platform compatibility

• offline syncing

• open-source transparency

Whether you're on Windows, macOS, or Linux, MPS ensures your watch history stays accurate, instant, and fully synced, no manual effort required.

If used with properly configured media players, Media Player Scrobbler provides the most reliable and seamless playback tracking experience available for Simkl.