{"id":51177060,"url":"https://github.com/tboy1337/mediarelay","last_synced_at":"2026-06-27T05:00:35.487Z","repository":{"id":315500040,"uuid":"1059761867","full_name":"tboy1337/MediaRelay","owner":"tboy1337","description":"A video streaming server that allows you to securely share your personal video library over the internet. Built with robust security, monitoring, and performance features.","archived":false,"fork":false,"pushed_at":"2026-06-25T11:56:09.000Z","size":358,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-25T12:18:10.223Z","etag":null,"topics":["media","online","python","relay","server","share","stream","streaming","video"],"latest_commit_sha":null,"homepage":"https://tboy1337.github.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tboy1337.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["tboy1337"],"patreon":"tboy1337","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"tboy1337","thanks_dev":null,"custom":null}},"created_at":"2025-09-18T23:01:41.000Z","updated_at":"2026-06-25T11:54:18.000Z","dependencies_parsed_at":"2025-09-19T01:19:45.206Z","dependency_job_id":"b0809fec-ca41-4402-b050-c7d542b04f6f","html_url":"https://github.com/tboy1337/MediaRelay","commit_stats":null,"previous_names":["tboy1337/mediarelay"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/tboy1337/MediaRelay","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FMediaRelay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FMediaRelay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FMediaRelay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FMediaRelay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tboy1337","download_url":"https://codeload.github.com/tboy1337/MediaRelay/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FMediaRelay/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34841990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"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":["media","online","python","relay","server","share","stream","streaming","video"],"created_at":"2026-06-27T05:00:18.349Z","updated_at":"2026-06-27T05:00:35.467Z","avatar_url":"https://github.com/tboy1337.png","language":"Python","funding_links":["https://github.com/sponsors/tboy1337","https://patreon.com/tboy1337","https://buymeacoffee.com/tboy1337"],"categories":[],"sub_categories":[],"readme":"# MediaRelay\r\n\r\nA video streaming server that allows you to securely share your personal video library over the internet. Built with robust security, monitoring, and performance features.\r\n\r\n## ✨ Features\r\n\r\n### 🔒 Security\r\n- **Multi-layer Authentication**: HTTP Basic Auth + Session Management\r\n- **Path Traversal Protection**: Prevents unauthorized file access\r\n- **Security Headers**: XSS, SameSite cookie protection, clickjacking protection\r\n- **Rate Limiting**: Configurable request throttling\r\n- **Security Audit Logging**: Comprehensive security event tracking\r\n- **Session Management**: Secure sessions with configurable timeouts\r\n\r\n### 🎥 Media Streaming  \r\n- **Universal Format Support**: MP4, MKV, AVI, MOV, WebM, M4V, FLV\r\n- **Subtitle Support**: SRT and WebVTT (`.srt`, `.vtt`) subtitle files\r\n- **Audio Support**: MP3, AAC, OGG, WAV\r\n- **Range Requests**: Efficient streaming with seek support\r\n- **Mobile Optimized**: Responsive design for all devices\r\n\r\n### 📊 Monitoring \u0026 Performance\r\n- **Health Check Endpoint**: Real-time server status\r\n- **Performance Metrics**: Request timing and throughput monitoring  \r\n- **Comprehensive Logging**: Application, security, error, and performance logs\r\n- **Multi-threaded**: Configurable concurrency for high performance\r\n- **Resource Monitoring**: CPU, memory, and disk snapshot logged at server startup (`log_system_info`)\r\n\r\n### 🛠️ Advanced Features\r\n- **Environment Configuration**: Full environment variable support\r\n- **90%+ Test Coverage**: Comprehensive test suite with branch coverage and security tests\r\n- **Service Management**: System service configurations — see [Deployment Guide](docs/deployment_guide.md)\r\n- **Log Rotation**: Automatic log rotation and archival\r\n- **API Support**: RESTful JSON API for integration\r\n\r\n## 📋 Requirements\r\n\r\n- **Python**: 3.12 or higher\r\n- **Operating System**: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+ recommended)\r\n- **Memory**: Minimum 2GB RAM, 4GB+ recommended for optimal performance\r\n- **Storage**: 1GB for application, additional space for video content\r\n- **Network**: Stable internet connection for remote access\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Installation\r\n\r\n**Recommended — install from PyPI:**\r\n\r\n```bash\r\n# Create virtual environment (recommended)\r\npython -m venv venv\r\nsource venv/bin/activate  # Linux/macOS\r\nvenv\\Scripts\\activate     # Windows\r\n\r\npip install mediarelay\r\n```\r\n\r\nThat installs the `mediarelay`, `mediarelay-config`, `mediarelay-genpass`, and `mediarelay-validate` commands. No need to clone the repository.\r\n\r\n**Windows users** can alternatively download a pre-built executable from [GitHub Releases](https://github.com/tboy1337/MediaRelay/releases). Place a `.env` file in the same directory as `MediaRelay.exe` and run the executable.\r\n\r\n**From source (development or contributing):**\r\n\r\n```bash\r\ngit clone https://github.com/tboy1337/MediaRelay.git\r\ncd MediaRelay\r\n\r\npython -m venv venv\r\nsource venv/bin/activate  # Linux/macOS\r\nvenv\\Scripts\\activate     # Windows\r\n\r\npip install -e \".[dev]\"\r\n```\r\n\r\nUse `pip install -e .` instead of `pip install -e \".[dev]\"` if you only need the application without test and lint tools.\r\n\r\n### 2. Configuration\r\n\r\n```bash\r\n# Generate sample configuration\r\nmediarelay-config\r\n\r\n# Copy and edit configuration\r\ncopy .env.example .env   # Windows\r\ncp .env.example .env     # Linux/macOS\r\n# Edit .env with your settings\r\n```\r\n\r\n### 3. Security Setup\r\n\r\nGenerate required security credentials:\r\n\r\n```bash\r\n# Generate Flask secret key and password hash\r\nmediarelay-genpass\r\n```\r\n\r\nThe script will:\r\n1. **Ask for your preferred username** (e.g., `admin`, `user`, etc.)\r\n2. **Generate or create your password**:\r\n   - Choose 'y' to generate a secure 35-character password automatically\r\n   - Choose 'n' to enter your own password (minimum 12 characters)\r\n3. **Generate a Flask secret key** (for session security)\r\n4. **Create a password hash** (for secure authentication)\r\n\r\n**Example output:**\r\n```\r\n============================================================\r\nCONFIGURATION VALUES FOR .env FILE\r\n============================================================\r\nVIDEO_SERVER_SECRET_KEY=a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890\r\nVIDEO_SERVER_USERNAME=admin\r\nVIDEO_SERVER_PASSWORD_HASH=scrypt:32768:8:1$abc123$def456...\r\n```\r\n\r\n**Important Security Notes**: \r\n- **Save your password securely** - you'll need it to log in to the web interface\r\n- **Copy all three generated values** to your `.env` file immediately\r\n- **Never share your secret key or password hash** - treat them like private keys\r\n- **Regenerate credentials** if you suspect they've been compromised\r\n- The script uses **cryptographically secure random generation** for maximum security\r\n\r\n### 4. Start the Server\r\n\r\n```bash\r\n# Start the server\r\nmediarelay\r\n\r\n# Or with custom configuration\r\nmediarelay --host 0.0.0.0 --port 8080\r\n```\r\n\r\nOnce the server is running, you can access it in your web browser at:\r\n- **Local access**: http://localhost:5000\r\n- **Network access**: http://YOUR_IP_ADDRESS:5000 (if configured with --host 0.0.0.0)\r\n\r\n### 🔧 Configuration\r\n\r\n#### Step-by-Step Configuration Process\r\n\r\n1. **Create your configuration file** (if you do not already have `.env.example` from a source checkout, run `mediarelay-config` first):\r\n   ```bash\r\n   copy .env.example .env   # Windows\r\n   cp .env.example .env     # Linux/macOS\r\n   ```\r\n\r\n2. **Generate security credentials**:\r\n   ```bash\r\n   mediarelay-genpass\r\n   ```\r\n\r\n3. **Update your `.env` file** with the generated values:\r\n   - Replace `VIDEO_SERVER_SECRET_KEY=your-secret-key-here` with your generated secret key\r\n   - Replace `VIDEO_SERVER_USERNAME=tboy1337` with your chosen username  \r\n   - Replace `VIDEO_SERVER_PASSWORD_HASH=your-password-hash-here` with your generated hash\r\n\r\n4. **Configure other settings** as needed (video directory, port, etc.)\r\n\r\n5. **Validate configuration** before production deployment:\r\n   ```bash\r\n   mediarelay-validate\r\n   ```\r\n\r\n6. **Start the server** (configuration is validated on startup):\r\n   ```bash\r\n   mediarelay\r\n   ```\r\n\r\n#### Key Environment Variables\r\n\r\nSee [Configuration Reference](docs/configuration_reference.md) for the complete list. Production-critical settings:\r\n\r\n```bash\r\n# Server Configuration\r\nVIDEO_SERVER_HOST=0.0.0.0\r\nVIDEO_SERVER_PORT=5000  \r\nVIDEO_SERVER_DIRECTORY=/path/to/videos\r\nVIDEO_SERVER_THREADS=6\r\n\r\n# Security (Required - Generate using mediarelay-genpass)\r\nVIDEO_SERVER_USERNAME=your_username                    # Your chosen username\r\nVIDEO_SERVER_PASSWORD_HASH=your_secure_hash            # Generated password hash\r\nVIDEO_SERVER_SECRET_KEY=your_secret_key                # Generated Flask secret key\r\n\r\n# Production mode (required for live deployment; enforces secure cookies and credential checks)\r\nVIDEO_SERVER_PRODUCTION=true\r\nVIDEO_SERVER_RATE_LIMIT=true                           # Required in production\r\n\r\n# Reverse proxy (set true ONLY when behind a trusted reverse proxy)\r\nVIDEO_SERVER_BEHIND_PROXY=false\r\nVIDEO_SERVER_PROXY_TRUSTED=false                       # Required true with BEHIND_PROXY in production\r\n\r\n# Optional monitoring token for detailed /health via X-Health-Token\r\n# VIDEO_SERVER_HEALTH_TOKEN=\r\n\r\n# Performance\r\nVIDEO_SERVER_RATE_LIMIT_PER_MIN=60\r\nVIDEO_SERVER_STREAM_RATE_LIMIT_PER_MINUTE=600\r\nVIDEO_SERVER_SESSION_TIMEOUT=3600\r\nVIDEO_SERVER_MAX_FILE_SIZE=21474836480  # 20GB default, set to 0 to disable\r\n\r\n# Session Cookies (set Secure=true when serving over HTTPS)\r\nVIDEO_SERVER_SESSION_COOKIE_SECURE=true\r\nVIDEO_SERVER_SESSION_COOKIE_HTTPONLY=true\r\nVIDEO_SERVER_SESSION_COOKIE_SAMESITE=Strict\r\n\r\n# Account lockout (failed login protection)\r\nVIDEO_SERVER_LOCKOUT_MAX_ATTEMPTS=5\r\nVIDEO_SERVER_LOCKOUT_DURATION=900\r\n\r\n# Logging\r\nVIDEO_SERVER_LOG_LEVEL=INFO\r\nVIDEO_SERVER_LOG_DIR=./logs\r\nVIDEO_SERVER_LOG_CONSOLE=true\r\n```\r\n\r\n## Development\r\n\r\nRun the full quality gate locally:\r\n\r\n```bash\r\npython scripts/verify.py\r\n```\r\n\r\nThis runs black, isort, mypy, bandit, pylint, pip-audit, and pytest with 90% branch coverage.\r\n\r\n## 🔒 Security\r\n\r\n### Authentication \u0026 Authorization\r\n\r\n```python\r\n# Multi-layer authentication\r\nHTTP_BASIC_AUTH + SESSION_MANAGEMENT + SAMESITE_COOKIES\r\n```\r\n\r\n### Security Headers\r\n\r\n```http\r\nX-Content-Type-Options: nosniff\r\nX-Frame-Options: SAMEORIGIN\r\nCross-Origin-Opener-Policy: same-origin\r\nCross-Origin-Resource-Policy: same-origin\r\nStrict-Transport-Security: max-age=31536000  # When VIDEO_SERVER_HSTS=true or VIDEO_SERVER_BEHIND_PROXY=true\r\nContent-Security-Policy: default-src 'self'; media-src 'self'; style-src 'self' 'unsafe-inline'\r\nReferrer-Policy: strict-origin-when-cross-origin\r\nPermissions-Policy: accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()\r\nX-Permitted-Cross-Domain-Policies: none\r\n```\r\n\r\n`X-XSS-Protection` is intentionally omitted (deprecated in modern browsers).\r\n\r\n### Reverse Proxy Warning\r\n\r\nSet `VIDEO_SERVER_BEHIND_PROXY=true` and `VIDEO_SERVER_PROXY_TRUSTED=true` only when MediaRelay runs behind a trusted reverse proxy (nginx, Caddy, etc.) and is bound to localhost. Without `PROXY_TRUSTED`, client IP and rate limits use the direct connection address, not `X-Forwarded-For`. Direct internet exposure with proxy headers enabled allows IP spoofing. See [SECURITY.md](SECURITY.md).\r\n\r\n### Security Monitoring\r\n\r\nAll security events are logged:\r\n- Authentication attempts (success/failure)\r\n- Path traversal attempts\r\n- Rate limit violations\r\n- File access attempts\r\n- Account lockout events\r\n\r\nLogout requires `POST /logout` with a CSRF token via the `X-CSRF-Token` header or `csrf_token` form field (see [API documentation](docs/api_documentation.md)). `GET /logout` is rejected with `405 Method Not Allowed`.\r\n\r\n`VIDEO_SERVER_HOST` is validated at startup (must be a valid IP address or hostname).\r\n\r\n## 📈 Performance\r\n\r\n### Performance Features\r\n\r\n- **Multi-threading**: Configurable worker threads\r\n- **Range Requests**: Efficient video streaming\r\n- **HTTP Caching**: Browser caching for static content\r\n- **Connection Pooling**: Supports multiple users simultaneously\r\n- **Memory Management**: Automatic resource cleanup\r\n\r\n## 📊 API Usage\r\n\r\n### Available Endpoints\r\n\r\n```bash\r\n# Health check (no auth required)\r\nGET /health\r\n\r\n# Directory listing  \r\nGET /api/files?path=movies\r\n\r\n# File streaming\r\nGET /stream/path/to/video.mp4\r\n\r\n# Web interface\r\nGET /\r\nGET /path/to/directory/\r\n```\r\n\r\n### Using the API\r\n\r\n```python\r\nimport requests\r\nfrom requests.auth import HTTPBasicAuth\r\n\r\nauth = HTTPBasicAuth('username', 'password')\r\n\r\n# Get file listing\r\nresponse = requests.get(\r\n    'http://localhost:5000/api/files', \r\n    auth=auth\r\n)\r\nfiles = response.json()\r\n\r\n# Stream video\r\nvideo_url = 'http://localhost:5000/stream/movie.mp4'\r\nresponse = requests.get(video_url, auth=auth, stream=True)\r\n```\r\n\r\n## 🔧 Troubleshooting\r\n\r\n### Common Issues\r\n\r\n**Server won't start**: Check logs in `logs/error.log`\r\n**Authentication issues**: \r\n  - Verify your `.env` file has all three security values from `mediarelay-genpass`\r\n  - Ensure you're using the correct username and password you generated\r\n  - Regenerate credentials if needed: `mediarelay-genpass`\r\n**Performance problems**: Increase thread count (`VIDEO_SERVER_THREADS`)\r\n**Network access**: Check firewall and port forwarding\r\n**Missing .env file**: Copy `.env.example` to `.env` and configure\r\n\r\n### Debug Mode\r\n\r\n```bash\r\nVIDEO_SERVER_DEBUG=true\r\nVIDEO_SERVER_LOG_LEVEL=DEBUG\r\nmediarelay\r\n```\r\n\r\n### Support\r\n\r\n- **Documentation**: [docs/README.md](docs/README.md)\r\n- **Logs**: Review application logs in `logs/`\r\n- **Health Check**: `curl http://localhost:5000/health`\r\n- **Security**: [SECURITY.md](SECURITY.md)\r\n- **Issues**: Create GitHub issue with logs and configuration\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the CRL License - see the [LICENSE.md](LICENSE.md) file for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftboy1337%2Fmediarelay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftboy1337%2Fmediarelay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftboy1337%2Fmediarelay/lists"}