A self-hosted media server and file management system
Vue ffmpegfile-serverjellyfinlaravelmediamedia-playermedia-servermediabrowsermediaservermusicmusic-librarymusic-playermusicplayerself-hostedvuejs
feat: updated readme and operation instructions
aminnausinc9d633ebf2b0
diff --git a/README.md b/README.mdindex 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+- 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.<!--  -->-+### π₯οΈ 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><!-- -->-<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" />+ + <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<!--  -->---### Player Options+<p align="center">+ <img src="https://github.com/user-attachments/assets/59a335c7-9b19-42ba-9bc0-8d0f3c2bf3cf" width="700" alt="Music Player" />+</p>--+### βοΈ 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" />+ + <img src="https://github.com/user-attachments/assets/05a2e4fd-e1c4-4fce-baed-31c850315a4c" width="320" alt="Player Option 2" />+</p>-+### π§° 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<!--  -->-+<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<!-- -->-+<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<!--+<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<!-- -->-+<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 repositorygit clone https://github.com/aminnausin/mediaServer.git--# Opencd mediaServer-# Install dependencies+# 2. Install backend dependenciescomposer 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 keysphp artisan key:generate+php artisan reverb:generate+# 6. Run database migrationsphp 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 assetsnpm 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 modenpm 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## Activitydiff --git a/doc/OPERATIONS.md b/doc/OPERATIONS.mdnew file mode 100644index 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.