User-centric docs.
This commit is contained in:
@@ -2,97 +2,44 @@
|
||||
|
||||
# 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)**
|
||||
|
||||
## Project Structure
|
||||
## What It Does
|
||||
|
||||
```
|
||||
hivescan/ Indexing & previews (library + CLI)
|
||||
indexer.py Media index generation
|
||||
scanning.py File system scanning
|
||||
parsing.py Torrent name parsing (PTN)
|
||||
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
|
||||
```
|
||||
- Scans your chosen media folder for all movies and series that can be found
|
||||
- Produces preview video clips and downloads metadata
|
||||
- Search on cast and character names, not just titles
|
||||
- Hand off playback to your preferred Windows player
|
||||
- Implement gamepad controls for MPC-BE which does not otherwise support that
|
||||
|
||||
## 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
|
||||
pip install -e .
|
||||
```
|
||||
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.
|
||||
|
||||
### 1. Scan & Index Media
|
||||
## Controls
|
||||
|
||||
```bash
|
||||
# Scan downloads, auto-detect common root, create .mediahive folder
|
||||
hivescan /media/torrents/*
|
||||
MediaHive is designed to work with a mouse, keyboard, or gamepad.
|
||||
|
||||
# Scan multiple locations
|
||||
hivescan /mnt/disk1/* /mnt/disk2/*
|
||||
| Input | Controls |
|
||||
| --- | --- |
|
||||
| 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
|
||||
hivescan /media/torrents/* -o /srv/media/.mediahive
|
||||
## Recommended Player: MPC-BE
|
||||
|
||||
# Skip cover/showreel generation
|
||||
hivescan /media/torrents/* --no-covers --no-showreels
|
||||
```
|
||||
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.
|
||||
|
||||
### 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
|
||||
# Start the web server
|
||||
mediahive /path/to/your/media/folder
|
||||
- `A` toggles play and pause.
|
||||
- `B` closes the player.
|
||||
- `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.
|
||||
|
||||
### 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)
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user