MeBox/README_EN.md

A Go rewrite of MediaStation

Lightweight · Fast · Single Binary · NAS Ready

---

📖 Why  ·  🚀 Quick Start  ·  ✨ Features  ·  🏗️ Layout  ·  ⚙️ Config  ·  🗺️ Roadmap

---

🤔 Why MediaStationGo?

MediaStationGo is a from-scratch Go rewrite of 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

Feature	Description
JWT dual-role auth	admin / user with refresh token support
One-click admin bootstrap	Auto-seeded admin / admin123 on first run
Profile management	Email, avatar, password change
User admin panel	Role promotion / demotion, enable / disable
Audit log	Login, library ops, downloads — all tracked

📚 Library Management

Feature	Description
Library CRUD	movie / tv / anime / music types supported
Recursive scanning	Filesystem walk + ffprobe metadata extraction
Smart filename parsing	Year + season/episode auto-detection
Multi-source scraping	TMDb → TheTVDB → Bangumi chain
HD poster upgrade	Optional Fanart.tv high-res fallback
Image proxy	TMDb / Bangumi / Douban / Fanart with disk cache
TV grouping	Season grouping with episode listing
Live fs watching	fsnotify-powered, 5-second coalesced debounce

🎬 Playback

Feature	Description
Direct streaming	HTTP Range support for instant seeking
HLS on-demand	Per-media ffmpeg job with HW acceleration
External subtitles	.srt / .vtt / .ass / .ssa → real-time WebVTT
Resume playback	Auto-saved every 10s + Continue Watching on home
Favorites & playlists	One-tap toggle / ordered playlists (CRUD)

🌐 PT Site Management

Feature	Description
6 site types	nexusphp · gazelle · unit3d · mteam · discuz · custom_rss
3 auth methods	Cookie / API Key / Auth Header
Site config	Full CRUD + connection test + enable toggle
Cross-site search	One-click search across all configured trackers
Extended config	Extra JSON: UA / RSS URL / timeout / priority / proxy / downloader

🤖 Automation

Feature	Description
Download client	qBittorrent Web UI API (add / list / delete)
RSS subscriptions	Regex filter + GUID dedup + 10-min polling
File organizer	Auto-categorize downloads: move / copy / hardlink / symlink

📊 Operations & Monitoring

Feature	Description
Live events	WebSocket push for scan / scrape / transcode / download / subscribe
Dashboard	CPU / Memory / Disk / Library counts / Goroutines
Task panel	Real-time ffmpeg jobs + qBittorrent torrents
NFO export	Kodi / Jellyfin compatible — single media or whole library
HW acceleration	Software / NVENC / Intel QSV / VAAPI encoder profiles
CI/CD	GitHub Actions + multi-arch GHCR release

🧠 AI & Discovery

Feature	Description
TMDb Discover	Trending / popular rails on homepage
AI smart search	OpenAI-compatible → natural language → structured query
AI recommendations	Personalized picks from your watch history

---

🚀 Quick Start

🐳 Docker (Recommended)

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):

{"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

git clone https://github.com/ShukeBta/MediaStationGo.git
cd MediaStationGo

# Build backend + frontend
make build

# Start the server
./bin/mediastation-go

🛠️ Local Development

# 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

---

🏗️ 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 before submitting.

---

📄 License

GNU General Public License v3.0

⚠️ License activation/validation is handled by a separate server: MediaStationLicenseServer. This project contains no license generation or validation logic.

---

_{Made with ❤️ by MediaStationGo Team}