StreamGrid

Your Streams, Your Layout, Your Way

StreamGrid revolutionizes multi-stream viewing by giving you complete freedom over your layout. Want a massive main stream surrounded by smaller feeds? Or five equally-sized streams? Or any other arrangement you can imagine? StreamGrid makes it possible. Built with Electron, React, and TypeScript, it's the perfect solution for watching multiple streams exactly the way you want.

📚 Documentation: API Reference | Bruno API Collection

StreamGrid.mp4

✨ Features

• Ultimate Layout Flexibility:
  • Create ANY layout you can imagine - from 2 streams to 5+ streams
  • Make streams any size you want - go big with your main stream while keeping others visible
  • Perfect for scenarios like:
    • One large main stream surrounded by smaller secondary streams
    • Equal-sized grid for monitoring multiple sources
    • Custom arrangements for esports tournaments or multi-angle viewing
• Intuitive Controls:
  • Drag & Drop: Instantly reorganize your layout
  • Resize Handles: Click and drag to adjust stream sizes in real-time
• Stream Management:
  • Add new streams with custom names and logos
  • Remove streams with a single click
  • Persistent layout saving with aggressive auto-save
  • Export and Import your stream setups to share with friends
• Grid Management System:
  • Save multiple grid configurations
  • Switch between different saved layouts instantly
  • Rename and organize your grid presets
  • Perfect for different viewing scenarios (gaming, monitoring, events)
• Responsive Design: Automatically adjusts to window size while maintaining video aspect ratios
• Stream Platform Support:
  • Local Files: Play video files directly from your computer
  • YouTube: Support for standard videos, live streams, and shorts
  • Twitch: Support for channel live streams
  • RTSP Streams (New in v2.0.0): Support for RTSP/RTSPS camera and streaming sources with automatic transcoding
    • Requires FFmpeg installation
    • Supports authentication (username/password in URL)
    • Low-latency HLS transcoding
    • Multiple concurrent RTSP streams
    • Automatic retry on connection loss
  • HLS Support: Compatible with HTTP Live Streaming (HLS) video sources
  • MPEG-DASH Support: Compatible with Dynamic Adaptive Streaming over HTTP (DASH) video sources
• Chat Integration:
  • YouTube chat for live streams and videos
  • Twitch chat for live streams
  • Draggable and resizable chat windows
• Cross-Platform: Available for Windows, macOS, and Linux
• REST API for Automation (New in v2.0.0):
  • Full programmatic control via REST API
  • Add, update, and remove streams remotely
  • Manage grid configurations programmatically
  • API key authentication with rate limiting
  • API documentation with Bruno test collection
• M3U Playlist Import (New in v2.0.0):
  • Import M3U/M3U8 playlists with one click
  • Automatic grid arrangement with intelligent layout
• Advanced Sound Management (New in v2.0.0):
  • Global mute/unmute all streams
  • Per-stream audio controls
  • Auto-start streams muted option
• Auto-Start & Auto-Restart (New in v2.0.0):
  • Automatically play all streams on app launch
  • Automatic retry for failed streams with exponential backoff

🚀 Getting Started

Option 1: Download Pre-built Application (Recommended)

1. Visit the Releases section
2. Download the latest version for your platform:
   • Windows: streamgrid-2.0.0-win-x64.exe
   • macOS (Intel): streamgrid-2.0.0-mac-x64.dmg
   • macOS (Apple Silicon): streamgrid-2.0.0-mac-arm64.dmg
   • Linux: streamgrid-2.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

2. Install dependencies

npm install

3. Run in development mode (for testing/development)

npm run dev

4. Build the application (for production)

# Build for your current platform
npm run build

# Or build for specific platforms:
npm run build:win    # Windows
npm run build:mac    # macOS
npm run build:linux  # Linux

5. Find your built application
   • Windows: dist/streamgrid-2.0.0-win-x64.exe
   • macOS: dist/streamgrid-2.0.0-mac-*.dmg
   • Linux: dist/streamgrid-2.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 browser
4. Low latency (~2-3 seconds) with automatic retry on connection loss

Adding an RTSP Stream

1. Click "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

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 wired network connection for cameras when possible
• Close unused RTSP streams to free resources
• RTSP transcoding uses ~100MB RAM per stream

🛠 Tech Stack

• Framework: Electron with electron-vite
• Frontend:
  • React
  • TypeScript
  • Material-UI
• State Management: Zustand
• Video Playback & Streaming:
  • React Player - Multi-platform video support
  • HLS.js - HLS streaming support
  • dash.js - MPEG-DASH streaming support
  • YouTube Player API integration
  • Twitch Player API integration
• Layout: React Grid Layout

🏗 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
│   │   │   ├── types/       # TypeScript type definitions
│   │   │   ├── 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-builder.yml    # Electron Builder configuration
├── electron.vite.config.ts # Vite configuration
├── package.json           # Project dependencies
└── tsconfig.json          # TypeScript configuration

📋 Changelog

Version 2.0.0 (Latest)

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 with row-budget algorithm

📚 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.