Watch history - ByteTrix/Media-Player-Scrobbler-for-Simkl GitHub Wiki

📺 Local Watch History Viewer

A new feature in MPS for SIMKL is the Local Watch History Viewer. This page allows you to browse, search, and analyze your locally tracked watch history—including movies, TV shows, and anime—directly in your browser.

Features

  • Unified History: View all your watched movies, TV shows, and anime in one place.
  • Powerful Search & Filters: Search by title, year, or overview. Filter by type (movie, show, anime) and year.
  • Modern UI: Switch between grid and list views. Responsive, fast, and visually appealing.
  • Statistics Dashboard: See total watched, breakdown by type, and interactive charts (trends, time-of-day, etc).
  • Pagination: Easily browse large histories with page navigation.
  • Dark/Light Theme: Toggle between dark and light modes.
  • Detailed Cards: Click any item for more info, including file details and episode breakdowns for TV/anime.
  • TV Shows & Anime Support: Full scrobbling and episode tracking for TV and anime, with special handling for anime metadata.
  • Charts & Analytics: Visualize your watching trends, media type distribution, and viewing times with interactive charts.
  • HTML/CSS/JS Implementation: Built with vanilla JavaScript, modern CSS, and HTML—no frameworks required.

How to Use

  1. Open the watch-history-viewer folder in your browser (open index.html).
  2. Make sure your local data.js (exported or generated by the app) is present in the same folder.
  3. Browse, search, and analyze your watch history!
  4. Use the controls to filter by type (movie, TV, anime), year, or search by title/overview.
  5. Click any card for detailed info, including file path, size, and episode list for shows/anime.
  6. Use the dashboard to view statistics and trends. Toggle between grid/list and dark/light themes as you prefer.

TV Shows & Anime Scrobbling

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

  • TV Shows: Episodes are detected and scrobbled as you watch them in supported players.
  • Anime: Anime episodes are also detected and tracked, with special handling for anime-specific metadata.
  • Unified History: All types (movies, shows, anime) appear in your local and online history.

How It Works

  • The app parses filenames and player info to detect if a file is a movie, TV show, or anime.
  • For TV/anime, it extracts season/episode and matches to Simkl's database.
  • Progress is tracked and synced just like for movies.

Notes

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

Sample

https://github.com/user-attachments/assets/b4337aa2-6cb6-4946-b2a2-496e122fbc2a

Technical Notes

  • Built with HTML, CSS, and vanilla JS—no frameworks required.
  • Uses Chart.js for statistics visualizations.
  • All data is processed locally; no data is sent anywhere.

👨‍💻 Developer Guide: Watch History

Overview

The local watch history system is managed by the WatchHistoryManager (see simkl_mps/watch_history_manager.py). It tracks all watched movies, TV shows, and anime, and powers the local history viewer.

File Locations

  • History Data:
    • watch_history.json is stored in your data directory (e.g. ~/.kavinthangavel/simkl-mps/ or click open config dir in tray app .
  • Viewer:
    • The HTML/JS viewer is auto-copied to ~/kavinthangavel/simkl-mps/watch-history-viewer/.
    • The viewer loads data.js (auto-generated from your history).

How It Works

  • All scrobbled media (movies, TV, anime) are added/updated in watch_history.json.
  • For TV/anime, episodes are tracked in an episodes array inside each show entry.
  • The manager ensures the viewer files are always up-to-date and generates a data.js file for the UI.
  • The viewer can be opened from the tray menu or by opening index.html in the viewer folder.

Editing & Debugging

  • Manual Edits: You can edit watch_history.json directly (with a text editor), but be careful—ensure valid JSON format.
  • Debugging:
    • Errors and actions are logged to simkl_mps.log in the same app data directory.
    • If the viewer fails to load, check for JSON errors or missing fields.
    • The manager will auto-repair an empty or corrupt history file.
  • Resetting:
    • To clear all history, use the tray menu or delete watch_history.json (a new one will be created).

Developer Tips

  • The manager supports pagination, sorting, and filtering for advanced integrations.
  • You can add custom fields to history entries for experiments (the viewer will ignore unknown fields).
  • To test the viewer with sample data, replace watch_history.json and reload the viewer.
  • The add_entry method is the main entry point for programmatic updates.

For more details, see the main Usage Guide and Media Players Guide.