Usage - ByteTrix/Media-Player-Scrobbler-for-Simkl GitHub Wiki

🎮 Usage Guide

This guide explains how to use MPS for SIMKL to track your movies and sync with your SIMKL profile.

🏁 Getting Started

  1. Install the app for your platform (see guides above).
  2. Authenticate with SIMKL on first run.
  3. Configure your media players (see Media Players Guide).
  4. Play movies in your configured player. The app tracks and syncs progress automatically.

🖥️ Windows (EXE)

  • Just install and launch. The app runs in the tray —no commands needed.
  • Use the tray icon for status and controls.

🐧 Linux (pipx)

  • Install with pipx (see Linux Guide).
  • Start with simkl-mps tray or simkl-mps start.
  • Tray icon provides controls and status.

🍏 Mac (pip, untested)

  • Install with pip (see Mac Guide).
  • Start with simkl-mps tray or simkl-mps start.
  • Tray icon provides controls and status.

Note: Mac support is experimental and untested.

📺 TV Shows & Anime Tracking

MPS for SIMKL now supports automatic tracking of TV shows and anime, in addition to movies.

  • TV show and anime episodes are detected and scrobbled as you watch them in supported players.
  • All types (movies, shows, anime) appear in your local and online history.
  • For best results, use clear filenames (e.g. Show.Name.S01E02.mkv or Anime.Title.12.mp4).
  • See the Media Players Guide for player-specific setup.

📊 Local Watch History Viewer

A new local watch history page is available! Open the watch-history-viewer folder in your browser to:

  • Browse all your watched movies, TV shows, and anime
  • Search, filter, and sort your history
  • View statistics and trends (charts, breakdowns)
  • Switch between grid/list views and dark/light themes

See Local Watch History for full details.

🔔 Tray Status Icons

MPS for SIMKL uses the system tray/notification area to show its current status across all platforms:

Icon Status Description
Running Running App is actively monitoring and ready to track media playback
Paused Paused Tracking is temporarily paused, no new media will be scrobbled
Stopped Stopped App is inactive and not tracking (but still running in tray)
Error Error There's an issue with the app (authentication, API, etc.)

Right-click the tray icon to access the app menu with options to:

  • Start/stop/pause monitoring
  • View currently detected media
  • Access settings
  • Exit the application

🚦 Real-World Performance Timings

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

🛠️ Common Operations

  • Tray: Right-click for menu, status, and tools.
  • CLI: 
    simkl-mps start        # Start in background
simkl-mps tray         # Start with tray UI
simkl-mps status       # Check status
simkl-mps stop         # Stop the app
simkl-mps --help       # Help

📝 Tips