aminnausin

Open Source

mediaServer

<img src="./public/logo.svg" alt="logo" width="100"> <h1 align="center" style="display: block; border: none; padding: 0px;"> MediaServer </h1> #### A self-hosted Media Server built with <a href="https://laravel.com/" target="_blank">Laravel</a>. <img src="https://img.shields.io/badge/vue-v3.5.27-white" alt="Vue"> <img src="https://img.shields.io/badge/laravel-v11.47-F9322C" alt="Laravel"> <img src="https://img.shields.io/github/license/aminnausin/mediaserver?color=purple" alt="License"> <img src="https://sonarcloud.io/api/project_badges/measure?project=aminnausin_mediaServer&metric=ncloc" alt="Lines of Code"> <a href="https://hub.docker.com/r/aminnausin/mediaserver"><img src="https://img.shields.io/docker/pulls/aminnausin/mediaserver?label=pulls&color=white&logo=docker&logoColor=white" alt="Docker Pulls"></a> <img src="https://repo-view-counter.nausin.me/?repo=aminnausin/mediaServer&colour=F9322C&label=views" alt="Repo View Counter"> <img src="https://sonarcloud.io/api/project_badges/measure?project=aminnausin_mediaServer&metric=duplicated_lines_density" alt="Duplicate Lines of Code"> <img src="https://sonarcloud.io/api/project_badges/measure?project=aminnausin_mediaServer&metric=sqale_index" alt="Technical Debt"> <img src="https://sonarcloud.io/api/project_badges/measure?project=aminnausin_mediaServer&metric=code_smells" alt="Code Smells"> <img src="https://sonarcloud.io/api/project_badges/measure?project=aminnausin_mediaServer&metric=reliability_rating" alt="Reliability Rating"> <a href="https://demo.mediaserver.nausin.me"><img src="https://img.shields.io/website?url=https%3A%2F%2Fdemo.mediaserver.nausin.me&up_color=0DA60D&down_color=F9322C&label=demo&link=https%3A%2F%2Fdemo.mediaserver.nausin.me&logo=digitalocean&logoColor=white" alt="Demo Status"></a> <a href="https://github.com/aminnausin/mediaServer/releases"><img src="https://img.shields.io/github/v/release/aminnausin/mediaserver?logo=github&label=latest" alt="Latest Version"></a>   <a href="#features">Core Features</a> • <a href="#demo">Demo</a> • <a href="#getting-started">Getting Started</a> • <a href="#similar-projects">Similar Projects</a>  ## Overview **MediaServer** is a lightweight, self-hosted media player for your home server (or NAS). It scans your folders, indexes your video and audio files, and serves them through a fast, minimalist web interface. It was built for people who prefer a YouTube-like browsing experience for their collection of media files with metadata customisation. ## How it differs from Jellyfin Jellyfin is designed primarily for commercial media, is metadata-first and works great for large automatically downloaded libraries. MediaServer is naturally folder-oriented and great for mixed, personal, or highly customised libraries. Both can serve shows, movies, and music but with different approaches. | Feature | Jellyfin | MediaServer | |---------|----------|-------------| | **Content Focus** | Official metadata-first; built for movies/TV/Music | Folder-first; great for mixed/personal content and TV shows / music | | **Watch History** | Only resume + watched flag | Full watch history with timestamps, re-watch counts, total view counts, per-user history, and playback heatmaps | | **Player Experience** | Fullscreen; no browsing while playing | YouTube-style; browse folders while watching | | **Libraries** | Unified global search | Library-scoped and account based access control | | **Sharing** | No shareable URLs for videos/folders/shows | Direct and readable folder/video links with rich [open graph previews](#%EF%B8%8F-open-graph-preview-example) |    ## Features ### Core Features - Fully custom-built media player (no native browser controls) - Folder-based browsing & sharing - Watch history, view counts and playback analytics - Subtitle support (VTT) with auto-extraction from embedded and external SRT / ASS - Music support with embedded cover art detection - Music player with lyrics viewer/editor based on LrcLib - Editable metadata for videos, folders, and albums - Docker-based deployment with automatic releases - Server dashboard for library management and background task queue - Open Graph preview generator (Anilist-style) - Fully responsive UI with Dark/Light mode <details> <summary>Extended Features</summary> #### 🖥️ Media Player - Custom UI with Keyboard Shortcuts: - `k`: Play/Pause - `j` / `←`: Rewind 10s - `l` / `→`: Fast Forward 10s - `SHIFT+N`: Play Next - `SHIFT+P`: Play Previous - `m`: Mute - `f`: Toggle Fullscreen - `t`: Toggle Theatre Mode - `c`: Toggle Lyrics / Default Subtitle Track - `p`: Toggle playlist (autoplay) - Playback Features: - Speed Controls - Player Statistics - Ambient Background Effect - User Playback Activty Graph - Auto-Scrolling Lyrics Viewer - Media Session API Integration - Skip Intro (manual detection) - Watch Party UI Demo *(coming soon)* #### 🔗 Sharing - Share individual videos or folders via URL (`/library/folder?video={id}` or `/library/{folder-name}`) #### 🗃️ Metadata - **Video Metadata**: - Thumbnail - Description - Tags - Season/Episode - Release Dates - Captions - **Music Metadata**: - Cover - Description - Tags - Disk/Track - Release Dates - Lyrics - Artist - Album - **Folder Metadata**: - Thumbnail - Description - Studio - Release Dates - **Persistent Metadata Mapping**: - Retains info even if file is moved or renamed when metadata tagging is enabled #### 📈 History & Stats - Track view counts (per user and total) - Filterable watch history - Future: playback frequency analytics #### 💬 Subtitles & Captions - Automatic extraction of embedded subtitles (SRT / ASS → VTT) - Manual extraction of external subtitles next to media (in format ```/media/library/folder/{filename}.{lang}.{extension}```) - Subtitle size controls in player #### 🛠️ Server Dashboard - Scanning Job Manager - Library / Folder Manager - User Manager - Server Performance Metrics #### 🖼️ Open Graph Image Previews MediaServer automatically generates [Open Graph](https://ogp.me/) images for media and folders, styled similarly to platforms like [AniList](https://anilist.co). These previews are embedded when sharing links on platforms like: - Discord - Twitter / X - Reddit - Facebook - Telegram Each image includes: - 📸 Thumbnail from the media or folder - 🎞️ Title, studio, description and metadata (e.g. season, tags, release date) - 🎨 Custom layout designed to look clean and modern The preview is rendered server-side using **Browsershot** and cached for performance. > Example: > Sharing `https://yourserver.com/library/show` will show a rich preview card with folder art and metadata. --- ✅ Works even on private, self-hosted domains as long as your Open Graph routes are accessible. </details> ### Roadmap See [ROADMAP.md](./doc/ROADMAP.md) for planned features, ongoing improvements, and known bugs. ## Demo > [!NOTE] > The demo is running the latest beta image with static media. User accounts and edits are reset automatically every 15 minutes. [![Current Beta](https://img.shields.io/github/v/release/aminnausin/mediaserver?include_prereleases&display_name=tag&label=latest%20beta)](https://github.com/aminnausin/mediaServer/releases) - 🚀 [Live Demo](https://demo.mediaserver.nausin.me) - 📦 [Docker Image](https://hub.docker.com/r/aminnausin/mediaserver) ### What to look for Take some time to explore the demo: - Browse through the available folders on the right in the sidebar - Interact with the player to see custom features - Hover over the timeline to see playback activity on each video - Login with the demo account to see the dashboard, server activity and library manager - Watch the default video on the demo to get a step by step installation guide. Below are screenshots of the current webpage on Desktop and Android.        ### Desktop Browser View <img src="https://github.com/user-attachments/assets/c163a27d-0c14-47e8-bb5e-cda06a9c635c" width="700" alt="Desktop Home View" />  ### Android Browser View  <img src="https://github.com/user-attachments/assets/083daf6b-b4c0-49f8-823b-228a32060e7b" width="250" alt="Android Dark Mode" />   <img src="https://github.com/user-attachments/assets/e010eec1-7aef-40ab-ab1b-4c1054a83e1b" width="250" alt="Android Light Mode" /> ### Open Graph Preview Example <img src="https://github.com/user-attachments/assets/2b4ebe41-c515-41c9-a76e-0fcd5db3d2f6" width="700" alt=Open Graph Preview> <details> <summary>Other Pages</summary> ### Music Player  <img src="https://github.com/user-attachments/assets/54deff73-3d34-45e0-bc38-ef88ef2a93d7" width="700" alt="Music Player" /> ### Lyrics Editor <img src="https://github.com/user-attachments/assets/b3e626cd-7664-4980-8ea1-323c1acbcf42" height="600" alt="Lyrics Editor" /> ### Lyrics Viewer <img src="https://github.com/user-attachments/assets/4183b000-cd35-40f4-853f-57c1e66339ae" width="700" alt="Lyrics Viewer Dark" /> <img src="https://github.com/user-attachments/assets/61099fa4-f009-4e5f-bb78-e2ed42ea6a9c" width="700" alt="Lyrics Viewer Light" /> ### Player Options  <img src="https://github.com/user-attachments/assets/6ca6378a-ad38-47f0-851f-c95d70aed984" width="700" alt="Player Option 1" /> <img src="https://github.com/user-attachments/assets/05a2e4fd-e1c4-4fce-baed-31c850315a4c" width="700" alt="Player Option 2" /> ### Setup Page <img src="https://github.com/user-attachments/assets/6953e236-e93d-45a4-b044-12f973781730" width="700" alt="Setup Page" /> ### Analytics  <img src="https://github.com/user-attachments/assets/2d3984bb-6512-4c0c-a304-6619393e1ed3" width="700" alt="Analytics Dashboard" /> ### Library Management  <img src="https://github.com/user-attachments/assets/dd4888a2-2003-4183-8cae-2a45d78dd115" width="700" alt="Library Manager" /> ### User Management  <img src="https://github.com/user-attachments/assets/d1195561-dcae-4dad-bfa4-18f9bfee7aea" width="700" alt="User Manager" /> ### Task Dashboard  <img src="https://github.com/user-attachments/assets/f73f27de-6035-46e6-a67d-f892e6bba67d" width="700" alt="Task Dashboard" /> ### Site Preferences <img src="https://github.com/user-attachments/assets/91d2a538-ede4-4ab9-9e06-06dfa0ca2d3a" width="700" alt="Site Preferences" /> ### User Account Settings <img src="https://github.com/user-attachments/assets/bd7b210b-2737-4101-bf27-3549a381526d" width="700" alt="User Account Settings" /> </details> ## Getting Started [![Current Build](https://img.shields.io/github/v/release/aminnausin/mediaserver?logo=github&label=latest)](https://github.com/aminnausin/mediaServer/releases) MediaServer can be run via Docker (recommended) or a standard manual installation. ### 🐳 Docker Installation (Recommended) > [!WARNING] > Use the beta image to get the latest features. 1. Download the latest or beta **Docker release ZIP** for your platform. - It includes a `docker-compose.yaml` file that automatically sets up the (latest by default) [required images](https://hub.docker.com/r/aminnausin/mediaserver). 2. Unzip it to a folder with generous **read/write/execute** permissions. - The server will perform the following in this directory: - Rewrite your media with embedded UUID's for tracking (ffmpeg copy codec). - Read and write extracted album art and thumbnails from music and videos. - Read and write generated preview images. - Read and write Laravel + NGINX logs. - Permissions must stay consistent in this folder to prevent server errors. - The container uses the UID and GID 9999 under www-data. 3. Run the startup script (with Docker running) and let it create/copy the required files: - Windows: `startDocker.bat` - Linux/macOS: `sudo bash startDocker.sh` 4. Visit [`https://app.test`](https://app.test) in your browser and follow the setup wizard. - You will need to add app.test to your hosts file if you don't have a real url or set your APP_HOST to localhost manually. - There is a powershell script included to do this automatically. - On Linux, you are given the command. 5. Add your media to `./data/media/LIBRARY/FOLDER/VIDEO.MP4` - Media must be grouped by a folder (library) and subfolder (folder) in order to show up on the website - There are certain names that you cannot use for folders or videos such as - profile - settings - history - dashboard - log-viewer - pulse - horizon - __debug - api - ... - `More to come...` ### ⚙️ Manual Installation > [!WARNING] > This setup is probably outdated and may need some tinkering to get right. I have since moved to docker for production installations but still use this method on my main instance (Linux). To set up MediaServer without Docker, you’ll need: - A web server: [Caddy](https://caddyserver.com/) or [NGINX](https://nginx.org/en) - Backend: [PHP 8.3+](https://www.php.net/), [PostgreSQL](https://www.postgresql.org/) - Frontend (for compiling only): [Node.js](https://nodejs.org/en) with [Vue 3](https://vuejs.org/) + [Tailwind CSS](https://tailwindcss.com/) - Media tools: [FFmpeg](https://www.ffmpeg.org/) *(required)*, [ExifTool](https://exiftool.org/) *(optional)* - HTTPS: A valid SSL certificate is required to enable certain metadata features > [!TIP] > You can use [Laragon](https://laragon.org/) to simplify local setup. This will only be available on the host machine. ```bash # 1. Clone the repository git clone https://github.com/aminnausin/mediaServer.git cd mediaServer # 2. Install backend dependencies composer install # 3. Install frontend dependencies npm install # 4. Set up your database and .env cp .env.example .env # Edit the .env file with your PostgreSQL DB info # Example: # DB_CONNECTION=pgsql # DB_HOST=127.0.0.1 # DB_PORT=5432 # DB_DATABASE=mediaServer # DB_USERNAME=postgres # DB_PASSWORD= # 5. Generate Laravel app and reverb keys php artisan key:generate php artisan reverb:generate # 6. Run database migrations php artisan migrate # 7. Link storage (for thumbnails, posters, etc.) php artisan storage:link # 9. Build frontend assets npm run build # 9. Set app domain in .env (required for Sanctum & WebSockets) (6001 for reverb) # Example: # APP_URL=https://app.test:8080 # SANCTUM_STATEFUL_DOMAINS=app.test:8080,0.0.0.0:6001,app.test:6001 # SESSION_DOMAIN=app.test # REVERB_HOST=app.test # 10. Run the app in development mode npm run vite:php ``` ## 📚 Additional Documentation - [Operations Guide](doc/OPERATIONS.md) – Symbolic linking, scanning, metadata jobs, supported formats ## Activity ![Repobeats Analytics](https://repobeats.axiom.co/api/embed/fece6050fc62da0ebd2d200f904abaa3d09900dd.svg) <a href="https://www.star-history.com/#aminnausin/mediaserver&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=aminnausin/mediaserver&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=aminnausin/mediaserver&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=aminnausin/mediaserver&type=Date" /> </picture> </a> ## Similar Projects [![jellyfin](https://jellyfin.org/images/logo.svg)](https://github.com/jellyfin/jellyfin) ## Services Used [![SonarQube Cloud](https://sonarcloud.io/images/project_badges/sonarcloud-dark.svg)](https://sonarcloud.io/summary/new_code?id=aminnausin_mediaServer) ## Disclaimer MediaServer is intended for personal use only. It is designed to help users organise and access **their own legally obtained media** on a self-hosted server. This project **does not condone or support piracy**, and I do not encourage the use of MediaServer for unauthorised distribution or consumption of copyrighted material. Please respect local laws and content ownership rights when using this software.

Video Streaming & Transcoding

73 Github Stars

Software by aminnausin

mediaServer