red-plex

Name	red-plex JSON
Version	1.13.0 JSON
	download
home_page	https://github.com/marceljungle/red-plex
Summary	A CLI and web GUI tool for creating Plex collections from RED and OPS collages and bookmarks
upload_time	2025-08-18 19:11:42
maintainer	None
docs_url	None
author	marceljungle
requires_python	>=3.8
license	None
keywords	plex music collections red ops redacted orpheus gazelle tracker
VCS
bugtrack_url
requirements	plexapi requests pyrate-limiter tenacity click pyyaml flask flask-socketio gunicorn eventlet thefuzz
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # red-plex

[![PyPI version](https://badge.fury.io/py/red-plex.svg)](https://badge.fury.io/py/red-plex)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A command-line tool and web interface for creating and updating Plex collections based on collages and bookmarks from Gazelle-based music trackers like **Redacted** ("RED") and **Orpheus Network** ("OPS"). 

red-plex bridges the gap between your curated music collections on private trackers and your personal Plex media server, automatically creating and maintaining Plex collections that mirror your tracker collages and bookmarks.

## Quick Start

1. **Install red-plex**: `pip install red-plex`
2. **Configure your API keys**: `red-plex config edit`
3. **Create your first collection**: 
   - **CLI**: `red-plex collages convert 12345 --site red`
   - **Web GUI**: `red-plex gui` (then visit http://127.0.0.1:8000)

## Web Interface

red-plex now includes a comprehensive web-based GUI for users who prefer a visual interface over command-line operations.

### Features

- **🌐 Dashboard**: Clean overview with feature cards and navigation
- **⚙️ Configuration Management**: View and edit all settings (API keys, Plex config, rate limits) through web forms
- **🎨 Collage Operations**: Convert new collages and view existing collections
- **🔖 Bookmark Operations**: Convert bookmarks from RED and OPS trackers
- **🏷️ Site Tags Operations**: Scan albums using album/artist names and create tag-based collections
- **🗄️ Database Management**: View statistics, update albums, reset tables
- **⚡ Real-time Updates**: Live status updates during long operations via WebSocket
- **📱 Mobile-Responsive**: Bootstrap-based design that works on all devices

### Usage

```bash
# Launch GUI server (default: http://127.0.0.1:8000)
red-plex gui

# Custom host/port
red-plex gui --host 0.0.0.0 --port 8080

# Debug mode with auto-reload
red-plex gui --debug
```

The web interface provides the same functionality as the CLI commands but with a user-friendly visual interface, real-time progress updates, and intuitive navigation.

## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Getting API Keys](#getting-api-keys)
- [Configuration](#configuration)
- [Web Interface](#web-interface)
- [Overview](#overview)
- [Features](#features)
- [Usage & Commands](#usage--commands)
  - [Configuration Commands](#configuration-commands)
  - [Collages](#collages)
  - [Upstream Sync](#upstream-sync)
  - [Bookmarks](#bookmarks)
  - [Site Tags](#site-tags)
  - [Remote Mappings](#remote-mappings)
  - [Fetch Mode (-fm)](#fetch-mode--fm)
  - [Database Commands](#database-commands)
- [Examples](#examples)
  - [Creating Collections](#creating-collections)
  - [Updating Collections](#updating-collections)
  - [Using Query Fetch Mode](#using-query-fetch-mode)
- [Configuration Details](#configuration-details)
- [Configuration Tips](#configuration-tips)
- [Troubleshooting](#troubleshooting)
- [Important Considerations](#important-considerations)
- [Contributing](#contributing)

---

## Prerequisites

- **Python 3.8 or higher**
- **Plex Media Server** with a configured music library
- **Active account** on RED and/or OPS with API access
- **Music library** organized in your Plex server

## Installation

### Using pip (recommended)

```bash
pip install red-plex
```

### Using pipx (isolated environment)

```bash
pipx install red-plex
```

### From source

```bash
git clone https://github.com/marceljungle/red-plex.git
cd red-plex
pip install -e .
```

## Getting API Keys

### For Redacted (RED)
1. Log into your RED account
2. Go to your profile settings
3. Navigate to "Access Settings" or "API"
4. Generate a new API key
5. **Keep this key secure and private**

### For Orpheus Network (OPS)
1. Log into your OPS account
2. Go to your user settings
3. Find the API section
4. Generate a new API key
5. **Keep this key secure and private**

## Configuration

After installation, you need to configure red-plex with your credentials:

```bash
# Open configuration file in your default editor
red-plex config edit
```

Edit the configuration file with your details:

```yaml
LOG_LEVEL: INFO
PLEX_URL: http://localhost:32400
PLEX_TOKEN: your_plex_token_here
SECTION_NAME: Music
RED:
  API_KEY: your_red_api_key_here
  BASE_URL: https://redacted.sh
  RATE_LIMIT:
    calls: 10
    seconds: 10
OPS:
  API_KEY: your_ops_api_key_here
  BASE_URL: https://orpheus.network
  RATE_LIMIT:
    calls: 4
    seconds: 15
```

### Getting Your Plex HTTPs URL

Visit: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token
Also visit: https://plex.tv/api/resources?includeHttps=1&X-Plex-Token={YOUR_TOKEN}

## Overview

- **Stores Data in SQLite**: Instead of CSV-based "caches," red-plex now stores albums, collages, and bookmarks in a lightweight SQLite database.
- **Collages & Bookmarks**: Fetch and manage torrent-based "collages" or personal "bookmarks" from Gazelle-based sites.
- **Plex Integration**: Compare the torrent group info with your Plex music library to create or update Plex collections.
- **Flexible Album Matching**: Match albums in Plex using either the original `torrent_name` (directory name) or a query-based approach (`Artist/Album`), ideal for organized libraries (e.g., Beets/Lidarr).
- **Incremental Updating**: Update previously created collections as new albums become available or site data changes.

## Features

- **Multi-Site**: Works with Redacted ("red") and Orpheus Network ("ops").
- **Web Interface**: Modern Flask-based GUI with Bootstrap styling and real-time updates.
- **Collections from Collages/Bookmarks**: Create or update entire Plex collections for each collage or bookmarked set.
- **Site Tags Mapping**: Map your Plex albums to site groups using album and artist names, then create collections based on specific tags.
- **Upstream Sync**: Push local Plex collection changes back to upstream collages on RED, enabling bidirectional synchronization between Plex collections and site collages.
- **Remote Mappings**: Core functionality that links Plex collections with site group IDs, enabling features like site tags and upstream sync.
- **Local SQLite Database**: All data (albums, collages, bookmarks, site mappings) is kept in one DB, no more CSV.
- **Two Fetch Modes**: Choose between `torrent_name` (default) for direct path matching or `query` for metadata-based searches in Plex.
- **Configurable Logging**: Choose between INFO, DEBUG, etc., in `config.yml`.
- **Rate Limiting**: Respects site rate limits and retries on errors.
- **Dual Interface**: Access all functionality via both command-line interface and web GUI.
- **Python 3.8+ Compatible**: Runs on modern Python versions with no external database dependencies.

## Usage & Commands

Type `red-plex --help` for detailed usage. Below is a summary of the main commands.

### Web Interface Commands

```bash
# Launch web GUI server
red-plex gui [--host HOST] [--port PORT] [--debug]

# Examples:
red-plex gui                           # Default: http://127.0.0.1:8000
red-plex gui --host 0.0.0.0            # Bind to all interfaces
red-plex gui --port 8080               # Custom port
red-plex gui --debug                   # Debug mode with auto-reload
```

### Configuration Commands

```bash
# Show current configuration (YAML)
red-plex config show

# Edit configuration in your default editor
red-plex config edit

# Reset configuration to default values
red-plex config reset
```

### Collages

```bash
# Create Plex collections for specific collage IDs
red-plex collages convert [COLLAGE_IDS] --site [red|ops] --fetch-mode [torrent_name|query]

# Update all collages in the database, re-checking the site data
red-plex collages update --fetch-mode [torrent_name|query]
```

### Upstream Sync

**⚠️ Important Prerequisites:**
- Only works with **RED** (Redacted) - OPS doesn't have the required API operations
- You must **own** the collages on the tracker site
- First **convert the collage** from the site using `red-plex collages convert` (even if the collage is empty)
- Run **remote mappings scan** to link Plex items with site group IDs: `red-plex db remote-mappings scan -s red`

**How it works:**
- Pushes local Plex collection changes back to upstream collages on RED
- Uses fuzzy string matching to find albums on the site (may cause occasional mismatches)
- Shows confirmation dialog with exactly what will be added before making changes
- **Never deletes** anything from upstream collages, only adds missing items
- If you update your Plex library, run a new remote-mappings scan to link new albums

```bash
# Sync all collections to upstream collages
red-plex collages update --push

# Sync specific collections to upstream collages  
red-plex collages update 12345 67890 --push

# Alternative flag name
red-plex collages update --update-upstream
```

**Scanning Process:**
- Can be cancelled anytime with **Ctrl+C** and resumed later
- Each mapping is saved to the database during scanning (no data loss)
- Scans latest added entries in Plex, so interrupted scans can continue from where they left off
- ⚠️ **Current limitation**: If you have many unmatched albums (e.g., 200 albums with no matches), they'll appear in the scan queue each time. This is being improved to ignore previously failed matches.

**Available in both CLI and Web Interface**

### Bookmarks

```bash
# Create Plex collections from your bookmarked releases
red-plex bookmarks convert --site [red|ops] --fetch-mode [torrent_name|query]

# Update all bookmarks in the database
red-plex bookmarks update --fetch-mode [torrent_name|query]
```

### Site Tags

```bash
# Create collections from albums matching specific tags
red-plex extras site-tags convert --tags [tag1,tag2,...] --collection-name [name]
```

### Remote Mappings

Remote mappings are the core functionality that links your Plex music library with site group IDs, enabling features like site tags and upstream sync.

```bash
# Scan albums and create remote mappings using album and artist names
red-plex db remote-mappings scan --site [red|ops] [--always-skip]

# Reset remote mappings (clears the relationship data)
red-plex db remote-mappings reset
```

**Scanning Features:**
- **Interruptible**: Can be cancelled with **Ctrl+C** at any time and resumed later
- **No data loss**: Each mapping is saved to database immediately during the scan
- **Incremental**: Processes latest Plex additions first, so you can resume interrupted scans
- **Fuzzy matching**: Uses string similarity to match Plex albums with site releases
- ⚠️ **Current limitation**: Albums with no matches will reappear in future scans (improvement planned)

### Fetch Mode (-fm)

The `--fetch-mode` (or `-fm`) option controls how red-plex locates albums in Plex:

#### For all commands (`collages convert`, `collages update`, `bookmarks convert`, `bookmarks update`):
- **torrent_name** (default): Searches for directories matching the torrent folder name
- **query**: Searches using `Artist` and `Album` metadata, ideal for organized libraries managed by tools like Beets or Lidarr

### Database Commands

```bash
# Show database location
red-plex db location

# Manage albums table
red-plex db albums reset        # Clear all album records
red-plex db albums update       # Pull fresh album info from Plex

# Manage collections table
red-plex db collections reset   # Clear the collage collections table

# Manage bookmarks table
red-plex db bookmarks reset     # Clear the bookmark collections table

# Manage remote mappings (core feature for site tags and upstream sync)
red-plex db remote-mappings scan --site [red|ops]  # Create Plex-to-site mappings
red-plex db remote-mappings reset                  # Clear remote mapping data
```

## Examples

### Creating Collections

```bash
# Single collage (Redacted), default mode
red-plex collages convert 12345 --site red

# Multiple collages (Orpheus), default mode
red-plex collages convert 1111 2222 3333 --site ops

# From bookmarks (RED or OPS), default mode
red-plex bookmarks convert --site red

# Remote mappings - scan albums and create mappings using album/artist names
red-plex db remote-mappings scan --site red

# Site tags - create collection from specific tags
red-plex extras site-tags convert --tags "electronic,ambient" --collection-name "Electronic Ambient"

# Upstream sync - push Plex collection changes back to RED collages (RED only)
red-plex collages update 12345 --push  # Sync specific collage
red-plex collages update --push         # Sync all collages
```

### Updating Collections

```bash
# Update all stored collages
red-plex collages update

# Update all stored bookmarks
red-plex bookmarks update

# Update albums from Plex
red-plex db albums update

# Sync collections to upstream collages (RED only)
red-plex collages update --push
```

### Using Query Fetch Mode

```bash
# Create a collection using query mode (for Beets/Lidarr organized libraries)
red-plex collages convert 12345 --site red --fetch-mode query

# Update all bookmarks using query mode
red-plex bookmarks update --site ops -fm query
```

### Complete Workflow Example

#### Command Line Interface
```bash
# 1. First time setup
red-plex config edit  # Add your API keys and Plex details

# 2. Update your local album database from Plex
red-plex db albums update

# 3. Create collections from specific collages
red-plex collages convert 12345 67890 --site red

# 4. Create collection from your bookmarks
red-plex bookmarks convert --site red

# 5. Scan albums for remote mappings (required for site tags and upstream sync)
red-plex db remote-mappings scan --site red

# 6. Create collections from specific tags
red-plex extras site-tags convert --tags "electronic,downtempo" --collection-name "Electronic Downtempo"

# 7. Sync collections back to upstream collages (RED only, requires ownership)
red-plex collages update --push

# 8. Later, update all collections with new releases
red-plex collages update
red-plex bookmarks update

# 9. If you add new music to Plex, re-scan for new mappings
red-plex db remote-mappings scan --site red
```

#### Web Interface
```bash
# 1. Launch the web interface
red-plex gui

# 2. Open http://127.0.0.1:8000 in your browser

# 3. Navigate to Configuration to add your API keys and Plex details

# 4. Use the Database page to update your local album database

# 5. Use the Collages page to convert specific collages

# 6. Use the Bookmarks page to convert your bookmarks

# 7. Use the Remote Mappings page to scan albums and create mappings

# 8. Use Site Tags to create collections from specific tags

# 9. Use the Collages page to sync collections to upstream (RED only)

# 10. Return to Database page later to update all collections
```

## Configuration Details

By default, configuration is stored in `~/.config/red-plex/config.yml`:

```yaml
LOG_LEVEL: INFO
OPS:
  API_KEY: your_ops_api_key_here
  BASE_URL: https://orpheus.network
  RATE_LIMIT:
    calls: 4
    seconds: 15
PLEX_TOKEN: your_plex_token_here
PLEX_URL: http://localhost:32400
RED:
  API_KEY: your_red_api_key_here
  BASE_URL: https://redacted.sh
  RATE_LIMIT:
    calls: 10
    seconds: 10
SECTION_NAME: Music
```

## Configuration Tips

- If HTTP fails, fetch an HTTPS URL:
  ```
  https://plex.tv/api/resources?includeHttps=1&X-Plex-Token={YOUR_TOKEN}
  ```
- Look for the `<Device>` node in the XML for a `uri`, use this `plex.direct` address.
- Use `DEBUG` log level for verbose debugging information
- Use `WARNING` log level for minimal output

## Troubleshooting

### Common Issues

#### Authentication Errors
- Verify your API keys are correct in `config.yml`
- Check that your Plex token is valid
- Ensure you have access to the sites you're trying to use

#### No Albums Found
- Run `red-plex db albums update` to refresh your Plex library
- Check that your Plex music library is properly configured
- Verify the `SECTION_NAME` in your config matches your Plex music library name

#### Rate Limiting Issues
- The tool respects site rate limits automatically
- If you encounter issues, try reducing the rate limit values in your config

#### Fetch Mode Issues
- Use `torrent_name` mode if your library structure matches torrent folder names
- Use `query` mode if you use Beets, Lidarr, or have renamed your music files
- Try both modes to see which works better for your library

#### Web Interface Issues
- **GUI won't start**: Ensure `gunicorn` and `eventlet` are installed: `pip install gunicorn eventlet`
- **Can't access GUI**: Check if the port is available and not blocked by firewall
- **GUI stuck on "Starting..."**: Check terminal logs for error messages
- **WebSocket connection failed**: Ensure your browser supports WebSockets and isn't blocking them

### Getting Help

1. Check the logs with `LOG_LEVEL: DEBUG` in your config
2. Verify your configuration with `red-plex config show`
3. Test your Plex connection by running `red-plex db albums update`
4. Open an issue on GitHub with detailed error messages

## Important Considerations

- **Album Matching Strategy**:
  - `torrent_name` (default): Matches albums by comparing torrent folder names with Plex directory paths
  - `query`: Uses artist and album metadata for matching, ideal for libraries organized by Beets, Lidarr, or other tools that rename files
- **Database Management**: All data is stored in `red_plex.db`. Use database reset commands (`db albums reset`, etc.) to clear specific tables when needed
- **Site Credentials**: Ensure your API keys are valid and have proper permissions
- **Rate Limiting**: The tool automatically respects site-specific rate limits to avoid being banned
- **Logging Levels**: 
  - `DEBUG`: Verbose output for troubleshooting
  - `INFO`: Standard information (default)
  - `WARNING`: Minimal output
- **Collection Updates**: When you run `collages update` or `bookmarks update`, new albums are added to existing Plex collections, but removed items from tracker collages are not automatically removed from Plex collections
- **Upstream Sync (RED Only)**: 
  - Only works with RED (Redacted) - OPS doesn't support the required API operations
  - You must own the collages you want to sync to
  - Convert collages from the site first, even if they're empty
  - Run `red-plex db remote-mappings scan --site red` to create the necessary mappings
  - Uses fuzzy string matching which may occasionally cause mismatches
  - Never deletes items from upstream collages, only adds missing ones
  - Can be interrupted with Ctrl+C and resumed later with no data loss
  - Re-scan after adding new music to your Plex library
- **Remote Mappings**: Core functionality that links Plex items with site group IDs. Required for both site tags and upstream sync features

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Development Setup

```bash
git clone https://github.com/marceljungle/red-plex.git
cd red-plex
pip install -e .
```

---

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/marceljungle/red-plex",
    "name": "red-plex",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "plex music collections red ops redacted orpheus gazelle tracker",
    "author": "marceljungle",
    "author_email": "gigi.dan2011@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/91/87/3ece1ccd873f093d0aab69228f663a3a58b096658bfe1192e395851609ef/red_plex-1.13.0.tar.gz",
    "platform": null,
    "description": "# red-plex\n\n[![PyPI version](https://badge.fury.io/py/red-plex.svg)](https://badge.fury.io/py/red-plex)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA command-line tool and web interface for creating and updating Plex collections based on collages and bookmarks from Gazelle-based music trackers like **Redacted** (\"RED\") and **Orpheus Network** (\"OPS\"). \n\nred-plex bridges the gap between your curated music collections on private trackers and your personal Plex media server, automatically creating and maintaining Plex collections that mirror your tracker collages and bookmarks.\n\n## Quick Start\n\n1. **Install red-plex**: `pip install red-plex`\n2. **Configure your API keys**: `red-plex config edit`\n3. **Create your first collection**: \n   - **CLI**: `red-plex collages convert 12345 --site red`\n   - **Web GUI**: `red-plex gui` (then visit http://127.0.0.1:8000)\n\n## Web Interface\n\nred-plex now includes a comprehensive web-based GUI for users who prefer a visual interface over command-line operations.\n\n### Features\n\n- **\ud83c\udf10 Dashboard**: Clean overview with feature cards and navigation\n- **\u2699\ufe0f Configuration Management**: View and edit all settings (API keys, Plex config, rate limits) through web forms\n- **\ud83c\udfa8 Collage Operations**: Convert new collages and view existing collections\n- **\ud83d\udd16 Bookmark Operations**: Convert bookmarks from RED and OPS trackers\n- **\ud83c\udff7\ufe0f Site Tags Operations**: Scan albums using album/artist names and create tag-based collections\n- **\ud83d\uddc4\ufe0f Database Management**: View statistics, update albums, reset tables\n- **\u26a1 Real-time Updates**: Live status updates during long operations via WebSocket\n- **\ud83d\udcf1 Mobile-Responsive**: Bootstrap-based design that works on all devices\n\n### Usage\n\n```bash\n# Launch GUI server (default: http://127.0.0.1:8000)\nred-plex gui\n\n# Custom host/port\nred-plex gui --host 0.0.0.0 --port 8080\n\n# Debug mode with auto-reload\nred-plex gui --debug\n```\n\nThe web interface provides the same functionality as the CLI commands but with a user-friendly visual interface, real-time progress updates, and intuitive navigation.\n\n## Table of Contents\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Getting API Keys](#getting-api-keys)\n- [Configuration](#configuration)\n- [Web Interface](#web-interface)\n- [Overview](#overview)\n- [Features](#features)\n- [Usage & Commands](#usage--commands)\n  - [Configuration Commands](#configuration-commands)\n  - [Collages](#collages)\n  - [Upstream Sync](#upstream-sync)\n  - [Bookmarks](#bookmarks)\n  - [Site Tags](#site-tags)\n  - [Remote Mappings](#remote-mappings)\n  - [Fetch Mode (-fm)](#fetch-mode--fm)\n  - [Database Commands](#database-commands)\n- [Examples](#examples)\n  - [Creating Collections](#creating-collections)\n  - [Updating Collections](#updating-collections)\n  - [Using Query Fetch Mode](#using-query-fetch-mode)\n- [Configuration Details](#configuration-details)\n- [Configuration Tips](#configuration-tips)\n- [Troubleshooting](#troubleshooting)\n- [Important Considerations](#important-considerations)\n- [Contributing](#contributing)\n\n---\n\n## Prerequisites\n\n- **Python 3.8 or higher**\n- **Plex Media Server** with a configured music library\n- **Active account** on RED and/or OPS with API access\n- **Music library** organized in your Plex server\n\n## Installation\n\n### Using pip (recommended)\n\n```bash\npip install red-plex\n```\n\n### Using pipx (isolated environment)\n\n```bash\npipx install red-plex\n```\n\n### From source\n\n```bash\ngit clone https://github.com/marceljungle/red-plex.git\ncd red-plex\npip install -e .\n```\n\n## Getting API Keys\n\n### For Redacted (RED)\n1. Log into your RED account\n2. Go to your profile settings\n3. Navigate to \"Access Settings\" or \"API\"\n4. Generate a new API key\n5. **Keep this key secure and private**\n\n### For Orpheus Network (OPS)\n1. Log into your OPS account\n2. Go to your user settings\n3. Find the API section\n4. Generate a new API key\n5. **Keep this key secure and private**\n\n## Configuration\n\nAfter installation, you need to configure red-plex with your credentials:\n\n```bash\n# Open configuration file in your default editor\nred-plex config edit\n```\n\nEdit the configuration file with your details:\n\n```yaml\nLOG_LEVEL: INFO\nPLEX_URL: http://localhost:32400\nPLEX_TOKEN: your_plex_token_here\nSECTION_NAME: Music\nRED:\n  API_KEY: your_red_api_key_here\n  BASE_URL: https://redacted.sh\n  RATE_LIMIT:\n    calls: 10\n    seconds: 10\nOPS:\n  API_KEY: your_ops_api_key_here\n  BASE_URL: https://orpheus.network\n  RATE_LIMIT:\n    calls: 4\n    seconds: 15\n```\n\n### Getting Your Plex HTTPs URL\n\nVisit: https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token\nAlso visit: https://plex.tv/api/resources?includeHttps=1&X-Plex-Token={YOUR_TOKEN}\n\n## Overview\n\n- **Stores Data in SQLite**: Instead of CSV-based \"caches,\" red-plex now stores albums, collages, and bookmarks in a lightweight SQLite database.\n- **Collages & Bookmarks**: Fetch and manage torrent-based \"collages\" or personal \"bookmarks\" from Gazelle-based sites.\n- **Plex Integration**: Compare the torrent group info with your Plex music library to create or update Plex collections.\n- **Flexible Album Matching**: Match albums in Plex using either the original `torrent_name` (directory name) or a query-based approach (`Artist/Album`), ideal for organized libraries (e.g., Beets/Lidarr).\n- **Incremental Updating**: Update previously created collections as new albums become available or site data changes.\n\n## Features\n\n- **Multi-Site**: Works with Redacted (\"red\") and Orpheus Network (\"ops\").\n- **Web Interface**: Modern Flask-based GUI with Bootstrap styling and real-time updates.\n- **Collections from Collages/Bookmarks**: Create or update entire Plex collections for each collage or bookmarked set.\n- **Site Tags Mapping**: Map your Plex albums to site groups using album and artist names, then create collections based on specific tags.\n- **Upstream Sync**: Push local Plex collection changes back to upstream collages on RED, enabling bidirectional synchronization between Plex collections and site collages.\n- **Remote Mappings**: Core functionality that links Plex collections with site group IDs, enabling features like site tags and upstream sync.\n- **Local SQLite Database**: All data (albums, collages, bookmarks, site mappings) is kept in one DB, no more CSV.\n- **Two Fetch Modes**: Choose between `torrent_name` (default) for direct path matching or `query` for metadata-based searches in Plex.\n- **Configurable Logging**: Choose between INFO, DEBUG, etc., in `config.yml`.\n- **Rate Limiting**: Respects site rate limits and retries on errors.\n- **Dual Interface**: Access all functionality via both command-line interface and web GUI.\n- **Python 3.8+ Compatible**: Runs on modern Python versions with no external database dependencies.\n\n## Usage & Commands\n\nType `red-plex --help` for detailed usage. Below is a summary of the main commands.\n\n### Web Interface Commands\n\n```bash\n# Launch web GUI server\nred-plex gui [--host HOST] [--port PORT] [--debug]\n\n# Examples:\nred-plex gui                           # Default: http://127.0.0.1:8000\nred-plex gui --host 0.0.0.0            # Bind to all interfaces\nred-plex gui --port 8080               # Custom port\nred-plex gui --debug                   # Debug mode with auto-reload\n```\n\n### Configuration Commands\n\n```bash\n# Show current configuration (YAML)\nred-plex config show\n\n# Edit configuration in your default editor\nred-plex config edit\n\n# Reset configuration to default values\nred-plex config reset\n```\n\n### Collages\n\n```bash\n# Create Plex collections for specific collage IDs\nred-plex collages convert [COLLAGE_IDS] --site [red|ops] --fetch-mode [torrent_name|query]\n\n# Update all collages in the database, re-checking the site data\nred-plex collages update --fetch-mode [torrent_name|query]\n```\n\n### Upstream Sync\n\n**\u26a0\ufe0f Important Prerequisites:**\n- Only works with **RED** (Redacted) - OPS doesn't have the required API operations\n- You must **own** the collages on the tracker site\n- First **convert the collage** from the site using `red-plex collages convert` (even if the collage is empty)\n- Run **remote mappings scan** to link Plex items with site group IDs: `red-plex db remote-mappings scan -s red`\n\n**How it works:**\n- Pushes local Plex collection changes back to upstream collages on RED\n- Uses fuzzy string matching to find albums on the site (may cause occasional mismatches)\n- Shows confirmation dialog with exactly what will be added before making changes\n- **Never deletes** anything from upstream collages, only adds missing items\n- If you update your Plex library, run a new remote-mappings scan to link new albums\n\n```bash\n# Sync all collections to upstream collages\nred-plex collages update --push\n\n# Sync specific collections to upstream collages  \nred-plex collages update 12345 67890 --push\n\n# Alternative flag name\nred-plex collages update --update-upstream\n```\n\n**Scanning Process:**\n- Can be cancelled anytime with **Ctrl+C** and resumed later\n- Each mapping is saved to the database during scanning (no data loss)\n- Scans latest added entries in Plex, so interrupted scans can continue from where they left off\n- \u26a0\ufe0f **Current limitation**: If you have many unmatched albums (e.g., 200 albums with no matches), they'll appear in the scan queue each time. This is being improved to ignore previously failed matches.\n\n**Available in both CLI and Web Interface**\n\n### Bookmarks\n\n```bash\n# Create Plex collections from your bookmarked releases\nred-plex bookmarks convert --site [red|ops] --fetch-mode [torrent_name|query]\n\n# Update all bookmarks in the database\nred-plex bookmarks update --fetch-mode [torrent_name|query]\n```\n\n### Site Tags\n\n```bash\n# Create collections from albums matching specific tags\nred-plex extras site-tags convert --tags [tag1,tag2,...] --collection-name [name]\n```\n\n### Remote Mappings\n\nRemote mappings are the core functionality that links your Plex music library with site group IDs, enabling features like site tags and upstream sync.\n\n```bash\n# Scan albums and create remote mappings using album and artist names\nred-plex db remote-mappings scan --site [red|ops] [--always-skip]\n\n# Reset remote mappings (clears the relationship data)\nred-plex db remote-mappings reset\n```\n\n**Scanning Features:**\n- **Interruptible**: Can be cancelled with **Ctrl+C** at any time and resumed later\n- **No data loss**: Each mapping is saved to database immediately during the scan\n- **Incremental**: Processes latest Plex additions first, so you can resume interrupted scans\n- **Fuzzy matching**: Uses string similarity to match Plex albums with site releases\n- \u26a0\ufe0f **Current limitation**: Albums with no matches will reappear in future scans (improvement planned)\n\n### Fetch Mode (-fm)\n\nThe `--fetch-mode` (or `-fm`) option controls how red-plex locates albums in Plex:\n\n#### For all commands (`collages convert`, `collages update`, `bookmarks convert`, `bookmarks update`):\n- **torrent_name** (default): Searches for directories matching the torrent folder name\n- **query**: Searches using `Artist` and `Album` metadata, ideal for organized libraries managed by tools like Beets or Lidarr\n\n### Database Commands\n\n```bash\n# Show database location\nred-plex db location\n\n# Manage albums table\nred-plex db albums reset        # Clear all album records\nred-plex db albums update       # Pull fresh album info from Plex\n\n# Manage collections table\nred-plex db collections reset   # Clear the collage collections table\n\n# Manage bookmarks table\nred-plex db bookmarks reset     # Clear the bookmark collections table\n\n# Manage remote mappings (core feature for site tags and upstream sync)\nred-plex db remote-mappings scan --site [red|ops]  # Create Plex-to-site mappings\nred-plex db remote-mappings reset                  # Clear remote mapping data\n```\n\n## Examples\n\n### Creating Collections\n\n```bash\n# Single collage (Redacted), default mode\nred-plex collages convert 12345 --site red\n\n# Multiple collages (Orpheus), default mode\nred-plex collages convert 1111 2222 3333 --site ops\n\n# From bookmarks (RED or OPS), default mode\nred-plex bookmarks convert --site red\n\n# Remote mappings - scan albums and create mappings using album/artist names\nred-plex db remote-mappings scan --site red\n\n# Site tags - create collection from specific tags\nred-plex extras site-tags convert --tags \"electronic,ambient\" --collection-name \"Electronic Ambient\"\n\n# Upstream sync - push Plex collection changes back to RED collages (RED only)\nred-plex collages update 12345 --push  # Sync specific collage\nred-plex collages update --push         # Sync all collages\n```\n\n### Updating Collections\n\n```bash\n# Update all stored collages\nred-plex collages update\n\n# Update all stored bookmarks\nred-plex bookmarks update\n\n# Update albums from Plex\nred-plex db albums update\n\n# Sync collections to upstream collages (RED only)\nred-plex collages update --push\n```\n\n### Using Query Fetch Mode\n\n```bash\n# Create a collection using query mode (for Beets/Lidarr organized libraries)\nred-plex collages convert 12345 --site red --fetch-mode query\n\n# Update all bookmarks using query mode\nred-plex bookmarks update --site ops -fm query\n```\n\n### Complete Workflow Example\n\n#### Command Line Interface\n```bash\n# 1. First time setup\nred-plex config edit  # Add your API keys and Plex details\n\n# 2. Update your local album database from Plex\nred-plex db albums update\n\n# 3. Create collections from specific collages\nred-plex collages convert 12345 67890 --site red\n\n# 4. Create collection from your bookmarks\nred-plex bookmarks convert --site red\n\n# 5. Scan albums for remote mappings (required for site tags and upstream sync)\nred-plex db remote-mappings scan --site red\n\n# 6. Create collections from specific tags\nred-plex extras site-tags convert --tags \"electronic,downtempo\" --collection-name \"Electronic Downtempo\"\n\n# 7. Sync collections back to upstream collages (RED only, requires ownership)\nred-plex collages update --push\n\n# 8. Later, update all collections with new releases\nred-plex collages update\nred-plex bookmarks update\n\n# 9. If you add new music to Plex, re-scan for new mappings\nred-plex db remote-mappings scan --site red\n```\n\n#### Web Interface\n```bash\n# 1. Launch the web interface\nred-plex gui\n\n# 2. Open http://127.0.0.1:8000 in your browser\n\n# 3. Navigate to Configuration to add your API keys and Plex details\n\n# 4. Use the Database page to update your local album database\n\n# 5. Use the Collages page to convert specific collages\n\n# 6. Use the Bookmarks page to convert your bookmarks\n\n# 7. Use the Remote Mappings page to scan albums and create mappings\n\n# 8. Use Site Tags to create collections from specific tags\n\n# 9. Use the Collages page to sync collections to upstream (RED only)\n\n# 10. Return to Database page later to update all collections\n```\n\n## Configuration Details\n\nBy default, configuration is stored in `~/.config/red-plex/config.yml`:\n\n```yaml\nLOG_LEVEL: INFO\nOPS:\n  API_KEY: your_ops_api_key_here\n  BASE_URL: https://orpheus.network\n  RATE_LIMIT:\n    calls: 4\n    seconds: 15\nPLEX_TOKEN: your_plex_token_here\nPLEX_URL: http://localhost:32400\nRED:\n  API_KEY: your_red_api_key_here\n  BASE_URL: https://redacted.sh\n  RATE_LIMIT:\n    calls: 10\n    seconds: 10\nSECTION_NAME: Music\n```\n\n## Configuration Tips\n\n- If HTTP fails, fetch an HTTPS URL:\n  ```\n  https://plex.tv/api/resources?includeHttps=1&X-Plex-Token={YOUR_TOKEN}\n  ```\n- Look for the `<Device>` node in the XML for a `uri`, use this `plex.direct` address.\n- Use `DEBUG` log level for verbose debugging information\n- Use `WARNING` log level for minimal output\n\n## Troubleshooting\n\n### Common Issues\n\n#### Authentication Errors\n- Verify your API keys are correct in `config.yml`\n- Check that your Plex token is valid\n- Ensure you have access to the sites you're trying to use\n\n#### No Albums Found\n- Run `red-plex db albums update` to refresh your Plex library\n- Check that your Plex music library is properly configured\n- Verify the `SECTION_NAME` in your config matches your Plex music library name\n\n#### Rate Limiting Issues\n- The tool respects site rate limits automatically\n- If you encounter issues, try reducing the rate limit values in your config\n\n#### Fetch Mode Issues\n- Use `torrent_name` mode if your library structure matches torrent folder names\n- Use `query` mode if you use Beets, Lidarr, or have renamed your music files\n- Try both modes to see which works better for your library\n\n#### Web Interface Issues\n- **GUI won't start**: Ensure `gunicorn` and `eventlet` are installed: `pip install gunicorn eventlet`\n- **Can't access GUI**: Check if the port is available and not blocked by firewall\n- **GUI stuck on \"Starting...\"**: Check terminal logs for error messages\n- **WebSocket connection failed**: Ensure your browser supports WebSockets and isn't blocking them\n\n### Getting Help\n\n1. Check the logs with `LOG_LEVEL: DEBUG` in your config\n2. Verify your configuration with `red-plex config show`\n3. Test your Plex connection by running `red-plex db albums update`\n4. Open an issue on GitHub with detailed error messages\n\n## Important Considerations\n\n- **Album Matching Strategy**:\n  - `torrent_name` (default): Matches albums by comparing torrent folder names with Plex directory paths\n  - `query`: Uses artist and album metadata for matching, ideal for libraries organized by Beets, Lidarr, or other tools that rename files\n- **Database Management**: All data is stored in `red_plex.db`. Use database reset commands (`db albums reset`, etc.) to clear specific tables when needed\n- **Site Credentials**: Ensure your API keys are valid and have proper permissions\n- **Rate Limiting**: The tool automatically respects site-specific rate limits to avoid being banned\n- **Logging Levels**: \n  - `DEBUG`: Verbose output for troubleshooting\n  - `INFO`: Standard information (default)\n  - `WARNING`: Minimal output\n- **Collection Updates**: When you run `collages update` or `bookmarks update`, new albums are added to existing Plex collections, but removed items from tracker collages are not automatically removed from Plex collections\n- **Upstream Sync (RED Only)**: \n  - Only works with RED (Redacted) - OPS doesn't support the required API operations\n  - You must own the collages you want to sync to\n  - Convert collages from the site first, even if they're empty\n  - Run `red-plex db remote-mappings scan --site red` to create the necessary mappings\n  - Uses fuzzy string matching which may occasionally cause mismatches\n  - Never deletes items from upstream collages, only adds missing ones\n  - Can be interrupted with Ctrl+C and resumed later with no data loss\n  - Re-scan after adding new music to your Plex library\n- **Remote Mappings**: Core functionality that links Plex items with site group IDs. Required for both site tags and upstream sync features\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/marceljungle/red-plex.git\ncd red-plex\npip install -e .\n```\n\n---\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A CLI and web GUI tool for creating Plex collections from RED and OPS collages and bookmarks",
    "version": "1.13.0",
    "project_urls": {
        "Bug Reports": "https://github.com/marceljungle/red-plex/issues",
        "Documentation": "https://github.com/marceljungle/red-plex#readme",
        "Homepage": "https://github.com/marceljungle/red-plex",
        "Source": "https://github.com/marceljungle/red-plex"
    },
    "split_keywords": [
        "plex",
        "music",
        "collections",
        "red",
        "ops",
        "redacted",
        "orpheus",
        "gazelle",
        "tracker"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "7e0c0587de30d5d7ea077fdc0d793c762c75c4b2f47c972e5f04a0d72729c8c7",
                "md5": "f1671944e1f4bc3ce5b59745be9d97d9",
                "sha256": "94e48ffbb2ff3e9f7c51085d3f3c082a8f4caf6bbd18f55c0fb19278e6ceb202"
            },
            "downloads": -1,
            "filename": "red_plex-1.13.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f1671944e1f4bc3ce5b59745be9d97d9",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 106380,
            "upload_time": "2025-08-18T19:11:41",
            "upload_time_iso_8601": "2025-08-18T19:11:41.372646Z",
            "url": "https://files.pythonhosted.org/packages/7e/0c/0587de30d5d7ea077fdc0d793c762c75c4b2f47c972e5f04a0d72729c8c7/red_plex-1.13.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "91873ece1ccd873f093d0aab69228f663a3a58b096658bfe1192e395851609ef",
                "md5": "c23f555a977fd6f1293e8a5abe62797c",
                "sha256": "c3b24f167c31a6f29142682f85fa7c387a39960eb3aa02150aecb4de6c83e4c4"
            },
            "downloads": -1,
            "filename": "red_plex-1.13.0.tar.gz",
            "has_sig": false,
            "md5_digest": "c23f555a977fd6f1293e8a5abe62797c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 81968,
            "upload_time": "2025-08-18T19:11:42",
            "upload_time_iso_8601": "2025-08-18T19:11:42.684829Z",
            "url": "https://files.pythonhosted.org/packages/91/87/3ece1ccd873f093d0aab69228f663a3a58b096658bfe1192e395851609ef/red_plex-1.13.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-18 19:11:42",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "marceljungle",
    "github_project": "red-plex",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "plexapi",
            "specs": []
        },
        {
            "name": "requests",
            "specs": []
        },
        {
            "name": "pyrate-limiter",
            "specs": []
        },
        {
            "name": "tenacity",
            "specs": []
        },
        {
            "name": "click",
            "specs": []
        },
        {
            "name": "pyyaml",
            "specs": []
        },
        {
            "name": "flask",
            "specs": []
        },
        {
            "name": "flask-socketio",
            "specs": []
        },
        {
            "name": "gunicorn",
            "specs": []
        },
        {
            "name": "eventlet",
            "specs": []
        },
        {
            "name": "thefuzz",
            "specs": []
        }
    ],
    "lcname": "red-plex"
}