Auto Subtitle Translator

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, your media files, the gemini-srt-translator tool, and the Gemini API. Always back up important data.
• The accuracy and quality of translations and transcriptions depend on the gemini-srt-translator tool, the selected Gemini model, the source subtitles or audio, and the Gemini API.
• Transcription and translation use your own Gemini API key. Depending on the selected model, video length, number of files processed, and whether transcription is enabled, this may consume API quota quickly or require a paid Gemini API key.
• Free-tier API keys may hit rate limits, especially when audio transcription fallback is enabled.

Introduction

• Auto Subtitle Translator is a utility designed to automatically monitor a user-specified media directory, such as ~/media, for new video files.
• When a supported video file is detected, the script can check whether subtitles already exist in your selected target language. If matching subtitles are found, the file is skipped to avoid unnecessary processing and Gemini API usage.
• If subtitles are available but not in your selected language, Auto Subtitle Translator uses the gemini-srt-translator Python tool to translate them using Google Gemini AI.
• Optionally, if a video has no subtitles at all, the script can transcribe the audio into a temporary subtitle file, translate that generated subtitle file into your selected language, and clean up temporary files afterward.
• This script runs in the background using a tmux session, allowing it to continue running even after you disconnect from your server.

Features

• Automatic Monitoring: Watches a user-specified media folder, such as ~/media, and its subfolders for new .mkv and .mp4 files.
• Skip Already Translated Videos: Checks whether the video already contains subtitles in your selected target language. If matching subtitles are detected, the video is skipped to reduce duplicate work and unnecessary Gemini API usage.
• Subtitle Translation: Uses the gemini-srt-translator Python package to extract and translate subtitles using Google Gemini AI.
• Optional Audio Transcription Fallback: If a video has no subtitles, the script can optionally transcribe the audio into a temporary subtitle file, translate it, and remove temporary files afterward.
• 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.
• Configurable Gemini Model: The installer allows you to select from supported Gemini models. Model availability, pricing, and limits depend on Google’s current Gemini API offerings and your API key.
• Thinking Level Selection: Where supported, the installer allows you to configure the Gemini model’s thinking level.
• Configurable Parallel Processing: You can choose how many videos are processed at the same time. Lowering this value can help reduce API usage and system load.
• Environment Variable for API Key: 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 or transcription/translation command.
• Easy Installation & Management: A setup script handles installation, uninstallation, updates, API key changes, model settings, transcription settings, and process-limit changes.

Prerequisites

• Python: Python 3.10 or newer is required. See the Python version management guide if needed.
• Gemini API Key: A valid Gemini API key is required. You can create one from Google AI Studio: https://aistudio.google.com/apikey
• Gemini API Usage: Some Gemini models or higher usage levels may require a paid API key or billing-enabled Google account. Free-tier keys may be rate-limited.
• SSH Access: You must connect to your Ultra.cc service via SSH.
• tmux: Used to keep the monitor running in the background.

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 whether to install, manage, uninstall, or reinstall Auto Subtitle Translator.
• Entering your GEMINI_API_KEY.
• Selecting your desired target subtitle language, such as English, Spanish, or Brazilian Portuguese.
• Specifying the media folder to monitor. You can accept the default, such as ~/media, or provide a custom path.
• Choosing whether audio transcription fallback should be enabled.
• Selecting the Gemini model to use.
• Configuring the Gemini thinking level, where available.
• Choosing how many videos can be processed in parallel.
• The installer will then:
• Create the required directory: ~/scripts/auto-subtitle-translator.
• Set up a Python virtual environment inside this directory.
• Install gemini-srt-translator and required Python packages.
• Copy and configure the monitoring script (media_monitor.py) and the tmux runner script (start-auto-subtitle-translator.sh).
• After installation, or after updating your API key, you may need to source your shell configuration file or open a new SSH 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:
• 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.
• media_monitor.py:
• This Python script monitors the configured media directory for supported video files. When a new .mkv or .mp4 file is detected:
• The file is added to the processing queue.
• The script checks whether the file already contains subtitles in your configured target language.
• If matching subtitles already exist, the file is skipped.
• If subtitles exist but are not in the target language, the script uses gemini-srt-translator to translate them.
• If no subtitles exist and audio transcription fallback is enabled, the script transcribes the video audio into a temporary subtitle file.
• The generated subtitle file is translated into your selected target language.
• Temporary transcription files are cleaned up after processing.
• Activity and command output are written to log files.
• The gst command from the gemini-srt-translator package handles the subtitle extraction, transcription, and translation workflow.

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.

Audio Transcription Fallback

• Auto Subtitle Translator can optionally transcribe audio when a video does not contain subtitles.
• When enabled, the script will:
• Detect that no subtitles are available.
• Generate a temporary subtitle file from the video’s audio.
• Translate that subtitle file into your selected target language.
• Clean up temporary files after processing.
• This feature can significantly increase Gemini API usage and processing time, especially for long videos.
• If you are using a free Gemini API key, consider keeping transcription disabled or using a low-cost model where available.

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!

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