StreamHive

StreamHive is a Flask-based local media streaming server for home and LAN use.

Features

• Browse shared folders from a web UI
• Stream video/audio with HTTP Range support (seekable playback)
• External and embedded subtitle support
• Optional password-based access
• QR code generation for quick device connection
• Desktop launcher with system tray support

Quick Start (Recommended)

Linux/macOS:

./play.sh start

Windows:

play.bat start

Then open http://localhost:8080.

The play command creates/repairs the local virtual environment, installs dependencies, bootstraps .env and config.json, and starts StreamHive. Local runtime files are intentionally ignored by Git.

Manual Development Setup

python -m venv venv
./venv/bin/python -m pip install -r requirements.txt
cp .env.example .env          # edit passwords/secrets before LAN use
cp config.example.json config.json
./venv/bin/python app.py

Unified Play Modes

Mode actions:

• ./play.sh start / play.bat start -> start aplikasi (auto install jika perlu)
• ./play.sh install / play.bat install -> install/bootstrap saja
• ./play.sh uninstall / play.bat uninstall -> uninstall runtime
• ./play.sh doctor / play.bat doctor -> health check setup
• ./play.sh auto / play.bat auto -> buka Play Hub selector (GUI) jika display tersedia

Smart autonomous behavior:

• Auto-install Python jika belum ada (pacman/apt/dnf/zypper/apk/brew di Unix, winget/choco/scoop di Windows)
• Auto-check dependency: jika sudah terpasang -> skip install
• Auto-install dependency optional yang belum ada secara berurutan (qrcode/Pillow/ffmpeg-python/psutil/pystray/python-dotenv)
• Smart skip/cooldown: jika optional install gagal (mis. offline), attempt berikutnya di-throttle otomatis (tidak spam install tiap run)
• Auto-bootstrap local .env, password, config.json
• Default lebih aman: file kredensial plaintext tidak ditulis kecuali diaktifkan
• Default ./play.sh / play.bat langsung start (one-command run)
• Play Hub GUI tetap tersedia via mode auto
• Launcher GUI sekarang responsif: tombol aksi selalu terlihat, QR panel lebih presisi
• Launcher punya Quick Setup Wizard (first-run + bisa dipanggil ulang dari tombol Quick Setup)
• Micro-interaction desktop: fade-in startup, hover states, dan pulse status saat server running
• Multi-user auth otomatis: akun admin + user (username/password)
• Admin dashboard web untuk kelola shared folder + user accounts secara langsung
• Runtime panel tidak tampil default; hanya muncul saat admin klik tombol toggle
• Fallback ke CLI server jika GUI gagal/tidak tersedia
• Password bisa diinput/edit dari GUI launcher
• Uninstaller dari launcher akan prioritas memakai Python venv project (lebih stabil, minim konflik global)

Autonomous Uninstall

Linux/macOS:

./play.sh uninstall

Windows:

play.bat uninstall

• Uninstaller menyediakan GUI checklist terintegrasi.
• Headless mode otomatis saat GUI tidak tersedia atau STREAMHIVE_SKIP_GUI=1.
• Fokus menghapus runtime/dependency/config lokal, tidak menghapus source code project.

Structured script wrappers:

• Linux/macOS: scripts/linux/install.sh, scripts/linux/start.sh, scripts/linux/uninstall.sh
• Windows: scripts/windows/install.bat, scripts/windows/start.bat, scripts/windows/uninstall.bat
• Legacy typo alias tetap ada di scripts/legacy/ (unistall.*) untuk backward compatibility.

Alternate Launch (Desktop)

./venv/bin/python launcher.py

Configuration

• Base constants: config.py
• Example env: .env.example
• Example runtime settings: config.example.json
• User runtime settings: config.json (local/ignored)
• Shared folders are loaded from config.SHARED_FOLDERS
• .env di root project akan otomatis diload saat startup.
• Security env vars (recommended):
  • STREAMHIVE_SECRET_KEY (required for persistent secure sessions)
  • STREAMHIVE_PASSWORD (default password akun admin)
  • STREAMHIVE_USER_PASSWORD (opsional; default user password awal jika ingin ditetapkan manual)
  • STREAMHIVE_MULTIUSER_AUTH=1 (aktifkan mode login admin/user)
  • STREAMHIVE_STORE_USER_PASSWORD=0|1 (default 0, simpan generated user password ke .env jika 1)
  • STREAMHIVE_WRITE_CREDENTIALS_FILE=0|1 (default 0, tulis .streamhive_credentials.txt jika 1)
  • STREAMHIVE_ALLOW_GUEST_LAN=1 (optional; allow LAN access without password)
  • STREAMHIVE_LOGIN_MAX_ATTEMPTS, STREAMHIVE_LOGIN_WINDOW_SEC, STREAMHIVE_LOGIN_BLOCK_SEC

Development Notes

Validation

./venv/bin/python -m pip install -r requirements-dev.txt
./venv/bin/python -m unittest discover -s tests -v
./venv/bin/python -m pip check
./venv/bin/python -m flake8 .
./venv/bin/python -m mypy .
./venv/bin/python -m black --check .

• Architecture: docs/reference/ARCHITECTURE.md
• Code map: docs/reference/CODEBASE.md
• Initialization plan and roadmap: docs/reference/INIT_PLAN.md