streamlink-server/README.md

Streamlink Server

A powerful streaming proxy server that handles various stream types through Streamlink with authentication support.

Overview

This server provides a secure way to proxy and convert video streams using Streamlink. It supports various streaming protocols and includes features for custom headers, proxy support, and authentication.

Key Features

• Stream conversion using Streamlink
• Authentication protection for all endpoints
• Support for custom HTTP headers
• Proxy server support
• Channel configuration via JSON
• Docker and Docker Compose support
• RESTful API endpoints
• Real-time stream monitoring and recovery
• Support for MPEG-TS output format

Requirements

• Python 3.11 or newer
• FFmpeg
• Streamlink 6.5.0 or newer
• Additional Python packages (installed via requirements.txt):
  • FastAPI 0.109.0+
  • uvicorn 0.27.0+
  • python-multipart 0.0.9+
  • python-dotenv 1.0.0
  • typing-extensions 4.9.0+

Installation

Standard Installation

git clone https://git.fiorinis.com/Home/streamlink-server.git
cd streamlink-server
pip install -r src/requirements.txt

Docker Installation

docker-compose up -d

Hugging Face Spaces Deployment

The project includes a specialized Dockerfile (Dockerfile_HF) optimized for deployment on Hugging Face Spaces. Once you have created the Space, you can create a Dockerfile and past the contents of Dockerfile_HF into it.

This version is specifically configured to run as a Space on huggingface.co, providing:

• Optimized container size
• Pre-configured environment for Spaces
• Automatic HTTPS handling
• Integration with Hugging Face's monitoring

Configuration

1. Create a .env file in the project root:

AUTH_USERNAME=your_username
AUTH_PASSWORD=your_password

2. Configure your channels in data/channels.json. Example:

{
    "channels": [
        {
            "id": "1",
            "name": "Example Channel",
            "url": "https://example.com/stream",
            "origin": "https://example.com",
            "referer": "https://example.com/player",
            "agent": "Mozilla/5.0...",
            "proxy": "http://proxy:8080"
        }
    ]
}

API Endpoints

Stream Endpoints

• GET /stream/{channel_id} - Stream a channel by ID
• GET /stream/url - Stream from a custom URL with query parameters

Utility Endpoints

• GET /utils/channels - List all available channels
• POST /utils/generate_url - Generate encoded streaming URLs

Authentication

All endpoints require authentication via query parameters:

• username: Your configured username
• password: Your configured password

Docker Environment Variables

• AUTH_USERNAME: Authentication username
• AUTH_PASSWORD: Authentication password
• TZ: Timezone (default: UTC)

Stream URL Parameters

When using the /stream/url endpoint:

• url: The source stream URL (required)
• origin: Custom Origin header
• referer: Custom Referer header
• agent: Custom User-Agent header
• proxy: Proxy server URL

Notes

• All streams are converted to MPEG-TS format for maximum compatibility
• The server includes automatic stream recovery on failures
• Default server port is 6090
• All API endpoints require authentication
• Docker setup includes optional VPN support via gluetun