AI Sub: AI-Powered Subtitle Generation with Translation
Table of Contents
- Overview
- Showcase
- How It Works
- Installation
- Usage
- Configuration
- Release Notes
- Known Limitations
- Advanced: Re-processing Segments
Overview
AI Sub is a command-line tool that leverages Google's Gemini models to generate high-quality, audio-synchronized subtitles. It is designed to produce dual-language subtitles (Original + English translation) by analyzing both audio and visual cues.
Showcase
Please visit ai-sub-showcase.
How It Works
- Segmentation: Splits the input video into manageable 5-minute segments.
- Re-encoding (Optional): Compresses segments (e.g., 1fps, 360p) to significantly reduce bandwidth usage and upload times without sacrificing AI analysis accuracy.
- Upload (Optional): Uploads segments to the Gemini Files API for cloud-based processing. This bypasses local processing constraints and leverages the API's multimodal capabilities.
- Lyrics Search and Scene Detection (Optional): Detects scenes and performs a web search for official lyrics to improve transcription accuracy for songs.
- Generation: Generates synchronized subtitles and translations by using the audio as the ground truth for timing and visuals for context.
- Assembly: Stitches the generated subtitles back together into a final SRT file (e.g.,
<video_name>.<shortcode>.srtwhere the shortcode combines model code and prompt versions such asvideo.g36f-0918.srt).
Installation
Prerequisites: Python 3.10 or higher.
-
Set up a Python virtual environment:
python -m venv venv source venv/bin/activate # On Windows, use `venv\Scripts\activate.bat`
-
Install AI Sub:
pip install --upgrade ai-sub
Usage
You can use AI Sub a Google AI Studio API Key and an optional langsearch API key for song lyrics web search.
Option 1 (Recommended): Google API Key + Langsearch API Key
This option provides the best quality for the free tier.
- As of 22 July 2026:
- Gemini API provides 20 free requests/day for gemini-3.7-flash
- Gemini API provides 500 free requests/day for gemini-3.5-flash-lite
- Langsearch provides 1000 free request/day for web searches
The limiting factor is the daily free quota for gemini-3.7-flash. You should be able to create subtitles for between 1 hour to 1 hour 40 mins of videos per day.
-
Obtain your API Keys:
-
Sign in to Google AI Studio.
-
Click "Create API Key".
-
Sign in to Langsearch.
-
API Keys -> Create API Key
-
Copy and securely store your keys. Never disclose your API key publicly.
-
-
Run the application:
Linux:
GOOGLE_KEY="YOUR_GOOGLE_API_KEY" LANGSEARCH_KEY="YOUR_LANGSEARCH_API_KEY" FILE_NAME="path/to/your/video.mp4" ai-sub \ --ai.model-lyrics=google-gla:gemini-3.5-flash-lite \ --ai.model-subtitles=google-gla:gemini-3.7-flash \ --ai.search.web-search-tool=langsearch \ --ai.google.key="${GOOGLE_KEY}" \ --ai.search.key="${LANGSEARCH_KEY}" \ "${FILE_NAME}"
Windows:
SET "GOOGLE_KEY=YOUR_GOOGLE_API_KEY" SET "LANGSEARCH_KEY=YOUR_LANGSEARCH_API_KEY" SET "FILE_NAME=path/to/your/video.mp4" ai-sub ^ --ai.model-lyrics=google-gla:gemini-3.5-flash-lite ^ --ai.model-subtitles=google-gla:gemini-3.7-flash ^ --ai.search.web-search-tool=langsearch ^ --ai.google.key="%GOOGLE_KEY%" ^ --ai.search.key="%LANGSEARCH_KEY%" ^ "%FILE_NAME%"
Option 2: Using Google API Key Only
This is the easiest option if you don't want to bother with creating a Langsearch API key. We can use duckduckgo to try to lookup lyrics, but it is not as reliable.
-
Obtain your API Key:
- Sign in to Google AI Studio.
- Click "Create API Key".
- Copy and securely store your key. Never disclose your API key publicly.
-
Run the application:
GOOGLE_KEY="YOUR_GOOGLE_API_KEY" FILE_NAME="path/to/your/video.mp4" ai-sub \ --ai.model-lyrics=google-gla:gemini-3.5-flash-lite \ --ai.model-subtitles=google-gla:gemini-3.7-flash \ --ai.search.web-search-tool=duckduckgo \ --ai.google.key="${GOOGLE_KEY}" \ "${FILE_NAME}"
Windows:
SET "GOOGLE_KEY=YOUR_GOOGLE_API_KEY" SET "FILE_NAME=path/to/your/video.mp4" ai-sub ^ --ai.model-lyrics=google-gla:gemini-3.5-flash-lite ^ --ai.model-subtitles=google-gla:gemini-3.7-flash ^ --ai.search.web-search-tool=duckduckgo ^ --ai.google.key="%GOOGLE_KEY%" ^ "%FILE_NAME%"
Configuration
For a detailed list of all configuration options, including AI models, re-encoding settings, and concurrency controls, please refer to CONFIGURATION.md.
All settings can be configured via command-line arguments (e.g., --ai.model=google-gla:gemini-3.7-flash) or environment variables with the AISUB_ prefix (e.g., AISUB_AI_MODEL=google-gla:gemini-3.7-flash).
Release Notes
For the latest updates and bug fixes, please refer to RELEASE_NOTES.md.
Known Limitations
- Timestamp Accuracy: Subtitle timestamps may occasionally be inaccurate due to limitations of the Gemini AI model. Shorter video segments generally yield better accuracy. Experiment with the
--split.max-secondssetting. - AI Hallucinations: Like all LLMs, Gemini may occasionally produce "hallucinations" or inaccurate information.
If you encounter issues, consider re-processing specific video segments as detailed below.
Advanced: Re-processing Segments
Intermediate files and job states are stored in a temporary directory (default: tmp_<input_file_name>). You can customize this location using the --dir.tmp flag.
The application creates separate state files for each processing stage (e.g., lyrics detection, subtitle generation). To re-process a specific segment, you must delete the state file for the stage you want to re-run.
File naming format: part_XXX.<stage>.<model_shortcode>.yaml
Example: To re-run subtitle generation for the third segment:
- Navigate to the temporary directory.
- Identify the model shortcode used for subtitles (e.g.,
g36fforgemini-3.7-flash). - Delete the corresponding state file (e.g.,
part_002.subtitles.g36f.yaml). - Re-run the script. It will detect the missing subtitle job state and re-process only that segment, using any existing lyrics data.
To re-run the entire pipeline for that segment (including lyrics search), delete both the lyrics and subtitles YAML files for that part.
1 maintainer
Metadata
1 maintainer
Release files for ai-sub 3.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ai_sub-3.6.0.tar.gz | 54.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ai_sub-3.6.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 111.7 kB
Release files / ai_sub-3.6.0.tar.gz
| Download URL | ai_sub-3.6.0.tar.gz |
|---|---|
| Size | 54.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d4bae80a0fe0dc5fcdbe34dbe3f5c163f06620115ab09ae87e645c5fa2fd0b0f
|
|
BLAKE2b-256 checksum How to use checksums |
e9b24d9be09a670b73602b03ee858e0d12c72c405b7914c388b166cf6cb890f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2026.
Transparency logRelease files / ai_sub-3.6.0-py3-none-any.whl
| Download URL | ai_sub-3.6.0-py3-none-any.whl |
|---|---|
| Size | 57.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c75d0ea5cd3ad92e07305e628ab2e7c50262430f73bbf57f789b0def75b162cb
|
|
BLAKE2b-256 checksum How to use checksums |
c53c87a85a6b4b417e76f7a47ddb5a8869a84e447332d676855ad86a7782d811
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2026.
Transparency log
