User-centric docs.
This commit is contained in:
@@ -2,97 +2,44 @@
|
|||||||
|
|
||||||
# MediaHive
|
# MediaHive
|
||||||
|
|
||||||
Media scanning, indexing, and Netflix-style web streaming for your torrent collection.
|
Netflix style browsing of your local media archive. Supports keyboard, mouse and gamepad navigation. Uses your favorite movie player.
|
||||||
|
|
||||||
**[Windows portable ZIP download](https://git.zi.fi/LeoVasanko/mediahive/releases)**
|
**[Windows portable ZIP download](https://git.zi.fi/LeoVasanko/mediahive/releases)**
|
||||||
|
|
||||||
## Project Structure
|
## What It Does
|
||||||
|
|
||||||
```
|
- Scans your chosen media folder for all movies and series that can be found
|
||||||
hivescan/ Indexing & previews (library + CLI)
|
- Produces preview video clips and downloads metadata
|
||||||
indexer.py Media index generation
|
- Search on cast and character names, not just titles
|
||||||
scanning.py File system scanning
|
- Hand off playback to your preferred Windows player
|
||||||
parsing.py Torrent name parsing (PTN)
|
- Implement gamepad controls for MPC-BE which does not otherwise support that
|
||||||
models.py Data models
|
|
||||||
images.py TMDb cover/backdrop downloading
|
|
||||||
showreel.py Video preview clip generation (ffmpeg)
|
|
||||||
tmdb_client.py TMDb API client with caching
|
|
||||||
utils.py Path, size, and timestamp helpers
|
|
||||||
mediahive/ FastAPI web server + Vue frontend
|
|
||||||
server.py FastAPI app (API + media serving)
|
|
||||||
__main__.py CLI entry point
|
|
||||||
frontend/ Vue 3 frontend source
|
|
||||||
src/
|
|
||||||
components/ Vue components (Netflix-style UI)
|
|
||||||
styles/ CSS styles
|
|
||||||
api.ts API calls to FastAPI backend
|
|
||||||
types.ts TypeScript interfaces
|
|
||||||
scripts/
|
|
||||||
devserver.py Development server (Vite + FastAPI)
|
|
||||||
rtorrent-manager.py Torrent scanning & rtorrent management
|
|
||||||
fastapi-vue/ Build utilities for frontend
|
|
||||||
rtorrent_client.py RTorrent XMLRPC/SCGI client
|
|
||||||
```
|
|
||||||
|
|
||||||
## Quick Start
|
Extract the ZIP in some place and run MediaHive.exe to start the app. Currently we have no installer, but you can pin to start/taskbar for easier access. On the first startup the app asks for your media folder, that can later be changed by clicking in-app folder icon.
|
||||||
|
|
||||||
```bash
|
Note that `.mediahive` folder is created in your media folder to hold all the metadata and preview clips, avoiding the lengthy processing that you will see on initial startup.
|
||||||
pip install -e .
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1. Scan & Index Media
|
## Controls
|
||||||
|
|
||||||
```bash
|
MediaHive is designed to work with a mouse, keyboard, or gamepad.
|
||||||
# Scan downloads, auto-detect common root, create .mediahive folder
|
|
||||||
hivescan /media/torrents/*
|
|
||||||
|
|
||||||
# Scan multiple locations
|
| Input | Controls |
|
||||||
hivescan /mnt/disk1/* /mnt/disk2/*
|
| --- | --- |
|
||||||
|
| Mouse | Click posters, rows, search, play, and folder actions directly. |
|
||||||
|
| Keyboard | Arrow keys move focus, `Enter` activates the focused item, `Escape` goes back, and `/` jumps to search. |
|
||||||
|
| Gamepad | D-pad or left stick moves focus, `A` selects or plays, and `B` goes back. |
|
||||||
|
|
||||||
# Override output directory
|
## Recommended Player: MPC-BE
|
||||||
hivescan /media/torrents/* -o /srv/media/.mediahive
|
|
||||||
|
|
||||||
# Skip cover/showreel generation
|
For the best playback quality, install [MPC-BE](https://github.com/Aleksoid1978/MPC-BE/releases) and set it as default player so that MediaHive opens video files with it. The MPC Video Renderer is better than other players, having Dolby Vision and other things you may need supported out of the box.
|
||||||
hivescan /media/torrents/* --no-covers --no-showreels
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Serve & Browse
|
For gamepad control, in MPC-BE Options, enable Web Interface, listen on port 13579. MediaHive automatically connects to that port on localhost.
|
||||||
|
|
||||||
```bash
|
- `A` toggles play and pause.
|
||||||
# Start the web server
|
- `B` closes the player.
|
||||||
mediahive /path/to/your/media/folder
|
- `Y` toggles mute.
|
||||||
|
- D-pad up and down change volume.
|
||||||
|
- D-pad left and right seek during playback, or step frames while paused.
|
||||||
|
|
||||||
# Server starts at http://localhost:8420
|
## Background
|
||||||
```
|
|
||||||
|
|
||||||
The app expects `<media-folder>/.mediahive/index.json` generated by hivescan.
|
This project started as a personal project that I have used for browsing my warez for some time now. It is still in early development, but I have just now made it public for a wider audience.
|
||||||
|
|
||||||
### 3. Development
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend && npm install && cd ..
|
|
||||||
python scripts/devserver.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Starts Vite dev server + FastAPI backend with auto-reload.
|
|
||||||
|
|
||||||
## API Endpoints
|
|
||||||
|
|
||||||
- `GET /api/index` — Load media index
|
|
||||||
- `POST /api/play` — Open media file with system player
|
|
||||||
- `POST /api/open-folder` — Open folder in file explorer
|
|
||||||
- `GET /api/media/{path}` — Serve media files (images, video)
|
|
||||||
|
|
||||||
## RTorrent Manager
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python scripts/rtorrent-manager.py /media/torrents*/.torrents/
|
|
||||||
```
|
|
||||||
|
|
||||||
Scans `.torrent` files, verifies downloads exist, loads into rtorrent.
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
- Python ≥ 3.14
|
|
||||||
- Node.js 18+ (frontend development)
|
|
||||||
- ffmpeg (showreel generation)
|
|
||||||
|
|||||||
+27
@@ -0,0 +1,27 @@
|
|||||||
|
# API
|
||||||
|
|
||||||
|
MediaHive exposes a small local API used by the desktop app and frontend.
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
| Method | Path | Purpose |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `GET` | `/api/health` | Lightweight health check. |
|
||||||
|
| `GET` | `/api/config` | Returns the currently selected media folder. |
|
||||||
|
| `POST` | `/api/change-folder` | Persists and switches the active media folder without restarting the app. |
|
||||||
|
| `GET` | `/api/index` | Returns the current in-memory media index. |
|
||||||
|
| `GET` | `/api/playback/resume-positions` | Returns saved resume positions by media path. |
|
||||||
|
| `GET` | `/api/status` | Returns scanner and library status information. |
|
||||||
|
| `POST` | `/api/scan` | Triggers a new scan if the scanner is active. |
|
||||||
|
| `POST` | `/api/play` | Opens a media file with the system player. |
|
||||||
|
| `POST` | `/api/open-folder` | Opens a folder in the system file explorer, or selects a file in its parent folder. |
|
||||||
|
| `GET` | `/api/mpcbe/status` | Reports whether MPC-BE's local web interface is reachable. |
|
||||||
|
| `GET` | `/api/media/{file_path:path}` | Serves files from the active media root. |
|
||||||
|
| `WS` | `/api/ws` | Streams live index updates and task progress events. |
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- `POST /api/change-folder` validates the new folder, saves it to config, and switches the in-memory scanner asynchronously.
|
||||||
|
- `POST /api/play` and `POST /api/open-folder` expect JSON request bodies matching the frontend calls.
|
||||||
|
- `GET /api/media/{file_path:path}` is constrained to the current media root.
|
||||||
|
- `GET /api/mpcbe/status` only checks the local MPC-BE web interface.
|
||||||
@@ -0,0 +1,76 @@
|
|||||||
|
# Development
|
||||||
|
|
||||||
|
This document covers the developer-facing ways to run MediaHive locally. The main [README.md](../README.md) is aimed at Windows end users.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Python 3.14+
|
||||||
|
- `uv`
|
||||||
|
- Node.js 18+
|
||||||
|
|
||||||
|
## Install Dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv sync --extra gui --group dev
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
## Run The Backend Directly
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run mediahive /path/to/media/folder
|
||||||
|
```
|
||||||
|
|
||||||
|
This starts the FastAPI backend and serves the built frontend.
|
||||||
|
|
||||||
|
## Run Frontend + Backend In Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run scripts/devserver.py /path/to/media/folder
|
||||||
|
```
|
||||||
|
|
||||||
|
This starts the FastAPI backend with auto-reload plus the Vite frontend dev server.
|
||||||
|
|
||||||
|
## Run The Desktop App In Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv run --extra gui python -m mediahive.winmain /path/to/media/folder
|
||||||
|
```
|
||||||
|
|
||||||
|
This launches the same pywebview-based desktop flow used by the Windows build.
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- The selected media folder is scanned continuously by the backend.
|
||||||
|
- The Windows desktop app remembers the chosen folder between launches.
|
||||||
|
- HTTP and WebSocket endpoints are documented in [API.md](API.md).
|
||||||
|
- MPC-BE integration details live in [mpc-be.md](mpc-be.md).
|
||||||
|
*** Add File: c:\mediahive\docs\API.md
|
||||||
|
# API
|
||||||
|
|
||||||
|
MediaHive exposes a small local API used by the desktop app and frontend.
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
| Method | Path | Purpose |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `GET` | `/api/health` | Lightweight health check. |
|
||||||
|
| `GET` | `/api/config` | Returns the currently selected media folder. |
|
||||||
|
| `POST` | `/api/change-folder` | Persists and switches the active media folder without restarting the app. |
|
||||||
|
| `GET` | `/api/index` | Returns the current in-memory media index. |
|
||||||
|
| `GET` | `/api/playback/resume-positions` | Returns saved resume positions by media path. |
|
||||||
|
| `GET` | `/api/status` | Returns scanner and library status information. |
|
||||||
|
| `POST` | `/api/scan` | Triggers a new scan if the scanner is active. |
|
||||||
|
| `POST` | `/api/play` | Opens a media file with the system player. |
|
||||||
|
| `POST` | `/api/open-folder` | Opens a folder in the system file explorer, or selects a file in its parent folder. |
|
||||||
|
| `GET` | `/api/mpcbe/status` | Reports whether MPC-BE's local web interface is reachable. |
|
||||||
|
| `GET` | `/api/media/{file_path:path}` | Serves files from the active media root. |
|
||||||
|
| `WS` | `/api/ws` | Streams live index updates and task progress events. |
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- `POST /api/change-folder` validates the new folder, saves it to config, and switches the in-memory scanner asynchronously.
|
||||||
|
- `POST /api/play` and `POST /api/open-folder` expect JSON request bodies matching the frontend calls.
|
||||||
|
- `GET /api/media/{file_path:path}` is constrained to the current media root.
|
||||||
|
- `GET /api/mpcbe/status` only checks the local MPC-BE web interface.
|
||||||
Reference in New Issue
Block a user