# AI Subtitle Translator
Advanced subtitle translator with AI support and web API. Converts SRT subtitle files to styled ASS format with bilingual or monolingual translations using OpenAI, Google Gemini, or DeepSeek APIs.
## Features
- **Bazarr Integration**: Direct post-processing hook for automatic subtitle translation
- **Web API**: FastAPI-based REST API for subtitle translation
- **CLI Tool**: Command-line interface for batch processing with subcommands
- **Multiple AI Providers**: OpenAI, Google Gemini, DeepSeek support
- **Fallback Providers**: Automatic failover to secondary AI providers when primary fails
- **Translation Validation**: Statistical analysis tool to detect and report sync/quality issues
- **Adaptive Batching**: Smart sentence-boundary detection prevents mid-sentence cuts
- **Bilingual Mode**: Displays original text on top and translated text below
- **Monolingual Mode**: Replaces original text with translation
- **Monolingual Extraction**: Convert existing bilingual files to monolingual without re-translating
- **Smart Translation**: Full text or selective difficulty translation modes
- **Resumable**: Automatically saves progress and can resume if interrupted
- **Batch Processing**: Processes subtitles in batches for efficient API usage
## Quick Start - Bazarr Integration
### 1. Docker Compose Setup
1. **Clone the repository:**
```bash
git clone https://github.com/yanp/ai-subtitle-translator.git
cd ai-subtitle-translator
```
2. **Set up environment variables:**
```bash
cp .env.example .env
# Edit .env and add: DEEPSEEK_API_KEY=your_actual_api_key_here
```
3. **Start the service:**
```bash
docker-compose up -d
```
### 2. Bazarr Hook Configuration
In Bazarr Settings → Subtitles → Custom Post-Processing → Command:
```bash
curl -X POST "http://ai-subtitle-translator:8080/translate" -F input_path="{{subtitles}}";
```
### 3. Integration with Existing Bazarr
If you already have Bazarr running, add the translator to your existing docker-compose:
```yaml
services:
subtitle-translator:
build: .
ports:
- "8000:8080"
environment:
- DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
- PUID=${PUID:-1000}
- PGID=${PGID:-1000}
volumes:
- /path/to/media:/media/subtitles # Same mount as Bazarr
restart: unless-stopped
networks:
- media-network
```
## Alternative Setup Methods
### Local Development
1. **Install uv:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **Install dependencies:**
```bash
uv sync --all-extras
```
3. **Set environment variables:**
```bash
export DEEPSEEK_API_KEY=your_api_key_here
```
4. **Run the API:**
```bash
uv run fastapi dev src/ai_subtitle_translator/app.py
```
### CLI Usage
The CLI uses subcommands for different operations:
**Translation:**
```bash
uv run ai-subtitle-translator translate input.srt [options]
```
**Translation Options:**
- `-o, --output`: Output file path
- `--translation-mode`: `bilingual` or `monolingual`
- `--prompt-template`: `full_text` or `selective_difficulty`
- `-p, --provider`: Primary AI provider (`openai`, `gemini`, `deepseek`)
- `--fallback-provider`: Secondary AI provider for automatic failover
- `--batch-size`: Number of lines per API call (default: adaptive)
**Translation Example:**
```bash
uv run ai-subtitle-translator translate movie.srt \
--translation-mode bilingual \
--provider deepseek \
--fallback-provider openai
```
**Validation:**
```bash
uv run ai-subtitle-translator validate input.ass [options]
```
**Validation Options:**
- `--threshold`: MAD threshold for detecting sync issues (default: 2.0)
- `--detailed`: Show detailed analysis per subtitle line
**Validation Example:**
```bash
uv run ai-subtitle-translator validate movie.en-zh.ass --detailed
```
**Extraction from Bilingual Files:**
```bash
# Extract monolingual subtitles from existing bilingual ASS files
uv run ai-subtitle-translator translate movie.en-zh.ass --extract-monolingual
```
This extracts only the translated text with proper monolingual styling and positioning, perfect when you want monolingual versions without re-translating.
## API Usage
### Configuration
The API is configured through environment variables.
### Translate Subtitle File
**POST** `/translate`
Supports two modes: file upload or file path processing.
#### Mode 1: File Upload (Web Interface)
Upload an SRT file and get back a translated ASS file.
**Parameters:**
- `file`: SRT subtitle file to upload
**Example:**
```bash
curl -X POST "http://localhost:8080/translate" \
-F "file=@subtitle.srt" \
-o translated_subtitle.ass
```
#### Mode 2: File Path (For Bazarr Integration)
Process files on the server filesystem using file paths.
**Parameters:**
- `input_path`: Path to SRT subtitle file on server
- `output_path`: Output path for translated file (optional, defaults to same directory with .en-zh.ass extension)
**Example:**
```bash
curl -X POST "http://localhost:8000/translate" \
-F "input_path=/media/subtitles/movie.srt"
```
**Response:**
```json
{
"success": true,
"message": "✅ Translation completed successfully",
"output_filename": "/media/subtitles/movie.en-zh.ass"
}
```
### Get Available Providers
**GET** `/providers`
Returns available AI providers and their configuration status.
## Configuration
### Environment Variables
#### API Keys (Required)
| Variable | Description | Required |
| ------------------ | ------------------------------ | ------------------- |
| `DEEPSEEK_API_KEY` | DeepSeek API key (recommended) | Yes |
| `OPENAI_API_KEY` | OpenAI API key | For OpenAI provider |
| `GEMINI_API_KEY` | Google Gemini API key | For Gemini provider |
#### API Server Defaults (Optional)
| Variable | Description | Default |
| --------------------------- | ---------------------------------------------------- | --------- |
| `DEFAULT_PROVIDER` | Default AI provider | deepseek |
| `FALLBACK_PROVIDER` | Default fallback provider | None |
| `DEFAULT_MODEL` | Default model name | None |
| `DEFAULT_TRANSLATION_MODE` | Default translation mode | bilingual |
| `DEFAULT_PROMPT_TEMPLATE` | Default prompt template | full_text |
| `DEFAULT_BATCH_SIZE` | Default batch size for API calls | 80 |
#### System Configuration (Optional)
| Variable | Description | Default |
| -------- | ----------------------------- | ------- |
| `PUID` | User ID for file permissions | 1000 |
| `PGID` | Group ID for file permissions | 1000 |
**API Server Configuration Example:**
```bash
# .env file for API server defaults
DEFAULT_PROVIDER=deepseek
FALLBACK_PROVIDER=openai
DEEPSEEK_API_KEY=your_deepseek_key
OPENAI_API_KEY=your_openai_key
```
**Note**: Set PUID/PGID to match your host user to avoid permission issues:
```bash
# Find your user/group IDs
id
# Set in .env file
PUID=1001
PGID=1001
```
### Translation Modes
- **Bilingual**: Shows original text on top, translation below
- **Monolingual**: Replaces original text with translation
### Prompt Templates
- **Full Text**: Translates every subtitle line
- **Selective Difficulty**: Only translates complex phrases, slang, or cultural references
## Development
### Setup
```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync --all-extras --dev
```
### Code Quality
```bash
# Format code
uv run black .
# Lint code
uv run ruff check .
# Type checking
uv run mypy .
```
### Testing
```bash
# Run tests
uv run pytest
# Run with coverage
uv run pytest --cov=src
```
## Health Monitoring
Check service health:
```bash
curl http://localhost:8080/health
```
Check available providers:
```bash
curl http://localhost:8080/providers
```
## Performance
- **Translation Speed**: ~5-30 seconds per file (depends on length)
- **API Costs**: ~$0.001-0.01 per subtitle file with DeepSeek
- **Batch Processing**: Optimized for efficiency
## Limitations
## Docker Build
### Build locally
```bash
docker build -t ai-subtitle-translator .
```
## License
MIT License - see LICENSE file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## Support
- Open an issue on GitHub
- Check the API documentation at `/docs` when running the server
- Review the example files in the repository
Raw data
{
"_id": null,
"home_page": null,
"name": "ai-subtitle-translator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "ai, ass, bazarr, deepseek, gemini, llm, openai, srt, subtitle, translation",
"author": null,
"author_email": "yanp <yanp@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/54/87/f88375fed062fe84926b822ff4dd7d785f3d507476e4e68cab325581135e/ai_subtitle_translator-0.8.0.tar.gz",
"platform": null,
"description": "# AI Subtitle Translator\n\nAdvanced subtitle translator with AI support and web API. Converts SRT subtitle files to styled ASS format with bilingual or monolingual translations using OpenAI, Google Gemini, or DeepSeek APIs.\n\n## Features\n\n- **Bazarr Integration**: Direct post-processing hook for automatic subtitle translation\n- **Web API**: FastAPI-based REST API for subtitle translation\n- **CLI Tool**: Command-line interface for batch processing with subcommands\n- **Multiple AI Providers**: OpenAI, Google Gemini, DeepSeek support\n- **Fallback Providers**: Automatic failover to secondary AI providers when primary fails\n- **Translation Validation**: Statistical analysis tool to detect and report sync/quality issues\n- **Adaptive Batching**: Smart sentence-boundary detection prevents mid-sentence cuts\n- **Bilingual Mode**: Displays original text on top and translated text below\n- **Monolingual Mode**: Replaces original text with translation\n- **Monolingual Extraction**: Convert existing bilingual files to monolingual without re-translating\n- **Smart Translation**: Full text or selective difficulty translation modes\n- **Resumable**: Automatically saves progress and can resume if interrupted\n- **Batch Processing**: Processes subtitles in batches for efficient API usage\n\n## Quick Start - Bazarr Integration\n\n### 1. Docker Compose Setup\n\n1. **Clone the repository:**\n\n ```bash\n git clone https://github.com/yanp/ai-subtitle-translator.git\n cd ai-subtitle-translator\n ```\n\n2. **Set up environment variables:**\n\n ```bash\n cp .env.example .env\n # Edit .env and add: DEEPSEEK_API_KEY=your_actual_api_key_here\n ```\n\n3. **Start the service:**\n ```bash\n docker-compose up -d\n ```\n\n### 2. Bazarr Hook Configuration\n\nIn Bazarr Settings \u2192 Subtitles \u2192 Custom Post-Processing \u2192 Command:\n\n```bash\ncurl -X POST \"http://ai-subtitle-translator:8080/translate\" -F input_path=\"{{subtitles}}\";\n```\n\n### 3. Integration with Existing Bazarr\n\nIf you already have Bazarr running, add the translator to your existing docker-compose:\n\n```yaml\nservices:\n subtitle-translator:\n build: .\n ports:\n - \"8000:8080\"\n environment:\n - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}\n - PUID=${PUID:-1000}\n - PGID=${PGID:-1000}\n volumes:\n - /path/to/media:/media/subtitles # Same mount as Bazarr\n restart: unless-stopped\n networks:\n - media-network\n```\n\n## Alternative Setup Methods\n\n### Local Development\n\n1. **Install uv:**\n\n ```bash\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n2. **Install dependencies:**\n\n ```bash\n uv sync --all-extras\n ```\n\n3. **Set environment variables:**\n\n ```bash\n export DEEPSEEK_API_KEY=your_api_key_here\n ```\n\n4. **Run the API:**\n ```bash\n uv run fastapi dev src/ai_subtitle_translator/app.py\n ```\n\n### CLI Usage\n\nThe CLI uses subcommands for different operations:\n\n**Translation:**\n\n```bash\nuv run ai-subtitle-translator translate input.srt [options]\n```\n\n**Translation Options:**\n\n- `-o, --output`: Output file path\n- `--translation-mode`: `bilingual` or `monolingual`\n- `--prompt-template`: `full_text` or `selective_difficulty`\n- `-p, --provider`: Primary AI provider (`openai`, `gemini`, `deepseek`)\n- `--fallback-provider`: Secondary AI provider for automatic failover\n- `--batch-size`: Number of lines per API call (default: adaptive)\n\n**Translation Example:**\n\n```bash\nuv run ai-subtitle-translator translate movie.srt \\\n --translation-mode bilingual \\\n --provider deepseek \\\n --fallback-provider openai\n```\n\n**Validation:**\n\n```bash\nuv run ai-subtitle-translator validate input.ass [options]\n```\n\n**Validation Options:**\n\n- `--threshold`: MAD threshold for detecting sync issues (default: 2.0)\n- `--detailed`: Show detailed analysis per subtitle line\n\n**Validation Example:**\n\n```bash\nuv run ai-subtitle-translator validate movie.en-zh.ass --detailed\n```\n\n**Extraction from Bilingual Files:**\n\n```bash\n# Extract monolingual subtitles from existing bilingual ASS files\nuv run ai-subtitle-translator translate movie.en-zh.ass --extract-monolingual\n```\n\nThis extracts only the translated text with proper monolingual styling and positioning, perfect when you want monolingual versions without re-translating.\n\n## API Usage\n\n### Configuration\n\nThe API is configured through environment variables.\n\n### Translate Subtitle File\n\n**POST** `/translate`\n\nSupports two modes: file upload or file path processing.\n\n#### Mode 1: File Upload (Web Interface)\n\nUpload an SRT file and get back a translated ASS file.\n\n**Parameters:**\n\n- `file`: SRT subtitle file to upload\n\n**Example:**\n\n```bash\ncurl -X POST \"http://localhost:8080/translate\" \\\n -F \"file=@subtitle.srt\" \\\n -o translated_subtitle.ass\n```\n\n#### Mode 2: File Path (For Bazarr Integration)\n\nProcess files on the server filesystem using file paths.\n\n**Parameters:**\n\n- `input_path`: Path to SRT subtitle file on server\n- `output_path`: Output path for translated file (optional, defaults to same directory with .en-zh.ass extension)\n\n**Example:**\n\n```bash\ncurl -X POST \"http://localhost:8000/translate\" \\\n -F \"input_path=/media/subtitles/movie.srt\"\n```\n\n**Response:**\n\n```json\n{\n \"success\": true,\n \"message\": \"\u2705 Translation completed successfully\",\n \"output_filename\": \"/media/subtitles/movie.en-zh.ass\"\n}\n```\n\n### Get Available Providers\n\n**GET** `/providers`\n\nReturns available AI providers and their configuration status.\n\n## Configuration\n\n### Environment Variables\n\n#### API Keys (Required)\n\n| Variable | Description | Required |\n| ------------------ | ------------------------------ | ------------------- |\n| `DEEPSEEK_API_KEY` | DeepSeek API key (recommended) | Yes |\n| `OPENAI_API_KEY` | OpenAI API key | For OpenAI provider |\n| `GEMINI_API_KEY` | Google Gemini API key | For Gemini provider |\n\n#### API Server Defaults (Optional)\n\n| Variable | Description | Default |\n| --------------------------- | ---------------------------------------------------- | --------- |\n| `DEFAULT_PROVIDER` | Default AI provider | deepseek |\n| `FALLBACK_PROVIDER` | Default fallback provider | None |\n| `DEFAULT_MODEL` | Default model name | None |\n| `DEFAULT_TRANSLATION_MODE` | Default translation mode | bilingual |\n| `DEFAULT_PROMPT_TEMPLATE` | Default prompt template | full_text |\n| `DEFAULT_BATCH_SIZE` | Default batch size for API calls | 80 |\n\n#### System Configuration (Optional)\n\n| Variable | Description | Default |\n| -------- | ----------------------------- | ------- |\n| `PUID` | User ID for file permissions | 1000 |\n| `PGID` | Group ID for file permissions | 1000 |\n\n**API Server Configuration Example:**\n\n```bash\n# .env file for API server defaults\nDEFAULT_PROVIDER=deepseek\nFALLBACK_PROVIDER=openai\nDEEPSEEK_API_KEY=your_deepseek_key\nOPENAI_API_KEY=your_openai_key\n\n```\n\n**Note**: Set PUID/PGID to match your host user to avoid permission issues:\n\n```bash\n# Find your user/group IDs\nid\n\n# Set in .env file\nPUID=1001\nPGID=1001\n```\n\n### Translation Modes\n\n- **Bilingual**: Shows original text on top, translation below\n- **Monolingual**: Replaces original text with translation\n\n### Prompt Templates\n\n- **Full Text**: Translates every subtitle line\n- **Selective Difficulty**: Only translates complex phrases, slang, or cultural references\n\n## Development\n\n### Setup\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install dependencies\nuv sync --all-extras --dev\n```\n\n### Code Quality\n\n```bash\n# Format code\nuv run black .\n\n# Lint code\nuv run ruff check .\n\n# Type checking\nuv run mypy .\n```\n\n### Testing\n\n```bash\n# Run tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=src\n```\n\n## Health Monitoring\n\nCheck service health:\n\n```bash\ncurl http://localhost:8080/health\n```\n\nCheck available providers:\n\n```bash\ncurl http://localhost:8080/providers\n```\n\n## Performance\n\n- **Translation Speed**: ~5-30 seconds per file (depends on length)\n- **API Costs**: ~$0.001-0.01 per subtitle file with DeepSeek\n- **Batch Processing**: Optimized for efficiency\n\n## Limitations\n\n\n## Docker Build\n\n### Build locally\n\n```bash\ndocker build -t ai-subtitle-translator .\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Support\n\n- Open an issue on GitHub\n- Check the API documentation at `/docs` when running the server\n- Review the example files in the repository\n",
"bugtrack_url": null,
"license": null,
"summary": "Advanced subtitle translator with LLM support for converting SRT to bilingual ASS files using OpenAI, Gemini, or DeepSeek APIs",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/yanp/ai-subtitle-translator",
"Issues": "https://github.com/yanp/ai-subtitle-translator/issues",
"Repository": "https://github.com/yanp/ai-subtitle-translator"
},
"split_keywords": [
"ai",
" ass",
" bazarr",
" deepseek",
" gemini",
" llm",
" openai",
" srt",
" subtitle",
" translation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "53abf3a3e4fba61f09d52f3cce14668846eb60c45bebcd2a57f43fab7a2cec5c",
"md5": "71cd6a9d8d90e3f570e64e8d08617dfe",
"sha256": "06d5d988989462edc07413988298f48d540bb4be2309b71d82effc41eb2fd0f0"
},
"downloads": -1,
"filename": "ai_subtitle_translator-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "71cd6a9d8d90e3f570e64e8d08617dfe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 36951,
"upload_time": "2025-09-07T20:27:36",
"upload_time_iso_8601": "2025-09-07T20:27:36.058932Z",
"url": "https://files.pythonhosted.org/packages/53/ab/f3a3e4fba61f09d52f3cce14668846eb60c45bebcd2a57f43fab7a2cec5c/ai_subtitle_translator-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5487f88375fed062fe84926b822ff4dd7d785f3d507476e4e68cab325581135e",
"md5": "e4fd48fd135d11e368dcc0f4c1725ac2",
"sha256": "39d1b286e93fe31928e85f364b22975a23e0f354097ec8cb310d6173f85e3a64"
},
"downloads": -1,
"filename": "ai_subtitle_translator-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "e4fd48fd135d11e368dcc0f4c1725ac2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 89303,
"upload_time": "2025-09-07T20:27:37",
"upload_time_iso_8601": "2025-09-07T20:27:37.547662Z",
"url": "https://files.pythonhosted.org/packages/54/87/f88375fed062fe84926b822ff4dd7d785f3d507476e4e68cab325581135e/ai_subtitle_translator-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 20:27:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yanp",
"github_project": "ai-subtitle-translator",
"github_not_found": true,
"lcname": "ai-subtitle-translator"
}
JSON
