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

• Movie identification: 15–30 seconds (typical)
• Mark as watched (online): 2–8 seconds (best connection)
• Offline scrobble: 4–10 seconds to process title, 1–3 seconds to add to backlog after threshold

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