# Media Player Scrobbler

**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.

{% embed url="<https://simkl.com/apps/windows/>" %}

{% embed url="<https://github.com/ByteTrix/Media-Player-Scrobbler-for-Simkl>" %}

<figure><img src="https://1063116720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkYIJb2JfKN8kBT29bf%2Fuploads%2Fb6SwluTLQomQ6X4v9253%2Fimage.png?alt=media&#x26;token=9415d4fd-bc58-47ad-ab86-24463e67d98f" alt=""><figcaption></figcaption></figure>

{% content-ref url="windows-tv-tracker" %}
[windows-tv-tracker](https://docs.simkl.org/how-to-use-simkl/advanced-usage/platform-integration/linking-simkl-with-popular-media-centers/media-player-trackers/windows-tv-tracker)
{% endcontent-ref %}

## 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%).

<figure><img src="https://1063116720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkYIJb2JfKN8kBT29bf%2Fuploads%2F09bQWrMckRtqyKh9CZWb%2Fimage.png?alt=media&#x26;token=939e31e4-4b62-435c-9465-22826fbcd95e" alt=""><figcaption></figcaption></figure>

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

### Key Features

* [x] &#x20;**Supports all major players** — VLC, PotPlayer, MPV, MPC-HC/BE, KMPlayer, SMPlayer, and more.
* [x] **Cross-platform** — Works on Windows, macOS, and Linux.
* [x] **Smart filename parsing** — Automatically identifies movies, shows, and anime from filenames.
* [x] **Accurate playback tracking** — Marks as watched at 70% completion by default.
* [x] **Offline queueing** — Saves progress offline and syncs when back online.
* [x] **Native experience** — System tray, auto-start, and background updates (Windows).
* [x] **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

* [x] VLC
* [x] PotPlayer
* [x] MPV
* [x] MPC-HC / MPC-BE
* [x] SMPlayer
* [x] KMPlayer
* [x] GNOME Videos
* [x] Dragon Player
* [x] iTunes (limited support)
* [x] More added regularly…

{% hint style="success" %}
**Best results**: VLC and MPV are recommended for best accuracy.
{% endhint %}

***

### 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** Breakdow&#x6E;**:**

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.

<figure><img src="https://1063116720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkYIJb2JfKN8kBT29bf%2Fuploads%2FSSc5GN0NkxtlvPXIo61f%2Fimage.png?alt=media&#x26;token=725ea678-6cb9-4410-8fa5-d7a5073046d5" alt=""><figcaption></figcaption></figure>

***

## Installation Guide

{% tabs %}
{% tab title="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 |
| {% endtab %} |                                           |                         |

{% tab title="Tray Menu Overview" %}

| Option                      | Description                                         |
| --------------------------- | --------------------------------------------------- |
| ▶️ **Start/Pause Tracking** | Toggle live tracking                                |
| 📜 **Status Info**          | Shows current player detection and connection state |
| ⚙️ **Tools**                | Access logs, configuration, and debugging           |
| 🔄 **Check for Updates**    | Installs new versions automatically                 |
| ❌ **Exit**                  | Closes the background service                       |
| {% endtab %}                |                                                     |

{% tab title="Tray Status Icons" %}

| Icon           | Status                    |                                   |
| -------------- | ------------------------- | --------------------------------- |
| 🟢 **Running** | Active and tracking media | Tracking active                   |
| 🟡 **Paused**  | Temporarily suspended     | Tracking paused                   |
| 🔵 **Stopped** | Idle but ready            | App idle but running              |
| 🔴 **Error**   | Connection or API issue   | Error (API/auth/player detection) |
| {% endtab %}   |                           |                                   |
| {% endtabs %}  |                           |                                   |

### Windows Installation Guide

Download & Setup

1. Download the latest installer from GitHub:\
   [Media Player Scrobbler for Simkl (Windows)](https://github.com/ByteTrix/Media-Player-Scrobbler-for-Simkl)
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](https://github.com/ByteTrix/Media-Player-Scrobbler-for-Simkl/blob/main/docs/windows-guide.md#-windows-installation--configuration-guide)
* [Optimizing for Windows](https://github.com/ByteTrix/Media-Player-Scrobbler-for-Simkl/blob/main/docs/windows-guide.md#-optimizing-for-windows)

***

### Linux Installation Guide

#### Prerequisites

Ensure Python 3.9+ and `pipx` are installed:

```bash
sudo apt install python3 python3-pip pipx
```

#### Install the Scrobbler

```bash
pipx install simkl-mps
```

#### Run the Application

```bash
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:

```bash
simkl-mps tray --autostart
```

***

### macOS Installation Guide

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

#### Installation

```bash
pip install "simkl-mps[macos]"
```

or

```bash
pipx install "simkl-mps[macos]"
```

#### Run

```bash
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:

```bash
~/.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&#x20;

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:

```bash
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**.