maateen · maateen · Nov 8, 2025 · Sep 8, 2025 · Oct 20, 2025 · Oct 21, 2025
@@ -10,20 +10,9 @@ repos:
       - id: mixed-line-ending
         args: ['--fix=lf']
 
-  - repo: https://github.com/psf/black
-    rev: 25.1.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.0
     hooks:
-      - id: black
-        language_version: python3
-
-  - repo: https://github.com/pycqa/isort
-    rev: 6.0.1
-    hooks:
-      - id: isort
-        args: ["--profile", "black"]
-
-  - repo: https://github.com/pycqa/flake8
-    rev: 7.3.0
-    hooks:
-      - id: flake8
-        args: [--max-line-length=88, --extend-ignore=E203]
+      - id: ruff-check
+        args: [ --fix ]
+      - id: ruff-format
@@ -7,18 +7,21 @@
 
 > ⚠️ **Active Development**: This project is under active development. Features may change and stability is not guaranteed. Use at your own risk.
 
-A Python automation tool that connects to your Bazarr instance, identifies movies missing subtitles, and automatically downloads them from SubSource.
+A Python automation tool that connects to your Bazarr instance, identifies movies and TV episodes missing subtitles, and automatically downloads them from SubSource.
 
 ## Features
 
 - 🎬 **Automatic Movie Detection**: Lists all movies missing subtitles from your Bazarr instance
+- 📺 **TV Series Episode Support**: Automatically downloads subtitles for wanted TV series episodes
 - 🌐 **SubSource Integration**: Downloads subtitles from SubSource's anonymous API (no account needed)
 - 📤 **Seamless Upload**: Automatically uploads downloaded subtitles back to Bazarr
+- 🔄 **Automatic Synchronization**: Built-in subtitle sync with configurable parameters (No Framerate Fix, GSS, etc.)
 - 🌍 **Multi-language Support**: Supports multiple languages, forced, and hearing impaired subtitles
 - ⏱️ **Smart Retry Logic**: Uses Bazarr's own search intervals to avoid redundant API calls
 - 📊 **Progress Tracking**: Tracks search history to prevent unnecessary duplicate searches
 - 🧹 **Clean Operation**: Automatically cleans up temporary files after successful uploads
 - ⚙️ **Configurable**: External configuration file for easy setup
+- 🔧 **Episode Matching**: Intelligent episode matching using season/episode patterns and scene names
 
 ## Requirements
 
@@ -63,6 +66,17 @@ A Python automation tool that connects to your Bazarr instance, identifies movie
    [download]
    directory = /tmp/downloaded_subtitles
 
+   [movies]
+   # Enable movie subtitle downloads
+   enabled = true
+
+   [episodes]
+   # Enable TV series episode subtitle downloads
+   enabled = true
+   # Search patterns: season_episode,episode_title,scene_name
+   search_patterns = season_episode,episode_title,scene_name
+
+
    [logging]
    level = INFO
    file = /var/log/bazarr_subsource.log
@@ -143,21 +157,98 @@ The tool's built-in tracking system prevents redundant searches, making frequent
 ### Download Settings
 - `directory`: Local directory for temporary subtitle files (default: `/tmp/downloaded_subtitles`)
 
+### Movies Settings
+- `enabled`: Enable movie subtitle downloads (default: `true`)
+
+### Episodes Settings
+- `enabled`: Enable TV series episode subtitle downloads (default: `true`)
+- `search_patterns`: Episode search patterns, comma-separated (default: `season_episode,episode_title,scene_name`)
+  - `season_episode`: Search using "Series S01E01" format
+  - `episode_title`: Search using "Series Episode Title" format
+  - `scene_name`: Search using scene release names
+
 ### Logging
 - `level`: Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
 - `file`: Log file path (default: `/var/log/bazarr_subsource.log`)
+- Log rotation: 10MB max file size, keeps 5 backup files
 
 ## How It Works
 
+### Movies
 1. **Connect to Bazarr**: Fetches all movies missing subtitles using the `/api/movies/wanted` endpoint
 2. **Search SubSource**: For each movie, searches SubSource API for available subtitles
 3. **Smart Filtering**: Uses Bazarr's own search intervals to avoid redundant searches
 4. **Download Process**: Downloads subtitle ZIP files and extracts the subtitle files
 5. **Upload to Bazarr**: Uploads extracted subtitles back to Bazarr using the `/api/movies/subtitles` endpoint
 6. **Cleanup**: Removes temporary files and updates tracking data
 
+### TV Series Episodes
+1. **Connect to Bazarr**: Fetches all episodes missing subtitles using the `/api/episodes/wanted` endpoint
+2. **Episode Enrichment**: Retrieves series information for each episode from `/api/series`
+3. **Multi-Pattern Search**: Searches SubSource using various patterns:
+   - Series name + S01E01 format
+   - Series name + episode title
+   - Scene release names
+4. **Episode Matching**: Filters SubSource results to match specific season/episode using regex patterns
+5. **Upload to Bazarr**: Uploads matched subtitles using the `/api/episodes/subtitles` endpoint
+6. **Cleanup**: Removes temporary files and updates episode tracking data
+
 ## Advanced Features
 
+### Automatic Subtitle Synchronization
+The tool uses Bazarr's built-in SubSync functionality for subtitle synchronization:
+
+#### Features
+- **Conditional Sync**: Automatically synchronizes subtitles only if SubSync is enabled in Bazarr
+- **Uses Bazarr Settings**: Reads sync parameters directly from your Bazarr configuration
+- **Audio/Video Reference**: Uses first audio track as reference for sync
+- **Framerate Handling**: Respects your Bazarr SubSync framerate settings
+- **Advanced Algorithms**: Uses Golden-Section Search (GSS) if enabled in Bazarr
+
+#### How It Works
+1. **Check SubSync Status**: Tool reads your Bazarr's SubSync settings via `/api/system/settings`
+2. **Upload**: Subtitle is uploaded to Bazarr successfully
+3. **Conditional Sync**: If SubSync is enabled in Bazarr, synchronization is performed
+4. **Retrieve Path**: Gets the server-side subtitle file path from Bazarr
+5. **Synchronize**: Calls Bazarr's `/api/subtitles` PATCH endpoint with your configured parameters
+6. **Verification**: Confirms successful synchronization before cleanup
+
+#### SubSync Configuration
+No configuration needed in this tool! SubSync settings are automatically retrieved from your Bazarr instance:
+- Enable/disable SubSync in Bazarr Settings → Subtitles → SubSync
+- Configure `max_offset_seconds`, `no_fix_framerate`, and `gss` settings in Bazarr
+- Tool automatically uses your Bazarr SubSync preferences
+
+**Note**: If SubSync is disabled in Bazarr, subtitles will be uploaded without synchronization.
+
+### Sub-Zero Subtitle Content Modifications
+The tool displays your Bazarr Sub-Zero configuration for subtitle content modifications:
+
+#### Features
+- **Automatic Detection**: Reads Sub-Zero modification settings from Bazarr
+- **Modification Display**: Shows which Sub-Zero mods are active
+- **No Configuration Required**: Uses your existing Bazarr Sub-Zero settings
+
+#### How It Works
+1. **Read Settings**: Tool fetches Sub-Zero configuration from `/api/system/settings`
+2. **Display Status**: Shows whether Sub-Zero mods are enabled and which ones are active
+3. **Automatic Triggering**: After successful subtitle upload, triggers Sub-Zero modifications if enabled
+4. **Post-Processing**: Sub-Zero mods are applied before subtitle synchronization
+
+#### Common Sub-Zero Modifications
+Based on your Bazarr configuration, common modifications include:
+- **common**: Basic fixes (OCR errors, formatting, color tags)
+- **hearing_impaired**: Hearing impaired content processing
+- **ocr**: Advanced OCR error correction
+- **fps**: Frame rate conversion fixes
+
+#### Processing Order
+After successful subtitle upload to Bazarr:
+1. **Sub-Zero Modifications** (if enabled): Applied first to improve subtitle quality
+2. **SubSync** (if enabled): Applied second to synchronize timing
+
+This ensures subtitles are properly cleaned up before timing synchronization.
+
 ### Intelligent Retry Logic
 The tool integrates with Bazarr's system tasks to determine optimal search intervals:
 - Reads Bazarr's "Search for Missing Movies Subtitles" task interval
@@ -253,17 +344,19 @@ bazarr-subsource/
 
 SubSource's anonymous API has rate limits. This tool implements:
 - 2-second delays between API calls
-- Intelligent retry logic based on Bazarr's intervals
+- Intelligent retry logic based on Bazarr's intervals for both movies and episodes
 - Local tracking to minimize unnecessary requests
+- Episode-specific search patterns to reduce API calls
 - No authentication headers or account credentials needed
 
 ## Troubleshooting
 
 ### Common Issues
 
-**"No movies are currently missing subtitles!"**
-- Check if your Bazarr has movies with missing subtitles
+**"No movies are currently missing subtitles!" / "No episodes want subtitles."**
+- Check if your Bazarr has movies/episodes with missing subtitles
 - Verify your Bazarr API key and URL are correct
+- For episodes: Ensure `episodes_enabled = true` in your config
 
 **"Error connecting to Bazarr API"**
 - Ensure Bazarr is running and accessible
@@ -279,6 +372,12 @@ SubSource's anonymous API has rate limits. This tool implements:
 - The tool creates a default config on first run
 - Edit `~/.config/bazarr-subsource/config.cfg` with your settings
 
+**Episode subtitles not found**
+- Episodes are searched using multiple patterns (S01E01, episode title, scene name)
+- SubSource has limited TV series coverage compared to movies
+- Check if the series name matches exactly in both Bazarr and SubSource
+- Some episodes may not have subtitles available on SubSource
+
 **Cron job not running or failing**
 - Check cron service is running: `sudo systemctl status cron`
 - Verify cron job syntax: `crontab -l`