Lightweight · Fast · Single Binary · NAS Ready
---
📖 Why
·
🚀 Quick Start
·
✨ Features
·
🏗️ Layout
·
⚙️ Config
·
🗺️ Roadmap
---
## 🤔 Why MediaStationGo?
> MediaStationGo is a from-scratch Go rewrite of [MediaStation](https://github.com/ShukeBta/MediaStation) — same full-featured media center experience, radically simpler deployment.
### Original MediaStation
- 🐍 Python / FastAPI + Vue
- 📦 Requires Python runtime & virtualenv
- 🐳 Docker mandatory or complex Python setup
- 📊 Deployment footprint > 500 MB
- 🔧 pip + npm dual build chains
### MediaStationGo ✨
- 🚀 Go 1.25 + React 18
- 📦 **Single static binary** (~30 MB)
- 🐳 Docker optional — runs natively bare-metal
- 🔥 Zero external dependencies (CGO off)
- ⚡ One-command build: `go build`
| Metric | Original | MediaStationGo |
|--------|:---:|:---:|
| Binary size | — | ≈ 30 MB |
| Memory (idle) | ~200 MB | ~30 MB |
| Cold start | ~3s | ~0.3s |
| Deploy steps | 5+ | 1 |
| Frontend (gzip) | ~250 KB | ~83 KB |
---
## ✨ Features
🔐 Authentication & Users
📚 Library Management
🎬 Playback
🌐 PT Site Management
🤖 Automation
📊 Operations & Monitoring
🧠 AI & Discovery
---
## 🚀 Quick Start
### 🐳 Docker (Recommended)
```bash
git clone https://github.com/ShukeBta/MediaStationGo.git
cd MediaStationGo
# Edit docker-compose.yml to mount your media at /media
docker compose up -d
```
> 🌐 The server auto-detects both your **local network IP** and **public IP** on startup (NAS / VPS supported):
> ```json
> {"msg":"server is ready","local":"http://192.168.1.4:8080","public":"http://1.2.3.4:8080"}
> ```
> Log in with `admin` / `admin123`.
### 💻 Bare Metal
| Prerequisite | Version |
|-------------|---------|
| Go | ≥ 1.25 |
| Node.js | ≥ 20 |
| FFmpeg | Any |
```bash
git clone https://github.com/ShukeBta/MediaStationGo.git
cd MediaStationGo
# Build backend + frontend
make build
# Start the server
./bin/mediastation-go
```
### 🛠️ Local Development
```bash
# Terminal 1: Go backend (port 8080, DEBUG mode)
make dev
# Terminal 2: Vite frontend (port 3000, proxies API calls)
make dev-web
```
---
## ⚙️ Configuration
Config precedence: **defaults** < `config.yaml` < `config/*.yaml` < **env vars** (prefix `MEDIASTATION_`)
### Key Environment Variables
| Variable | Default | Purpose |
|----------|---------|---------|
| `MEDIASTATION_APP_PORT` | `8080` | HTTP listen port |
| `MEDIASTATION_APP_DATA_DIR` | `./data` | Data root (DB / cache / JWT) |
| `MEDIASTATION_APP_WEB_DIR` | `./web/dist` | SPA bundle directory |
| `MEDIASTATION_DATABASE_DB_PATH` | `./data/mediastation.db` | SQLite file path |
| `MEDIASTATION_SECRETS_JWT_SECRET` | *(auto)* | JWT signing key |
| `MEDIASTATION_SECRETS_TMDB_API_KEY` | *(empty)* | TMDb scraping (required) |
| `MEDIASTATION_SECRETS_BANGUMI_ACCESS_TOKEN` | *(empty)* | Bangumi rate limit boost |
| `MEDIASTATION_APP_CORS_ORIGINS` | *(empty)* | Allow-list (JSON array) |
| `ADMIN_INITIAL_PASSWORD` | `admin123` | Initial admin password |
### Runtime Settings
Admin panel → Settings tab, stored in the `settings` table:
| Key | Purpose |
|-----|---------|
| `qbittorrent.url` | qBittorrent Web UI URL |
| `qbittorrent.username` | Username |
| `qbittorrent.password` | Password |
| `qbittorrent.savepath` | Default save path (optional) |
> 💡 After editing, hit **Downloads → Reload Config** or `POST /api/downloads/reload`.
📖 Full config template: [`config.example.yaml`](config.example.yaml)
---
## 🏗️ Project Layout
```
MediaStationGo/
├── cmd/server/main.go ← Entry point
├── internal/
│ ├── config/ ← Viper configuration layer
│ ├── database/ ← GORM + SQLite (WAL) bootstrap
│ ├── model/ ← Data models + AutoMigrate registry
│ ├── repository/ ← Data access layer
│ ├── service/ ← Business logic (core)
│ │ ├── auth.go login / register / JWT
│ │ ├── media.go library + media CRUD
│ │ ├── scanner.go filesystem walker + ffprobe
│ │ ├── scraper.go scrape orchestrator + filename cleaner
│ │ ├── tmdb.go / bangumi.go third-party providers
│ │ ├── site.go site CRUD + cross-site search
│ │ ├── site_adapter.go 6 PT site adapters
│ │ ├── stream.go direct play + HLS
│ │ ├── transcoder.go per-media ffmpeg job manager
│ │ ├── subtitle.go external subs → WebVTT
│ │ ├── image_proxy.go cached image proxy
│ │ ├── playback.go history / favorites / playlists
│ │ ├── watcher.go fsnotify debouncer
│ │ ├── qbittorrent.go qBittorrent v2 API client
│ │ ├── downloads.go download orchestrator
│ │ ├── subscription.go RSS poller
│ │ ├── organizer.go media file organizer
│ │ ├── stats.go dashboard snapshot
│ │ ├── profile.go user profile mutations
│ │ ├── audit.go audit log writer
│ │ └── ws_hub.go WebSocket pub/sub broker
│ ├── middleware/ ← JWT / CORS / admin middleware
│ └── handler/ ← HTTP route definitions (by concern)
├── web/ ← React 18 + Vite + Tailwind CSS
│ ├── src/api/ axios service wrappers
│ ├── src/components/ Card / Layout / APIConfigsPanel / etc.
│ ├── src/hooks/ useWebSocket & friends
│ ├── src/pages/ Home · Library · Search · Player · Downloads · Admin · Sites
│ ├── src/stores/ Zustand (auth)
│ └── src/types/ TypeScript domain types
├── Dockerfile ← Multi-stage, multi-arch build
├── docker-compose.yml ← NAS-friendly one-command deploy
├── Makefile ← build / dev / docker / test
├── config.example.yaml ← Full configuration reference
└── .github/workflows/ ← CI + GHCR publish
```
---
## 🗺️ Roadmap
| Feature | Status |
|---------|:---:|
| Jellyfin / Emby compatibility layer | 🔨 In Progress |
| DLNA / Chromecast casting | 📋 Planned |
| Online subtitle search providers | 📋 Planned |
| Multi-bitrate ABR transcode | 📋 Planned |
| STRM direct streaming (WebDAV / Alist / S3) | ✅ Complete |
---
## 🤝 Contributing
Issues and PRs are welcome! Please read the [Contribution Guidelines](CONTRIBUTING.md) before submitting.
---
## 📄 License
[GNU General Public License v3.0](LICENSE)
> ⚠️ License activation/validation is handled by a separate server: [MediaStationLicenseServer](https://github.com/ShukeBta/MediaStationLicenseServer). This project contains no license generation or validation logic.
---
Made with ❤️ by MediaStationGo Team
