📘

Auto Subtitle Translator

The scripts and documents shared here are provided as-is by fellow customers. Ultra.cc does not review, test, or endorse these contributions. Their inclusion does not imply fitness for any particular purpose, nor guarantee compliance with our Terms of Service. No official support is provided for their use. You assume all risk in using them.

Disclaimer

This is an unofficial utility. While it aims to be robust, use it at your own risk. Ensure you understand how it interacts with your system and the gemini-srt-translator tool. Always back up important data. The accuracy and quality of translations depend on the gemini-srt-translator tool and the Gemini API.

Introduction

The Auto Subtitle Translator is a utility designed to automatically monitor a user-specified media directory (default: ~/media) for new video files (MKV, MP4). It then utilizes the gemini-srt-translator python tool to extract and translate their subtitles using the power of Google Gemini AI. The subtitles will be translated into your chosen target language.

This script runs in the background using a tmux session, ensuring continuous operation even if you disconnect from your server.

Features

Automatic Monitoring: Watches a user-specified media folder (default: ~/media) and its subfolders for new .mkv and .mp4 files.
Parallel Processing: Can process up to 3 video files simultaneously to speed up subtitle generation.
Configurable Target Language: You specify the desired language for the subtitles during installation.
Customizable Media Folder: Choose your preferred media folder to monitor during installation.
Environment Variable for API Key: Securely uses the GEMINI_API_KEY environment variable.
Background Operation: Runs within a tmux session, allowing it to operate independently of your active SSH connection.
Detailed Logging:

monitor.log: Tracks file detection and script operation.
process.log: Logs the output and status of each gst translate command (typically the last block of output after progress indicators).

Easy Installation & Management: A comprehensive setup script handles installation, uninstallation, and updates.

Prerequisites

Python: Python 3.10 or newer is required. See guide here for managing Python versions if needed.
Gemini API Key: A valid Gemini API key is necessary. Get it for free here.

Installation

Connect to your Ultra.cc service via SSH.
Execute the following command:

source ~/.profile

Next, execute the following command:

bash <(wget -qO- https://scripts.ultra.cc/comm-v1/Auto-Subtitle-Translator/main.sh)

The script will guide you through the following:

Choosing to Install (or manage/uninstall if already installed).
Entering your GEMINI_API_KEY. This will be stored in your shell configuration file (e.g., ~/.bashrc or ~/.zshrc).
Entering your desired target language for subtitles (e.g., English, Spanish, Brazilian Portuguese).
Specifying the media folder to monitor. You can accept the default (~/media) or provide a custom path (e.g., ~/videos, /mnt/media).

The installer will then:

Create the necessary directory: ~/scripts/auto-subtitle-translator.
Set up a Python virtual environment inside this directory.
Install gemini-srt-translator and watchdog Python packages.
Copy and configure the monitoring script (media_monitor.py) and the tmux runner script (start-auto-subtitle-translator.sh).

After the installation (or if you’ve updated the API key), you’ll need to source your shell configuration file or open a new terminal session for the GEMINI_API_KEY environment variable to become active:

source ~/.bashrc

How It Works

The core of the application consists of two main scripts located in ~/scripts/auto-subtitle-translator:

media_monitor.py:

This Python script uses the watchdog library to monitor the user-configured media directory for new video files.
When a new .mkv or .mp4 file is detected, it’s added to a queue.
A thread pool manages a configurable number of parallel workers (default: 3).
Each worker picks a file from the queue and executes the gst translate command (from the gemini-srt-translator package installed in the application’s virtual environment).
The gst command handles the actual subtitle extraction and translation.
Activity is logged to monitor.log and process.log within the ~/scripts/auto-subtitle-translator directory.

start-auto-subtitle-translator.sh:

This shell script is responsible for starting media_monitor.py inside a detached tmux session named auto-subtitle-translator.
It ensures that the correct Python virtual environment and Python’s unbuffered output mode (u) are used.
This allows the monitor to run continuously in the background and ensures console logs appear correctly in tmux.

Usage

Navigate to the Installation Directory:

cd ~/scripts/auto-subtitle-translator

Run the Start Script:

./start-auto-subtitle-translator.sh

The script will check the following:

Check if a tmux session named auto-subtitle-translator is already running.
If not, it will start a new detached session and launch the media_monitor.py script within it.
If it is running, it will inform you.

Manage `tmux` Session:

Attach to the session (to view logs or script output):

tmux attach -t auto-subtitle-translator

Detach from the session (leaving the script running): Press Ctrl+b then d.
List all tmux sessions:

tmux ls

Kill the session (to stop the monitor completely):

tmux kill-session -t auto-subtitle-translator

Manage Installation

The setup script is not just for initial installation. You can run it again at any time to manage your Auto Subtitle Translator setup:

bash <(wget -qO- https://scripts.ultra.cc/comm-v1/Auto-Subtitle-Translator/main.sh)

The script provides a menu with the following management options:

Install/Uninstall ${APPNAME}: Standard installation or complete removal.
Upgrade gemini-srt-translator Package: Updates the core Python package (gemini-srt-translator) within the application’s virtual environment to its latest version. If the monitor is running, you may need to restart it for changes to take full effect.
Update GEMINI_API_KEY: Allows you to change the Gemini API key stored in your shell configuration. Remember to source your shell config or open a new terminal after updating. The monitor script will pick up the new key on its next execution of gst translate (or after a restart if it had failed previously due to an invalid key).
Update Monitored Media Folder: Lets you change the directory that the media_monitor.py script watches for new video files. You’ll need to stop and restart the monitor script (via tmux kill-session and then running ./start-auto-subtitle-translator.sh) for this change to take effect.

Uninstallation

To uninstall the Auto Subtitle Translator:

Run the Main Setup Script again:

bash <(wget -qO- https://scripts.ultra.cc/comm-v1/Auto-Subtitle-Translator/main.sh)

Choose Uninstall.

When prompted by the menu, select the “Uninstall” option.

The uninstallation process will:

Attempt to stop the running auto-subtitle-translator tmux session.
Remove the entire ~/scripts/auto-subtitle-translator directory and all its contents.
Ask if you want to remove the GEMINI_API_KEY export from your shell configuration file.

If you require further assistance, you can open a support ticket here!

Feedback and suggestions regarding this article are welcome on our Discord server

Auto Subtitle Translator
Disclaimer
Introduction
Features
Prerequisites
Installation
How It Works
Usage
Manage tmux Session:
Manage Installation
Uninstallation

Auto Subtitle Translator

Auto Subtitle Translator

Disclaimer

Introduction

Features

Prerequisites

Installation

How It Works

Usage

Manage tmux Session:

Manage Installation

Uninstallation

Manage `tmux` Session: