# 🎬 Simkl Scrobbler
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[]()
[](CONTRIBUTING.md)
A cross-platform automatic movie tracker that seamlessly integrates with [Simkl](https://simkl.com). It monitors your media players and automatically updates your watched history - no manual scrobbling required! ✨
<div align="center">
<img src="https://eu.simkl.in/img_blog_2012/logo.png" alt="Simkl Logo" width="150"/>
<br/>
<em>Your movies, automatically tracked whenever you watch them</em>
</div>
## ✨ 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
```bash
# 📥 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](docs/installation.md)
- 🎮 [Usage Guide](docs/usage.md)
- 🎥 [Supported Media Players](docs/media-players.md)
- ⚙️ [Advanced Configuration](docs/configuration.md)
- 🔧 [Troubleshooting](docs/troubleshooting.md)
- 💻 [Development Guide](docs/development.md)
- 📝 [Todo List](docs/todo.md) - 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! 🎉
```mermaid
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
<div align="center">
<table>
<tr>
<td align="center"><img src="https://upload.wikimedia.org/wikipedia/commons/3/38/VLC_icon.png" width="40px"/><br/>VLC</td>
<td align="center"><img src="https://upload.wikimedia.org/wikipedia/commons/7/76/Media_Player_Classic_logo.png" width="40px"/><br/>MPC-HC</td>
<td align="center"><img src="https://upload.wikimedia.org/wikipedia/commons/7/73/Mpv_logo_%28official%29.png" width="40px"/><br/>MPV</td>
<td align="center">🎮<br/>Many More</td>
</tr>
</table>
</div>
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 👥 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 🙏 Acknowledgments
- [Simkl](https://simkl.com) for their excellent API
- [guessit](https://github.com/guessit-io/guessit) for powerful video filename parsing
- [iamkroot's Trakt Scrobbler](https://github.com/iamkroot/trakt-scrobbler/) for inspiration
---
<div align="center">
<p>Made with ❤️ by <a href="https://github.com/kavinthangavel">kavinthangavel</a></p>
<p>
<a href="https://github.com/kavinthangavel/simkl-movie-tracker/stargazers">⭐ Star us on GitHub</a> •
<a href="https://github.com/kavinthangavel/simkl-movie-tracker/issues">🐛 Report Bug</a> •
<a href="https://github.com/kavinthangavel/simkl-movie-tracker/issues">✨ Request Feature</a>
</p>
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/kavinthangavel/simkl-scrobbler",
"name": "simkl-scrobbler",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "simkl, scrobbler",
"author": "kavinthangavel",
"author_email": "kavinthangavel.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/62/db/bc3b2e88b969b25c828544a7039152ddcfd1eefeee9c5bdfebe164b8a7d3/simkl_scrobbler-1.2.3.tar.gz",
"platform": null,
"description": "# \ud83c\udfac Simkl Scrobbler\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[]()\n[](CONTRIBUTING.md)\n\nA cross-platform automatic movie tracker that seamlessly integrates with [Simkl](https://simkl.com). It monitors your media players and automatically updates your watched history - no manual scrobbling required! \u2728\n\n<div align=\"center\">\n <img src=\"https://eu.simkl.in/img_blog_2012/logo.png\" alt=\"Simkl Logo\" width=\"150\"/>\n <br/>\n <em>Your movies, automatically tracked whenever you watch them</em>\n</div>\n\n## \u2728 Features\n\n- \ud83c\udfae **Universal Media Player Support** - Works with VLC, MPV, MPC-HC, PotPlayer, and many others\n- \ud83d\ude80 **Zero Configuration** - Smart detection works out of the box\n- \ud83c\udf0d **Cross-Platform** - Full support for Windows, macOS, and Linux\n- \ud83d\udd04 **Multiple Run Modes** - Foreground, system tray, or background service\n- \ud83d\udcca **Position Tracking** - Monitors actual playback position for supported players\n- \ud83d\udd0c **Offline Support** - Queues updates when you're not connected\n- \ud83e\udde0 **Smart Detection** - Intelligent movie recognition from filenames\n\n## \u26a1 Quick Start\n\n```bash\n# \ud83d\udce5 Install\npip install simkl-scrobbler\n\n# \ud83d\udd11 Set up with your Simkl account\nsimkl-scrobbler init\n\n# \ud83d\ude80 Start tracking your movies\nsimkl-scrobbler start\n```\n\n## \ud83d\udcda Documentation\n\nFor detailed instructions, please see the documentation:\n\n- \ud83d\udccb [Installation Guide](docs/installation.md)\n- \ud83c\udfae [Usage Guide](docs/usage.md)\n- \ud83c\udfa5 [Supported Media Players](docs/media-players.md)\n- \u2699\ufe0f [Advanced Configuration](docs/configuration.md)\n- \ud83d\udd27 [Troubleshooting](docs/troubleshooting.md)\n- \ud83d\udcbb [Development Guide](docs/development.md)\n- \ud83d\udcdd [Todo List](docs/todo.md) - Completed and planned features\n\n## \ud83d\udd0d How It Works\n\nThe 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! \ud83c\udf89\n\n```mermaid\ngraph LR\n A[Media Player] -->|Window Title| B[Simkl Scrobbler]\n B -->|Parse Title| C[Movie Identification]\n C -->|Track Progress| D[Simkl API]\n D -->|Mark as Watched| E[Simkl Profile]\n \n style A fill:#f9d5e5,stroke:#333,stroke-width:2px\n style E fill:#d5f5e3,stroke:#333,stroke-width:2px\n```\n\n## \ud83d\udcca Supported Players\n\n<div align=\"center\">\n <table>\n <tr>\n <td align=\"center\"><img src=\"https://upload.wikimedia.org/wikipedia/commons/3/38/VLC_icon.png\" width=\"40px\"/><br/>VLC</td>\n <td align=\"center\"><img src=\"https://upload.wikimedia.org/wikipedia/commons/7/76/Media_Player_Classic_logo.png\" width=\"40px\"/><br/>MPC-HC</td>\n <td align=\"center\"><img src=\"https://upload.wikimedia.org/wikipedia/commons/7/73/Mpv_logo_%28official%29.png\" width=\"40px\"/><br/>MPV</td>\n <td align=\"center\">\ud83c\udfae<br/>Many More</td>\n </tr>\n </table>\n</div>\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udc65 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\ude4f Acknowledgments\n\n- [Simkl](https://simkl.com) for their excellent API\n- [guessit](https://github.com/guessit-io/guessit) for powerful video filename parsing\n- [iamkroot's Trakt Scrobbler](https://github.com/iamkroot/trakt-scrobbler/) for inspiration\n\n---\n\n<div align=\"center\">\n <p>Made with \u2764\ufe0f by <a href=\"https://github.com/kavinthangavel\">kavinthangavel</a></p>\n <p>\n <a href=\"https://github.com/kavinthangavel/simkl-movie-tracker/stargazers\">\u2b50 Star us on GitHub</a> \u2022\n <a href=\"https://github.com/kavinthangavel/simkl-movie-tracker/issues\">\ud83d\udc1b Report Bug</a> \u2022\n <a href=\"https://github.com/kavinthangavel/simkl-movie-tracker/issues\">\u2728 Request Feature</a>\n </p>\n</div>\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatic Movie Scrobbler for Simkl",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/kavinthangavel/simkl-scrobbler",
"Repository": "https://github.com/kavinthangavel/simkl-scrobbler"
},
"split_keywords": [
"simkl",
" scrobbler"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "261089f57e767f33b53cb63da8a02c42f6d4b74e4b40295a5600d7312b55418a",
"md5": "5c37294fa83175ef7b89d80abe272ff2",
"sha256": "bbf689a577ea5ae70e45b08505468947a841d64ca90e2f4791e74d5f484a4bc8"
},
"downloads": -1,
"filename": "simkl_scrobbler-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c37294fa83175ef7b89d80abe272ff2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 60807,
"upload_time": "2025-04-21T07:37:08",
"upload_time_iso_8601": "2025-04-21T07:37:08.424639Z",
"url": "https://files.pythonhosted.org/packages/26/10/89f57e767f33b53cb63da8a02c42f6d4b74e4b40295a5600d7312b55418a/simkl_scrobbler-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "62dbbc3b2e88b969b25c828544a7039152ddcfd1eefeee9c5bdfebe164b8a7d3",
"md5": "4ca7f9221ddc0da757e8273d32c00420",
"sha256": "fde8a2afcbc6c070a4acbf260e359cbd268d4aaa71517a1c0403d0b1fa5ef61a"
},
"downloads": -1,
"filename": "simkl_scrobbler-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "4ca7f9221ddc0da757e8273d32c00420",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 50513,
"upload_time": "2025-04-21T07:37:09",
"upload_time_iso_8601": "2025-04-21T07:37:09.784779Z",
"url": "https://files.pythonhosted.org/packages/62/db/bc3b2e88b969b25c828544a7039152ddcfd1eefeee9c5bdfebe164b8a7d3/simkl_scrobbler-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-21 07:37:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kavinthangavel",
"github_project": "simkl-scrobbler",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "simkl-scrobbler"
}
JSON
