Subtitle tool

This utility uses Google Gemini to generate subtitles to audio and video files.

Dependencies

ffmpeg needs to be installed for audio extraction.

Process

Extract the audio from the video
Send the audio to Gemini for transcription
Backup the existing subtitle
Save the new subtitle

Dependencies

Export the API key for Gemini to the environment variable GEMINI_API_KEY or specify it in the command line with the flag --api-key.
ffmpeg needs to be installed (brew install ffmpeg, apt-get install ffmpeg or dnf install ffmpeg)
Ensure uv installs its dev dependencies with uv sync --extra dev.

Installation

pip install subtitle-tool

Developing

For local development it is useful to install the binary from the development location into the user's PATH. For this, run the following commands:

uv tool install -e .
uv tool update-shell

Usage

Subtitle files with the defaults:

subtitle-tool video.avi
subtitle-tool audio.mp3

Usage options:

Usage: subtitle-tool [OPTIONS] MEDIAFILE

  Generate subtitles for a media file

Options:
  --api-key TEXT                  Google Gemini API key
  -m, --ai-model TEXT             Gemini model to use  [default:
                                  gemini-2.5-flash]
  -s, --subtitle-path TEXT        Subtitle file name [default: MEDIAFILE.srt]
  -v, --verbose                   Enable debug logging for subtitle_tool
                                  modules
  -d, --debug                     Enable debug logging for all modules
  -k, --keep-temp-files           Do not erase temporary files
  -l, --audio-segment-length INTEGER
                                  Length of audio segments to be subtitled in
                                  seconds  [default: 30]
  -p, --parallel-segments INTEGER
                                  Number of segments subtitled in parallel
                                  [default: 5]
  --help                          Show this message and exit.

Development Status
- 4 - Beta
License
- OSI Approved :: MIT License
Programming Language
- Python :: 3.11

Release files for subtitle-tool 0.1.56

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for subtitle-tool 0.1.56
File	Size	Uploaded
subtitle_tool-0.1.56.tar.gz	50.9 kB	Oct 19, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for subtitle-tool 0.1.56
File	Interpreter	ABI	Platform	Reset
subtitle_tool-0.1.56-py3-none-any.whl 17.8 kB Oct 19, 2025	Python 3	none	any	Details

Total release size: 68.6 kB

Release files / subtitle_tool-0.1.56.tar.gz

Download URL	subtitle_tool-0.1.56.tar.gz
Size	50.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`0e76e6f5d74d85f53587a7ad65fe5c2fb926688eb480bcad7e5c84c609bfa8f4`
BLAKE2b-256 checksum How to use checksums	`9298e5f535ed000c03444216033150f8fd713b8445aeb2d9707d47f4beeb1fb4`
Upload date	Oct 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.4`

Release files / subtitle_tool-0.1.56-py3-none-any.whl

Download URL	subtitle_tool-0.1.56-py3-none-any.whl
Size	17.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`673b9a45a97262a0e19a95f2bc00a18d7b4cf24f9574b7e399c1e5d2eed68a0b`
BLAKE2b-256 checksum How to use checksums	`497614bc3aff6d0fb0fcb8f5347ccb15b85b880da24f06ca05a51fa193e7570a`
Upload date	Oct 19, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.4`