🦊 SubFox

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

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:

nano .env

Add:

OPENAI_API_KEY=your_api_key_here

---

3. Start SubFox

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:

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:

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 🦊

Maintained by Eddie Nielsen

---

📜 License

GNU GPL v3