LiveTube

Generate HSL live streams with fallback support. LiveTube is a lightweight web server that resolves live stream URLs to HLS (HTTP Live Streaming) format using yt-dlp, providing a simple API for accessing live streams programmatically.

Features

• HLS Stream Resolution: Automatically resolves video IDs or channel URLs to HLS manifest URLs.
• Fallback Support: Validates streams and provides fallbacks if primary sources fail.
• Caching: Optional TTL-based caching to reduce API calls and improve performance.
• Multi-Platform Binaries: Pre-compiled executables for Linux, macOS, and Windows along with Docker support.
• API Key Protection: Optional authentication for securing endpoints.
• CORS Support: Configurable cross-origin resource sharing.

Installation

1. Docker

Pull and run the Docker image:

docker run -d \
  --name livetube \
  -p 3000:3000 \
  ghcr.io/p1n2o/livetube:latest

Or use Docker Compose:

services:
  livetube:
    image: ghcr.io/p1n2o/livetube:latest
    container_name: livetube
    ports:
      - "3000:3000"

2. Pre-compiled Binaries

Download the latest release from the releases page and run the appropriate binary for your platform:

• Linux x64: livetube-linux-x64
• Linux ARM64: livetube-linux-arm64
• macOS x64: livetube-macos-x64
• macOS ARM64: livetube-macos-arm64
• Windows x86_64: livetube-windows-x64.exe

Example (linux-x64):

curl -L https://github.com/P1N2O/livetube/releases/latest/download/livetube-linux-x64 -o livetube && chmod +x livetube && ./livetube

3. Source (Bun)

1. Prerequisites: Install Bun.

   curl -fsSL https://bun.com/install | bash

2. Clone the Repository:

   git clone https://github.com/p1n2o/livetube.git && cd livetube

3. Install Dependencies:

   bun install

4. Build and Run:

   bun run build && && cd dist && chmod +x livetube-linux-x64 && ./livetube-linux-x64

Usage

Basic API Usage

• By Video ID: http://localhost:3000?v=VIDEO_ID
• By Channel URL: http://localhost:3000?c=CHANNEL_HANDLE
• Direct HLS URL: http://localhost:3000?x=HLS_URL
• Multiple Streams with fallback: http://localhost:3000?v=VIDEO_ID&c=CHANNEL_HANDLE&x=HLS_URL

Example:

curl "http://localhost:3000?v=dQw4w9WgXcQ"

This will redirect to the HLS manifest URL if the stream is live.

Health Check:

curl http://localhost:3000/health

Configuration

Set environment variables to configure the server:

• HOST: Binding host (default: 127.0.0.1)
• PORT: Port number (default: 3000)
• API_KEY: Optional API key for authentication (Bearer token or User-Agent substring)
• MEMOIZATION_TTL: Cache time-to-live in minutes (default: 30, set to 0 to disable)
• CUSTOM_X_HEADER: Custom header key to pass to x requests
• CORS_ORIGIN: Allowed CORS origins (default: *)

Authentication

If API_KEY is set, requests must include:

• Header: Authorization: Bearer YOUR_API_KEY
• Or User-Agent containing the API key.

Development

Setup

1. Clone and Install:

   git clone https://github.com/p1n2o/livetube.git && cd livetube && bun install

2. Development Tasks:

   • bun run dev: Run in watch mode

Project Structure

.
├── index.ts          # Main application entry point
├── package.json      # Package manifest
├── bun.lock          # Dependency lock file
├── build.ts          # Build script for binaries
├── Dockerfile        # Multi-stage Docker build
├── README.md         # This file
└── .vscode/          # VS Code settings

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Commit changes: git commit -m 'Add amazing feature'
5. Push to branch: git push origin feature/amazing-feature
6. Open a Pull Request

Reporting Issues

Report bugs or request features via GitHub Issues.

API Reference

Endpoints

• GET / - Main endpoint for stream resolution
  • Query Parameters:
    • v: YT video ID
    • c: YT channel handle
    • x: Direct HLS URL for validation
• GET /health - Health check endpoint

Response Codes

• 200: Success (redirects to HLS URL or returns status)
• 302: Redirect to HLS manifest
• 401: Unauthorized (missing API key)
• 404: No valid stream found

License

This project is licensed under the MIT License - see the LICENSE file for details.