Back to Administration

Developer Guide

Technical documentation for maintaining and supporting the OneSignal Livestream platform code.

Architecture Overview

The system follows a modern streaming architecture:

  • Ingest: Nginx with the ngx_rtmp_module handles RTMP/SRT ingest.
  • Delivery: Nginx serves HLS segments. A Python/Flask backend acts as an HLS proxy to rewrite manifests for DVR and Huawei OBS offloading.
  • Backend API: Flask handles stream management, clipping, branding, and user authentication.
  • Workers: Standalone Python scripts handle background tasks like thumbnail generation and OBS synchronization.
  • Database: MySQL/MariaDB stores stream metadata, clip info, and user permissions.

Core Components

1. HLS Proxy & Manifest Rewriting

Located in app/api/internal_api.py and app/services/routing_service.py.

  • Rewrites #EXTINF tags to include wall-clock timestamps for precise clipping.
  • Handles redirects to Huawei OBS if a segment is no longer available on local disk.

2. Live Clipping Engine

  • Frontend: Custom Video.js plugin (videojs-clipping-plugin.js) for marker selection.
  • Backend: clip_service.py calculates offsets.
  • Transcoding: transcoder_service.py uses FFmpeg to extract segments and concatenate them into a final MP4.

3. OBS Synchronization (obs_sync.py)

  • Monitors the hls/ directory for new .ts segments.
  • Uploads them to Huawei OBS.
  • Ensures local disk doesn't overflow while maintaining a 24-hour DVR history on OBS.

Codebase Structure

/root/.gemini/antigravity/scratch/OneSignal/
├── backend/            # Flask Application
│   ├── app/
│   │   ├── api/        # Blueprints and Routes
│   │   ├── services/   # Business Logic (Core)
│   │   ├── models/     # DB Models (SQLAlchemy)
│   │   └── repositories/ # Data Access Layer
├── frontend/           # Static Assets (HTML, CSS, JS)
├── nginx/              # Custom Nginx configurations
├── scripts/            # Background workers and maintenance scripts
└── logs/               # Application and service logs

Configuration

Configuration is managed via a .env file in the backend/ directory. Key variables include:

  • DATABASE_URL: Connection string.
  • OBS_ACCESS_KEY/SECRET_KEY: Huawei Cloud credentials.
  • DVR_BYPASS_TOKEN: Secret for authorized DVR access.

Deployment & Development

  • Services: Managed via Systemd or the run_background_services.sh script.
  • Database Migrations: Handled via Flask-Migrate (flask db upgrade).
  • Nginx: Main config includes nginx/frontend.conf, nginx/api.conf, and nginx/stream.conf.