playeronegameover/streampulse repository overview

⁠StreamPulse

A self-hosted Plex media server dashboard with real-time stream monitoring, per-user watch statistics, library browsing, trend analysis, server health monitoring, and push notifications. Cinema-themed dark UI with PWA support.

⁠Features

• Dashboard with live-updating server activity overview and customizable sections (show/hide stat cards, now playing, play history chart, recently added, most watched/listened, recent activity)
• Now Playing - real-time active stream monitoring via SSE showing video/audio codec, bitrate, resolution, transcoding status, progress, and user info
• Per-user statistics split by watch (video) and listen (audio), with play counts, durations, favorite media type, library completion tracking, activity heatmap, and currently watching status
• Historical playback trend analysis with configurable time ranges (7d, 30d, 90d, all time) showing top movies, shows, and tracks
• Searchable, filterable media library browser with item detail modals showing play history and session data, thumbnail previews, and aggregate overview stats
• Chronological watch history with filtering by date range, media type, user (admin), and search with infinite scroll. GeoIP location (city/country) for WAN sessions
• Global search across watch history, library items, and users (admin) with thumbnail previews
• Data export - download watch history as CSV or JSON with optional filters. Non-admin users can only export their own data
• Server health - connectivity checks, external access verification, live CPU/memory charts, bandwidth history with LAN/WAN split, playback quality breakdown (Direct Play / Direct Stream / Transcode), resolution distribution, network stats (LAN vs WAN), uptime monitoring with ping response time chart, active transcode sessions with detailed source/destination codec and resolution info, and full library/history sync (admin only)
• Screening - full-screen cinema lobby mode for TV displays with configurable recently-added carousels and optional PIN lock
• Notifications - push to Discord, Slack, Pushover, Telegram, Gotify, ntfy, or custom webhooks for playback, content, and server events. Includes notification history log and content batching
• Automated reports - weekly and monthly activity reports sent to configured notification channels on a per-channel schedule
• Multi-server - connect and switch between multiple Plex servers with per-server history tracking
• Multi-user access - any Plex user can sign in after admin setup. First user becomes admin; others get limited default permissions
• User management - admin panel for managing user roles and per-page access permissions
• Data scoping - non-admin users only see their own play history, streams, statistics, and exports
• Background sync - watch history, library metadata, and session tracking stored locally and refreshed automatically. Uptime pings every 60 seconds
• GeoIP location - automatic city/country resolution for WAN sessions via ip-api.com with caching. Tautulli imports also enriched with geo data
• PWA - installable on iOS and Android with offline-capable service worker
• Fully responsive mobile-friendly UI with media-aware thumbnails (rectangular posters for video, square album art for music)
• Light/Dark/System theme with system preference detection

⁠Quick Start

1. Create a project directory:

mkdir StreamPulse && cd StreamPulse

2. Create a docker-compose.yml:

services:
  streampulse:
    image: playeronegameover/streampulse:latest
    container_name: streampulse
    restart: unless-stopped
    ports:
      - "3333:3333"
    volumes:
      - streampulse-data:/app/database
    environment:
      NODE_ENV: production
      HOST: 0.0.0.0
      PORT: 3333
      LOG_LEVEL: info
      TZ: UTC                      # change to your timezone
      SESSION_DRIVER: cookie
      APP_KEY: ${APP_KEY}

volumes:
  streampulse-data:

3. Create a .env file alongside your docker-compose.yml:

APP_KEY=your-secret-key-here

Generate a secure key with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

4. Start:

docker compose up -d

Migrations run automatically on startup.

5. Open: http://your-server-ip:3333

Sign in with your Plex account. The first user to log in becomes the admin. After login, connect your Plex server in the setup wizard.

⁠Updating

docker compose pull
docker compose up -d

⁠Environment Variables

⁠In-App Settings

Plex server configuration is done via the Setup page after first login (stored in the database, not environment variables).

Screening mode settings are configurable via the settings panel on the Screening page:

⁠Data Persistence

The SQLite database is stored at /app/database/streampulse.sqlite3 inside the container. The compose file maps this to a named volume (streampulse-data) so data survives container restarts and rebuilds.

Backup:

docker cp streampulse:/app/database/streampulse.sqlite3 ./backup.sqlite3

Restore:

docker compose down
docker run --rm -v streampulse-data:/data -v $(pwd):/backup alpine cp /backup/backup.sqlite3 /data/streampulse.sqlite3
docker compose up -d

⁠Networking

The container needs network access to your Plex Media Server. If Plex runs on the same machine as Docker:

• Linux - Use host.docker.internal (Docker 20.10+) or --network host
• macOS / Windows - Use host.docker.internal

When configuring your Plex server in the setup wizard, enter the IP or hostname reachable from inside the container (not localhost unless using host networking).

⁠Notifications

Configure push notifications from the Notifications page (admin only). Supports multiple channels, each subscribing to specific events with optional filtering.

Channels: Discord, Slack, Pushover, Telegram, Gotify, ntfy, Webhook (with custom headers and full event payload)

Events:

• Playback: started, completed, paused, resumed, transcoding, concurrent streams (per-user)
• Content: added (with batching), removed
• Server: update available, unreachable, restored
• Reports: weekly summary (configurable day/time), monthly summary (1st of each month, configurable time)

Filters per channel: users, media types, location (LAN/WAN), libraries, concurrent stream threshold

⁠Reverse Proxy

StreamPulse uses Server-Sent Events (SSE) for real-time features. Your reverse proxy must not buffer SSE responses.

Nginx:

server {
    listen 80;
    server_name StreamPulse.example.com;

    location / {
        proxy_pass         http://127.0.0.1:3333;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection 'upgrade';
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_buffering    off;
        proxy_cache        off;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

IIS (requires URL Rewrite + ARR modules):

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Proxy to StreamPulse" stopProcessing="true">
          <match url="(.*)" />
          <action type="Rewrite" url="http://localhost:3333/{R:1}" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

For IIS, also increase the ARR timeout to 300s and disable response buffering in Application Request Routing Cache - Server Proxy Settings.

⁠Security

⁠Disclaimer

StreamPulse is an independent project and is not affiliated with, endorsed by, or associated with Plex, Inc.

This software relies on third-party services and APIs, including the Plex Media Server API. Certain features may become temporarily or permanently unavailable if those dependencies change, become incompatible, or are discontinued for any technical or legal reason.

Media artwork, thumbnails, and metadata displayed within StreamPulse are retrieved from Plex and their upstream providers. These assets may be subject to copyright and remain the property of their respective rights holders.

This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors be liable for any claim, damages, or other liability arising from the use of this software.