Plexboxd

Plexboxd is a Discord bot that automatically tracks movies watched on Plex and integrates with Letterboxd to log and rate them. It monitors your Plex server for watched content and sends an embed with all necessary information to a Discord channel, allowing you to rate films directly from Discord - which then automatically adds them to your Letterboxd diary.

Features

• 🎬 Plex Integration: Monitors your Plex server for newly watched movies
• 🤖 Discord Notifications: Sends an embed with all necessary movie information to a Discord channel when you finish watching a film
• ⭐ Letterboxd Integration: Rate movies directly from Discord with seamless Letterboxd logging
• 📊 Watch History: Keeps track of your viewing history with timestamps and rating data
• 🌙 Date Threshold: Configurable time threshold to determine if late-night watches count for the current or previous day
• 📚 Multi-Library Support: Correctly identifies which library a movie was played from, even with duplicates across libraries
• 🚫 Library Exclusion: Exclude specific libraries from notifications (e.g., 4K or Kids libraries)

Requirements

• Python 3.7+
• A Discord account and a Discord server where you have admin permissions
• A Plex Media Server
• A Letterboxd account

Installation

1. Clone the repository

git clone https://github.com/nichtlegacy/plexboxd.git
cd plexboxd

2. Install the required dependencies

pip install -r requirements.txt

3. Create a .env file based on the provided .env.example

cp .env.example .env

4. Fill in the required environment variables in the .env file (see Configuration section)

5. Start the bot

python src/plex_bot.py

Docker Support

Plexboxd now supports running in a Docker container, making it easier to deploy and manage on any system that supports Docker. The official image is available on GitHub Container Registry (GHCR) at ghcr.io/nichtlegacy/plexboxd:latest.

Running with Docker

You can run Plexboxd using Docker in two ways: via the docker run command or with a docker-compose.yml file (recommended for easier configuration and persistence).

Prerequisites for Docker

• Docker installed on your system (Install Docker)
• (Optional) Docker Compose installed for using docker-compose.yml (Install Docker Compose)

Option 1: Using docker run

Pull the latest image and run it with your environment variables:

docker run -d \
  --name plexboxd \
  --restart unless-stopped \
  -e DISCORD_TOKEN="your-discord-token" \
  -e DISCORD_LOGGING_WEBHOOK_URL="your-webhook-url" \
  -e DISCORD_USER_ID="your-user-id" \
  -e PLEX_USERNAME="your-plex-username" \
  -e PLEX_TOKEN="your-plex-token" \
  -e PLEX_SERVER_URL="http://your-plex-server:32400" \
  -e EXCLUDED_LIBRARIES="" \
  -e NOTIFY_CHANNEL_ID="your-channel-id" \
  -e GUILD_ID="your-guild-id" \
  -e LETTERBOXD_USERNAME="your-letterboxd-username" \
  -e LETTERBOXD_PASSWORD="your-letterboxd-password" \
  -e DATE_THRESHOLD_HOUR="7" \
  -v /path/to/your/logs:/app/logs \
  -v /path/to/your/data:/app/data \
  ghcr.io/nichtlegacy/plexboxd:latest

Replace /path/to/your/logs and /path/to/your/data with actual paths on your host system (e.g., /mnt/user/appdata/plexboxd/logs and /mnt/user/appdata/plexboxd/data).

Option 2: Using Docker Compose (Recommended)

Using docker-compose simplifies configuration by allowing you to use a .env file and manage persistent volumes more easily. Below is an example docker-compose.yml:

version: '3.8'

services:
  plexboxd:
    image: ghcr.io/nichtlegacy/plexboxd:latest
    container_name: plexboxd
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./logs:/app/logs
      - ./data:/app/data

Steps to Use Docker Compose

1. Save the above content in a file named docker-compose.yml.

2. Create a .env file in the same directory with the following variables (see Configuration for details):

   DISCORD_TOKEN=your-discord-token
   DISCORD_LOGGING_WEBHOOK_URL=your-webhook-url
   DISCORD_USER_ID=your-user-id
   PLEX_USERNAME=your-plex-username
   PLEX_TOKEN=your-plex-token
   PLEX_SERVER_URL=http://your-plex-server:32400
   EXCLUDED_LIBRARIES=
   NOTIFY_CHANNEL_ID=your-channel-id
   GUILD_ID=your-guild-id
   LETTERBOXD_USERNAME=your-letterboxd-username
   LETTERBOXD_PASSWORD=your-letterboxd-password
   DATE_THRESHOLD_HOUR=7

3. (Optional, but recommended) Create the logs and data directories for persistence:

   mkdir logs data

4. Start the container:

   docker-compose up -d

5. To stop it:

   docker-compose down

Persistent Volumes

To ensure logs and data (like movie_data.db) persist across container restarts, map the following volumes:

• Logs: Host path (e.g., ./logs) to container path /app/logs
• Data: Host path (e.g., ./data) to container path /app/data

These mappings are included in the docker-compose.yml example above. Adjust the host paths to suit your system (e.g., /mnt/user/appdata/plexboxd/logs on Unraid).

Configuration

Environment Variables

The .env file contains all the necessary configuration parameters:

Discord Configuration

• DISCORD_TOKEN: Your Discord bot token from the Discord Developer Portal
• DISCORD_LOGGING_WEBHOOK_URL: Webhook URL for sending logs to a Discord channel
• NOTIFY_CHANNEL_ID: ID of the Discord channel where movie notifications will be sent
• GUILD_ID: ID of your Discord server
• DISCORD_USER_ID: Your Discord user ID to be notified when a movie is watched

Plex Configuration

• PLEX_USERNAME: Your Plex account username
• PLEX_TOKEN: Your Plex authentication token
• PLEX_SERVER_URL: URL of your Plex server (e.g., http://192.168.1.100:32400)
• EXCLUDED_LIBRARIES: Comma-separated list of library names to exclude from notifications (e.g., 4K Movies,Kids Movies)

Letterboxd Configuration

• LETTERBOXD_USERNAME: Your Letterboxd username
• LETTERBOXD_PASSWORD: Your Letterboxd password
• DATE_THRESHOLD_HOUR: Hour (in 24-hour format) to determine the cutoff for assigning movie watch dates (default: 7)

How to Get Required Tokens

Discord Bot Token

1. Go to the Discord Developer Portal
2. Create a new application
3. Go to the "Bot" tab and create a bot
4. Copy the token and add it to your .env file

Discord Channel and Guild IDs

1. Enable Developer Mode in Discord (User Settings > Advanced > Developer Mode)
2. Right-click on your server icon and select "Copy ID" for the Guild ID
3. Right-click on the notification channel and select "Copy ID" for the Channel ID

Plex Token

1. Log in to your Plex Web App
2. Play any media item
3. Right-click anywhere and choose "View Page Source"
4. Search for "X-Plex-Token" and copy the token value

Project Structure

📦 Plexboxd
├─ /data                            # Stores persistent data
│  └─ movie_data.db               # Cached movie data and watch history
├─ /logs                            # Log files directory
│  ├─ letterboxd_integration.log    # Letterboxd integration logs
│  └─ plex_bot.log                  # Main bot logs
├─ /src                             # Source code
│  ├─ letterboxd_integration.py     # Letterboxd API interaction and logging
│  ├─ logging_config.py             # Logging configuration for the bot
│  ├─ plex_bot.py                   # Main bot code and Plex monitoring
│  ├─ utils.py                      # Utility functions for Discord embeds
│  └─ views.py                      # Discord UI components (buttons, selects)
├─ .env                             # Environment variables (sensitive data)
├─ .env.example                     # Example environment variables file
├─ .gitignore                       # Git ignore configuration
└─ requirements.txt                 # Python dependencies

How It Works

1. Plex Monitoring: The bot connects to your Plex server and periodically checks for recently watched movies.

2. Discord Notifications: When a movie is watched, the bot sends an embed with all necessary movie information to the configured Discord channel.

   

3. Rating Interface: Each notification includes a dropdown menu to rate the movie directly from Discord.

   

4. Letterboxd Integration: When you rate a movie, the bot:

   • Logs into your Letterboxd account using requests
   • Searches for the movie using Selenium (headless)
   • Adds it to your diary with the correct date and rating via requests
   • Confirms the action with a success message

   

5. Date Assignment Logic: The bot uses the DATE_THRESHOLD_HOUR setting to determine if late-night watches count for the current or previous day in your Letterboxd diary.

Logging

The bot maintains two primary log files:

1. plex_bot.log

   • Bot startup and initialization
   • Plex connection status
   • Movie detection events
   • Discord notification events
   • Error messages

2. letterboxd_integration.log

   • Letterboxd login attempts
   • Movie search operations
   • Diary entry creation
   • Date assignment decisions

Both logs can also be forwarded to a Discord channel using the DISCORD_LOGGING_WEBHOOK_URL for easier monitoring.

Troubleshooting

Common Issues

1. Bot can't connect to Plex

   • Verify your Plex server is running
   • Check your PLEX_SERVER_URL and PLEX_TOKEN in the .env file
   • Ensure your firewall allows connections to your Plex server

2. Letterboxd integration fails

   • Verify your Letterboxd credentials
   • Check if Letterboxd is experiencing downtime
   • Ensure you have Chrome installed for Selenium (used for movie search)

3. Discord notifications aren't showing up

   • Verify your bot has proper permissions in the Discord server
   • Check if the NOTIFY_CHANNEL_ID is correct
   • Make sure the bot has access to the notification channel

Checking Logs

• Review the log files in the /logs directory for detailed error information
• If you've configured Discord logging, check the logging channel for real-time updates

Security Notes

• Your Letterboxd credentials and other sensitive information are stored in the .env file. Keep this file secure and never commit it to version control.

Contributing

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

Acknowledgements

• Plex for providing an excellent media server platform that makes tracking watched movies possible.
• Letterboxd for their movie logging and rating service, which inspired the core integration of this bot.
• Discord for their robust API and bot framework, enabling seamless notifications and interactions.
• PlexAPI - A Python library for interacting with Plex servers, heavily utilized in this project for movie tracking.
• Selenium - Used for headless browser automation to search for movies on Letterboxd.
• discord.py - The backbone of the Discord bot functionality, making embeds and interactive components possible.

Disclaimer

This project is not affiliated with or endorsed by Plex, Letterboxd, or Discord. It is an independent tool built for personal use and shared for educational purposes. Use it at your own risk and be respectful of the respective APIs by avoiding excessive requests. The developers are not responsible for any issues arising from misuse, including potential account restrictions by the integrated services.

License

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