Merge pull request #148 from marceljungle/copilot/fix-42177ad9-1e36-4cef-977a-83c1fa1ff330

marceljungle · web-flow · commit 23389850c208 · 2025-07-13T11:48:37.000+02:00
Improve project README with comprehensive documentation and enhanced metadata
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 marceljungle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,11 +1,32 @@
 # red-plex
 
-red-plex is a command-line tool for creating and updating Plex collections based on collages and bookmarks from Gazelle-based music trackers (Redacted “RED” and Orpheus “OPS”). It stores all data in a local SQLite database and provides commands to synchronize your music library with Plex and the torrent data from these trackers.
+[![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 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**: `red-plex collages convert 12345 --site red`
+
+## What are RED and OPS?
+
+- **Redacted (RED)**: A private music tracker focused on high-quality audio files
+- **Orpheus Network (OPS)**: Another private music tracker with curated content
+- Both use the Gazelle framework and offer "collages" (curated collections) and personal bookmarks
 
 ## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Getting API Keys](#getting-api-keys)
+- [Configuration](#configuration)
 - [Overview](#overview)
 - [Features](#features)
-- [Installation](#installation)
 - [Usage & Commands](#usage--commands)
   - [Configuration Commands](#configuration-commands)
   - [Collages](#collages)
@@ -18,21 +39,102 @@ red-plex is a command-line tool for creating and updating Plex collections based
   - [Using Query Fetch Mode](#using-query-fetch-mode)
 - [Configuration Details](#configuration-details)
 - [Configuration Tips](#configuration-tips)
-- [Considerations](#considerations)
+- [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 Token
+
+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.
+- **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”).
+- **Multi-Site**: Works with Redacted ("red") and Orpheus Network ("ops").
 - **Collections from Collages/Bookmarks**: Create or update entire Plex collections for each collage or bookmarked set.
 - **Local SQLite Database**: All data (albums, collages, bookmarks) 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.
@@ -41,20 +143,6 @@ red-plex is a command-line tool for creating and updating Plex collections based
 - **Simple CLI**: All major tasks are accessed via subcommands like `collages`, `bookmarks`, `db`, etc.
 - **Python 3.8+ Compatible**: Runs on modern Python versions with no external database dependencies.
 
-## Installation
-
-Install via pip:
-
-```bash
-pip install red-plex
-```
-
-Or use pipx for an isolated environment:
-
-```bash
-pipx install red-plex
-```
-
 ## Usage & Commands
 
 Type `red-plex --help` for detailed usage. Below is a summary of the main commands.
@@ -76,7 +164,7 @@ red-plex config reset
 
 ```bash
 # Create Plex collections for specific collage IDs
-red-plex collages convert [COLLAGE_IDS] --site [red|ops] --fetch-mode [torrent_name|query]
+red-plex collages convert [COLLAGE_IDS] --site [red|ops] --fetch-mode [normal|query]
 
 # Update all collages in the database, re-checking the site data
 red-plex collages update --fetch-mode [torrent_name|query]
@@ -96,10 +184,15 @@ red-plex bookmarks update --fetch-mode [torrent_name|query]
 
 The `--fetch-mode` (or `-fm`) option controls how red-plex locates albums in Plex:
 
-- **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.
+#### For `collages convert`:
+- **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
+
+#### For other commands (`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
 
-This option applies to `collages convert`, `collages update`, `bookmarks convert`, and `bookmarks update`. Defaults to `torrent_name` if omitted.
+> **Note**: There's a terminology difference between commands - `collages convert` uses "normal" while other commands use "torrent_name", but both refer to the same functionality.
 
 ### Database Commands
 
@@ -149,13 +242,33 @@ red-plex db albums update
 ### Using Query Fetch Mode
 
 ```bash
-# Create a collection using query mode
+# 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
+
+```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. Later, update all collections with new releases
+red-plex collages update
+red-plex bookmarks update
+```
+
 ## Configuration Details
 
 By default, configuration is stored in `~/.config/red-plex/config.yml`:
@@ -186,14 +299,72 @@ SECTION_NAME: Music
   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
+
+#### "No module named 'plexapi'" Error
+```bash
+pip install plexapi
+# or
+pip install red-plex --upgrade
+```
+
+#### 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
 
-## Considerations
+#### Fetch Mode Issues
+- Use `torrent_name`/`normal` 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
+
+### 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`/`normal` (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
+
+## 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 .
+```
+
+---
 
-- **Album Matching**:
-  - `torrent_name` (default): Matches folder paths.
-  - `query`: Uses metadata for reliable matching in renamed libraries.
-- **Database**: All data in `red_plex.db`. Reset tables with `db albums reset`, etc.
-- **Site Credentials**: Ensure valid API keys in `config.yml`.
-- **Rate Limits**: Adheres to site-specific settings.
-- **Logging**: Use `DEBUG` for verbose logs or `WARNING` for less output.
-- **Updates**: `collages update` and `bookmarks update` add new albums but do not remove existing items in Plex.
+**Disclaimer**: This tool is for personal use with your own music library and tracker accounts. Respect the rules and terms of service of the private trackers you use.
diff --git a/red_plex/infrastructure/cli/cli.py b/red_plex/infrastructure/cli/cli.py
@@ -143,12 +143,12 @@ def update_collages(ctx, fetch_mode: str):
               help='Specify the site: red (Redacted) or ops (Orpheus).')
 @click.option(
     '--fetch-mode', '-fm',
-    type=click.Choice(['normal', 'query'], case_sensitive=False),  # Added case_sensitive
-    default='normal',
+    type=click.Choice(['torrent_name', 'query'], case_sensitive=False),  # Added case_sensitive
+    default='torrent_name',
     show_default=True,
     help=(
             '(Optional) Album lookup strategy:\n'
-            '\n- normal: uses torrent dir name (original behavior).\n'
+            '\n- torrent_name: uses torrent dir name (original behavior).\n'
             '\n- query: uses Plex queries (Beets/Lidarr friendly).\n'
     )
 )
diff --git a/setup.py b/setup.py
@@ -25,13 +25,20 @@
 setup(
     name='red_plex',
     version=version,
-    description='A tool for creating Plex playlists or collections from RED collages',
+    description='A CLI tool for creating Plex collections from RED and OPS collages and bookmarks',
     long_description=long_description,
     long_description_content_type="text/markdown",
     author='marceljungle',
     author_email='gigi.dan2011@gmail.com',
     url='https://github.com/marceljungle/red-plex',
+    project_urls={
+        'Bug Reports': 'https://github.com/marceljungle/red-plex/issues',
+        'Source': 'https://github.com/marceljungle/red-plex',
+        'Documentation': 'https://github.com/marceljungle/red-plex#readme',
+    },
+    keywords='plex music collections red ops redacted orpheus gazelle tracker',
     packages=find_namespace_packages(include=['red_plex*']),
+    python_requires='>=3.8',
     include_package_data=True,
     install_requires=[
         'plexapi',
@@ -46,7 +53,18 @@
         red-plex=red_plex.infrastructure.cli.cli:main
     ''',
     classifiers=[
+        'Development Status :: 4 - Beta',
+        'Intended Audience :: End Users/Desktop',
+        'License :: OSI Approved :: MIT License',
         'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
+        'Programming Language :: Python :: 3.12',
         'Operating System :: OS Independent',
+        'Topic :: Multimedia :: Sound/Audio',
+        'Topic :: Internet :: WWW/HTTP :: Indexing/Search',
+        'Environment :: Console',
     ],
 )
