# Subtitle tool
[](https://codecov.io/gh/jeduardo/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
1. Extract the audio from the video
2. Send the audio to Gemini for transcription
3. Backup the existing subtitle
4. 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
```shell
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:
```shell
uv tool install -e .
uv tool update-shell
```
## Usage
- Subtitle files with the defaults:
```shell
subtitle-tool video.avi
subtitle-tool audio.mp3
```
- Usage options:
```text
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.
```
Raw data
{
"_id": null,
"home_page": null,
"name": "subtitle-tool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "ai, audio, cli, gemini, google-gemini, srt, subtitles, video",
"author": null,
"author_email": "\"J. Eduardo\" <contact@jeduardo.com>",
"download_url": "https://files.pythonhosted.org/packages/6c/27/2314f8a979faa53798cb52493917f10d83ac0b8c5eade1f648e50c916f81/subtitle_tool-0.1.54.tar.gz",
"platform": null,
"description": "# Subtitle tool\n\n[](https://codecov.io/gh/jeduardo/subtitle-tool)\n\nThis utility uses Google Gemini to generate subtitles to audio and video files.\n\n## Dependencies\n\n`ffmpeg` needs to be installed for audio extraction.\n\n## Process\n\n1. Extract the audio from the video\n2. Send the audio to Gemini for transcription\n3. Backup the existing subtitle\n4. Save the new subtitle\n\n## Dependencies\n\n- Export the API key for Gemini to the environment variable `GEMINI_API_KEY`\n **or** specify it in the command line with the flag `--api-key`.\n\n- `ffmpeg` needs to be installed (`brew install ffmpeg`, `apt-get install ffmpeg` or `dnf install ffmpeg`)\n\n- Ensure `uv` installs its dev dependencies with `uv sync --extra dev`.\n\n## Installation\n\n```shell\npip install subtitle-tool\n```\n\n## Developing\n\nFor local development it is useful to install the binary from the development\nlocation into the user's `PATH`. For this, run the following commands:\n\n```shell\nuv tool install -e .\nuv tool update-shell\n```\n\n## Usage\n\n- Subtitle files with the defaults:\n\n```shell\nsubtitle-tool video.avi\nsubtitle-tool audio.mp3\n```\n\n- Usage options:\n\n```text\nUsage: subtitle-tool [OPTIONS] MEDIAFILE\n\n Generate subtitles for a media file\n\nOptions:\n --api-key TEXT Google Gemini API key\n -m, --ai-model TEXT Gemini model to use [default:\n gemini-2.5-flash]\n -s, --subtitle-path TEXT Subtitle file name [default: MEDIAFILE.srt]\n -v, --verbose Enable debug logging for subtitle_tool\n modules\n -d, --debug Enable debug logging for all modules\n -k, --keep-temp-files Do not erase temporary files\n -l, --audio-segment-length INTEGER\n Length of audio segments to be subtitled in\n seconds [default: 30]\n -p, --parallel-segments INTEGER\n Number of segments subtitled in parallel\n [default: 5]\n --help Show this message and exit.\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool for generating subtitles using Google Gemini models.",
"version": "0.1.54",
"project_urls": {
"Homepage": "https://github.com/jeduardo/subtitle-tool",
"Issues": "https://github.com/jeduardo/subtitle-tool/issues",
"Repository": "https://github.com/jeduardo/subtitle-tool.git"
},
"split_keywords": [
"ai",
" audio",
" cli",
" gemini",
" google-gemini",
" srt",
" subtitles",
" video"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fe93ccf60efdb3bd10750abb64595261c3bcda830becf34f207381ae4b3c197d",
"md5": "5bae851144b21f7153fa57c9eab151e4",
"sha256": "a23f868c2d118b3388ba5dfd7b35e2d67c93f79fe3d6d36de5ae159072171fce"
},
"downloads": -1,
"filename": "subtitle_tool-0.1.54-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5bae851144b21f7153fa57c9eab151e4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 17774,
"upload_time": "2025-08-08T13:22:09",
"upload_time_iso_8601": "2025-08-08T13:22:09.932450Z",
"url": "https://files.pythonhosted.org/packages/fe/93/ccf60efdb3bd10750abb64595261c3bcda830becf34f207381ae4b3c197d/subtitle_tool-0.1.54-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6c272314f8a979faa53798cb52493917f10d83ac0b8c5eade1f648e50c916f81",
"md5": "8e443a97a894267fe1ca5f7ff656bd77",
"sha256": "6b199aba8ba5a0945c569d4ff7f1b154c350b1c0cd90f86a089e13ded85540ec"
},
"downloads": -1,
"filename": "subtitle_tool-0.1.54.tar.gz",
"has_sig": false,
"md5_digest": "8e443a97a894267fe1ca5f7ff656bd77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 50513,
"upload_time": "2025-08-08T13:22:10",
"upload_time_iso_8601": "2025-08-08T13:22:10.765252Z",
"url": "https://files.pythonhosted.org/packages/6c/27/2314f8a979faa53798cb52493917f10d83ac0b8c5eade1f648e50c916f81/subtitle_tool-0.1.54.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 13:22:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeduardo",
"github_project": "subtitle-tool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "subtitle-tool"
}
JSON
