<p align="center">
  <img src="app/static/subfox-logo.png" width="600">
</p>

<p align="center">
  Fast, clean subtitle translation for real-world <code>.srt</code> files
</p>


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 🦊**

Maintained by **Eddie Nielsen**

---

## 📜 License

GNU GPL v3
