# Media Library Viewer

Media library management tool with Jellyfin integration, SSH file inspection, server monitoring, and safe remote job templates.

See `docs/REQUIREMENTS.md` for the living requirements, decisions, and planning history.
See `docs/MIGRATION_PLAN.md` for the FastAPI + React architecture plan.

Project policy/docs:

- License: `LICENSE` (MIT)
- Contributing guide: `CONTRIBUTING.md`

## Architecture

The project consists of two subprojects:

- **`backend/`** — FastAPI Python API (see `backend/README.md`)
- **`frontend/`** — React + TypeScript SPA (see `frontend/README.md`)
- **`archive/`** — Original Streamlit prototype (preserved for reference)

## Features

- Dashboard with now-playing sessions, server monitoring overview, and per-library media counts
- Server monitoring with CPU, IO wait, RAM, network, and disk I/O charts
- SQLite-indexed media table with full-library sort/filter
- Remote file browser with ffprobe preview and job execution
- Jellyfin API integration for library metadata
- SSH-based file inspection and remote job templates

## Quick Start

### Backend

```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
uvicorn media_library_viewer_api.main:app --reload --port 8000
```

### Frontend

```bash
cd frontend
npm install
npm run dev
```

Frontend runs on http://localhost:5173 and proxies API requests to http://localhost:8000.

## Configuration

Create a `.env` file in the project root:

```bash
JELLYFIN_URL=https://jellyfin.example.com
JELLYFIN_API_KEY=your-api-key
JELLYFIN_USER_ID=

SSH_HOST=media-server.example.com
SSH_USERNAME=username
SSH_PORT=22
SSH_KEY_FILENAME=/home/username/.ssh/id_rsa
SSH_PASSWORD=

REMOTE_MEDIA_ROOT=/srv/media
REMOTE_PATH_PREFIX=
```

## Remote server requirements

The remote server needs:

- Linux `/proc` and `/sys/block` for monitoring
- `/bin/sh` (POSIX shell)
- `python3`, `ffprobe`, `find`, `stat`, `df`, `awk`

The SSH client rejects unknown host keys. Connect manually once first:

```bash
ssh user@host
```

## Development

```bash
# Backend
cd backend && PYTHONPATH=src python -m py_compile src/media_library_viewer_api/main.py

# Frontend
cd frontend && npx tsc --noEmit && npm run build
```

## Notes

- Jellyfin server root URL required (not `/web`). The client strips trailing `/web` defensively.
- SSH commands run through `/bin/sh -c` regardless of remote login shell.
- Job templates are shell-quoted. Add new templates in `backend/src/media_library_viewer_api/jobs.py`.
- Monitoring collector uses JSONL in `/tmp`, pruned to 7 days / 70k lines.