🚀 ShokoBridge v5.1.2 - Python Base Image Update

This release provides a minor update to the underlying environment and matches the internal script versioning.

🛠 Build & Environment

• Python Upgrade: Updated the base image to Python 3.14.5-alpine 🐍 for improved stability and security patches within the 3.14 branch.
• Version Alignment: Bumped internal SCRIPT_VERSION to v5.1.2 to ensure consistency with the release tag.

---

Full Changelog: v5.1.1...v5.1.2 (v5.1.1...v5.1.2)

ShokoBridge v5.1.1 - Python 3.14 Upgrade

This release updates the project's runtime to Python 3.14, ensuring it stays current with the latest language features and improvements. All related project files, including the Docker image and dependency configurations, have been updated to match.

🔧 Build & Dependency Updates

• 🚀 Python 3.14 Runtime: The core runtime has been upgraded from Python 3.13 to 3.14.
• 🐳 Base Image Update: The Dockerfile now uses python:3.14.2-alpine as its base, bringing in the latest Python 3.14 environment.
• 📦 Dependency Refresh: Pipfile.lock and requirements.txt have been regenerated to align with the new Python version and ensure all dependencies are compatible.
• 📝 Documentation Update: The README.md has been updated to reflect the new Python 3.14 requirement for manual setups.
• 📌 Script Version Bump: The internal script version in ShokoBridge.py has been updated to v5.1.1.

ShokoBridge v5.1.0 - Security & Maintainability Release

This release focuses on significantly improving the security and maintainability of the Docker image. It includes critical security patches by updating the base image and implements best practices by running the container as a non-root user by default.

✨ Features & Enhancements

• 🛡️ Security Hardening (Non-Root User): The Docker container now runs as a dedicated, unprivileged user (appuser) by default. This is a major security enhancement that reduces the potential attack surface and aligns with containerization best practices.
  • Note for Docker Compose users: This change reinforces the importance of setting PUID and PGID in your environment to ensure the container has the correct permissions to write to your data volume.
• 🔒 Base Image Security Update: The Python base image has been updated to 3.13.7-alpine to incorporate upstream patches for high and medium-tier security vulnerabilities.
• 🔧 Improved Dockerfile Maintainability: The Dockerfile has been refactored to use ARG variables for the Python version, making future updates simpler and less error-prone.

ShokoBridge v5.0.1 - Docker Hotfix Release

This is a critical patch release that addresses a bug in the Docker build process which caused the v5.0.0 image to fail at runtime with a ModuleNotFoundError.

🐛 Bug Fixes

• fix(docker): Corrected the dependency installation path in the Dockerfile.
  • A subtle issue in the multi-stage build was copying Python dependencies to an incorrect directory within the final image. This caused the application to crash immediately as it could not find required libraries like requests.
  • This has been resolved by specifying the correct, explicit path. The Docker image is now fully functional.

ShokoBridge v5.0.0 - The Complete Rewrite

This release marks a complete, ground-up rewrite of ShokoBridge, evolving it from a single monolithic script into a robust, modular, and maintainable application. The focus of this release is on reliability, testability, and a vastly improved user experience.

---

🏗️ Major Architectural Overhaul

Contrasting with the previous version, which was a single ~400-line script, the project is now a structured Python package with a clear separation of concerns:

• 📦 Monolith to Modular: The single ShokoBridge.py has been replaced by a shokobridge/ package. The core logic now resides in bridge.py, which orchestrates dedicated manager and client classes.
• 📡 Dedicated Clients: API interactions are now handled by clients/shoko.py and clients/tmdb.py, which manage requests, caching, and data parsing.
• 📁 Filesystem Abstraction: All file operations (linking, moving, cleaning) are now managed by file_manager.py, which also handles transactional processing for media and supplemental files.
• 🗃️ Database Manager: All SQLite logic is now encapsulated within database.py, providing a clean interface for state management.

🧪 Unprecedented Reliability and Testing

For the first time, ShokoBridge has a comprehensive test suite, ensuring stability and preventing regressions.

• ✅ Full Test Coverage: Over 20 unit tests have been introduced, covering the core application logic, database operations, and file management.
• 🎭 Mocked Dependencies: Tests use extensive mocking to ensure they are fast, reliable, and independent of external services.
• 🛡️ Graceful Error Handling: The new architecture allows the application to handle errors gracefully, logging issues to a report file and continuing its run without crashing.

📚 Documentation and User Experience

The user-facing documentation and setup process have been completely revamped for clarity and ease of use.

• 📖 Overhauled README.md: The documentation is now a comprehensive guide covering the "why," features, and a clear, step-by-step setup for both Docker and Manual installations.
• 🐳 Streamlined Docker Setup: The docker-compose.yml is now clearer and better documented. All persistent data is centralized into a single ./data volume mount, simplifying setup and backups.
• ⚙️ Clearer Configuration: The config.json and its documentation have been refined to be more intuitive.

✨ Enhanced Features

• 🔄 Transactional File Groups: The script now processes a media file and all its supplemental files (e.g., .srt, .ass) as a single atomic unit. If any part fails, the entire group is rolled back.
• 🧠 Smarter Fallbacks: The script now includes more intelligent fallback mechanisms, such as title-similarity matching for episodes that lack a direct TMDb ID.
• 🎬 Improved Movie Pathing: Correctly handles movie placement in a subfolder of the main destination if a separate movie destination is not specified.

ShokoBridge v4.4.0: Supplemental Files & Transactional Operations

This is a major feature release that significantly enhances the script's robustness and file handling capabilities. ShokoBridge now fully manages supplemental files (like subtitles) and ensures that all file operations are atomic, preventing an incomplete or corrupt library structure.

✨ Major New Features

• 📂 Supplemental File Support: The script now automatically discovers and processes related files (e.g., .srt, .ass, .nfo) that share the same base name as the primary video file. When a video file is moved, copied, or linked, its sidecar files are brought along with it, ensuring your subtitles and other metadata are always where they need to be.

• 🛡️ Transactional File Groups: All file operations for a media item and its supplemental files are now treated as a single, atomic transaction. If any part of the operation fails (e.g., a subtitle file can't be linked), all changes for that group are automatically rolled back. This prevents partial entries and ensures your destination library remains clean and consistent.

• 🧹 Enhanced Cleanup: The --cleanup functionality has been greatly improved. It now correctly identifies and removes not only the stale media link but also all of its associated supplemental files. Furthermore, it will clean up any empty parent directories that are left behind after removing links, keeping your library tidy.

🛠️ Other Improvements

• 🏗️ Code Refactoring: The main script logic has been refactored into more focused functions (run_add_new, run_cleanup) to improve readability and make future development easier.
• 📝 Documentation: The README.md has been extensively updated to reflect all new features, provide a clearer feature list, and correct minor errors.

This update makes ShokoBridge more reliable and powerful for managing complex anime libraries. As always, please report any issues you encounter on the GitHub repository.

ShokoBridge v4.3.1: Docker Support & Project Cleanup

This is a quality-of-life and project structure update that makes ShokoBridge significantly easier to install, run, and manage, thanks to official Docker support. While there are no new media processing features, this release fundamentally improves the user experience.

🎉 What's New

• 🐳 Official Docker Support!

  • ShokoBridge is now available as an official image on Docker Hub! You can pull r33cy/shokobridge:latest to get started.
  • A docker-compose.yml file is now included in the repository, making setup as simple as editing a few paths and running docker-compose run.
  • This is now the recommended way to run ShokoBridge, eliminating the need for manual Python environment setup.

• 🗃️ Refactored Data Directory

  • All persistent data files (shokobridge_state.db, shokobridge_tmdb_cache.json, logs, and reports) are now stored in a single data/ directory.
  • This simplifies the project structure and makes mounting volumes in Docker much cleaner.

• 📝 Documentation Overhaul

  • The README.md has been updated to reflect the new Docker-first setup.
  • The project's origin story has been clarified to better explain why ShokoBridge is the essential tool for modern Plex users.

How to Upgrade or Install using Docker

1. Create a project directory on your host machine (e.g., /opt/shokobridge).

2. Inside that directory, create your config.json file.

3. Create a docker-compose.yml file using the template below, making sure to edit the host-side paths to match your system.

   version: '3.8'
   services:
     shokobridge:
       image: r33cy/shokobridge:latest
       container_name: shokobridge
       volumes:
         # Mount your config file
         - ./config.json:/app/config.json:ro
         # Mount your host media paths to the container paths defined in config.json
         - /path/on/host/to/anime:/anime:ro
         - /path/on/host/to/plex-shows:/plex-shows
         - /path/on/host/to/plex-movies:/plex-movies
         # Mount a single directory for all persistent data
         - ./data:/app/data

4. Run the script from your project directory:

   docker-compose run --rm shokobridge

ShokoBridge v4.3: The Movie & Optimization Update

This is a significant feature and performance release for ShokoBridge! Version 4.3 introduces first-class support for anime movies and dramatically improves performance by intelligently reducing API calls. Your library building process is now faster, smarter, and more organized than ever.

🎉 What's New

• 🎬 Movie Library Support!

  • ShokoBridge now correctly identifies files as movies based on their TMDb Movie ID.
  • A new optional destination_movies key in config.json allows you to route all movies to a completely separate folder, perfect for maintaining distinct "TV Shows" and "Movies" libraries in Plex.
  • If the new key is omitted, movies are placed in a subfolder within the main destination directory.

• ⚡️ Major Performance & API Optimizations

  • The script now leverages the rich TMDb data provided directly by the Shoko API for both movies and TV episodes.
  • This change drastically reduces the number of external calls to the TMDb API, resulting in:
    • Faster processing times.
    • Less waiting and fewer potential rate-limiting issues.
    • Increased reliability by depending more on your local Shoko instance.

• 🧠 Smarter Identification Logic

  • The file identification process has been refined into a clear hierarchy for maximum accuracy:
    1. Check for a TMDb Movie ID.
    2. If not a movie, check for a TMDb Episode ID.
    3. If no ID match, attempt a Title Similarity Match for regular episodes.
    4. If none of the above, classify as an Extra based on its AniDB type.

• 📝 Updated Documentation & Tools

  • The README.md has been completely updated to reflect the new movie handling features and configuration options.
  • The api_validator.py diagnostic tool has been improved to show when Shoko is providing rich TMDb data, making it easier to understand the script's behavior.

How to Upgrade

1. Replace your old ShokoBridge.py with the new version.
2. Update your config.json to include the new destination_movies path.

Example config.json update:

{
    "directories": {
        "source_root": "/mnt/z/Media/Anime",
        "destination": "/mnt/z/Media/Plex-Anime-Shows",
        "destination_movies": "/mnt/z/Media/Plex-Anime-Movies"
    }
}

ShokoBridge v4.2: The Solution to Plex's Dropped Scanner Support (Inaugural Release)

Welcome to the first public release of ShokoBridge! This project was born out of necessity. When Plex removed support for third-party scanners and agents, it broke the beloved Shoko Metadata plugin, leaving many users—especially those on locked-down platforms like the Nvidia Shield—unable to integrate their anime libraries correctly.

ShokoBridge is the purpose-built solution to that problem. Instead of relying on a plugin, it works externally to create a perfect, Plex-compatible library structure that Plex's native scanner can understand. It intelligently renames and links your files based on TMDb's season/episode format, giving you a perfectly organized and scannable library without any manual effort.

✨ Key Features of the Initial Release

• 🧠 Intelligent Two-Tiered Matching: At the heart of v4.2 is a powerful matching system that guarantees the highest possible accuracy.

  • Primary Match: Uses the direct TMDb Episode ID from Shoko for a perfect, 1:1 match.
  • Fallback Match: If a direct ID is missing, the script intelligently falls back to comparing the Shoko episode title with TMDb titles, finding the best match based on a configurable similarity score. This ensures even partially linked series are organized correctly.

• 🔗 Your Files, Your Way: Flexible File Operations: You have complete control over how your library is built. Choose the method that best suits your storage setup in the config.json file.

  • symlink (Default): The perfect solution for network shares or cross-drive setups.
  • hardlink: The most space-efficient option, ideal when your source and destination are on the same filesystem.
  • copy: Creates a full duplicate of your files, ensuring maximum compatibility and a separate, managed library.
  • move: Migrates your collection entirely into the new Plex-compatible structure.

• 🛡️ Safe and Stateful Management: We've built in a suite of tools to ensure you can manage your library with confidence.

  • Stateful Database: A local SQLite database tracks every processed file, preventing duplicates and ensuring the script only works on new additions.
  • --dry-run Mode: See exactly what the script will do without it touching a single file.
  • --cleanup Mode: Safely removes dead links and empty folders from your destination, keeping your library pristine.
  • Unmatched Reports: Generates a clear report of any files that couldn't be processed, so you know exactly what needs attention in Shoko.

• 🧩 Built for Complex Setups:

  • Path Mapping: Solves the "split-brain" problem where Plex and the script see different paths to your media (e.g., Docker, WSL, or NAS environments).
  • Cross-Platform: Works seamlessly on Windows, Linux, and WSL.

• ⚙️ Robust Foundation:

  • Centralized config.json: All settings in one easy-to-edit file.
  • Smart Caching: Minimizes TMDb API calls for faster subsequent runs.
  • Detailed Logging: Comprehensive logs with a --debug flag make troubleshooting a breeze.

This release transforms ShokoBridge into a truly "set it and forget it" solution for any serious anime collector using Plex. We're excited to share it with the community and look forward to your feedback!