A small collection of utilities for fixing (time‑shifting) and translating SRT subtitle files.
The tools are deliberately lightweight, command‑line‑first, and can be combined with any LLM that speaks the OpenAI API (including local models).

1. Prerequisites
2. Installation
3. Quick‑Start
   • Time‑shifting a subtitle file
   • Using the GUI wrapper
   • Translating a subtitle file
4. Detailed Usage
   • subtitle_timeshift.py
   • subtitle_timeshift_gui.sh
   • subtitle_mkv2srt.py
   • subtitle_translate.py
5. Configuration & Environment Variables
6. Troubleshooting
7. Contributing
8. License

# Clone the repository
git clone https://github.com/jonsafari/subtitle‑toolkit.git
cd subtitle‑toolkit

# Create a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt   # (see below)

requirements.txt (included in the repo)

openai>=1.0

If you only need the time‑shifting utilities you can skip the openai dependency.

Make the scripts executable:

chmod +x subtitle_timeshift.py subtitle_timeshift_gui.sh subtitle_mkv2srt.py subtitle_translate.py

# Shift every timestamp 2.5 seconds earlier (positive = earlier)
cat original.srt | ./subtitle_timeshift.py --shift-seconds 2.5 > shifted.srt

# Or align the first subtitle to a concrete start time
cat original.srt | ./subtitle_timeshift.py --first-entry-starts-at 00:01:32,945 > aligned.srt

./subtitle_timeshift_gui.sh

For an all-GUI experience, you can edit the file Subtitle_Timeshift.desktop to ensure your correct local path in the Exec line, and then copy it to ~/Desktop. Afterwards you should see an icon on your desktop, which will launch the script above.

sensible-editor Subtitle_Timeshift.desktop
cp Subtitle_Timeshift.desktop ~/Desktop/

The GUI dialogue will:

1. Prompt you to pick a video (optional – just opens it with the default player).
2. Ask for the desired start time of the first subtitle (HH:MM:SS,mmm).
3. Let you select the input SRT file and the output filename.
4. Run subtitle_timeshift.py behind the scenes and write the corrected file.

Note: The GUI only works on systems with zenity and a graphical environment.

# Basic call – uses the default instruction file `subtitle_translate.txt`
./subtitle_translate.py path/to/english.srt

# Custom instruction file, chunk size, output SRT file and API endpoint
./subtitle_translate.py path/to/english.srt \
    --instructions instructions/subtitle_translate_-_en-es_-_Gavin_and_Stacey.txt \
    --output path/to/spanish.srt \
    --api-base http://localhost:8080/v1 \
    --model-id llama3:8b \
    --api-key dummy-key

Behaviour notes

• The script tolerates malformed timestamp lines – they are passed through unchanged.
• If a shift would produce a negative time, the timestamp is clamped to 00:00:00,000.
• The script keeps the original line endings (\n or \r\n).

A thin wrapper that:

1. Uses zenity dialogs to collect:
   • (optional) a video file – opened with the system’s default player (open on macOS, xdg-open on Linux).
   • Desired start time (HH:MM:SS,mmm).
   • Input SRT file.
   • Output filename.
2. Calls subtitle_timeshift.py with --first-entry-starts-at.
3. Writes the result to the chosen output path.

Dependencies

• zenity – graphical dialog utility.
• open (macOS) or xdg-open (Linux) – used to launch the video file.

If you do not need the GUI, just use subtitle_timeshift.py directly.

Extracts subtitles from MKV files and converts them to SRT (SubRip) format.

# Extract all subtitles from an MKV file
./subtitle_mkv2srt.py --input video.mkv

# Extract subtitles in a specific language
./subtitle_mkv2srt.py --input video.mkv --language en

# Extract to a specific output file
./subtitle_mkv2srt.py --input video.mkv --output subtitles.srt

• The script requires ffmpeg to be installed and available in $PATH.
• ASS/SSA formatting tags like {\an7} are automatically removed to ensure compatibility with video players.
• If no subtitles are found in the MKV file, the script will report this and exit.

Large subtitle files (e.g. full‑season SRTs) often exceed the token limits of LLM APIs. This script:

1. Splits the file into units (the classic SRT block: index, timestamps, text, blank line).
2. Chunks a configurable number of units together (default 30).
3. Prepends a user‑provided instruction file (e.g. “You are an expert translator …”).
4. Sends each chunk to an OpenAI‑compatible chat endpoint.
5. Writes the translated output to a new .srt file.

./subtitle_translate.py season01.srt \
    --instructions instructions/subtitle_translate_-_en-es_-_Schitts_Creek.txt \
    --output path/to/spanish.srt \
    --api-base http://localhost:8080/v1 \
    --model-id llama3:8b \
    --api-key dummy-key

• Instruction file – This file is important and provides useful context about the show/movie that you're translating. I recommend copying the Synopsis section of the Wikipedia article for the show/movie that you're translating. The file must be plain text.
• API limits – Adjust --chunk-size if you hit token‑limit errors. Smaller chunks = more requests, larger chunks = fewer requests but higher token usage.
• Model behaviour – The provided instruction files explicitly ask the model not to add extra text, to keep the original formatting, and to translate only the dialogue. If you notice stray commentary, tweak the instruction file accordingly.

The command‑line arguments always take precedence over environment variables.

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b my‑feature).
3. Make your changes, add tests if applicable.
4. Ensure the code follows the existing style (PEP 8, docstrings).
5. Open a Pull Request with a clear description of the change.

Areas where help is especially appreciated

• Adding support for Windows GUI (e.g., PowerShell + Out-GridView).
• Improving error handling for malformed SRT files.
• Providing ready‑made instruction templates for other language pairs.
• Any other subtitle tools or ideas.

This project is released under the GPLv3 License – see the LICENSE file for details.

If you find the toolkit useful, please star the repo or share it. For questions or feature requests, open an issue on GitHub.