Skip to content

A self-hosted media server and file management system

chore: update readme

aminnausinbb1386a37e8a
diff --git a/README.md b/README.md
index 07b9e365..0b9256f0 100755
--- a/README.md
+++ b/README.md
@@ -5,15 +5,8 @@
<h1 align="center" style="display: block; border: none; padding: 0px;">
MediaServer
</h1>
-<!-- <p align="center"> -->
- <!-- <br>
- <a href="http://www.amitmerchant.com/electron-markdownify"><img src="https://raw.githubusercontent.com/amitmerchant1990/electron-markdownify/master/app/img/markdownify.png" alt="Markdownify" width="200"></a>
- <br> -->
- <!-- # MediaServer -->
- <!-- <br> -->
-<!-- </p> -->
-#### <p align="center">A minimalist self-hosted Media Server built with <a href="https://laravel.com/" target="_blank">Laravel</a>. </p>
+#### <p align="center">A self-hosted Media Server built with <a href="https://laravel.com/" target="_blank">Laravel</a>. </p>
<p align="center">
<img src="https://img.shields.io/badge/vue-v3.5.27-white" alt="Vue">
@@ -74,17 +67,17 @@ Both can serve shows, movies, and music but with different approaches.
### 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
+- 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>
@@ -99,16 +92,18 @@ Both can serve shows, movies, and music but with different approaches.
- `SHIFT+P`: Play Previous
- `m`: Mute
- `f`: Toggle Fullscreen
- - `c`: Toggle Lyrics / Captions
+ - `t`: Toggle Theatre Mode
+ - `c`: Toggle Lyrics / Default Subtitle Track
- `p`: Toggle playlist (autoplay)
- Playback Features:
- Speed Controls
- Player Statistics
- - Ambient Background (toggleable)
- - Heatmap Visualisation (after 5+ seeks)
- - Watch Party UI Demo *(coming soon)*
+ - 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
@@ -188,76 +183,9 @@ The preview is rendered server-side using **Browsershot** and cached for perform
</details>
-### Planned Features
-
-#### V0.17 (Coming Soon)
-
-- πŸ“Š Advanced Playback Stats
- - Activity
- - Most Played (daily, weekly, monthly)
- - Personal Favorites
- - Average watch time over time
-- πŸ“ Captions/Subtitles Support
- - Auto embedded subtitle extraction
-- Two-way audio metadata editing (apply deep metadata edits to file)
- - Ex/ Artist, Album, Cover-Art, Disk, Track, Year, Composer, Genre
- - Real World Ex/ Musicolet Editor
-- πŸ–ΌοΈ Image Extraction / Generation / Upload System
- - Implement a better system for image metadata
- - Have 3 different levels
- - embedded (cover art or auto thumbnails)
- - auto (from 3rd party metadata sources)
- - user (uploaded / provided via url by the user)
-- Download Links
- - Must be optional and per library or folder
-- Indexing Overhaul
-- Media Tagging Cache
- - Put tagged media in cache, ideally on a different disk to reduce thrashing and increase speed
-- Server Configuration Interface (Tentative Placement)
- - Configure Concurrent Process Limits
- - Manage global settings
- - Scan Frequency
- - Cache Location
- - Supported File Types
- - FFmpeg / ExifTool Settings
-- Audio Spectograph Visuals (Low Priority)
- - Just for fun
-
-#### V0.18
-
-- πŸ’¬ Timed Comments (like SoundCloud)
-- πŸ” User Roles (Admin / Contributor / Viewer)
-- πŸ‘€ User Profiles & Friends System
-- Activity Tracker
- - Logins / Logouts
- - Edits
- - Playback Start / Stop / Finish
- - Shares
- - Deletes
-
-#### Future Versions
-
-- πŸŽ‰ Live Sync Playback (Parties)
-- In Browser Lyrics Editor/Generator with Playback (currently can only paste in timed lyrics but not generate them)
-- Playlists
-- Library Manager
- - Add libraries in browser via path
- - Mount path in docker and then point to it
- - Similar to Immich
- - Track symbolic links
-
-### Ongoing Improvements
-
-- πŸ› οΈ Refactor Index and Verify Metadata Jobs (MAJOR) (Oldest code in the project)
- - Break into service structure with concurrent index jobs
- - Simplify metadata extraction and stop storing folder structure in JSON files
- - Implement cache disk feature to reduce time taken to tag media
-- Make feature domains consistent
- - `library` instead of `category`
- - `media` instead of `video` (maybe a better name exists)
-- Fix date inconsistencies and store everything in the same format / time-zone
+### Roadmap
-</details>
+See [ROADMAP.md](./doc/ROADMAP.md) for planned features, ongoing improvements, and known bugs.
## Demo
@@ -269,6 +197,16 @@ The preview is rendered server-side using **Browsershot** and cached for perform
- πŸš€ [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.
<!-- ![image](https://github.com/aminnausin/mediaServer/assets/83550431/495ba4cb-0e30-45e3-91b7-d3a3dae454b6) -->
@@ -282,7 +220,7 @@ Below are screenshots of the current webpage on Desktop and Android.
![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
+### Desktop Browser View
<p align="center">
<img src="https://github.com/user-attachments/assets/c163a27d-0c14-47e8-bb5e-cda06a9c635c" width="700" alt="Desktop Home View" />
@@ -292,7 +230,7 @@ Below are screenshots of the current webpage on Desktop and Android.
![Dark](https://github.com/user-attachments/assets/8813ac95-3874-44a5-b1e2-5fc7ef73e768)
![Light](https://github.com/user-attachments/assets/2da8c1ce-41f4-4462-afdb-bf9bc5856db8) -->
-### πŸ“± Android View
+### Android Browser View
<!--
![image](https://github.com/user-attachments/assets/dba26693-265f-4fe8-a1b1-c3d62e5f0974)
@@ -305,7 +243,7 @@ Below are screenshots of the current webpage on Desktop and Android.
<img src="https://github.com/user-attachments/assets/e010eec1-7aef-40ab-ab1b-4c1054a83e1b" width="250" alt="Android Light Mode" />
</p>
-### πŸ–ΌοΈ Open Graph Preview Example
+### Open Graph Preview Example
<p align="center">
<img src="https://github.com/user-attachments/assets/2b4ebe41-c515-41c9-a76e-0fcd5db3d2f6" width="700" alt=Open Graph Preview>
@@ -314,7 +252,7 @@ Below are screenshots of the current webpage on Desktop and Android.
<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)
@@ -325,20 +263,20 @@ Below are screenshots of the current webpage on Desktop and Android.
<img src="https://github.com/user-attachments/assets/54deff73-3d34-45e0-bc38-ef88ef2a93d7" width="700" alt="Music Player" />
</p>
-### 🎡 Lyrics Editor
+### Lyrics Editor
<p align="center">
<img src="https://github.com/user-attachments/assets/b3e626cd-7664-4980-8ea1-323c1acbcf42" height="600" alt="Lyrics Editor" />
</p>
-### πŸ“– Lyrics Viewer
+### Lyrics Viewer
<p align="center">
<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" />
</p>
-### βš™οΈ Player Options
+### Player Options
<p align="center">
@@ -348,20 +286,20 @@ Below are screenshots of the current webpage on Desktop and Android.
<img src="https://github.com/user-attachments/assets/05a2e4fd-e1c4-4fce-baed-31c850315a4c" width="700" alt="Player Option 2" />
</p>
-### 🧰 Setup Page
+### Setup Page
<p align="center">
<img src="https://github.com/user-attachments/assets/6953e236-e93d-45a4-b044-12f973781730" width="700" alt="Setup Page" />
</p>
-### πŸ“Š Analytics
+### Analytics
<!-- ![image](https://github.com/user-attachments/assets/625e29b7-506f-4cf6-890f-ebdff50c6ea0) -->
<p align="center">
<img src="https://github.com/user-attachments/assets/2d3984bb-6512-4c0c-a304-6619393e1ed3" width="700" alt="Analytics Dashboard" />
</p>
-### πŸ“ Library Management
+### Library Management
<!--![image](https://github.com/user-attachments/assets/ed5b4cf5-2155-4f90-8d81-b86893ace9c1) -->
@@ -369,7 +307,7 @@ Below are screenshots of the current webpage on Desktop and Android.
<img src="https://github.com/user-attachments/assets/dd4888a2-2003-4183-8cae-2a45d78dd115" width="700" alt="Library Manager" />
</p>
-### πŸ‘₯ User Management
+### User Management
<!--![image](https://github.com/user-attachments/assets/ad1addff-e949-48ac-9f8c-f070deda1002 -->
@@ -377,7 +315,7 @@ Below are screenshots of the current webpage on Desktop and Android.
<img src="https://github.com/user-attachments/assets/d1195561-dcae-4dad-bfa4-18f9bfee7aea" width="700" alt="User Manager" />
</p>
-### πŸ“ Task Dashboard
+### Task Dashboard
<!--![image](https://github.com/user-attachments/assets/e38cedee-3f74-4c77-8311-74e5a35d7b4e) -->
@@ -385,13 +323,13 @@ Below are screenshots of the current webpage on Desktop and Android.
<img src="https://github.com/user-attachments/assets/f73f27de-6035-46e6-a67d-f892e6bba67d" width="700" alt="Task Dashboard" />
</p>
-### πŸŽ›οΈ Site Preferences
+### Site Preferences
<p align="center">
<img src="https://github.com/user-attachments/assets/91d2a538-ede4-4ab9-9e06-06dfa0ca2d3a" width="700" alt="Site Preferences" />
</p>
-### πŸ‘€ User Account Settings
+### User Account Settings
<p align="center">
<img src="https://github.com/user-attachments/assets/bd7b210b-2737-4101-bf27-3549a381526d" width="700" alt="User Account Settings" />
@@ -408,7 +346,7 @@ MediaServer can be run via Docker (recommended) or a standard manual installatio
### 🐳 Docker Installation (Recommended)
> [!WARNING]
-> Use the beta image to get the latest features. The main image is a couple of months behind.
+> Use the beta image to get the latest features.
1. Download the latest or beta **Docker release ZIP** for your platform.
@@ -458,11 +396,11 @@ MediaServer can be run via Docker (recommended) or a standard manual installatio
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
+- 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.
@@ -516,7 +454,7 @@ npm run vite:php
## πŸ“š Additional Documentation
-- [πŸ› οΈ Operations Guide](doc/OPERATIONS.md) – Symbolic linking, scanning, metadata jobs, supported formats
+- [Operations Guide](doc/OPERATIONS.md) – Symbolic linking, scanning, metadata jobs, supported formats
## Activity
@@ -532,8 +470,6 @@ npm run vite:php
## Similar Projects
-Some similar projects that serve the same purpose but were not direct sources of inspiration include:
-
[![jellyfin](https://jellyfin.org/images/logo.svg)](https://github.com/jellyfin/jellyfin)
## Services Used
diff --git a/doc/ROADMAP.md b/doc/ROADMAP.md
new file mode 100644
index 00000000..47f71305
--- /dev/null
+++ b/doc/ROADMAP.md
@@ -0,0 +1,74 @@
+# Roadmap
+
+This document tracks planned features, ongoing improvements, and known bugs.
+
+> [!NOTE]
+> The information in this document was summarised by AI from my distributed development plans.
+
+## v0.17 β€” In Progress
+
+### βœ… Completed
+
+- Mobile UI fixes (ambient mode, progress bar, hover states)
+- Auth timeout fixes
+- UI Overhaul
+ - Updgrade to Tailwind V4
+ - Convert main Pinia stores to TypeScript
+ - Integrate cedar-ui
+ - Implement system wide colour palettes
+- Embedded subtitle support (SRT / ASS β†’ VTT auto-extraction)
+- Playback progress tracking (guest + user)
+- Download links
+ - Configurable per folder and per library
+ - Guest downloads can be toggled
+- Media tagging cache
+ - Cache ffprobe output to database
+ - Improves metadata verification speed
+- Logo
+
+### πŸ”§ In Progress / Planned
+
+- **Two-way audio metadata editing** β€” apply edits directly to file (Artist, Album, Cover Art, Disk, Track, Year, Composer, Genre)
+- **Thumbnail system overhaul**
+ - Auto-generated from cover art or video frames
+ - Third-party sources (e.g. AniList)
+ - User-uploaded or URL-provided thumbnails
+- **Metadata & ingestion overhaul** β€” simplify extraction, stop storing folder structure in JSON, concurrent index jobs
+- **Browsing pages** β€” dedicated Folder, Seasons, Artists, and Albums views based on user feedback
+- **Advanced playback stats**
+ - Activity feed
+ - Most played (daily, weekly, monthly)
+ - Personal favourites
+ - Average watch time over time
+- **Server configuration interface** *(tentative)*
+ - Concurrent process limits
+ - Global settings (scan frequency, cache location, supported file types, FFmpeg / ExifTool)
+- **Audio spectrograph visuals** *(low priority, just for fun)*
+
+## v0.18 β€” Planned
+
+- **User roles** β€” Admin / Contributor / Viewer permissions
+- **Timed comments** (SoundCloud-style)
+- **User profiles & friends system**
+- **Activity tracker** β€” logins, edits, playback start/stop/finish, shares, deletes
+- **Playback stats continued**
+- Possible: OGP image generation as a microservice (Go or Node)
+- Possible: Metadata extraction microservice
+
+## Future Versions
+
+- **Live sync playback** β€” watch parties
+- **Playlists**
+- **In-browser lyrics editor** with playback sync (currently paste-only)
+- **Library manager** β€” add libraries via path in browser, track symbolic links
+- **Basic transcoding** for unsupported file types
+
+## Ongoing Improvements
+
+- Refactor index and verify metadata jobs β€” oldest code in the project, needs a full service-based rewrite
+- Make feature domains consistent (`library` not `category`, `media` not `video`)
+- Fix date inconsistencies β€” standardise format and timezone across the codebase
+
+## Known Bugs / Investigations
+
+- UUID embedding is bottlenecked by disk speed β€” investigating cache-disk approach to copy, process, and write back in bulk