Skip to content

README.md

Latest commit

 

History

History
345 lines (284 loc) · 13.4 KB

README.md

File metadata and controls

345 lines (284 loc) · 13.4 KB
Raw

StreamGrid

StreamGrid

Your streams, your layout, your way

StreamGrid is a multi-stream viewer that gives you total control over how you watch. Build a giant main feed ringed by smaller cameras, a tidy equal grid for monitoring, or any arrangement in between — then drag, resize, and auto-fit it to your window in a click. Built with Electron, React, and TypeScript, it's the command center for watching many live sources at once.

📚 Documentation: API Reference | Bruno API Collection

StreamGrid.mp4

✨ Features

  • Layouts that fill the window:
    • Build ANY arrangement — from 2 feeds to 20+
    • Drag to reorder and grab a corner to resize in real time
    • One-click Auto-arrange packs every feed edge-to-edge, stretching tiles to fill the screen at the best fit for your window
  • Grid management:
    • Save unlimited grid presets and switch instantly (Ctrl/Cmd+1–9, Ctrl/Cmd+Tab)
    • Rename, duplicate, export, and delete from the All grids view
    • Import a shared grid straight from the + menu, or export yours to send to a friend
    • The quick switcher (Ctrl/Cmd+K) jumps between grids in a keystroke
  • Stream platform support:
    • Local files — play video straight from your computer
    • YouTube — standard videos, live streams, and shorts
    • Twitch — channel live streams
    • RTSP / RTSPS — IP cameras and streaming sources with automatic FFmpeg transcoding (auth, low-latency HLS, multiple concurrent streams, auto-retry)
    • HLS — HTTP Live Streaming sources
    • MPEG-DASH — Dynamic Adaptive Streaming over HTTP
  • Sound management:
    • Global mute/unmute for the whole wall
    • Per-stream audio controls
    • Option to start streams muted
  • Chat integration:
    • YouTube and Twitch live chat as draggable, resizable panels
  • Automation:
    • Auto-start all streams on launch (with configurable delay)
    • Automatic retry for failed streams with exponential backoff
    • REST API for full programmatic control — add/update/remove streams and manage grids remotely, with API-key auth and rate limiting
    • M3U / M3U8 playlist import with automatic arrangement
  • Persistent everything: aggressive auto-save on every meaningful change
  • Cross-platform: Windows, macOS, and Linux

🚀 Getting Started

Option 1: Download Pre-built Application (Recommended)

  1. Visit the Releases section
  2. Download the latest version for your platform:
    • Windows: streamgrid-3.0.0-win-x64.exe
    • macOS (Intel): streamgrid-3.0.0-mac-x64.dmg
    • macOS (Apple Silicon): streamgrid-3.0.0-mac-arm64.dmg
    • Linux: streamgrid-3.0.0-linux-x64.AppImage
  3. Install and run StreamGrid

Option 2: Build from Source

Prerequisites

  • Node.js 18.x or higher
  • npm 9.x or higher
  • FFmpeg (required for RTSP streaming support)
Installing FFmpeg

Windows:

  1. Download FFmpeg from ffmpeg.org
  2. Extract to C:\ffmpeg
  3. Add C:\ffmpeg\bin to your system PATH
  4. Or use Chocolatey: choco install ffmpeg

macOS:

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install ffmpeg

Linux (Fedora/RHEL):

sudo yum install ffmpeg

Steps

  1. Clone the repository
git clone https://github.com/LordKnish/StreamGrid.git
cd StreamGrid
  1. Install dependencies
npm install
  1. Run in development mode (for testing/development)
npm run dev
  1. Package the application (for distribution)
npm run dist:win        # Windows (NSIS installer)
npm run dist:mac:x64    # macOS (Intel)
npm run dist:mac:arm64  # macOS (Apple Silicon)
npm run dist:linux      # Linux (AppImage + deb)

To produce an unpacked build for the current platform without an installer:

npm run build:unpack
  1. Find your built application in the dist/ directory, e.g.:
    • Windows: dist/streamgrid-3.0.0-win-x64.exe
    • macOS: dist/streamgrid-3.0.0-mac-*.dmg
    • Linux: dist/streamgrid-3.0.0-linux-x64.AppImage

📹 RTSP Stream Support

StreamGrid supports RTSP (Real Time Streaming Protocol) streams from IP cameras, security systems, and other RTSP sources.

Requirements

  • FFmpeg must be installed on your system (see installation instructions above)
  • RTSP stream URL from your camera or source

RTSP URL Format

rtsp://[username:password@]host[:port]/path

Examples:

rtsp://192.168.1.100:554/stream1
rtsp://admin:password@192.168.1.100/live
rtsps://secure-camera.example.com/stream

How It Works

  1. StreamGrid detects RTSP URLs automatically
  2. FFmpeg transcodes the RTSP stream to HLS format in real-time
  3. The HLS stream is served locally and played in the app
  4. Low latency (~2-3 seconds) with automatic retry on connection loss

Adding an RTSP Stream

  1. Click the Add Stream button
  2. Enter your RTSP URL in the Stream URL field
  3. The app will show "RTSP stream (requires FFmpeg)" if detected
  4. Add a name and optional logo
  5. Click Add Stream

Troubleshooting RTSP Streams

"FFmpeg not installed" error:

  • Install FFmpeg using the instructions above
  • Restart StreamGrid after installation
  • Verify FFmpeg is in your system PATH: ffmpeg -version
  • The status bar shows whether FFmpeg was detected on launch

Stream fails to load:

  • Verify the RTSP URL is correct
  • Check if authentication is required (username/password)
  • Ensure your firewall allows RTSP connections
  • Try using TCP transport: rtsp://camera?tcp

High latency or buffering:

  • RTSP streams have inherent 2-3 second latency due to HLS transcoding
  • Check your network connection to the camera
  • Reduce the number of concurrent RTSP streams

Stream stops after a while:

  • StreamGrid automatically retries failed streams (up to 3 times)
  • Check camera timeout settings
  • Verify network stability

Performance Tips

  • Limit concurrent RTSP streams to 3-4 for best performance
  • Use a wired network connection for cameras when possible
  • Close unused RTSP streams to free resources
  • RTSP transcoding uses ~100MB RAM per stream

🛠 Tech Stack

🏗 Project Structure

StreamGrid/
├── src/
│   ├── main/                 # Electron main process
│   │   └── index.ts         # Main process entry point
│   ├── preload/             # Preload scripts for IPC
│   │   ├── index.ts         # Preload implementation
│   │   └── index.d.ts       # TypeScript definitions
│   ├── renderer/            # React application
│   │   ├── src/
│   │   │   ├── assets/      # Images, icons, styles
│   │   │   ├── components/  # React components
│   │   │   │   ├── StreamGrid.tsx
│   │   │   │   ├── StreamCard.tsx
│   │   │   │   └── ...
│   │   │   ├── hooks/       # Custom React hooks
│   │   │   ├── store/       # Zustand state management
│   │   │   ├── theme.ts     # Design tokens + MUI theme
│   │   │   ├── types/       # TypeScript type definitions
│   │   │   ├── utils/       # Helpers (grid import, parsing)
│   │   │   ├── workers/     # Web workers
│   │   │   └── App.tsx      # Main React component
│   │   └── index.html       # HTML entry point
│   └── shared/              # Shared types between processes
│       └── types/
├── resources/               # Application resources
│   ├── icon.png            # App icon
│   └── icon.svg            # App icon (vector)
├── dist/                   # Built applications (after build)
├── out/                    # Compiled TypeScript (generated)
├── electron.vite.config.ts # Vite configuration
├── package.json           # Project dependencies
└── tsconfig.json          # TypeScript configuration

📋 Changelog

Version 3.0.0 (Latest)

Layout Engine & Grid Management

🚀 New & Improved

  • Window-filling auto-arrange — a rebuilt layout engine that picks the best row/column split for the current window and stretches every tile edge-to-edge, with no empty bands or letterboxing between feeds
  • Reliable grid management — fixed renaming in the All grids view, corrected grid duplication, and a redesigned, faster All grids browser with search
  • Import from the + menu — right-click the new-grid + button to import a shared grid; import is also available from the All grids view
  • Streamlined auto-arrange — the confirmation is now a simple prompt
  • Live status bar — shows FFmpeg readiness, the active grid, and feed count

🐛 Bug Fixes

  • Grids now stay in sync across the tab strip, quick switcher, and All grids view after rename/duplicate/delete/import
  • Layout calculations measure the real canvas, so feeds fit the window accurately

Version 2.0.0

Major Feature Release - Automation & Advanced Controls

🚀 New Features

  • REST API - Full programmatic control with authentication and rate limiting
  • M3U Playlist Import - Import playlists with intelligent auto-arrangement
  • RTSP Stream Support - Production-ready IP camera streaming with FFmpeg transcoding
  • Sound Management System - Global and per-stream audio controls
  • Auto-Start Streams - Automatically play all streams on launch
  • Auto-Restart Failed Streams - Automatic retry with exponential backoff
  • Auto-Arrange Grid - Intelligent grid layout

📚 Documentation

  • Complete REST API documentation (docs/API.md)
  • Bruno API test collection (bruno/README.md)
  • Comprehensive RTSP setup guide in README

🐛 Bug Fixes

  • Fixed Linux auto-updater errors
  • Improved CSP handling for Twitch embeds
  • Enhanced error handling across all components

Version 1.2.0

Major Performance Update & Enhanced Features

🚀 Performance Optimizations

  • Removed artificial loading delays - Faster application startup
  • Virtual grid rendering - Implemented react-window for efficient handling of large grids
  • Player pool system - Reuses video player instances to optimize memory usage
  • Debounced state updates - Reduced I/O operations with intelligent 5-second intervals
  • Web worker integration - Layout calculations now run in separate thread for UI responsiveness
  • Lazy loading - Chat components load on-demand for faster initial render
  • Code splitting - Optimized bundle sizes with manual chunking strategy
  • Performance monitoring - Built-in hooks to track and analyze app performance

💾 Enhanced Saving System

  • Aggressive auto-save - Immediate saves on all critical operations:
    • Stream addition/removal
    • Stream property updates
    • Layout changes (resize/reposition)
    • Grid switching
    • Application quit
    • Browser refresh/close

🎯 New Features

  • Local file support - Play video files directly from your computer
  • Grid management system - Save, load, and organize multiple grid configurations
  • Import grid configurations - Share and import grid setups from JSON files
  • Auto-generated avatars - Streams without logos get unique identicon avatars
  • Comprehensive error handling - Improved error boundaries and user feedback

🐛 Bug Fixes

  • Fixed grid rename functionality
  • Resolved Twitch streams not starting (added required parent parameter)
  • Improved drag functionality and text selection handling
  • Fixed duplicate logo URL issues

Version 1.1.0

Multi-Platform Streaming Support

  • Added DASH streaming protocol support
  • Integrated YouTube live chat functionality
  • Added Twitch stream and chat support
  • Improved URL handling and stream type detection
  • Enhanced drag-and-drop functionality
  • Added GitHub version checking with update alerts

Version 1.0.0

Initial Release

  • Core multi-stream grid functionality
  • Drag-and-drop stream repositioning
  • Resizable stream windows
  • Stream import/export capabilities
  • Cross-platform support (Windows, macOS, Linux)
  • HLS streaming support
  • Persistent layout saving

🤝 Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.