SubFox 🦊

🎬 Intelligent subtitle translation with disk cache & batching

SubFox translates subtitle files efficiently using batching and a persistent disk cache — reducing API calls and improving performance.

---

🚀 Version

Current version: 0.1.0

---

⚡ Features

• 🔁 Batch translation (packed subtitles)
• 💾 Disk cache (persistent across restarts)
• ⚡ Reduced API usage via caching
• 🧠 Smart fallback per subtitle line
• 🐳 Docker-based deployment
• 📡 API-driven translation flow
• 📊 Progress tracking support

---

⚡ Quick Start

1. Clone project

git clone https://git.lanx.dk/ed/subfox.git
cd subfox

---

2. Setup environment

Create .env:

OPENAI_API_KEY=your_api_key_here

---

3. Start with Docker

docker compose up -d --build

---

4. Open in browser

http://localhost:8000

---

🧠 How it Works

Upload SRT
   ↓
Parse blocks
   ↓
Batch translation (packed)
   ↓
Cache lookup
   ↓
OpenAI (if needed)
   ↓
Fallback per-line (if mismatch)
   ↓
Return translated subtitles

---

💾 Cache System

SubFox uses a disk-based cache:

• Stored in /data/cache
• Persisted via Docker volume
• One file per translation (hashed key)

Example:

/data/cache/en_da/
├── a1b2c3d4.json
├── f6g7h8i9.json

---

🐳 Docker Configuration

Example volume setup:

volumes:
  - ./uploads:/app/uploads
  - ./outputs:/app/outputs
  - /mnt/user/appdata/subfox/cache:/data/cache

---

📡 API

Version endpoint

GET /version

Response:

{
  "version": "0.1.0"
}

---

📜 Changelog

See CHANGELOG.md

---

🛠 Tech Stack

• Python 3.11
• FastAPI
• OpenAI API
• Docker
• JSON-based disk cache

---

❤️ Credits

Built with ❤️ for Lanx by NodeFox 🦊 Maintained by Eddie Nielsen

Learn. Adopt. Survive. Share.