Fast, clean subtitle translation for real-world .srt files
SubFox is a lightweight web app that translates subtitle files using OpenAI — built for speed, simplicity, and real-world usage.
No clutter. No broken formatting. Just clean translations.
---
## ⚡ Features
* 🚀 Parallel translation (very fast)
* 🧠 Smart retry + backoff (stable)
* 💾 Built-in cache (saves time & cost)
* 🎛️ Per-job settings (model, workers, language)
* 📊 Live progress tracking
* 🔽 One-click download
---
## 📦 Quick Start
### 1. Clone the project
```bash
git clone https://git.lanx.dk/ed/subfox.git
cd subfox
```
---
## 🔑 Setup (OpenAI API key)
### 1. Create an API key
1. Go to: https://platform.openai.com/api-keys
2. Click **"Create new secret key"**
3. Copy the key
---
### 2. Add it to SubFox
Create a `.env` file in the project root:
```bash
nano .env
```
Add:
```env
OPENAI_API_KEY=your_api_key_here
```
---
### 3. Start SubFox
```bash
docker compose up --build -d
```
Open in browser:
```
http://localhost:8000
```
---
## 🧠 How it works
1. Upload an `.srt` file
2. Choose translation settings:
* target language
* model
* number of workers
3. SubFox processes the file in parallel
4. Download the translated subtitles
---
## ⚙️ Configuration
You can configure defaults using environment variables:
```env
OPENAI_API_KEY=...
SUBFOX_MODEL=gpt-4o-mini
SUBFOX_WORKERS=4
SUBFOX_MAX_RETRIES=3
SUBFOX_RETRY_BASE_DELAY=1.0
```
---
## 🔒 Security
* Your API key is **never stored or shared**
* Do NOT commit `.env` to Git
Add to `.gitignore`:
```bash
echo ".env" >> .gitignore
```
---
## 📁 Project Structure
```
app/
├── main.py
├── services/
│ └── subtitle_service.py
├── translators/
│ └── fast_engine.py
├── templates/
│ └── index.html
├── static/
│ └── subfox-logo.png
data/
└── output/
```
---
## 🚀 Performance
SubFox uses:
* parallel workers (multi-threaded)
* API request batching (logical)
* caching for repeated lines
Result:
👉 extremely fast subtitle translation
---
## ❤️ Credits
Built with ❤️ for Lanx by [NodeFox 🦊](https://nodefox.lanx.dk)
Maintained by [Eddie Nielsen](https://lanx.dk)
> A system is only as good as the one who understands it.
---
## 📜 License
GNU GPL v3