SeriesSubSync

SeriesSubSync is an automated script for finding, extracting, and translating subtitles for video series. It's designed to run on a schedule (e.g., via cron) in a media server environment (like Emby, Plex, or Jellyfin) to ensure all new episodes have multilingual subtitles ready for viewing.

Key Features

• Automatic Discovery: Finds new, stable video files (.mkv) that don't yet have translated subtitles.
• Robust Extraction: Intelligently finds a preferred subtitle language (chi) but falls back to any available subtitle track if the preferred one is missing.
• High-Quality Translation: Uses the DeepL API to translate subtitles into multiple target languages (defaults to Italian, Chinese, and British English).
• Trilingual Output: Creates a single, combined .srt file with all three languages stacked for easy switching in media players.
• Secure: Reads the DeepL API key from an environment variable to keep your secrets safe.
• Efficient & Lightweight: Perfect for low-resource VPS setups. It creates tiny text files and cleans up after itself.

Prerequisites

• bash shell (standard on macOS and Linux)
• ffmpeg and ffprobe: For subtitle extraction.

  # On macOS with Homebrew
  brew install ffmpeg
  
  # On Debian/Ubuntu
  sudo apt-get update && sudo apt-get install ffmpeg

• Python 3
• Python libraries: deepl, langdetect

  pip3 install deepl langdetect

Setup

1. Clone the repository: Choose a suitable location for the project. Common choices are a tools or git folder in your home directory on Linux, or /Applications/ on macOS.

   git clone https://github.com/YIN-Renlong/SeriesSubSync.git
   cd SeriesSubSync

2. Make the script executable:

   chmod +x process_video.sh

3. Set your DeepL API Key: The script requires a DEEPL_API_KEY environment variable.

   export DEEPL_API_KEY="your-real-deepl-api-key"

   Tip: To make this permanent, add the export line to your shell profile (~/.zshrc on modern macOS/Linux, or ~/.bash_profile).

Usage

Place the scripts in a permanent directory (as chosen in the setup step). The script is designed to be run from within a directory containing video files. The cron example below handles this automatically.

Interactive Mode

To process a single file from a list of new videos in the current directory:

./process_video.sh

Automatic (Cron) Mode

To process all new, stable files without user interaction. This is the intended mode for automation.

./process_video.sh --auto

Example crontab entry:

This will run the script every 15 minutes. You must replace /path/to/your/videos with the absolute path to your media library.

The command >> sync.log 2>&1 will create a log file named sync.log inside the project directory, capturing all output and errors for easy debugging.

1. Edit your crontab:

   crontab -e

2. Add the following line, adjusting the paths for your system.

   Generic Template:

   */15 * * * * cd /path/to/your/videos && /path/to/SeriesSubSync/process_video.sh --auto >> /path/to/SeriesSubSync/sync.log 2>&1

   ---

   Example for a Linux Server (Ubuntu/Debian):

   Let's assume your videos are in /srv/media/tv and you cloned the project to /home/user/tools/SeriesSubSync.

   */15 * * * * cd /srv/media/tv && /home/user/tools/SeriesSubSync/process_video.sh --auto >> /home/user/tools/SeriesSubSync/sync.log 2>&1

   ---

   Example for macOS:

   Let's assume your videos are in ~/Movies/TV_Shows and you cloned the project to /Applications/SeriesSubSync.

   */15 * * * * cd /Users/yourusername/Movies/TV_Shows && /Applications/SeriesSubSync/process_video.sh --auto >> /Applications/SeriesSubSync/sync.log 2>&1

Note: The cron command now does two things: cd into the directory where your media files are, and then calls the script using its full, absolute path. This is a very robust way to ensure the script always works correctly, no matter where it's called from.