🎬 Simkl Scrobbler

A cross-platform automatic movie tracker that seamlessly integrates with Simkl. It monitors your media players and automatically updates your watched history - no manual scrobbling required! ✨

Your movies, automatically tracked whenever you watch them

✨ Features

• 🎮 Universal Media Player Support - Works with VLC, MPV, MPC-HC, PotPlayer, and many others
• 🚀 Zero Configuration - Smart detection works out of the box
• 🌍 Cross-Platform - Full support for Windows, macOS, and Linux
• 🔄 Multiple Run Modes - Foreground, system tray, or background service
• 📊 Position Tracking - Monitors actual playback position for supported players
• 🔌 Offline Support - Queues updates when you're not connected
• 🧠 Smart Detection - Intelligent movie recognition from filenames

⚡ Quick Start

# 📥 Install
pip install simkl-scrobbler

# 🔑 Set up with your Simkl account
simkl-scrobbler init

# 🚀 Start tracking your movies
simkl-scrobbler start

📚 Documentation

For detailed instructions, please see the documentation:

• 📋 Installation Guide
• 🎮 Usage Guide
• 🎥 Supported Media Players
• ⚙️ Advanced Configuration
• 🔧 Troubleshooting
• 💻 Development Guide
• 📝 Todo List - Completed and planned features

🔍 How It Works

The application monitors your active windows to detect media players, extracts the movie title, and uses the Simkl API to identify and track your watching progress. When you've watched enough of a movie (default: 80%), it's automatically marked as watched in your Simkl account! 🎉

graph LR
    A[Media Player] -->|Window Title| B[Simkl Scrobbler]
    B -->|Parse Title| C[Movie Identification]
    C -->|Track Progress| D[Simkl API]
    D -->|Mark as Watched| E[Simkl Profile]
    
    style A fill:#f9d5e5,stroke:#333,stroke-width:2px
    style E fill:#d5f5e3,stroke:#333,stroke-width:2px

📊 Supported Players

VLC

MPC-HC

MPV

🎮 Many More

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🙏 Acknowledgments

• Simkl for their excellent API
• guessit for powerful video filename parsing
• iamkroot's Trakt Scrobbler for inspiration