# Bazarr LLM Translate
Advanced subtitle translator with LLM 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
- **Web API**: FastAPI-based REST API for subtitle translation
- **CLI Tool**: Command-line interface for batch processing
- **Multiple AI Providers**: OpenAI, Google Gemini, DeepSeek support
- **Bilingual Mode**: Displays original text on top and translated text below
- **Monolingual Mode**: Replaces original text with translation
- **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
- **Containerized**: Docker support with multi-platform builds
## Quick Start
### Using Docker (Recommended)
1. **Pull the image:**
```bash
docker pull ghcr.io/yanp/llm-subtitle-translator:latest
```
2. **Run the container:**
```bash
docker run -d \
-p 8080:8080 \
-e DEEPSEEK_API_KEY=your_api_key_here \
ghcr.io/yanp/llm-subtitle-translator:latest
```
3. **Access the API:**
- Web interface: http://localhost:8080/docs
- Health check: http://localhost:8080/health
### Using Docker Compose
1. **Clone the repository:**
```bash
git clone https://github.com/yanp/llm-subtitle-translator.git
cd llm-subtitle-translator
```
2. **Set up environment variables:**
```bash
cp .env.example .env
# Edit .env with your API keys
```
3. **Start the service:**
```bash
docker-compose up -d
```
### Local Development
1. **Install uv:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
2. **Install dependencies:**
```bash
uv venv
uv pip install -e .
```
3. **Set environment variables:**
```bash
export DEEPSEEK_API_KEY=your_api_key_here
```
4. **Run the API:**
```bash
uv run fastapi dev src/llm_subtitle_translator/app.py
```
5. **Or use the CLI:**
```bash
uv run translate-subtitles input.srt --translation-mode bilingual
```
## API Usage
### 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
- `provider`: AI provider (`openai`, `gemini`, `deepseek`) - default: `deepseek`
- `model`: Specific model name (optional)
- `translation_mode`: `bilingual` or `monolingual` - default: `bilingual`
- `prompt_template`: `full_text` or `selective_difficulty` - default: `selective_difficulty`
- `batch_size`: Number of lines per API call - default: `50`
**Example:**
```bash
curl -X POST "http://localhost:8080/translate" \
-F "file=@subtitle.srt" \
-F "provider=deepseek" \
-F "translation_mode=bilingual" \
-F "prompt_template=selective_difficulty" \
-o translated_subtitle.ass
```
#### Mode 2: File Path (Bazarr Hook)
Process files on the server filesystem (ideal for Bazarr hooks).
**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)
- `provider`: AI provider (`openai`, `gemini`, `deepseek`) - default: `deepseek`
- `model`: Specific model name (optional)
- `translation_mode`: `bilingual` or `monolingual` - default: `bilingual`
- `prompt_template`: `full_text` or `selective_difficulty` - default: `selective_difficulty`
- `batch_size`: Number of lines per API call - default: `50`
**Example:**
```bash
curl -X POST "http://localhost:8080/translate" \
-F "input_path=/media/subtitles/movie.srt" \
-F "output_path=/media/subtitles/movie.en-zh.ass" \
-F "provider=deepseek" \
-F "translation_mode=bilingual"
```
### Get Available Providers
**GET** `/providers`
Returns available AI providers and their configuration status.
## CLI Usage
```bash
uv run translate-subtitles input.srt [options]
```
**Options:**
- `-o, --output`: Output file path
- `--translation-mode`: `bilingual` or `monolingual`
- `--prompt-template`: `full_text` or `selective_difficulty`
- `-p, --provider`: AI provider (`openai`, `gemini`, `deepseek`)
- `-m, --model`: Specific model name
- `--batch-size`: Batch size for API calls
**Example:**
```bash
uv run translate-subtitles movie.srt \
--translation-mode bilingual \
--prompt-template selective_difficulty \
--provider deepseek \
--batch-size 50
```
## Configuration
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `OPENAI_API_KEY` | OpenAI API key | For OpenAI provider |
| `GEMINI_API_KEY` | Google Gemini API key | For Gemini provider |
| `DEEPSEEK_API_KEY` | DeepSeek API key | For DeepSeek provider |
### 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 venv
uv pip install -e ".[dev]"
# Activate virtual environment
source .venv/bin/activate
```
### Code Quality
```bash
# Format code
black .
# Lint code
ruff check .
# Type checking
mypy .
```
### Testing
```bash
# Run tests
pytest
# Run with coverage
pytest --cov=.
```
## Docker
### Build locally
```bash
docker build -t llm-subtitle-translator .
```
### Multi-platform build
```bash
docker buildx build --platform linux/amd64,linux/arm64 -t llm-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": "llm-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/d2/c3/9920e96bfb9f4189a8dff8884bdbba7aaa44f4b60cdecd3ace411cb5e1d0/llm_subtitle_translator-0.1.0.tar.gz",
"platform": null,
"description": "# Bazarr LLM Translate\n\nAdvanced subtitle translator with LLM 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- **Web API**: FastAPI-based REST API for subtitle translation\n- **CLI Tool**: Command-line interface for batch processing\n- **Multiple AI Providers**: OpenAI, Google Gemini, DeepSeek support\n- **Bilingual Mode**: Displays original text on top and translated text below\n- **Monolingual Mode**: Replaces original text with translation\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- **Containerized**: Docker support with multi-platform builds\n\n## Quick Start\n\n### Using Docker (Recommended)\n\n1. **Pull the image:**\n ```bash\n docker pull ghcr.io/yanp/llm-subtitle-translator:latest\n ```\n\n2. **Run the container:**\n ```bash\n docker run -d \\\n -p 8080:8080 \\\n -e DEEPSEEK_API_KEY=your_api_key_here \\\n ghcr.io/yanp/llm-subtitle-translator:latest\n ```\n\n3. **Access the API:**\n - Web interface: http://localhost:8080/docs\n - Health check: http://localhost:8080/health\n\n### Using Docker Compose\n\n1. **Clone the repository:**\n ```bash\n git clone https://github.com/yanp/llm-subtitle-translator.git\n cd llm-subtitle-translator\n ```\n\n2. **Set up environment variables:**\n ```bash\n cp .env.example .env\n # Edit .env with your API keys\n ```\n\n3. **Start the service:**\n ```bash\n docker-compose up -d\n ```\n\n### Local Development\n\n1. **Install uv:**\n ```bash\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n2. **Install dependencies:**\n ```bash\n uv venv\n uv pip install -e .\n ```\n\n3. **Set environment variables:**\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/llm_subtitle_translator/app.py\n ```\n\n5. **Or use the CLI:**\n ```bash\n uv run translate-subtitles input.srt --translation-mode bilingual\n ```\n\n## API Usage\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)\nUpload an SRT file and get back a translated ASS file.\n\n**Parameters:**\n- `file`: SRT subtitle file to upload\n- `provider`: AI provider (`openai`, `gemini`, `deepseek`) - default: `deepseek`\n- `model`: Specific model name (optional)\n- `translation_mode`: `bilingual` or `monolingual` - default: `bilingual`\n- `prompt_template`: `full_text` or `selective_difficulty` - default: `selective_difficulty`\n- `batch_size`: Number of lines per API call - default: `50`\n\n**Example:**\n```bash\ncurl -X POST \"http://localhost:8080/translate\" \\\n -F \"file=@subtitle.srt\" \\\n -F \"provider=deepseek\" \\\n -F \"translation_mode=bilingual\" \\\n -F \"prompt_template=selective_difficulty\" \\\n -o translated_subtitle.ass\n```\n\n#### Mode 2: File Path (Bazarr Hook)\nProcess files on the server filesystem (ideal for Bazarr hooks).\n\n**Parameters:**\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- `provider`: AI provider (`openai`, `gemini`, `deepseek`) - default: `deepseek`\n- `model`: Specific model name (optional)\n- `translation_mode`: `bilingual` or `monolingual` - default: `bilingual`\n- `prompt_template`: `full_text` or `selective_difficulty` - default: `selective_difficulty`\n- `batch_size`: Number of lines per API call - default: `50`\n\n**Example:**\n```bash\ncurl -X POST \"http://localhost:8080/translate\" \\\n -F \"input_path=/media/subtitles/movie.srt\" \\\n -F \"output_path=/media/subtitles/movie.en-zh.ass\" \\\n -F \"provider=deepseek\" \\\n -F \"translation_mode=bilingual\"\n```\n\n### Get Available Providers\n\n**GET** `/providers`\n\nReturns available AI providers and their configuration status.\n\n## CLI Usage\n\n```bash\nuv run translate-subtitles input.srt [options]\n```\n\n**Options:**\n- `-o, --output`: Output file path\n- `--translation-mode`: `bilingual` or `monolingual`\n- `--prompt-template`: `full_text` or `selective_difficulty`\n- `-p, --provider`: AI provider (`openai`, `gemini`, `deepseek`)\n- `-m, --model`: Specific model name\n- `--batch-size`: Batch size for API calls\n\n**Example:**\n```bash\nuv run translate-subtitles movie.srt \\\n --translation-mode bilingual \\\n --prompt-template selective_difficulty \\\n --provider deepseek \\\n --batch-size 50\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OPENAI_API_KEY` | OpenAI API key | For OpenAI provider |\n| `GEMINI_API_KEY` | Google Gemini API key | For Gemini provider |\n| `DEEPSEEK_API_KEY` | DeepSeek API key | For DeepSeek provider |\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 venv\nuv pip install -e \".[dev]\"\n\n# Activate virtual environment\nsource .venv/bin/activate\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack .\n\n# Lint code\nruff check .\n\n# Type checking\nmypy .\n```\n\n### Testing\n\n```bash\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=.\n```\n\n## Docker\n\n### Build locally\n\n```bash\ndocker build -t llm-subtitle-translator .\n```\n\n### Multi-platform build\n\n```bash\ndocker buildx build --platform linux/amd64,linux/arm64 -t llm-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",
"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.1.0",
"project_urls": {
"Homepage": "https://github.com/yanp/llm-subtitle-translator",
"Issues": "https://github.com/yanp/llm-subtitle-translator/issues",
"Repository": "https://github.com/yanp/llm-subtitle-translator"
},
"split_keywords": [
"ai",
" ass",
" bazarr",
" deepseek",
" gemini",
" llm",
" openai",
" srt",
" subtitle",
" translation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d83434fc9634fba6104930b7f75c865ed151c0d6dd2e5243cc9231eacaa9ae21",
"md5": "b83bff351ccc802fd955a4518653fd1d",
"sha256": "75f4785064f2ee5f54cae10f398e442fbc2488e3ae3cb2ecd28ded96d30b4877"
},
"downloads": -1,
"filename": "llm_subtitle_translator-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b83bff351ccc802fd955a4518653fd1d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 23895,
"upload_time": "2025-07-24T00:15:35",
"upload_time_iso_8601": "2025-07-24T00:15:35.556672Z",
"url": "https://files.pythonhosted.org/packages/d8/34/34fc9634fba6104930b7f75c865ed151c0d6dd2e5243cc9231eacaa9ae21/llm_subtitle_translator-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d2c39920e96bfb9f4189a8dff8884bdbba7aaa44f4b60cdecd3ace411cb5e1d0",
"md5": "d0eee30d49706152a5ebe16da3f0f03b",
"sha256": "11b784d9cdfa25620467319e9aaa036691e88d613b206e1a79c9055064bc5a91"
},
"downloads": -1,
"filename": "llm_subtitle_translator-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d0eee30d49706152a5ebe16da3f0f03b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 73486,
"upload_time": "2025-07-24T00:15:36",
"upload_time_iso_8601": "2025-07-24T00:15:36.630831Z",
"url": "https://files.pythonhosted.org/packages/d2/c3/9920e96bfb9f4189a8dff8884bdbba7aaa44f4b60cdecd3ace411cb5e1d0/llm_subtitle_translator-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 00:15:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yanp",
"github_project": "llm-subtitle-translator",
"github_not_found": true,
"lcname": "llm-subtitle-translator"
}
JSON
