From 2e2f0775a83fdabd9572a638384b23984b867369 Mon Sep 17 00:00:00 2001 From: Alexander Wagner Date: Sun, 26 Jul 2026 22:12:01 +0200 Subject: [PATCH 1/4] Add OpenRTMP and NOALBS JSON statistics guide --- guides/openrtmp-noalbs-json-stats/index.php | 216 ++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 guides/openrtmp-noalbs-json-stats/index.php diff --git a/guides/openrtmp-noalbs-json-stats/index.php b/guides/openrtmp-noalbs-json-stats/index.php new file mode 100644 index 0000000..8b244b7 --- /dev/null +++ b/guides/openrtmp-noalbs-json-stats/index.php @@ -0,0 +1,216 @@ + 'https://schema.org', + '@type' => 'TechArticle', + 'headline' => 'Use OpenRTMP JSON statistics with NOALBS', + 'description' => $pageDescription, + 'author' => ['@type' => 'Organization', 'name' => 'OpenRTMP'], + 'mainEntityOfPage' => 'https://openrtmp.org/guides/openrtmp-noalbs-json-stats/' +]; +include __DIR__ . '/../../includes/header.php'; +?> + +
+
+ NOALBS · JSON statistics · Monitoring +

Use OpenRTMP JSON statistics with NOALBS

+

Connect NOALBS to the key-protected OpenRTMP statistics endpoint, configure bitrate and RTT triggers, and keep the nginx-compatible XML endpoint as a fallback for older NOALBS versions or existing integrations.

+
+ +
+
+
+
Released support: NOALBS v2.19.0 includes the native OpenRTMP provider. It reads /stats?key=... directly and uses OpenRTMP's bitrate_kbps and rtt_ms values for scene switching.
+ +

What you need

+
    +
  • A running librtmp2-server instance with its HTTP listener reachable from NOALBS.
    • +
  • A stream created through the OpenRTMP panel or REST API.
    • +
  • The stream's stats_key.
    • +
  • NOALBS v2.19.0 or newer for the native JSON provider.
    • +
+

The OpenRTMP server and protocol stack are still alpha software. Test the exact publisher, statistics, reconnect, and scene-switching workflow before relying on it for a critical production stream.

+ +

Create a stream and obtain its keys

+

The easiest option is librtmp2-server-panel. Create a stream in the panel and copy its statistics URL or stats_key.

+

You can also create a stream with the REST API:

+ 
curl -X POST http://openrtmp-server:8080/api/v1/streams \
+  -H "Authorization: Bearer <api_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"id":"mobile","name":"Mobile ingest","app":"live"}'
+

The response contains three separate credentials:

+ 
{
+  "id": "mobile",
+  "name": "Mobile ingest",
+  "app": "live",
+  "publish_key": "live_REDACTED_EXAMPLE",
+  "play_key": "play_REDACTED_EXAMPLE",
+  "stats_key": "sts_REDACTED_EXAMPLE",
+  "enabled": true
+}
+ +

Publish, play, and statistics keys

+ + + + + + + +
KeyPurposeWhere to use it
publish_keyAuthorizes a publisher.OBS, FFmpeg, Moblin, or another RTMP/RTMPS publishing client.
play_keyAuthorizes playback.OBS media sources, players, or relay consumers that pull the stream.
stats_keyAuthorizes access to statistics for one stream.NOALBS, monitoring tools, dashboards, and direct statistics checks.
+
Do not interchange the keys. NOALBS only needs the stats_key. Never place the API bearer token, publish_key, or play_key in the NOALBS statistics URL.
+ +

Native JSON endpoint

+

The public per-stream endpoint is:

+ 
http://openrtmp-server:8080/stats?key=sts_REDACTED_EXAMPLE
+

While the publisher is live, the response is a flat JSON object suitable for the native NOALBS provider:

+ 
{
+  "uptime": 18,
+  "bitrate_kbps": 10565.5,
+  "rtt_ms": 100.4,
+  "bytes_in": 34618510,
+  "video": {
+    "codec": "hvc1",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30.0
+  },
+  "audio": {
+    "codec": "Opus"
+  }
+}
+

The key-protected public endpoint intentionally omits the stream ID, display name, application name, players, and server-wide summary. Administrative API endpoints can expose more detail when authenticated with the API bearer token.

+ +

Statistics fields and units

+ + + + + + + + +
FieldMeaning
bitrate_kbpsCurrent incoming publisher bitrate in kilobits per second. NOALBS compares this value with the low and offline thresholds.
rtt_msCurrent publisher round-trip time in milliseconds. NOALBS compares this value with the rtt and rttOffline thresholds.
uptimePublisher connection duration in seconds.
bytes_inTotal media bytes received from the current publisher connection.
+ +

Configure NOALBS v2.19.0 or newer

+

Add an OpenRTMP stream server entry to NOALBS. The complete statsUrl must include the stream's stats_key:

+ 
{
+  "switcher": {
+    "triggers": {
+      "low": 2500,
+      "offline": 500,
+      "rtt": 200,
+      "rttOffline": 2000
+    },
+    "streamServers": [
+      {
+        "name": "openrtmp",
+        "priority": 0,
+        "enabled": true,
+        "streamServer": {
+          "type": "OpenRTMP",
+          "statsUrl": "http://openrtmp-server:8080/stats?key=sts_REDACTED_EXAMPLE"
+        }
+      }
+    ]
+  }
+}
+

The thresholds belong in switcher.triggers, not inside the provider object:

+
    +
  • low: switch to the low-bitrate scene when bitrate_kbps is at or below this value.
    • +
  • offline: switch to the offline scene when a positive bitrate_kbps is at or below this value.
    • +
  • rtt: switch to the low-bitrate scene when rtt_ms is at or above this value.
    • +
  • rttOffline: switch to the offline scene when rtt_ms is at or above this value.
    • +
+

If the stream is offline, the endpoint does not return the live JSON object. The native provider treats a non-successful, unreachable, or non-JSON response as offline.

+ +

nginx-compatible XML fallback

+

Use the XML endpoint when running an older NOALBS release, preserving an existing Nginx provider configuration, or testing compatibility with software that expects nginx-rtmp statistics:

+ 
http://openrtmp-server:8080/stats-nginx?key=sts_REDACTED_EXAMPLE
+

OpenRTMP redacts the real application and stream names in the public XML response. Therefore, the NOALBS provider must use the fixed values live and stream:

+ 
{
+  "name": "openrtmp-xml",
+  "priority": 0,
+  "enabled": true,
+  "streamServer": {
+    "type": "Nginx",
+    "statsUrl": "http://openrtmp-server:8080/stats-nginx?key=sts_REDACTED_EXAMPLE",
+    "application": "live",
+    "key": "stream"
+  }
+}
+

The provider's key value above is the literal redacted stream name stream. It is not the OpenRTMP stats_key; that credential remains inside statsUrl.

+ +

Choose the correct host

+

The URL must be reachable from the machine or container running NOALBS. A URL that works in your desktop browser may still fail from inside a container.

+ + + + + + + + +
DeploymentRecommended host in statsUrl
NOALBS and OpenRTMP on the same Docker networkUse the OpenRTMP service or container DNS name, for example http://openrtmp-server:8080/....
NOALBS on the Docker hostUse the published host port, for example http://127.0.0.1:8080/....
NOALBS on another serverUse a private network address, VPN hostname, or protected public HTTPS hostname that the NOALBS machine can resolve and reach.
NOALBS in a separate containerDo not use localhost unless OpenRTMP shares the same network namespace. Inside a normal container, localhost points back to NOALBS itself.
+

Prefer the internal service name when both applications share a trusted Docker network. Prefer the public HTTPS URL when NOALBS runs remotely and the endpoint is intentionally exposed through a reverse proxy.

+ +

Protect statistics keys

+
    +
  • Replace statistics keys with sts_REDACTED before posting screenshots, logs, configuration files, or issue reports.
    • +
  • Do not commit a real statsUrl containing a key to a public repository.
    • +
  • Redact query strings in reverse-proxy access logs and monitoring alerts where possible.
    • +
  • Rotate or recreate a stream if its statistics key has been exposed.
    • +
  • Use HTTPS whenever the statistics request crosses an untrusted network.
    • +
+ +

Troubleshooting

+

401 Unauthorized

+

Confirm that the query parameter contains the stream's exact stats_key. Also check whether a reverse proxy has added its own authentication requirement or removed the query string while rewriting the request.

+ +

404 Not Found

+

Verify the endpoint path and HTTP port. Test /stats?key=... directly against the OpenRTMP HTTP listener before testing the reverse-proxy URL. A proxy location that only forwards another prefix will return 404 even when OpenRTMP is healthy.

+ +

502 Bad Gateway

+

The reverse proxy cannot reach the OpenRTMP HTTP service. Check the upstream host, port, Docker network, container health, and whether the proxy is trying to use a public hostname that resolves back to itself. From a containerized proxy, use the correct internal service name and port.

+ +

NOALBS reports the server as unreachable

+

Run the request from the same machine or container as NOALBS. Check DNS resolution, firewall rules, TLS certificate trust, and whether localhost refers to the wrong container. Keep the query string intact.

+ +

The URL works publicly but not internally

+

Hairpin NAT, split DNS, or reverse-proxy routing may make the public hostname unusable from the internal network. Use an internal Docker DNS name, private IP, or internal DNS record in NOALBS while keeping the public URL for browsers and remote integrations.

+ +

The XML provider shows zero bitrate or offline

+

Use application: "live" and key: "stream" exactly. Do not put the real OpenRTMP application or stream ID in those fields. Confirm that the publisher is live and that the URL points to /stats-nginx, not /stats.

+ +
+

Test the endpoint before enabling switching

+

Open the sanitized URL with curl, confirm live bitrate and RTT values, then start NOALBS and verify each threshold with non-critical scenes.

+
+ Open server documentation + View NOALBS v2.19.0 +
+
+
+ + +
+
+
+ + From b7ef160f9ca3492abbbb5daa606557c9f1cf68ef Mon Sep 17 00:00:00 2001 From: Alexander Wagner Date: Sun, 26 Jul 2026 22:12:40 +0200 Subject: [PATCH 2/4] Link NOALBS statistics guide --- guides/index.php | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/guides/index.php b/guides/index.php index ed040ff..12e194d 100644 --- a/guides/index.php +++ b/guides/index.php @@ -1,7 +1,7 @@ @@ -37,6 +37,13 @@ Read the codec guide → + +
Comparison · Migration

OpenRTMP vs nginx-rtmp

From c67221dfba74b6818087438cabe3c1e0e2db4724 Mon Sep 17 00:00:00 2001 From: Alexander Wagner Date: Sun, 26 Jul 2026 22:13:03 +0200 Subject: [PATCH 3/4] Add NOALBS statistics guide to sitemap --- sitemap.xml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/sitemap.xml b/sitemap.xml index 5d1b3f7..55284b5 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -14,7 +14,7 @@ https://openrtmp.org/guides/ - 2026-07-18 + 2026-07-26 weekly 0.8 @@ -36,6 +36,12 @@ monthly 0.8 + + https://openrtmp.org/guides/openrtmp-noalbs-json-stats/ + 2026-07-26 + monthly + 0.8 + https://openrtmp.org/guides/openrtmp-vs-nginx-rtmp/ 2026-07-18 From 0d2aaebc4a4d7bd37be17980058cef852db285a1 Mon Sep 17 00:00:00 2001 From: Alexander Wagner Date: Sun, 26 Jul 2026 22:13:19 +0200 Subject: [PATCH 4/4] Smoke-test NOALBS statistics guide --- .github/workflows/site-checks.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/site-checks.yml b/.github/workflows/site-checks.yml index 5bc150d..2529d2b 100644 --- a/.github/workflows/site-checks.yml +++ b/.github/workflows/site-checks.yml @@ -44,6 +44,7 @@ jobs: /guides/self-hosted-rtmp-server-docker/ \ /guides/rtmps-server-obs/ \ /guides/enhanced-rtmp-hevc-av1-opus/ \ + /guides/openrtmp-noalbs-json-stats/ \ /guides/openrtmp-vs-nginx-rtmp/ \ /docs/ \ /download/ \