alex
47baee854b
Test coverage: - test_utils.py: formatting helpers (human_size, ticks_to_minutes, format_duration, format_bitrate, ffprobe summaries, stream parsing) - test_path_utils.py: path resolution (prefix, media root mapping, edge cases with spaces/special chars) - test_domain_media.py: Jellyfin item normalization (HDR detection, media sources, stream extraction, display formatting) - test_jobs.py: job template rendering and shell quoting safety - test_media_index.py: SQLite index CRUD, querying, filtering, sorting, pagination - test_config.py: pydantic-settings env loading - test_api.py: full FastAPI integration tests with mocked SSH/Jellyfin (all endpoints: dashboard, monitoring, media, files, jobs) All tests run without network/SSH dependencies using mocks.
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 (seebackend/README.md)frontend/— React + TypeScript SPA (seefrontend/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
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
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:
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
/procand/sys/blockfor monitoring /bin/sh(POSIX shell)python3,ffprobe,find,stat,df,awk
The SSH client rejects unknown host keys. Connect manually once first:
ssh user@host
Development
# 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/webdefensively. - SSH commands run through
/bin/sh -cregardless 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.