MPS for SIMKL (Media Player Scrobbler) is a cross-platform app that automatically tracks your movie watching in popular media players and syncs your progress to your SIMKL account. It runs in the background or system tray, requires minimal setup, and supports Windows, macOS (experimental), and Linux.

• Windows: Use the Windows Guide (EXE installer, tray app, no commands needed).
• Linux: Use the Linux Guide (pipx recommended, tray app, setup command needed).
• macOS: Use the Mac Guide (pip install, tray app, setup command needed, experimental/untested).

After installation, authenticate with SIMKL and configure your media players using the Media Players Guide (this step is critical for accurate tracking).

• Windows Guide
• Linux Guide
• Mac Guide
• Supported Media Players
• Usage Guide
• Local Watch History
• Advanced & Developer Guide
• Troubleshooting Guide
• Todo List

graph TD
    A[Media Player] -->|Playback Info| B[MPS for SIMKL]
    B -->|Extract & Parse| C[Identify Media Title]
    C -->|Search| D[SIMKL API]
    D -->|Metadata| E[Track Progress]
    E -->|>80% Complete| F[Mark as Watched]
    F -->|Update| G[SIMKL Profile]
    style A fill:#d5f5e3,stroke:#333,stroke-width:2px
    style G fill:#d5f5e3,stroke:#333,stroke-width:2px

1. Detection: Monitors media players via window titles or player APIs.
2. Identification: Extracts and matches media titles against SIMKL.
3. Tracking: Monitors playback position (requires player configuration via Media Players Guide).
4. Completion: Marks as watched when the configured threshold (default 80%) is reached.
5. Sync: Updates your SIMKL profile automatically.

Online:

• Player Detection: ~4.2 sec
• Movie Info Scrobble: ~3.7 sec
• Notification: ~1.5 sec
• Completion Detection Delay: ~5.2 sec
• Completion Sync: ~13.3 sec
• Completion Notification: ~1.5 sec

Offline:

• Movie Scrobble: ~1.2 sec
• Notification: ~0.5 sec
• Completion Save: ~3 sec
• Completion Notification: ~0.5 sec

MPS for SIMKL is licensed under the GNU GPL v3 License. See the LICENSE file for details.