Subtitles King

Self-hosting guide

Run the full Subtitles King stack on your own hardware. Useful for privacy, regulated workloads, or unlimited usage.

There are two pieces to the stack:

  1. Upload server (Go) — receives uploads, runs the pipeline, serves downloads.
  2. MCP binary (Go) — the agent-facing front-end. Forwards to the upload server.

You can run either or both. The MCP binary by default talks to our hosted upload server; only run the upload server too if you want a fully air-gapped setup.

System requirements

| Tool | Why | |---|---| | Go 1.22+ | Compile both binaries. | | ffmpeg | Compression and subtitle burn-in. | | Python 3.10+ + openai-whisper | Transcription. | | ~5 GB free disk | Whisper model + temp files. | | GPU optional | Massively speeds up Whisper. |

Tested on Ubuntu 22.04, Debian 12, macOS 14+. Windows works if you can make ffmpeg and Whisper available.

Install (full stack)

1. Clone the repo

git clone https://github.com/kirillzubovsky/subtitlesking-mcp
cd subtitlesking-mcp

The bridge binary and the full upload server now live in the same repo — one clone gives you everything.

2. Install system dependencies

The pipeline needs ffmpeg with libass (for subtitle burn-in) and Python 3 (for the Whisper venv). On macOS the default Homebrew ffmpeg formula no longer ships libass, so use the libass-enabled tap:

# macOS
brew tap homebrew-ffmpeg/ffmpeg
brew install homebrew-ffmpeg/ffmpeg/ffmpeg

# Ubuntu / Debian
sudo apt update
sudo apt install -y ffmpeg python3 python3-venv python3-pip

# Fedora
sudo dnf install -y ffmpeg python3 python3-pip

# Verify libass is present (must print a "subtitles" line):
ffmpeg -filters 2>&1 | grep -E '\bsubtitles\b'

Then the Whisper venv (~5 min, ~5 GB for torch + Whisper weights):

python3 -m venv sk
sk/bin/pip install -r requirements.txt

3. Build the upload server

go build -o subtitlesking .

4. Build the MCP binary

go build -o subtitlesking-mcp ./cmd/mcp-server

5. Run

# Upload server (port 8080)
PORT=8080 ./subtitlesking

# In another shell, point MCP at it
SUBTITLESKING_URL=http://localhost:8080 ./subtitlesking-mcp

Register the local MCP binary with your client (Claude Code, Cursor, etc.) the same way you would the hosted version.

Install (MCP binary only)

If you just want the MCP binary and are happy to talk to our hosted backend (for free-tier usage), grab a prebuilt release from github.com/kirillzubovsky/subtitlesking-mcp/releases:

# macOS Apple Silicon — substitute darwin-amd64, linux-amd64, linux-arm64,
# or windows-amd64 for your platform
curl -L https://github.com/kirillzubovsky/subtitlesking-mcp/releases/latest/download/subtitlesking-mcp-darwin-arm64.tar.gz \
  | tar -xz
sudo mv subtitlesking-mcp /usr/local/bin/

Or build from source (needs Go 1.22+):

git clone https://github.com/kirillzubovsky/subtitlesking-mcp
cd subtitlesking-mcp
go build -o subtitlesking-mcp .

Configuration

Both binaries take config from environment variables.

Upload server

| Variable | Default | Purpose | |---|---|---| | PORT | 8080 | HTTP port. | | ENV | (unset) | If production, generates https:// download URLs. |

The default API key for the upload server's /presign and /downloadpresign endpoints is hard-coded as MY_AWESOME_API_KEY — change it in src/server/main.go before exposing publicly. (Note: this only affects webform/REST clients. The MCP bridge does not use this key — every MCP call is forwarded as-is to /mcp, which mints presigned URLs internally.)

MCP binary

The downloadable binary is a thin JSON-RPC stdio↔HTTP bridge. It does not ship its own tool semantics — every call is forwarded to <SUBTITLESKING_URL>/mcp.

| Variable | Default | Purpose | |---|---|---| | SUBTITLESKING_URL | https://brains.subtitlesking.com | Backend /mcp endpoint to forward to. |

Deployment

Docker

A Dockerfile ships in the repo. Build:

docker build -t subtitlesking .
docker run -p 8080:8080 subtitlesking

systemd

Drop the service file into /etc/systemd/system/subtitlesking.service (template included in the repo) and:

sudo systemctl daemon-reload
sudo systemctl enable subtitlesking
sudo systemctl start subtitlesking

Reverse proxy (nginx + Let's Encrypt)

A sample nginx config is included. Wire up TLS with certbot:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d subtitles.your-domain.com

Storage

Videos and metadata live under files/<videoID>/ next to the upload server binary. The metadata DB is a SQLite file at videos.db. For multi-host deployments, mount a shared volume.

Cleanup

The upload server has a built-in hourly job that removes any video older than 24 hours. Adjust in main.go if you want longer retention.

Next steps