NG-S4: an Nginx + Stunnel4 RTMP/RTMPS restream server with HLS preview and hardware-accelerated, HDR-aware multi-format transcoding for Linux and WSL2. Broadcast one source to many platforms at once.
NG-S4 turns a single Linux box into a multi-platform restream server built entirely from native, apt-installable components: nginx with the RTMP module, stunnel4 for RTMPS, and ffmpeg for encoding. Publish one master feed and NG-S4 fans it out to Twitch, YouTube, Kick and any other RTMP/RTMPS target, re-encoding each output independently so every platform receives a stream that suits its limits.
The headline capability is per-target transcoding. You can send 4K60 HDR (HEVC, Main10) to YouTube while simultaneously delivering a tone-mapped SDR H.264 copy to Twitch that respects its 6000 kbps ceiling and lower frame rate, all from the same ingest.
The transcode engine detects the best encoder for the host at runtime, so the same project runs on an Ubuntu 26.04 workstation with an NVIDIA GPU (NVENC), a Raspberry Pi on Ubuntu 24.04 (V4L2 M2M), or any machine using software x264/x265.
- One ingest, many outputs: publish once over RTMP and NG-S4 pushes a tailored encode to every enabled platform.
- Per-platform profiles: resolution, frame rate, codec, bitrate ceiling, buffer and HDR/SDR are configured independently per target in
master.env. - HDR aware: HDR sources pass through to HDR targets (HEVC Main10, BT.2020/PQ via YouTube's HLS ingest) and are tone-mapped to SDR (BT.709) for platforms that do not support HDR.
- Hardware accelerated: NVENC on NVIDIA hosts, V4L2 M2M on Raspberry Pi, automatic software fallback, all selected at runtime.
- YouTube HLS ingest: YouTube HDR live streams use YouTube's HLS ingest endpoint over HTTPS; ffmpeg pushes HEVC segments directly, no stunnel required.
- RTMPS via stunnel4: platforms that require RTMPS (Kick) are reached through a local stunnel tunnel.
- HLS preview: the ingest is also published as low-latency HLS for monitoring on the LAN.
- LAN friendly: the allowed publish/play network is a single configuration value.
- Host agnostic: scripts derive their own paths and write no home directory into any config.
- Native and lean: bash, nginx, stunnel and ffmpeg only, installed from apt. No Python, no third-party runtimes.
flowchart LR
SRC["OBS / camera<br/>H.264 over RTMP"] -->|publish| ING["nginx ingest<br/>app: ingest"]
ING -->|on publish: exec| ENG["ng-s4-transcode.sh"]
ING -.->|HLS| LAN["LAN preview players"]
ENG -->|"H.264 SDR, 6000k, 1080p"| TW["Twitch (RTMP)"]
ENG -->|"HEVC HDR, HLS PUT"| YT["YouTube (HTTPS HLS ingest)"]
ENG -->|"H.264 SDR"| KIS["stunnel :19352"] --> KI["Kick (RTMPS)"]
NG-S4/
├── example.env/ # Templates: copy into real.env and edit
│ ├── master.env # All configuration, including transcode profiles
│ ├── nginx.conf # Ingest + HLS (tokens substituted at setup)
│ ├── stunnel.conf # RTMPS tunnels for YouTube/Kick
│ └── cleaned_up/ # Comment-free copies of the above
├── real.env/ # Your live configuration (git ignored)
├── UNIX-Scripts/
│ ├── setup-restream.sh # Install and configure everything
│ ├── ng-s4-transcode.sh # The fan-out transcode engine
│ ├── ng-s4-doctor.sh # Capability and configuration check
│ ├── manage-services.sh # Start/stop/status for nginx + stunnel4
│ ├── generate-stunnel-cert.sh # Self signed certificate for stunnel
│ ├── reset-restream.sh # Uninstall and clean up
│ └── stream-gphoto2-webcam.sh # Stream a DSLR/mirrorless camera to ingest
├── WSL2-Setup/ # Optional PowerShell helpers for Windows/WSL2
└── docs/README.md # This file
- A Linux host with
sudo. Tested targets:- Ubuntu 26.04 workstation with an NVIDIA GPU (NVENC encode).
- Raspberry Pi on Ubuntu 24.04 (V4L2 M2M encode).
- Packages installed automatically by the setup script from apt:
nginx,libnginx-mod-rtmp,stunnel4,ffmpeg,gphoto2. - For NVENC you also need the NVIDIA driver present (
nvidia-smiworking). NG-S4 does not install GPU drivers; it detects and uses them. - For HDR ingest you need an ffmpeg with
libx265andlibzimg(thezscalefilter). Ubuntu's ffmpeg ships both. Run the doctor to confirm.
git clone <repository_url> && cd NG-S4
# 1. Create your live configuration from the templates.
mkdir -p real.env
cp example.env/master.env real.env/master.env
cp example.env/nginx.conf real.env/nginx.conf
cp example.env/stunnel.conf real.env/stunnel.conf
# 2. Edit real.env/master.env: set LAN_CIDR, your stream keys and the per
# platform profiles (see below). For Kick, also set the ingest host in
# real.env/stunnel.conf.
nano real.env/master.env
# 3. Install and start everything.
sudo bash UNIX-Scripts/setup-restream.sh
# 4. Verify the host can encode what you intend to send.
bash UNIX-Scripts/ng-s4-doctor.shThen point OBS (or any encoder) at the ingest:
- Server:
rtmp://<this-host>:1935/ingest - Stream key: any name, for example
live
Monitor locally while you stream:
- HLS preview:
http://<this-host>:8080/hls/ingest/live/index.m3u8 - RTMP stats:
http://<this-host>:8080/stat - Health:
http://<this-host>:8080/healthz
All configuration lives in one file. The most important core values:
| Variable | Purpose |
|---|---|
LAN_CIDR |
Network allowed to publish and play, for example 192.168.0.0/24. |
NGINX_HTTP_PORT |
Port for HLS, stats and health (default 8080). |
HLS_BASE_DIR |
Where HLS segments are written (default /mnt/hls). |
INGEST_APP |
Name of the nginx RTMP application (default ingest). |
ENCODER_BACKEND |
auto, nvenc, v4l2m2m or software. |
SOURCE_HDR |
auto (probe the stream), hdr, or sdr. |
LOG_DIR |
Setup, reset and transcode logs (default /var/log/ng-s4). |
The nginx port, LAN range and HLS path are tokens in nginx.conf; the setup script renders them from master.env, so you edit values in one place only.
master.env defines a space-separated TARGETS list (for example TW YT KI) and one block of variables per target.
Each block is independent, so every platform gets exactly the format it needs.
| Variable (per target) | Meaning |
|---|---|
<ID>_ENABLE |
1 to stream to this target, 0 to skip. |
<ID>_URL / <ID>_KEY |
Ingest base URL (no key) and the stream key. |
<ID>_VCODEC |
h264, hevc, or copy (pass the source through untouched). |
<ID>_HDR |
hdr keeps the HDR colour space; sdr tone-maps an HDR source down. |
<ID>_SCALE |
Output size such as 1920:-2 (-2 keeps the aspect ratio); empty keeps the source. |
<ID>_FPS |
Output frame rate; empty keeps the source. |
<ID>_VBITRATE / <ID>_MAXRATE / <ID>_BUFSIZE |
Rate control, used to respect platform ceilings. |
<ID>_ABITRATE |
Audio bitrate (AAC, 48 kHz stereo). |
This is the shipped default. YouTube receives the HDR master, Twitch receives a tone-mapped SDR copy within its limits:
# Twitch: tone-mapped to SDR, 1080p30, hard 6000 kbps ceiling.
TW_ENABLE=1 TW_VCODEC=h264 TW_HDR=sdr TW_SCALE="1920:-2" TW_FPS=30
TW_VBITRATE=6000k TW_MAXRATE=6000k TW_BUFSIZE=9000k
# YouTube: HLS ingest over HTTPS, HDR preserved as HEVC Main10 at source resolution/fps.
YT_ENABLE=1 YT_INGEST=hls YT_VCODEC=hevc YT_HDR=hdr YT_SCALE="" YT_FPS=""
YT_VBITRATE=45000k YT_MAXRATE=51000k YT_BUFSIZE=90000kWith an NVIDIA host this runs the YouTube path fully on the GPU (hevc_nvenc, Main10, BT.2020/PQ) and tone-maps the Twitch path on decode, so a single publish produces both outputs.
Set YT_VCODEC=copy to pass an already-encoded HEVC HDR master straight through with no re-encode, for the lowest possible latency and load.
The engine chooses an encoder backend at runtime (override with ENCODER_BACKEND):
- NVIDIA (Ubuntu 26.04 host):
h264_nvenc/hevc_nvenc, with HDR HEVC passthrough kept entirely on the GPU. The setup script adds the nginx user to thevideoandrendergroups so the worker can reach/dev/nvidia*. - Raspberry Pi (Ubuntu 24.04):
h264_v4l2m2m. Because the Pi encoder has no 10-bit HDR path, any HDR target automatically falls back to softwarelibx265for that output. Keep Pi workloads to 1080p SDR for real-time performance. - Software fallback:
libx264/libx265on any host.
Run UNIX-Scripts/ng-s4-doctor.sh on each machine to print the detected backend, available encoders, HDR tone-mapping filters and the status of every configured target.
- Set
LAN_CIDRto your subnet so other machines may publish and play. - Open the required ports on the host firewall (for example with
ufw):1935/tcpfor RTMP andNGINX_HTTP_PORT(default8080) for HLS, stats and health.
sudo bash UNIX-Scripts/manage-services.sh status all
sudo bash UNIX-Scripts/manage-services.sh restart nginx
sudo bash UNIX-Scripts/manage-services.sh stop stunnel4Transcode logs are written per stream and per target under LOG_DIR (default /var/log/ng-s4), for example transcode-live.log and transcode-live-YT.log.
UNIX-Scripts/stream-gphoto2-webcam.sh streams a gphoto2-compatible camera straight into the ingest, where it is transcoded and fanned out like any other source.
It selects the best available H.264 encoder (NVENC, V4L2 M2M, or x264) automatically.
# Uses rtmp://127.0.0.1:1935/ingest/camera by default.
sudo bash UNIX-Scripts/stream-gphoto2-webcam.sh
# Or specify a different ingest target:
sudo bash UNIX-Scripts/stream-gphoto2-webcam.sh rtmp://127.0.0.1:1935/ingest/cam1Bitrate, frame rate and audio settings can be overridden with environment variables (VIDEO_BITRATE, VIDEO_FRAMERATE, AUDIO_BITRATE, and so on).
Kick uses RTMPS, delivered by pushing plain RTMP to a local stunnel port that wraps it in TLS.
The accept port in real.env/stunnel.conf must match KI_STUNNEL_PORT in master.env (default 19352).
Set the correct Kick ingest host in stunnel.conf; the certificate is generated by the setup script (regenerate manually with sudo bash UNIX-Scripts/generate-stunnel-cert.sh).
YouTube does not use stunnel: the engine pushes HEVC segments directly to YouTube's HLS ingest endpoint over HTTPS, which ffmpeg handles natively.
To route that HLS PUT over stunnel instead (TLS is applied at the TCP layer regardless of payload), uncomment [youtube_hls] in stunnel.conf and set YT_STUNNEL_PORT in master.env; the engine then connects in plain HTTP to the local port and sets the Host header so YouTube still accepts it.
Two test entry points need no stream keys and never contact a platform, so real.env/ (which is git ignored) can stay empty during development:
- Command assembly (any machine, no ffmpeg needed):
bash test-suite/run-tests.shuses a mock ffmpeg to assert that every target builds the correct command (RTMP vs HLS vs stunnel, tone mapping, encoder selection, skipped/placeholder targets). - Real encode on the host (needs ffmpeg):
bash test-suite/run-local-encode.shtranscodes the bundledtest-suite/testIMG+AUDIO.mkvto a local HLS folder (/tmp/ng-s4-test/hls) using thelocalingest profile intest-suite/testmaster.env. This exercises the real encoders, filters and tone mapping on your hardware without any key. Override withENCODER_BACKEND=nvenc SOURCE_HDR=hdr DURATION=20 bash test-suite/run-local-encode.sh.
Real keys live only in real.env/master.env, which is git ignored, so they are never committed. They are needed only for the final end to end acceptance test against the live platforms (where an unlisted or promptly unpublished VOD is the simplest way to verify YouTube).
sudo bash UNIX-Scripts/reset-restream.shThis stops the services and any running transcodes, purges nginx and stunnel4, and removes the installed engine (/usr/local/bin/ng-s4-transcode.sh), the pointer file (/etc/default/ng-s4) and the HLS directory. Logs under LOG_DIR are kept.
The WSL2-Setup/ PowerShell scripts remain available to install a distribution, run the Linux setup inside it, and manage Windows Firewall rules for reaching the ingest from the LAN.
Hardware encode inside WSL2 is limited, so NVENC/HDR workloads are best run on a native Linux host.
See the scripts in WSL2-Setup/ for Install-RestreamWSL.ps1, WSL2-mgr.ps1 (backup/restore) and WSL2-UFW.ps1 (firewall).
- Capability check: run
UNIX-Scripts/ng-s4-doctor.shfirst; it flags missing encoders, filters or keys. - A target does not start: check its
*_ENABLE,*_URLand*_KEY. Placeholder keys are skipped on purpose. SeeLOG_DIR/transcode-<name>-<ID>.log. - nginx: logs in
/var/log/nginx/error.log; validate config withsudo nginx -t. - stunnel4: logs at the
outputpath in/etc/stunnel/stunnel.conf. - stunnel "address already in use": a leftover or duplicate stunnel instance is holding the accept port.
setup-restream.shnow stops every stunnel variant and frees the configured accept ports before starting, so re-running setup clears it. Ports are never changed by this. - NVENC permission errors: confirm the nginx user is in the
video/rendergroups (the setup script adds it) and restart nginx. - Firewall: ensure
1935/tcpand the HTTP port are open for LAN sources.
NG-S4 is licensed under the GNU General Public Licence v3 or later (see LICENSE).
A commercial or separate licence is available on request from the owner.