rubenc2/gateway repository overview

⁠Gateway

⁠Overview

Gateway is a containerized media gateway and playout application for contribution and distribution workflows.

It started from the Playout codebase and extends it beyond file-only operation by adding HLS inputs, generated SES test-signal inputs, operator monitoring, self-healing supervision, and configurable multicast output.

Gateway 1.0.6 supports:

• File input
• HLS input with playable-stream probing
• Built-in SES color bars/test signal
• Single Stream multicast output
• ST 2022-7 redundant multicast output
• Optional CBR Output normalization
• Live bitrate monitoring
• Operator logs viewer
• Shared system status widget with CPU and input state
• Sentinel-based recovery and process supervision

Future roadmap items include ATSC 3.0 output with GPAC, GPU-aware encoding, SRT input, RTMP input, and future RIST support.

Gateway is built with Python, Flask, Gunicorn, Apache, FFmpeg, TSDuck, Mediainfo, Supervisor, and Docker.

⁠Current Version

1.0.6

Docker image:

rubenc2/gateway:1.0.6

latest currently points to the same release.

Supported platforms:

• linux/amd64
• linux/arm64

⁠Main Features

• Secure HTTPS web UI with basic authentication
• File upload and playout
• HLS URL catalog and validation
• HLS probing that verifies playable renditions and sample media segments
• Built-in SES color bars
• Single Stream and ST 2022-7 multicast output
• Optional CBR Output mode using libx264 and AAC
• Follow mode with muxrate guardrails
• Input switching locked while On-Air
• Real-time bitrate graphs
• Monitor page with live logs and downloadable logs
• CPU status indicator
• Docker healthcheck
• Supervisor-managed services
• Sentinel recovery loop for playout resilience

⁠Muxrate, CBR Output, and CBR-Lock

Gateway has three related output concepts: Muxrate, CBR Output, and CBR-lock.

⁠Muxrate

Muxrate is the target bitrate of the final transport stream output.

It defines the size of the output pipe that Gateway sends over multicast.

For example:

Muxrate = 6000000

means Gateway will try to produce a final transport stream around 6 Mb/s.

The muxrate applies whether Gateway is using:

• Single Stream output
• ST 2022-7 output
• Follow mode
• CBR Output mode

⁠Follow Mode

When CBR Output is disabled, Gateway runs in Follow mode.

In Follow mode, Gateway tries to preserve the selected input instead of fully transcoding it.

This is useful when the input is already properly encoded and already fits inside the configured muxrate.

In this mode, Gateway validates the selected input before starting. If the input bitrate is too high for the configured muxrate, Gateway blocks startup and asks the operator to either increase muxrate or enable CBR Output.

⁠CBR Output

CBR Output tells Gateway to transcode the selected input into a controlled constant bitrate output profile.

This is useful when the input bitrate is variable, too high, unpredictable, or not shaped correctly for the target transport stream.

When enabled, Gateway calculates the video bitrate from the configured muxrate:

Video bitrate = Muxrate - 1.3 Mb/s

The reserved 1.3 Mb/s gives room for audio, mux overhead, PSI/SI tables, null packets, and transport stability.

CBR Output uses:

• Video codec: libx264
• Audio codec: AAC at 192 kb/s
• GOP: approximately two seconds, based on the input frame rate
• H.264 CBR HRD signaling
• Constant frame rate enforcement
• AUD and repeated headers for decoder resilience

Example:

Muxrate = 6000000
CBR Output = enabled

Approximate video bitrate = 4700000
Audio bitrate = 192000
Final transport output = around 6000000

⁠CBR-Lock

CBR-lock is an additional option for adaptive HLS inputs.

Adaptive HLS streams often contain multiple renditions, such as:

1920x1080
1280x720
854x480

Without CBR-lock, the input may follow the adaptive stream behavior, and resolution can change if the source moves between renditions.

With CBR-lock enabled, Gateway selects the highest playable HLS rendition and locks the output geometry to that resolution.

If the input later drops to a lower resolution, Gateway keeps the output resolution stable by scaling and padding as needed.

This is useful when downstream systems expect a stable output format.

Example:

HLS master playlist contains:
- 1920x1080
- 1280x720
- 854x480

CBR Output = enabled
CBR-lock = enabled

Gateway locks output geometry to 1920x1080.
If the source drops to 1280x720, Gateway scales/pads back to 1920x1080.

⁠Status Widget Modes

Gateway reports the active output behavior in the status widget:

• Follow: CBR Output is disabled. Gateway preserves the input where possible.
• CBR: CBR Output is enabled. Gateway transcodes to a controlled bitrate.
• CBR-lock: CBR Output is enabled and HLS adaptive resolution lock is active.

⁠Simple Rule of Thumb

Use Follow when the input is already clean and fits inside the muxrate.

Use CBR Output when you want Gateway to normalize bitrate and encoding behavior.

Use CBR-lock when the input is adaptive HLS and downstream systems require stable output resolution.

⁠Security

The container is designed for appliance-style deployment:

• Self-signed SSL certificate generated at runtime
• Apache redirects HTTP to HTTPS
• Gunicorn serves Flask behind Apache
• Supervisor manages core services
• No SSH service exposed inside the container
• Docker healthcheck uses /status

Production deployments should always override the default credentials.

⁠Quick Start

Gateway requires host networking for multicast and interface behavior.

docker pull rubenc2/gateway:1.0.6

docker rm -f gateway

docker run -itd \
  --name gateway \
  --restart unless-stopped \
  --network host \
  -e IPADDRESS="<host-ip>" \
  -e SERVERNAME="" \
  -e APP_USERNAME="admin" \
  -e APP_PASSWORD="<change-me>" \
  rubenc2/gateway:1.0.6

Then open:

https://<host-ip>

⁠Docker Compose

services:
  gateway:
    image: rubenc2/gateway:1.0.6
    container_name: gateway
    network_mode: host
    restart: unless-stopped
    environment:
      IPADDRESS: "<host-ip>"
      SERVERNAME: ""
      APP_USERNAME: "admin"
      APP_PASSWORD: "<change-me>"
      CPU_STATUS_GREEN_MAX: "65.0"
      CPU_STATUS_ORANGE_MAX: "85.0"
      CPU_STATUS_EMA_ALPHA: "0.35"
      GATEWAY_LOG_LEVEL: "INFO"
      GATEWAY_THUMBNAIL_FPS: "1.0"
      SENTINEL_INTERVAL_RUNNING: "5"
      SENTINEL_INTERVAL_IDLE: "10"
      SENTINEL_STATUS_LOG_INTERVAL: "60"
    volumes:
      - gateway_uploads:/var/www/html/uploads
      - gateway_hls:/var/www/html/hls
      - gateway_output:/var/www/html/output
      - gateway_state:/var/www/html/state
      - gateway_logs:/home/appuser/logs

volumes:
  gateway_uploads:
  gateway_hls:
  gateway_output:
  gateway_state:
  gateway_logs:

⁠Environment Variables

Common runtime variables:

• IPADDRESS: Host IP address used for redirects, certificate name, and app configuration
• SERVERNAME: Optional DNS name. If empty, Gateway uses IPADDRESS
• APP_USERNAME: Web UI username
• APP_PASSWORD: Web UI password
• CPU_STATUS_GREEN_MAX: CPU green threshold, default 65.0
• CPU_STATUS_ORANGE_MAX: CPU amber threshold, default 85.0
• CPU_STATUS_EMA_ALPHA: CPU smoothing factor, default 0.35
• GATEWAY_LOG_LEVEL: App logging level, default INFO
• GATEWAY_THUMBNAIL_FPS: Thumbnail sampling rate, default 1.0
• SENTINEL_INTERVAL_RUNNING: Sentinel check interval while running, default 5
• SENTINEL_INTERVAL_IDLE: Sentinel check interval while idle, default 10

⁠Healthcheck

docker inspect --format='{{json .State.Health}}' gateway

⁠Dependencies

Included in the image:

• Python 3.12
• Apache2
• Gunicorn
• Flask
• FFmpeg v7+
• TSDuck 3.39+
• Mediainfo
• Supervisor

⁠Links

• GitLab: https://gitlab.com/rubenc2/gateway⁠
• Docker Hub: https://hub.docker.com/r/rubenc2/gateway⁠

⁠Roadmap

Planned future work:

• ATSC 3.0-compatible output using GPAC
• GPU-aware encoding support for VAAPI and NVIDIA/NVENC where available
• SRT input
• RTMP input
• Future RIST support
• Hardened bitrate history storage
• Expanded observability and diagnostics

⁠License

GPL-3.0 due to libx264 usage.