161 lines
2.4 KiB
Markdown
161 lines
2.4 KiB
Markdown
<p align="center">
|
|
<img src="app/static/subfox-logo.png" width="800">
|
|
</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 🦊](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
|