{"id":29353721,"url":"https://github.com/streamwall/streamwall-suite","last_synced_at":"2026-04-09T23:01:47.215Z","repository":{"id":303337308,"uuid":"1015135531","full_name":"streamwall/streamwall-suite","owner":"streamwall","description":"Comprehensive livestream management platform - orchestration repository for the Streamwall ecosystem","archived":false,"fork":false,"pushed_at":"2025-07-15T23:46:30.000Z","size":3076,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-16T18:59:56.878Z","etag":null,"topics":["discord-bot","docker","electron","livestream","microservices","nodejs","rails","twitch","typescript"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/streamwall.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES_SUMMARY.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-07T04:07:06.000Z","updated_at":"2025-07-15T23:46:33.000Z","dependencies_parsed_at":"2025-07-07T05:25:12.276Z","dependency_job_id":"0e84715d-f6f9-4373-9d57-25fdc5233c4e","html_url":"https://github.com/streamwall/streamwall-suite","commit_stats":null,"previous_names":["streamwall/streamwall-suite"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/streamwall/streamwall-suite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamwall%2Fstreamwall-suite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamwall%2Fstreamwall-suite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamwall%2Fstreamwall-suite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamwall%2Fstreamwall-suite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/streamwall","download_url":"https://codeload.github.com/streamwall/streamwall-suite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/streamwall%2Fstreamwall-suite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278981518,"owners_count":26079640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord-bot","docker","electron","livestream","microservices","nodejs","rails","twitch","typescript"],"created_at":"2025-07-09T02:09:02.139Z","updated_at":"2025-10-08T17:10:28.822Z","avatar_url":"https://github.com/streamwall.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Streamwall\n\nA comprehensive livestream management platform that automatically discovers, monitors, and displays multiple livestreams in a customizable grid layout.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Quick Start](#quick-start)\n- [Architecture](#architecture)\n- [Development](#development)\n- [Services](#services)\n- [Configuration](#configuration)\n- [API Reference](#api-reference)\n- [Deployment](#deployment)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n\n## Overview\n\nStreamwall helps communities track and display multiple livestreams from protests, events, and breaking news. It consists of:\n\n- **Automated Discovery** - Bots monitor Discord channels and Twitch chat for stream links\n- **Real-time Monitoring** - Continuously checks stream status and updates metadata\n- **Flexible Display** - Desktop app shows multiple streams in a customizable grid\n- **Centralized API** - REST API with real-time updates via WebSockets\n\n### Key Features\n\n- 🔍 Auto-discovers streams from Discord/Twitch chat\n- 📊 Real-time stream status monitoring\n- 🖥️ Multi-stream grid display with audio control\n- 🔄 Automatic stream rotation for large collections\n- 📍 Location tracking and mapping\n- 👥 Multi-user support with admin controls\n- 🔌 Extensible plugin architecture\n\n## Quick Start\n\n### Instant Demo (Recommended First Step)\n\n```bash\ngit clone --recursive https://github.com/streamwall/streamwall-suite.git\ncd streamwall-suite\nmake              # Interactive setup - just follow the prompts!\n```\n\nThe Makefile will detect if you're new and offer:\n- **Demo mode** - Try it out with sample data and mock integrations\n- **Setup mode** - Configure for real use with your Discord/Twitch accounts\n\n### Essential Commands\n\n```bash\nmake              # Start here - smart mode detection\nmake demo         # Quick demo with sample data\nmake up           # Start all services\nmake down         # Stop all services\nmake logs         # View logs (or logs SERVICE=name)\nmake status       # Check what's running\nmake shell        # Open container shell\nmake help         # See all available commands\n```\n\n## Architecture\n\n### System Overview\n\n```mermaid\ngraph TB\n    %% External Sources\n    Discord[\"💬 Discord\u003cbr/\u003eChannels\"]\n    Twitch[\"📺 Twitch\u003cbr/\u003eChat\"]\n    Users[\"👥 Users\u003cbr/\u003e(Web/Mobile)\"]\n    \n    %% Core Services\n    Monitor[\"🤖 Livestream Link Monitor\u003cbr/\u003e(Node.js Bot)\"]\n    API[\"🔧 StreamSource API\u003cbr/\u003e(Rails + ActionCable)\"]\n    Updater[\"🔄 Livesheet Updater\u003cbr/\u003e(Status Checker)\"]\n    Display[\"🖥️ Streamwall Desktop\u003cbr/\u003e(Electron + React)\"]\n    \n    %% Data Stores\n    DB[(PostgreSQL\u003cbr/\u003eDatabase)]\n    Redis[(Redis\u003cbr/\u003eCache/PubSub)]\n    \n    %% Stream Platforms\n    Platforms[\"📹 Stream Platforms\u003cbr/\u003eTwitch • YouTube\u003cbr/\u003eFacebook • Kick • TikTok\"]\n    \n    %% Data Flow\n    Discord --\u003e Monitor\n    Twitch --\u003e Monitor\n    Monitor --\u003e|\"Discovers \u0026 Validates\u003cbr/\u003eStream URLs\"| API\n    \n    API \u003c--\u003e|\"Stores/Retrieves\"| DB\n    API \u003c--\u003e|\"Cache \u0026 PubSub\"| Redis\n    API --\u003e|\"WebSocket\u003cbr/\u003eUpdates\"| Display\n    API --\u003e|\"REST API\"| Users\n    \n    Updater --\u003e|\"Checks Status\"| Platforms\n    Updater --\u003e|\"Updates Status\"| API\n    \n    Display --\u003e|\"Fetches Streams\"| API\n    Display --\u003e|\"Embeds Players\"| Platforms\n    \n    %% Styling\n    classDef service fill:#4A90E2,stroke:#2E5C8A,color:#fff\n    classDef external fill:#50C878,stroke:#3A9B5C,color:#fff\n    classDef storage fill:#FF6B6B,stroke:#C54545,color:#fff\n    classDef platform fill:#9B59B6,stroke:#7D3C98,color:#fff\n    \n    class Monitor,API,Updater,Display service\n    class Discord,Twitch,Users external\n    class DB,Redis storage\n    class Platforms platform\n```\n\n### Core Services\n\n1. **StreamSource** (Rails API)\n   - Central data store and REST API\n   - Real-time updates via ActionCable WebSockets\n   - User authentication and authorization\n   - Stream metadata management\n\n2. **Livestream Link Monitor** (Node.js)\n   - Discord bot that watches for stream URLs\n   - Twitch chat monitor for stream discovery\n   - Intelligent deduplication and validation\n   - Posts discovered streams to API\n\n3. **Livesheet Updater** (Node.js)\n   - Monitors stream health and status\n   - Updates live/offline state\n   - Batch processing for efficiency\n\n4. **Streamwall** (Electron + React)\n   - Desktop application for display\n   - Customizable grid layouts\n   - Per-stream audio control\n   - Keyboard shortcuts for power users\n\n### Data Flow\n\n1. Users post stream links in Discord/Twitch\n2. Monitor bot detects and validates URLs\n3. Validated streams posted to StreamSource API\n4. Livesheet Updater checks stream health\n5. Streamwall desktop app fetches and displays streams\n6. Real-time updates flow via WebSockets\n\n## Development\n\n### Prerequisites\n\n- Docker \u0026 Docker Compose\n- Git\n- Node.js 18+ (for Streamwall desktop app)\n- 8GB RAM recommended\n- Ports 3000, 5432, 6379 available\n\n### Development Setup\n\n```bash\n# Clone with submodules\ngit clone --recursive https://github.com/streamwall/streamwall-suite.git\ncd streamwall\n\n# Interactive setup\nmake setup\n\n# Start in development mode\nmake up\n\n# View logs\nmake logs\n\n# Open a service shell\nmake shell SERVICE=streamsource\n```\n\n### Development Workflow\n\n1. **Making Changes**\n   ```bash\n   # Create feature branch\n   git checkout -b feature/my-feature\n\n   # Make changes, test locally\n   make up\n   make logs\n\n   # Run tests\n   cd streamsource \u0026\u0026 bundle exec rspec\n   cd livestream-link-monitor \u0026\u0026 npm test\n   ```\n\n2. **Database Changes**\n   ```bash\n   # Create migration\n   make shell SERVICE=streamsource\n   rails generate migration AddFieldToStreams field:type\n   rails db:migrate\n   ```\n\n3. **Debugging**\n   ```bash\n   # Check service health\n   make status\n\n   # View specific service logs\n   make logs SERVICE=streamsource\n\n   # Access Rails console\n   make shell SERVICE=streamsource\n   rails console\n   ```\n\n### Code Style\n\n- **Ruby**: Follow Ruby Style Guide, use RuboCop\n- **JavaScript**: ESLint with Airbnb config\n- **React**: Functional components with hooks\n- **Git**: Conventional commits (feat:, fix:, docs:)\n\n## Services\n\n### StreamSource API\n\nThe central Rails API that manages all stream data.\n\n**Key Endpoints:**\n- `GET /api/v1/streams` - List all streams\n- `POST /api/v1/streams` - Create stream\n- `GET /api/v1/streams/:id` - Get stream details\n- `PATCH /api/v1/streams/:id` - Update stream\n- `DELETE /api/v1/streams/:id` - Delete stream\n\n**WebSocket Channels:**\n- `StreamsChannel` - Real-time stream updates\n- `PresenceChannel` - User presence tracking\n\n**Authentication:**\n- JWT-based authentication\n- Bearer token in Authorization header\n- Admin role for privileged operations\n\n### Livestream Link Monitor\n\nDiscord/Twitch bot for automated stream discovery.\n\n**Features:**\n- Multi-server Discord support\n- Twitch chat monitoring\n- URL validation and deduplication\n- Location extraction from messages\n- Rate limiting and spam protection\n\n**Supported Platforms:**\n- Twitch (twitch.tv)\n- YouTube (youtube.com, youtu.be)\n- Facebook (facebook.com/*/videos)\n- Kick (kick.com)\n- TikTok (tiktok.com)\n\n### Livesheet Updater\n\nMonitors stream health and updates status.\n\n**Features:**\n- Parallel stream checking\n- Retry logic for transient failures\n- Batch updates for efficiency\n- Configurable check intervals\n\n### Streamwall Desktop\n\nElectron app for displaying multiple streams.\n\n**Features:**\n- Drag-and-drop grid layout\n- Per-stream audio control\n- Fullscreen mode\n- Keyboard shortcuts\n- Stream rotation\n- Layout persistence\n\n**Keyboard Shortcuts:**\n- `Space` - Toggle selected stream audio\n- `M` - Mute all streams\n- `F` - Fullscreen mode\n- `R` - Rotate streams\n- `1-9` - Quick switch layouts\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file from `.env.example`:\n\n```bash\n# Core Settings\nNODE_ENV=production\nRAILS_ENV=production\n\n# Database\nPOSTGRES_USER=streamwall\nPOSTGRES_PASSWORD=secure_password\nPOSTGRES_DB=streamwall_production\nDATABASE_URL=postgresql://streamwall:secure_password@postgres:5432/streamwall_production\n\n# Redis\nREDIS_URL=redis://redis:6379/0\n\n# Security (generate with: openssl rand -hex 32)\nSECRET_KEY_BASE=your_secret_key_base\nJWT_SECRET=your_jwt_secret\nSTREAMSOURCE_API_KEY=your_api_key\n\n# Discord Bot (optional)\nDISCORD_TOKEN=your_discord_bot_token\nDISCORD_CHANNEL_ID=channel_to_monitor\n\n# Twitch Bot (optional)\nTWITCH_CHANNEL=channel_to_monitor\nTWITCH_USERNAME=your_bot_username\nTWITCH_OAUTH_TOKEN=oauth:your_token\n```\n\n### Service Configuration\n\nEach service can be configured through environment variables:\n\n**StreamSource:**\n- `RAILS_MAX_THREADS` - Puma thread count\n- `WEB_CONCURRENCY` - Puma worker count\n- `RAILS_LOG_LEVEL` - Logging verbosity\n\n**Monitor Bot:**\n- `BACKEND_TYPE` - 'streamsource' (API backend)\n- `CHECK_INTERVAL` - How often to process messages\n- `LOCATION_MAPPING` - Enable location detection\n\n**Updater:**\n- `UPDATE_INTERVAL` - Check frequency in seconds\n- `CONCURRENT_CHECKS` - Parallel check limit\n- `TIMEOUT` - HTTP request timeout\n\n## API Reference\n\n### Authentication\n\n```bash\n# Login\nPOST /api/v1/auth/login\n{\n  \"email\": \"user@example.com\",\n  \"password\": \"password\"\n}\n\n# Returns\n{\n  \"token\": \"jwt_token\",\n  \"user\": { \"id\": 1, \"email\": \"user@example.com\" }\n}\n\n# Use token in headers\nAuthorization: Bearer jwt_token\n```\n\n### Streams API\n\n```bash\n# List streams with filters\nGET /api/v1/streams?status=live\u0026location=Seattle\u0026platform=twitch\n\n# Create stream\nPOST /api/v1/streams\n{\n  \"url\": \"https://twitch.tv/example\",\n  \"title\": \"Seattle Protest\",\n  \"location\": \"Seattle, WA\"\n}\n\n# Update stream\nPATCH /api/v1/streams/123\n{\n  \"status\": \"offline\",\n  \"notes\": \"Stream ended at 10pm\"\n}\n```\n\n### WebSocket Subscriptions\n\n```javascript\n// Connect to ActionCable\nconst cable = ActionCable.createConsumer('ws://localhost:3000/cable');\n\n// Subscribe to streams channel\nconst subscription = cable.subscriptions.create('StreamsChannel', {\n  received(data) {\n    console.log('Stream update:', data);\n  }\n});\n```\n\n## Deployment\n\n### Production with Docker\n\n1. **Prepare Environment**\n   ```bash\n   # Copy and edit production env\n   cp .env.example .env.production\n   # Edit with production values\n\n   # Set secure passwords and keys\n   openssl rand -hex 32  # For SECRET_KEY_BASE\n   openssl rand -hex 32  # For JWT_SECRET\n   ```\n\n2. **Deploy with Docker Compose**\n   ```bash\n   # Use production compose file\n   docker compose -f docker-compose.production.yml up -d\n\n   # Run migrations\n   docker compose exec streamsource rails db:migrate\n\n   # Create admin user\n   docker compose exec streamsource rails console\n   \u003e User.create!(email: \"admin@example.com\", password: \"secure_password\", admin: true)\n   ```\n\n3. **Configure Reverse Proxy (nginx)**\n   ```nginx\n   server {\n     listen 80;\n     server_name streamwall.example.com;\n\n     location / {\n       proxy_pass http://localhost:3000;\n       proxy_set_header Host $host;\n       proxy_set_header X-Real-IP $remote_addr;\n     }\n\n     location /cable {\n       proxy_pass http://localhost:3000;\n       proxy_http_version 1.1;\n       proxy_set_header Upgrade $http_upgrade;\n       proxy_set_header Connection \"upgrade\";\n     }\n   }\n   ```\n\n### SSL/TLS Setup\n\n```bash\n# Using Let's Encrypt\ncertbot --nginx -d streamwall.example.com\n\n# Update nginx config for SSL\n# Certbot will handle this automatically\n```\n\n### Monitoring\n\n- Use `make status` to check service health\n- Monitor logs with `make logs`\n- Set up alerts for service failures\n- Track API response times\n- Monitor disk usage for PostgreSQL\n\n## Troubleshooting\n\n### Common Issues\n\n**Services won't start:**\n```bash\n# Check Docker\ndocker info\n\n# Check ports\nlsof -i :3000  # Should be free\n\n# Reset everything\nmake clean\nmake up\n```\n\n**Can't connect to API:**\n```bash\n# Check service health\ncurl http://localhost:3000/health\n\n# Check logs\nmake logs SERVICE=streamsource\n\n# Verify database\nmake shell SERVICE=postgres\npsql -U streamwall -d streamwall_production\n```\n\n**Discord bot not working:**\n```bash\n# Verify token\necho $DISCORD_TOKEN\n\n# Check bot permissions in Discord\n# Needs: Read Messages, Send Messages, Read Message History\n\n# Check logs\nmake logs SERVICE=livestream-monitor\n```\n\n**Streams not updating:**\n```bash\n# Check updater service\nmake logs SERVICE=livesheet-updater\n\n# Verify API connectivity\ncurl http://localhost:3000/api/v1/streams\n\n# Check Redis\nmake shell SERVICE=redis\nredis-cli ping\n```\n\n### Debug Mode\n\nEnable debug logging:\n```bash\n# In .env\nLOG_LEVEL=debug\nRAILS_LOG_LEVEL=debug\n\n# Restart services\nmake restart\n```\n\n## Contributing\n\n### Getting Started\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Contribution Guidelines\n\n- Write tests for new features\n- Update documentation\n- Follow existing code style\n- Add entries to CHANGELOG\n- Keep commits atomic and descriptive\n\n### Testing\n\n```bash\n# Run all tests\nmake test\n\n# Service-specific tests\ncd streamsource \u0026\u0026 bundle exec rspec\ncd livestream-link-monitor \u0026\u0026 npm test\ncd streamwall \u0026\u0026 npm test\n```\n\n### Reporting Issues\n\n- Use GitHub Issues\n- Include reproduction steps\n- Provide error messages and logs\n- Specify your environment\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Acknowledgments\n\n- Built for activists and journalists covering protests\n- Inspired by the need for better real-time stream aggregation\n- Thanks to all contributors and testers\n\n---\n\nFor more details on specific services, see their README files in each service directory.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamwall%2Fstreamwall-suite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstreamwall%2Fstreamwall-suite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstreamwall%2Fstreamwall-suite/lists"}