# 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/92/98/e5f535ed000c03444216033150f8fd713b8445aeb2d9707d47f4beeb1fb4/subtitle_tool-0.1.56.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.56",
"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": "497614bc3aff6d0fb0fcb8f5347ccb15b85b880da24f06ca05a51fa193e7570a",
"md5": "85dd13124b8ba7116d2b5809820309a5",
"sha256": "673b9a45a97262a0e19a95f2bc00a18d7b4cf24f9574b7e399c1e5d2eed68a0b"
},
"downloads": -1,
"filename": "subtitle_tool-0.1.56-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85dd13124b8ba7116d2b5809820309a5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 17772,
"upload_time": "2025-10-19T11:16:33",
"upload_time_iso_8601": "2025-10-19T11:16:33.601974Z",
"url": "https://files.pythonhosted.org/packages/49/76/14bc3aff6d0fb0fcb8f5347ccb15b85b880da24f06ca05a51fa193e7570a/subtitle_tool-0.1.56-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9298e5f535ed000c03444216033150f8fd713b8445aeb2d9707d47f4beeb1fb4",
"md5": "a7ba13817f5c7ff34917f2c366d0fea6",
"sha256": "0e76e6f5d74d85f53587a7ad65fe5c2fb926688eb480bcad7e5c84c609bfa8f4"
},
"downloads": -1,
"filename": "subtitle_tool-0.1.56.tar.gz",
"has_sig": false,
"md5_digest": "a7ba13817f5c7ff34917f2c366d0fea6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 50867,
"upload_time": "2025-10-19T11:16:34",
"upload_time_iso_8601": "2025-10-19T11:16:34.542874Z",
"url": "https://files.pythonhosted.org/packages/92/98/e5f535ed000c03444216033150f8fd713b8445aeb2d9707d47f4beeb1fb4/subtitle_tool-0.1.56.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 11:16:34",
"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
