A Metadata Correction Transparent Proxy for Koito that intercepts music playback and scrobble requests, applies user-defined metadata correction rules, and forwards the modified requests to the upstream Koito service.
Built with Go and the Gin Web Framework, Koito Proxy acts as a lightweight middleware layer between your music client and Koito.
This project is actively maintained. Internal rule handling and storage mechanisms are still experimental and may change between releases.
Instead of relying on manual fixes or post-scrobble corrections in Koito:
Metadata correction is applied before requests reach the upstream API.
This allows track metadata to be normalized, merged, or rewritten automatically before Koito processes it.
Koito Proxy sits between your music client and Koito:
- Intercepts scrobble API requests
- Applies metadata correction rules in real time
- Normalizes or merges track metadata automatically
- Transparently forwards the modified request upstream
- Returns the upstream response unchanged
- ⚡ Transparent reverse proxy for Koito API traffic
- 🧠 Rule-based metadata transformation engine
- 🔁 Create rules from track merges performed through Koito's Web UI
- 🗄️ SQLite-backed rule storage
- 🐳 Docker-first deployment
- 🚀 Lightweight and resource-efficient
Music Client (e.g. Navidrome)
│
▼
Koito Proxy
│
▼
Upstream Koito API Service
- Go (Golang)
- Gin Web Framework
- SQLite
- GORM
- Docker
- Docker Compose
- Docker
- Docker Compose
mkdir -p koito-proxy
cd koito-proxy
wget https://raw.githubusercontent.com/DarknessKiller/koito_proxy/refs/heads/master/compose.yml
docker compose up -dservices:
koito-proxy:
container_name: koito-proxy
image: ghcr.io/darknesskiller/koito_proxy:latest
environment:
# Required
- KOITO_URL=http://localhost:4110
# Optional
- PROXY_PORT=4112
- PROXY_DB=/app/data/koito_proxy.db
volumes:
- ./data:/app/data
ports:
- "4112:4112"
restart: unless-stopped| Variable | Required | Default | Description |
|---|---|---|---|
KOITO_URL |
Yes | - | URL of the upstream Koito instance that requests will be forwarded to. |
PROXY_PORT |
No | 4112 |
Port the proxy listens on inside the container. |
PROXY_DB |
No | /app/data/koito_proxy.db |
Path to the SQLite database file used for rule storage. |
environment:
- KOITO_URL=http://koito:4110
- PROXY_DB=/app/data/koito_proxy.dbenvironment:
- KOITO_URL=http://koito:4110
- PROXY_PORT=5000
ports:
- "5000:5000"environment:
- KOITO_URL=http://koito:4110
- PROXY_PORT=5000
- PROXY_DB=/app/data/custom.db
ports:
- "5000:5000"- A client sends a scrobble request intended for Koito.
- Koito Proxy intercepts the request.
- Relevant metadata is extracted from the payload.
- The rule engine evaluates and applies matching transformations.
- The modified request is forwarded to the upstream Koito instance.
- The upstream response is returned to the client transparently.
Rules allow metadata to be rewritten before Koito receives it.
Typical use cases include:
- Correcting artist names
- Merging duplicate artists
- Fixing album titles
- Normalizing track metadata
- Handling inconsistent tags from different music sources
All transformations occur before the request reaches Koito.
Koito Proxy stores rule definitions in a SQLite database.
By default:
/app/data/koito_proxy.db
The database location can be customized using the PROXY_DB environment variable.
- Rewrite rule engine
- Replace database layer with GORM
- Implement Rules CRUD API
- Fully transparent proxy behavior
- Deterministic metadata transformations
- Lightweight runtime footprint
- Simple deployment and maintenance
- Minimal configuration requirements