Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tboy1337/mediarelay

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.
https://github.com/tboy1337/mediarelay

media online python relay server share stream streaming video

Last synced: 2 days ago
JSON representation

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.

Awesome Lists containing this project

README 

          
# MediaRelay



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.



## ✨ Features



### 🔒 Security

- **Multi-layer Authentication**: HTTP Basic Auth + Session Management

- **Path Traversal Protection**: Prevents unauthorized file access

- **Security Headers**: XSS, SameSite cookie protection, clickjacking protection

- **Rate Limiting**: Configurable request throttling

- **Security Audit Logging**: Comprehensive security event tracking

- **Session Management**: Secure sessions with configurable timeouts



### 🎥 Media Streaming  

- **Universal Format Support**: MP4, MKV, AVI, MOV, WebM, M4V, FLV

- **Subtitle Support**: SRT and WebVTT (`.srt`, `.vtt`) subtitle files

- **Audio Support**: MP3, AAC, OGG, WAV

- **Range Requests**: Efficient streaming with seek support

- **Mobile Optimized**: Responsive design for all devices



### 📊 Monitoring & Performance

- **Health Check Endpoint**: Real-time server status

- **Performance Metrics**: Request timing and throughput monitoring  

- **Comprehensive Logging**: Application, security, error, and performance logs

- **Multi-threaded**: Configurable concurrency for high performance

- **Resource Monitoring**: CPU, memory, and disk snapshot logged at server startup (`log_system_info`)



### 🛠️ Advanced Features

- **Environment Configuration**: Full environment variable support

- **90%+ Test Coverage**: Comprehensive test suite with branch coverage and security tests

- **Service Management**: System service configurations — see [Deployment Guide](docs/deployment_guide.md)

- **Log Rotation**: Automatic log rotation and archival

- **API Support**: RESTful JSON API for integration



## 📋 Requirements



- **Python**: 3.12 or higher

- **Operating System**: Windows 10+, macOS 10.15+, or Linux (Ubuntu 20.04+ recommended)

- **Memory**: Minimum 2GB RAM, 4GB+ recommended for optimal performance

- **Storage**: 1GB for application, additional space for video content

- **Network**: Stable internet connection for remote access



## 🚀 Quick Start



### 1. Installation



**Recommended — install from PyPI:**



```bash

# Create virtual environment (recommended)

python -m venv venv

source venv/bin/activate  # Linux/macOS

venv\Scripts\activate     # Windows



pip install mediarelay

```



That installs the `mediarelay`, `mediarelay-config`, `mediarelay-genpass`, and `mediarelay-validate` commands. No need to clone the repository.



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



**From source (development or contributing):**



```bash

git clone https://github.com/tboy1337/MediaRelay.git

cd MediaRelay



python -m venv venv

source venv/bin/activate  # Linux/macOS

venv\Scripts\activate     # Windows



pip install -e ".[dev]"

```



Use `pip install -e .` instead of `pip install -e ".[dev]"` if you only need the application without test and lint tools.



### 2. Configuration



```bash

# Generate sample configuration

mediarelay-config



# Copy and edit configuration

copy .env.example .env   # Windows

cp .env.example .env     # Linux/macOS

# Edit .env with your settings

```



### 3. Security Setup



Generate required security credentials:



```bash

# Generate Flask secret key and password hash

mediarelay-genpass

```



The script will:

1. **Ask for your preferred username** (e.g., `admin`, `user`, etc.)

2. **Generate or create your password**:

   - Choose 'y' to generate a secure 35-character password automatically

   - Choose 'n' to enter your own password (minimum 12 characters)

3. **Generate a Flask secret key** (for session security)

4. **Create a password hash** (for secure authentication)



**Example output:**

```

============================================================

CONFIGURATION VALUES FOR .env FILE

============================================================

VIDEO_SERVER_SECRET_KEY=a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890

VIDEO_SERVER_USERNAME=admin

VIDEO_SERVER_PASSWORD_HASH=scrypt:32768:8:1$abc123$def456...

```



**Important Security Notes**: 

- **Save your password securely** - you'll need it to log in to the web interface

- **Copy all three generated values** to your `.env` file immediately

- **Never share your secret key or password hash** - treat them like private keys

- **Regenerate credentials** if you suspect they've been compromised

- The script uses **cryptographically secure random generation** for maximum security



### 4. Start the Server



```bash

# Start the server

mediarelay



# Or with custom configuration

mediarelay --host 0.0.0.0 --port 8080

```



Once the server is running, you can access it in your web browser at:

- **Local access**: http://localhost:5000

- **Network access**: http://YOUR_IP_ADDRESS:5000 (if configured with --host 0.0.0.0)



### 🔧 Configuration



#### Step-by-Step Configuration Process



1. **Create your configuration file** (if you do not already have `.env.example` from a source checkout, run `mediarelay-config` first):

   ```bash

   copy .env.example .env   # Windows

   cp .env.example .env     # Linux/macOS

   ```



2. **Generate security credentials**:

   ```bash

   mediarelay-genpass

   ```



3. **Update your `.env` file** with the generated values:

   - Replace `VIDEO_SERVER_SECRET_KEY=your-secret-key-here` with your generated secret key

   - Replace `VIDEO_SERVER_USERNAME=tboy1337` with your chosen username  

   - Replace `VIDEO_SERVER_PASSWORD_HASH=your-password-hash-here` with your generated hash



4. **Configure other settings** as needed (video directory, port, etc.)



5. **Validate configuration** before production deployment:

   ```bash

   mediarelay-validate

   ```



6. **Start the server** (configuration is validated on startup):

   ```bash

   mediarelay

   ```



#### Key Environment Variables



See [Configuration Reference](docs/configuration_reference.md) for the complete list. Production-critical settings:



```bash

# Server Configuration

VIDEO_SERVER_HOST=0.0.0.0

VIDEO_SERVER_PORT=5000  

VIDEO_SERVER_DIRECTORY=/path/to/videos

VIDEO_SERVER_THREADS=6



# Security (Required - Generate using mediarelay-genpass)

VIDEO_SERVER_USERNAME=your_username                    # Your chosen username

VIDEO_SERVER_PASSWORD_HASH=your_secure_hash            # Generated password hash

VIDEO_SERVER_SECRET_KEY=your_secret_key                # Generated Flask secret key



# Production mode (required for live deployment; enforces secure cookies and credential checks)

VIDEO_SERVER_PRODUCTION=true

VIDEO_SERVER_RATE_LIMIT=true                           # Required in production



# Reverse proxy (set true ONLY when behind a trusted reverse proxy)

VIDEO_SERVER_BEHIND_PROXY=false

VIDEO_SERVER_PROXY_TRUSTED=false                       # Required true with BEHIND_PROXY in production



# Optional monitoring token for detailed /health via X-Health-Token

# VIDEO_SERVER_HEALTH_TOKEN=



# Performance

VIDEO_SERVER_RATE_LIMIT_PER_MIN=60

VIDEO_SERVER_STREAM_RATE_LIMIT_PER_MINUTE=600

VIDEO_SERVER_SESSION_TIMEOUT=3600

VIDEO_SERVER_MAX_FILE_SIZE=21474836480  # 20GB default, set to 0 to disable



# Session Cookies (set Secure=true when serving over HTTPS)

VIDEO_SERVER_SESSION_COOKIE_SECURE=true

VIDEO_SERVER_SESSION_COOKIE_HTTPONLY=true

VIDEO_SERVER_SESSION_COOKIE_SAMESITE=Strict



# Account lockout (failed login protection)

VIDEO_SERVER_LOCKOUT_MAX_ATTEMPTS=5

VIDEO_SERVER_LOCKOUT_DURATION=900



# Logging

VIDEO_SERVER_LOG_LEVEL=INFO

VIDEO_SERVER_LOG_DIR=./logs

VIDEO_SERVER_LOG_CONSOLE=true

```



## Development



Run the full quality gate locally:



```bash

python scripts/verify.py

```



This runs black, isort, mypy, bandit, pylint, pip-audit, and pytest with 90% branch coverage.



## 🔒 Security



### Authentication & Authorization



```python

# Multi-layer authentication

HTTP_BASIC_AUTH + SESSION_MANAGEMENT + SAMESITE_COOKIES

```



### Security Headers



```http

X-Content-Type-Options: nosniff

X-Frame-Options: SAMEORIGIN

Cross-Origin-Opener-Policy: same-origin

Cross-Origin-Resource-Policy: same-origin

Strict-Transport-Security: max-age=31536000  # When VIDEO_SERVER_HSTS=true or VIDEO_SERVER_BEHIND_PROXY=true

Content-Security-Policy: default-src 'self'; media-src 'self'; style-src 'self' 'unsafe-inline'

Referrer-Policy: strict-origin-when-cross-origin

Permissions-Policy: accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()

X-Permitted-Cross-Domain-Policies: none

```



`X-XSS-Protection` is intentionally omitted (deprecated in modern browsers).



### Reverse Proxy Warning



Set `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).



### Security Monitoring



All security events are logged:

- Authentication attempts (success/failure)

- Path traversal attempts

- Rate limit violations

- File access attempts

- Account lockout events



Logout 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`.



`VIDEO_SERVER_HOST` is validated at startup (must be a valid IP address or hostname).



## 📈 Performance



### Performance Features



- **Multi-threading**: Configurable worker threads

- **Range Requests**: Efficient video streaming

- **HTTP Caching**: Browser caching for static content

- **Connection Pooling**: Supports multiple users simultaneously

- **Memory Management**: Automatic resource cleanup



## 📊 API Usage



### Available Endpoints



```bash

# Health check (no auth required)

GET /health



# Directory listing  

GET /api/files?path=movies



# File streaming

GET /stream/path/to/video.mp4



# Web interface

GET /

GET /path/to/directory/

```



### Using the API



```python

import requests

from requests.auth import HTTPBasicAuth



auth = HTTPBasicAuth('username', 'password')



# Get file listing

response = requests.get(

    'http://localhost:5000/api/files', 

    auth=auth

)

files = response.json()



# Stream video

video_url = 'http://localhost:5000/stream/movie.mp4'

response = requests.get(video_url, auth=auth, stream=True)

```



## 🔧 Troubleshooting



### Common Issues



**Server won't start**: Check logs in `logs/error.log`

**Authentication issues**: 

  - Verify your `.env` file has all three security values from `mediarelay-genpass`

  - Ensure you're using the correct username and password you generated

  - Regenerate credentials if needed: `mediarelay-genpass`

**Performance problems**: Increase thread count (`VIDEO_SERVER_THREADS`)

**Network access**: Check firewall and port forwarding

**Missing .env file**: Copy `.env.example` to `.env` and configure



### Debug Mode



```bash

VIDEO_SERVER_DEBUG=true

VIDEO_SERVER_LOG_LEVEL=DEBUG

mediarelay

```



### Support



- **Documentation**: [docs/README.md](docs/README.md)

- **Logs**: Review application logs in `logs/`

- **Health Check**: `curl http://localhost:5000/health`

- **Security**: [SECURITY.md](SECURITY.md)

- **Issues**: Create GitHub issue with logs and configuration



## 📄 License



This project is licensed under the CRL License - see the [LICENSE.md](LICENSE.md) file for details.