scrobblex

Report a Bug · Request a Feature · Ask a Question

Table of Contents

• 💡 About
• 🚀 Features
• 🐥 Getting Started
  • Usage
  • Docker
    • Using docker run
    • Using compose.yml
• 📄 Environment Variables
• 🚧 Roadmap
• 🛟 Support
  • FAQ
    • How to get your Plex user
• 🤝🏻 Contributing
• 👥 Authors & contributors
• 🛡️ Security
• 🪪 License
• ❤️ Acknowledgements

---

💡 About

Scrobblex is a self-hosted nodejs app that enables Plex scrobbling integration with Trakt via webhooks. It also allows you to push your ratings to Trakt.

Plex provides webhook integration for all Plex Pass subscribers, and users of their servers. A webhook is a request that the Plex application sends to third party services when a user takes an action, such as watching a movie or episode.

You can ask Plex to send these webhooks to this app, which will then log those plays in your Trakt account.

This tool is not affiliated with, endorsed by, or associated with Plex Inc.

Screenshots

This is basically a command line app, so there are no screenshots really, BUT I wanted to have at least some pretty logs:

🚀 Features

• Scrobble Plex plays to Trakt
• Push Plex ratings to Trakt
• Self-hosted
• No Trakt VIP account required

🐥 Getting Started

You don't need a Trakt VIP account to use this app (scrobblex will take care of that), BUT you need a Plex Pass subscription in order to have access to webhooks.

If you don't have a Plex Pass is also possible to use Tautulli notifications instead (see FAQ)

Usage

git clone https://github.com/ryck/scrobblex.git && cd scrobblex
npm install
npm run start

Once Scrobblex is running, just go to http://$YOUR_IP:$PORT/ (ie: http://10.20.30.40:3090/) and a web page will guide you to get your token.

Docker

Scrobblex is designed to be run in Docker. You can host it right on your Plex server!

To run it yourself, first create an API application through Trakt here.

Set the Redirect URI (previously know as Allowed Hostnames) to be the URI you will hit to access Scrobblex, plus /authorize.

So if you're exposing your server at http://10.20.30.40:3090, you'll set it to http://10.20.30.40:3090/authorize.

Bare IP addresses and ports are totally fine, but keep in mind your Scrobblex instance must be accessible to all the Plex servers you intend to play media from.

You can also have multiple URIs, one per line.

Again, once Scrobblex is running, just go to http://$YOUR_IP:$PORT/ (ie: http://127.0.0.1:3090/) and a web page will guide you to get your token.

Using docker run

docker run \
  --name=scrobbler \
  --restart always \
  -v <path to configs>:/app/data \
  -e TRAKT_ID=<trakt_id> \
  -e TRAKT_SECRET=<trakt_secret> \
  -p 3090:3090 \
  rickgc/scrobblex:latest

Using compose.yml

services:
  scrobbled:
    image: rickgc/scrobblex:latest
    container_name: scrobblex
    restart: always
    ports:
      - 3090:3090
    environment:
      - TRAKT_ID=YOUR_TRAKT_ID
      - TRAKT_SECRET=YOUR_TRAKT_SECRET
    volumes:
      - ./scrobblex:/app/data

📄 Environment Variables

Variable	Default	Required	Description
TRAKT_ID	undefined	Yes	Trakt application ID
TRAKT_SECRET	undefined	Yes	Trakt application secret
PLEX_USER	undefined	No	Plex username (comma separated list if you want to allow multiple users)
PORT	3090	No	Exposed express port
LOG_LEVEL	info	No	winston log level: ie: info, debug

🚧 Roadmap

See the open issues for a list of proposed features (and known issues).

• Top Feature Requests (Add your votes using the 👍 reaction)
• Top Bugs (Add your votes using the 👍 reaction)
• Newest Bugs

🛟 Support

Reach out to the maintainer at one of the following places:

• GitHub Discussions
• Contact options listed on this GitHub profile

FAQ

How to get your Plex user

You can find your plex user (don't confuse it with your Plex ID) by going to the Plex website and logging in. Your username will be in the top right corner.

Alternatively, you can find it by going to your account settings. Your username will be below your profile picture.

How to use Tautulli

1. Install Tautulli (if you don't have it already!)
2. Open Tautulli Settings
3. Open "Notification Agents"
4. In "Configuration" tab

• Webhook URL: scrobblex URL (ie, http://127.0.0.1:3090/plex)
• Webhook Method: Post
• Description: Scrobblex

5. Open "Triggers" tab and only select "Watched" checkmark
6. Open "Data" tab and click "Watched" item to expand. Keep JSON Headers empty and paste the following into "JSON Data":

{
  "event": "media.scrobble",
  "server": "tautulli",
  "Account": {
    "title": "{username}"
  },
  "Metadata": {
    <episode>
    "grandparentTitle": "{show_name}",
    "parentIndex": "{season_num}",
    "index": "{episode_num}",      
    </episode>
    "title": "<episode>{episode_name}</episode><movie>{title}</movie>",
    "type": "{media_type}",
    "year": "{year}",
    "Guid": [
      {
        "id": "imdb://{imdb_id}"
      },
      {
        "id": "tvdb://{thetvdb_id}"
      },
      {
        "id": "tmdb://{themoviedb_id}"
      }
    ]
  }
}

and click Save

(Optional): If you have multiple users on the same plex server, open Conditions tab and add Username is [select your username] Go back to Tautulli Settings and click Restart

🤝🏻 Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

👥 Authors & contributors

The original setup of this repository is by Ricardo Gonzalez.

For a full list of all authors and contributors, see the contributors page.

🛡️ Security

scrobblex follows good practices of security, but 100% security cannot be assured. scrobblex is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

🪪 License

This project is licensed under the MIT license.

See LICENSE for more information.

❤️ Acknowledgements

XanderStrike for his goplaxt project (now sadly dicontinued). It was a great inspiration for this project. Scrobblex is basically the same thing, but in NodeJS, so kudos to him!

If you want something more powerful, (or something that doesn't need a plex pass), check PlexTraktSync, it's an awesome project that will allow you to sync your watched media, your ratings, your lists, etc. from Plex to Trakt.