Skip to content

A self-hosted media server and file management system

feat: updated readme and operation instructions

aminnausinc9d633ebf2b0
diff --git a/README.md b/README.md
index 8fdf1bd6..12beadbf 100755
--- a/README.md
+++ b/README.md
@@ -32,92 +32,134 @@
## Overview
-This is a fast and easily accessible all in one media player for your home server.
-It automatically scans and indexes your videos and serves them in a minimalistic and easy to use interface.
+**MediaServer** is a lightweight self-hosted media player designed for your home server. It automatically scans and indexes your video and audio libraries and presents it through a modern, minimalist web interface.
-The main benefit is that you host content yourself and thus control the speed at which videos can load. No more buffering !
-Extra features include watch history, ambient mode, editable video metadata and online file management.
+Unlike traditional video platforms, MediaServer gives you full control over where and how your content is served β€” with no buffering and no third-party limitations.
+
+Major features include watch history, music player with lyrics support, extensive metadata and online file management.
## Features
### Key Features
-- Minimalist UI
-- Custom Media Player
-- Video and Folder Sharing
-- Watch History Tracking
-- Customisable Metadata
-- Dark/Light mode
-- Server Dashboard
+- πŸŽ₯ Custom Media Player
+- πŸ“ Video and Folder Sharing
+- 🧠 Watch History & View Counts
+- πŸ“ Editable Metadata for Videos, Music & Folders
+- πŸŒ— Dark / Light Mode Toggle
+- 🎡 Lyrics Viewer and Editor with LrcLib
+- πŸ“Š Server Dashboard
+- 🎧 Music Support with Embedded Cover Art Detection
+- πŸ–ΌοΈ Open Graph Preview Generator (Anilist-style thumbnails for link sharing)
<details>
<summary>Extended Features</summary>
-- Minimalist UI
-- Custom Media Player
- - Custom UI
- - Music Support (with cover art)
- - Keybinds
- - k (play/pause)
- - j / LeftArrow (rewind 10s)
- - l / rightArrow (fast forward 10s)
- - SHIFT+N (play next)
- - SHIFT+P (play previous)
- - m (mute/unmute)
- - f (full screen/exit full screen)
+#### πŸ–₯️ Media Player
+
+- Custom UI with Keyboard Shortcuts:
+ - `k`: Play/Pause
+ - `j` / `←`: Rewind 10s
+ - `l` / `β†’`: Fast Forward 10s
+ - `SHIFT+N`: Next
+ - `SHIFT+P`: Previous
+ - `m`: Mute
+ - `f`: Toggle Fullscreen
+ - `l`: Toggle Lyrics / Captions
+- Playback Features:
- Speed Controls
- Player Statistics
- - Ambient Background
- - Provides ambient backlight based on video content in darkmode
- - Can be disabled
- - Video Playback Heatmap
- - Shows up after 5 seeks to any point in a video
- - Ranges from 1 to 25 at any 100th point in the video
- - Can be disabled
- - Watch Party UI Demo (upcoming)
-- Video and Folder Sharing
- - With video id or folder name in the URL
-- Customisable Video Metadata
+ - Ambient Background (toggleable)
+ - Heatmap Visualization (after 5+ seeks)
+ - Watch Party IU Demo *(coming soon)*
+
+#### πŸ”— Sharing
+
+- Share individual videos or folders via URL (`/library/folder?video={id}` or `/library/{folder-name}`)
+
+#### πŸ—ƒοΈ Metadata
+
+- **Video Metadata**:
- Thumbnail
- Description
- - Episode / Season number
+ - Tags
+ - Season/Episode
- Release Dates
+ - Captions
+- **Music Metadata**:
+ - Cover
+ - Description
- Tags
-- Customisable Folder Metadata
+ - Track/Disk
+ - Release Dates
+ - Lyrics
+ - Artist
+ - Album
+- **Folder Metadata**:
- Thumbnail
- Description
- - Release Dates
- Studio
-- Watch History Tracking
- - Can filter history by any video or folder attribute
-- View Counts
- - See how many times you have viewed a video vs everybody else
-- Persistent Metadata
- - Moved or reuploaded videos will be matched with pre-existing metadata
-- Dark/Light mode
-- Server Dashboard
- - Index process manager
- - Library Manager
- - Folder Manager
- - User Manager
- - Server Statistics
- </details>
-
-### Features to add
-
-- Video playback statistics
- - Most Played in the last X days
- - Your favourite video / folder / category
- - Avg time / count watched per day / week / month
-- Timed video comments (like on soundcloud)
-- Uploadable images (With supabase or local storage based on admin preference)
-- User profiles
-- User friends system
-- Synchronised playback with a user party system
-- User access levels (Admin, Contributor, General)
-- Automatic scrubbing of metadata with admin selected source API
-- Embedded Music Lyrics
-- Captions
+ - Release Dates
+- Persistent Metadata Mapping:
+ - Retains info even if file is moved or renamed
+
+#### πŸ“ˆ History & Stats
+
+- Track view counts (per user and total)
+- Filterable watch history
+- Future: playback frequency analytics
+
+#### πŸ› οΈ 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>
+
+### Planned Features
+
+- πŸ“Š Advanced Playback Stats
+ - Most Played (daily, weekly, monthly)
+ - Personal Favorites
+ - Average watch time over time
+- πŸ’¬ Timed Comments (like SoundCloud)
+- πŸ–ΌοΈ Uploadable Images (For profiles, thumbnails, etc)
+- πŸ‘€ User Profiles & Friends System
+- πŸŽ‰ Live Sync Playback (Parties)
+- πŸ” User Roles (Admin / Contributor / Viewer)
+- 🌐 Metadata Auto-Scraper from APIs
+- πŸ“ Captions/Subtitles Support
+
+</details>
## Demo
@@ -135,146 +177,167 @@ Below are screenshots of the current webpage on Desktop and Android.
<!-- ![image](https://github.com/user-attachments/assets/37313603-68b2-46f4-8190-5a0a692acecf)
![image](https://github.com/user-attachments/assets/b7a10430-d98c-4d5c-9a8f-a550434eb9c1) -->
-![image](https://github.com/user-attachments/assets/b0b33874-6643-47e7-bcbd-4c16bcfa3f50)
+### πŸ–₯️ Desktop View
+
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/b0b33874-6643-47e7-bcbd-4c16bcfa3f50" width="700" alt="Desktop Home View" />
+</p>
<!--
![Dark](https://github.com/user-attachments/assets/8813ac95-3874-44a5-b1e2-5fc7ef73e768)
![Light](https://github.com/user-attachments/assets/2da8c1ce-41f4-4462-afdb-bf9bc5856db8) -->
-<p align="center">
-Android
-</p>
+### πŸ“± Android View
-<p align="center">
- <img src="https://github.com/user-attachments/assets/dba26693-265f-4fe8-a1b1-c3d62e5f0974" alt="Dark Mode">
- <img src="https://github.com/user-attachments/assets/d6e47258-f6a5-4bc5-9363-a9bff154e813" alt="Light Mode">
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/dba26693-265f-4fe8-a1b1-c3d62e5f0974" width="250" alt="Android Dark Mode" />
+ &nbsp;
+ <img src="https://github.com/user-attachments/assets/d6e47258-f6a5-4bc5-9363-a9bff154e813" width="250" alt="Android Light Mode" />
</p>
<details>
<summary>Other Pages</summary>
-### Music Player
+### 🎡 Music Player
<!-- ![image](https://github.com/user-attachments/assets/6b20b784-e781-45f9-bf3d-5f31947329de)
![image](https://github.com/user-attachments/assets/2b1da093-d026-4db1-b4a4-741be37510e7) -->
-![image](https://github.com/user-attachments/assets/59a335c7-9b19-42ba-9bc0-8d0f3c2bf3cf)
-
-### Player Options
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/59a335c7-9b19-42ba-9bc0-8d0f3c2bf3cf" width="700" alt="Music Player" />
+</p>
-![image](https://github.com/user-attachments/assets/23feedaf-74b0-4fe4-b239-804bb4d0f1fe)
-![image](https://github.com/user-attachments/assets/05a2e4fd-e1c4-4fce-baed-31c850315a4c)
+### βš™οΈ Player Options
-### Setup Page
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/23feedaf-74b0-4fe4-b239-804bb4d0f1fe" width="320" alt="Player Option 1" />
+ &nbsp;
+ <img src="https://github.com/user-attachments/assets/05a2e4fd-e1c4-4fce-baed-31c850315a4c" width="320" alt="Player Option 2" />
+</p>
-![image](https://github.com/user-attachments/assets/6953e236-e93d-45a4-b044-12f973781730)
+### 🧰 Setup Page
-### Analytics
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/6953e236-e93d-45a4-b044-12f973781730" width="700" alt="Setup Page" />
+</p>
+### πŸ“Š Analytics
<!-- ![image](https://github.com/user-attachments/assets/625e29b7-506f-4cf6-890f-ebdff50c6ea0) -->
-![image](https://github.com/user-attachments/assets/1b69bd5e-5356-4ef0-931b-b7231b7bb638)
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/1b69bd5e-5356-4ef0-931b-b7231b7bb638" width="700" alt="Analytics Dashboard" />
+</p>
-### Library Management
+### πŸ“ Library Management
<!--![image](https://github.com/user-attachments/assets/ed5b4cf5-2155-4f90-8d81-b86893ace9c1) -->
-![image](https://github.com/user-attachments/assets/01d59dfb-c511-4786-ae92-4784667db84d)
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/01d59dfb-c511-4786-ae92-4784667db84d" width="700" alt="Library Manager" />
+</p>
-### User Management
+### πŸ‘₯ User Management
<!--![image](https://github.com/user-attachments/assets/ad1addff-e949-48ac-9f8c-f070deda1002 -->
-![image](https://github.com/user-attachments/assets/988aa053-9ca8-4ae7-8235-fc344fbd0d0c)
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/988aa053-9ca8-4ae7-8235-fc344fbd0d0c" width="700" alt="User Manager" />
+</p>
-### Task Dashboard
+### πŸ“ Task Dashboard
<!--![image](https://github.com/user-attachments/assets/e38cedee-3f74-4c77-8311-74e5a35d7b4e) -->
-![image](https://github.com/user-attachments/assets/d7749c4c-b6c1-4e55-8550-535126c2538d)
+<p align="center">
+ <img src="https://github.com/user-attachments/assets/d7749c4c-b6c1-4e55-8550-535126c2538d" width="700" alt="Task Dashboard" />
+</p>
</details>
## How To Use
-### Installation
+MediaServer can be run via Docker (recommended) or a standard manual installation.
+
+### 🐳 Docker Installation (Recommended)
-#### Docker
+1. Download the latest or beta **Docker release ZIP** for your platform.
+2. Unzip it to a folder with full **read/write/execute** permissions.
+3. Run the startup script (with Docker running) and let it create/copy the required files:
-You can download the zip archive for your platform from the latest or beta docker release.
+ - Windows: `startDocker.bat`
+ - Linux/macOS: `sudo bash startDocker.sh`
-- Unzip it to the location of your choice
- - Make sure that location has sufficient read/write/execute permissions for docker
-- Run `./startDocker.bat` (Windows) or `sudo bash startDocker.sh` and let it create/copy the required files
-- Visit `https://app.test` and follow the setup instructions there
-- Place your media in `./data/media/CATEGORY/FOLDER/VIDEO.MP4`
- - Media must be grouped by a folder (category) and subfolder (folder) in order to show up on the website
- - There are certain names that you cannot use for folders or videos
+4. Visit [`https://app.test`](https://app.test) in your browser and follow the setup wizard.
+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
- `More to come...`
-#### Standard
+### βš™οΈ Manual Installation
+
+To set up MediaServer without Docker, you’ll need:
-To run this yourself, you require a webserver such as [Caddy](https://caddyserver.com/) or [NGINX](https://nginx.org/en/index.html), [PostgreSQL](https://www.postgresql.org/), A build of Vue and Tailwind with [Node](https://nodejs.org/en), [FFmpeg](https://www.ffmpeg.org/), [ExifTool](https://exiftool.org/) (Optional) and PHP 8.3+. You can use [Laragon](https://laragon.org/) or the docker compose file to run in a single application. A valid SSL certificate is required to use some metadata features.
+- πŸ–₯️ 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/) or the included `docker-compose.yml` to simplify local setup.
```bash
-# Clone
+# 1. Clone the repository
git clone https://github.com/aminnausin/mediaServer.git
-
-# Open
cd mediaServer
-# Install dependencies
+# 2. Install backend dependencies
composer install
-npm i
+# 3. Install frontend dependencies
+npm install
-# Setup a database of your choice and input the required details in the .env file.
+# 4. Set up your database and .env
+cp .env.example .env
+
+# Edit the .env file with your Postgress DB info
# Example:
-DB_CONNECTION=pgsql
-DB_HOST=127.0.0.1
-DB_PORT=5432
-DB_DATABASE=mediaServer
-DB_USERNAME=postgres
-DB_PASSWORD=
-
-# Setup Laravel
+# 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
-# Link storage folders
-php artisan link
-
-# Setup Laravel Reverb (Websocket) Environment (Or fill out the Reverb Variables Yourself)
-php artisan install:broadcasting
+# 7. Link storage (for thumbnails, posters, etc.)
+php artisan storage:link
-# Build the app
+# 9. Build frontend assets
npm run build
-# Set up your App URL in the .env file
+# 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
+# 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
-SESSION_DOMAIN=app.test
-
-REVERB_HOST=app.test
-
-# Run locally with Laravel
+# 10. Run the app in development mode
npm run vite:php
```
-### Operating Instructions
-
-To connect to your file server, create a Symbolic link between your storage folder and ./storage/app/public/media.
-To see any of your videos, you must `INDEX FILES` from the user dropdown menu or start the Laravel scheduler which scans
-every 6 hours. `SYNC FILES` will synchronise local cache json files with the database. The `VERIFY FILES` job will pull metadata
-from the files using FFprobe.
+## πŸ“š Additional Documentation
-Different folders are accessed via url/folder/subfolder. Using just URL/folder will open the first subfolder scanned.
-You can share direct links to both videos and folders with the share buttons in the UI. Access to any category requires you to know its name by design.
+- [πŸ› οΈ Operations Guide](doc/OPERATIONS.md) – Symbolic linking, scanning, metadata jobs, supported formats
-#### Default File Types
+### Default File Types
- MP4 (ExifTool/FFmpeg)
- MKV (FFmpeg)
@@ -284,7 +347,7 @@ You can share direct links to both videos and folders with the share buttons in
> **Note:**
> You can add more by changing the code inside `./app/jobs/VerifyFiles.php` under the `generateVideos` function and in `./app/jobs/EmbedUidInMetadata.php` under the `handleEmbed` function.
-> _Eventually_, I will make this dependant on values from the database which can be configured from a settings dashboard
+> *Eventually*, I will make this dependant on values from the database which can be configured from a settings dashboard
## Activity
diff --git a/doc/OPERATIONS.md b/doc/OPERATIONS.md
new file mode 100644
index 00000000..60b4323c
--- /dev/null
+++ b/doc/OPERATIONS.md
@@ -0,0 +1,108 @@
+# πŸ› οΈ MediaServer Operations Guide
+
+This guide explains how to manage and operate MediaServer after installation.
+
+## πŸ“‚ File Linking (Incompatible with Docker)
+
+To connect your media storage to MediaServer, create a symbolic link from your media directory to Laravel's public storage:
+
+```bash
+ln -s /your/media/root ./storage/app/public/media
+```
+
+> Ensure this directory is accessible by the Laravel process and has read/write/execute permissions (for writing metadata).
+
+## πŸ”„ File Scanning & Metadata Jobs
+
+MediaServer supports multiple background jobs for managing your media library.
+
+### Index Files
+
+* Use this to detect and register new media files in your library.
+* Triggered manually from the UI (`User Dropdown β†’ Index Files`) or automatically by the Laravel scheduler.
+
+### Sync Files
+
+* Syncs the local `.json` metadata files with the database.
+* Ensures consistency between file-based caches and the DB state.
+
+### Verify Files
+
+* Extracts technical metadata from files using **FFprobe** (from FFmpeg).
+* This includes duration, resolution, codecs, and more.
+
+### Verify Folders
+
+* Generates metadata from folders based on the files within it.
+* This metadata includes primary media type (for different UI on videos vs audio), total file size, file counts.
+* Downloads external thumbnails and stores them locally for faster loading times.
+
+### Scan Files
+
+* Runs Index and Verify Files / Folders.
+* Generates all content and metadata in one go.
+* You should use this most of the time unless you are only filling missing data (like folder metadata).
+
+### ⏰ Scheduled Automation
+
+These jobs are also triggered automatically every 6 hours by Laravel’s scheduler.
+
+To start the scheduler manually in dev environments:
+
+```bash
+php artisan schedule:work
+```
+
+## 🌐 URL Structure & Navigation
+
+MediaServer follows a strict URL hierarchy:
+
+```
+/LIBRARY/FOLDER?VIDEO=VIDEO.ID
+```
+
+| Level | Description |
+| ---------- | --------------------------------- |
+| `LIBRARY` | Top-level folder name |
+| `FOLDER` | Subfolder (e.g., a show or album) |
+| `VIDEO` | Media file (MP4, MP3, etc.) |
+
+### 🧭 Routing Behavior
+
+* Visiting `/library/subfolder` shows the contents of a folder.
+* Visiting `/library` automatically opens the **first scanned subfolder** that you have access to.
+* Access to any **library** (top-level folder) requires **knowledge of its name** β€” this is intentional for ease of sharing.
+
+## πŸ”— Sharing Media
+
+You can share direct links via the UI using the **Share** button:
+
+* 🎞️ Individual videos / songs
+* πŸ“ Folders
+
+Shared links preserve access restrictions β€” unauthorized users cannot view private folders.
+
+## 🎡 Supported Media Formats
+
+| Format | Metadata Extractor |
+| ------- | ------------------ |
+| `.mp4` | FFmpeg + ExifTool |
+| `.mkv` | FFmpeg |
+| `.mp3` | FFmpeg |
+| `.ogg` | FFmpeg |
+| `.wav` | FFmpeg |
+| `.aac` | FFmpeg |
+| `.flac` | FFmpeg |
+
+Everything else defaults to .mp4 when scanned by FFmpeg and may not work.
+
+You also require a compatible browser to play content with certain codecs like HVEC. There is no transcoding.
+
+## βž• Adding Support for New Formats
+
+To support more formats, update the following backend jobs:
+
+* `app/Jobs/VerifyFiles.php` β†’ `extractMimeType()`
+* `app/Jobs/EmbedUidInMetadata.php` β†’ `handleEmbed()`
+
+> In future releases, supported file types will be configurable via the settings dashboard.