🎬 Subservient - The AI Subtitle Synchronizer

<div align="center">

</div> <br>

🔍 What Subservient Does

🎯 Automated subtitle synchronization for your video collection

Transform your viewing experience with perfectly synchronized subtitles in multiple languages. Subservient automatically extracts, downloads, and syncs subtitle files using advanced audio analysis, eliminating the frustration of out-of-sync dialogue. Unlike comprehensive media management systems like Bazarr or Sonarr, Subservient is a <b>standalone, easy to use CLI tool</b> that is dedicated specifically to subtitle synchronization. Simply point it at your video files, and it handles the technical complexity while giving you control over the results.

🔄 Core Workflow

Extract → Download → Synchronize → Verify

1. 📤 Subtitle Extraction: Automatically extracts embedded subtitles from video files
2. 🌐 Intelligent Download: Searches OpenSubtitles for missing languages based on your preferences
3. 🎵 Audio-Based Synchronization: Uses FFSubSync's advanced audio analysis to achieve frame-perfect timing
4. ✅ Quality Verification: Presents sync results for manual verification when automatic quality thresholds aren't met

🧹 Optional: Content cleaning tool available separately to remove promotional text and translator notes

Processing Modes

| Mode | Description | Best For | |------|-------------|----------| | 🎭 Movie Mode | Processes the largest video file in each folder | Film collections with extras and multiple versions | | 📺 Series Mode | Processes all videos with SxxExx pattern detection | TV shows with consistent episode naming |

⚡ Synchronization Strategies

| Strategy | Approach | Performance | |----------|----------|-------------| | 🚀 First Match | Uses first successful sync | Quick processing, good results | | 🎯 Smart Sync | Tests all newly downloaded subtitles, picks the best synced one | Slower but highest quality sync |

💡 Built for Real-World Use

Whether you're managing a personal movie collection, processing TV series with hundreds of episodes, or handling multilingual content for family viewing, Subservient adapts to your workflow while maintaining professional-grade subtitle quality.

<br>

📋 Table of Contents

1. 🔧 Installing and Configuring Subservient
2. 🎯 Using Subservient
3. ⚙️ How Subservient Works: The Four-Phase Automation Process
4. 🔍 Troubleshooting Common Issues
5. ❓ Frequently Asked Questions (FAQ)
6. 📚 Changelog
7. 🚀 Future Updates & Roadmap
8. 💝🎉 Support & Donations
9. 📄 License

<br>

🔧 INSTALLING AND CONFIGURING SUBSERVIENT

🚀 Quick Start Guide - New to Subservient?

1. Install first - Follow the installation steps below (or watch the video guide)
2. Read the documentation - Take time to understand how Subservient works and what it can do
3. Configure your settings - Review the .config file thoroughly - this controls everything Subservient does
4. Need help? Ask questions on GitHub or Buy Me a Coffee

Subservient works out of the box with sensible defaults, but proper configuration is key to making it work exactly how you want it to.

<b>Subservient offers two installation methods, each with distinct advantages:</b>

🖥️ Native Python Installation (Recommended for Performance)

Best for: Windows, macOS, and Linux users who want maximum performance

• ✅ Advantages: Uses 100% of your system resources, faster processing, native OS integration
• ⚠️ Complexity: Requires multiple applications to be installed and might need manual PATH configurations. More complex.

🐳 Docker Container Installation

Best for: Unraid, Linux servers, and users who prefer containerized applications

• ✅ Advantages: Easy setup, isolated environment, consistent across platforms
• ⚠️ Performance: May be slower, especially with limited RAM/CPU allocation

---

📺 Video Installation Guide (Native Python)

The video below provides a comprehensive walkthrough for the native Python installation, covering Python setup, required dependencies, setting up an OpenSubtitles consumer, and external tools like ffmpeg and mkvtoolnix.

📝 Note: Although this video was created for an older Subservient version, the installation procedure remains exactly the same.

<a href="https://www.youtube.com/watch?v=33lcr6dCtRw"> <img src="https://i.ibb.co/6JBG73qP/Screenshot-2025-07-28-112319.png" alt="Subservient Installation Video Guide" width="480"/> </a>

---

Choose your installation method:

<details> <summary><strong>🐍 Install Subservient with Python (Native Installation)</strong></summary> <br>

Best for: Users who want direct Python access, development, or full customization control

After downloading the Subservient folder from the GitHub repository, ensure that all required files are present in the same folder.

📁 Required Files

| File | Purpose | |------|---------| | subordinate.py | Main menu and setup | | extraction.py | Extract internal subtitles | | acquisition.py | Download from OpenSubtitles | | synchronisation.py | AI sync and cleanup | | utils.py | Shared utilities | | .config | Configuration file | | requirements.txt | Python dependencies |

⚠️ Keep all files together in the Subservient folder. Don't move or edit anything until setup is complete.

<br> <details> <summary><strong>🐍 Step 1: Install Python</strong></summary>

Subservient requires Python 3.8+. If you don't have Python:

1. Download from python.org
2. Install (Windows: recommended to install directly to C:\Python[version]\ for easier path management)
3. During installation, check "Add Python to PATH"
4. Test with: open a terminal and test by typing python --version. This should show the current version.

💡 Windows Installation Tip: Installing to a simple path like C:\Python[version]\ (you can shorten the folder name) makes troubleshooting much easier than the default AppData location.

🚨 If python --version doesn't work, Python wasn't added to PATH correctly during install.

Manual PATH Fix (Windows): Add these two folders to your system PATH (adjust path if you chose a different location):

• If installed to C-drive: C:\Python[version]\ and C:\Python[version]\Scripts\
• If default location: C:\Users\[YourUsername]\AppData\Local\Programs\Python\Python[version]\ and C:\Users\[YourUsername]\AppData\Local\Programs\Python\Python[version]\Scripts\

</details> <details> <summary><strong>🏗️ Step 2: Initial Setup</strong></summary>

Position the Subservient folder where you want to keep it permanently, then:

🚀 START: Run subordinate.py (double-click or python subordinate.py)

During initial setup:

| Step | Description | Status | |------|-------------|--------| | 📦 | Check for essential Python packages | Auto-install if missing | | ⚓ | Create anchor point and pathfiles | Saves to system config | | ✅ | Verify installation | Shows confirmation |

⚠️ Windows Users: Microsoft Visual C++ Build Tools are required for Python package installation. If you don't have them installed, Subservient will notice this, direct you to install them first and then exit. See Step 4 for installation instructions.

<br> <details> <summary><strong>🔧 Technical Setup Details</strong> ( click to expand)</summary>

• If you miss essential Python packages, it will attempt to install them using 'pip install'. Once you have the packages installed, it will either continue or quit depending on your system. If it quits, restart subordinate.py and it should continue to the initial setup.
• When it proceeds to the initial setup, it will create a Subservient_pathfiles textfile, where it
  will store all pathfiles. These paths will then be used throughout all Subservient scripts. This textfile is in your local appdata folder. The directory of this folder depends on your OS.
• When finished, you will see a confirmation that everything is set up correctly.

</details> <br>

📝 NOTE: If you ever decide to move the Subservient folder after installation, Subservient will automatically detect when essential files are missing or moved and will provide clear instructions. The old pathfile will be autom