Adaptive bitrate (ABR) in Nighthawk creates multiple renditions of the same live stream so players can switch quality dynamically. This guide focuses on what ABR variants Nighthawk actually supports, how licensing gates ABR at startup, and the specific playback caveats to be aware of—especially when you enforce signed playback.
See /server-docs for installation and configuration context.
Prerequisites and licensing
Before you plan an ABR ladder, confirm that your deployment is licensed for ABR. If ABR is requested but the runtime determines the license isn’t sufficient, ABR is disabled during startup. In practice, setting NH_ABR=on with a default/standard plan (or no plan set) results in a log note that ABR was requested but requires a higher license and is disabled. Treat this as a capability gate; it does not imply any throughput, latency, or availability profile.
If you’re deciding plan tiers that include ABR, see /#pricing for an overview of available options.
Supported ABR renditions
Nighthawk’s ABR logic recognizes a fixed set of variant names. Requests for unknown variants are skipped at startup.
- Supported variants: 1080p, 720p, 480p, 360p, 240p
- Behavior on typos/unknowns: the runtime logs that the variant is unknown and continues without it
Plan your ladder using only these names. When you configure variants, keep them strictly to the accepted set so you don’t end up with gaps between your intended ladder and what actually comes up at runtime.
Variant naming in playback URLs
When ABR is enabled and variants are active, you can address individual renditions by a suffix in the stream key. For example, mystream_720p refers to the 720p rendition. This is useful when you want to sign and test a single rung or when your player selects a specific variant.
If you enforce signed playback, use the included helper to generate a signed URL for either the base stream or a specific variant. The helper signs the stream key (including any _720p-style suffix) and an expiry with HMAC-SHA256, then appends token and expiry parameters to the URL. You remain responsible for choosing an appropriate TTL and for managing the secret.
Enforcing signed playback (and how it interacts with ABR)
Signed playback is off by default. When you set the playback secret in the environment and restart, Nighthawk enforces signed tokens on playback requests (HLS, HTTP-FLV, WebRTC). For HLS specifically, the runtime ensures sessions trigger the on_play path so token validation occurs before a session proceeds.
Two caveats to be aware of when combining ABR and signed playback:
- Internal ABR fetches: The ABR transcoder pulls the source stream from inside the container. During on_play validation, loopback requests are exempted from token checks only when ABR is actually enabled. This prevents the internal transcoder pipeline from being blocked by viewer-side token enforcement.
- Variant-specific tokens: If you sign a URL for mystream_720p, the token is bound to that specific stream key. A token for mystream does not authorize mystream_720p, and vice versa. Ensure your backend issues tokens that match what the player will request.
If you do not set a playback secret, playback proceeds without token checks. These controls are application-layer checks; they do not guarantee security or delivery in every scenario.
Configuration steps: ABR and signed playback together
- Decide your ladder from the supported set: 1080p, 720p, 480p, 360p, 240p.
- Verify your license tier enables ABR; if not, ABR will be disabled at startup even if requested.
- Set NH_ABR=on and define only supported variants.
- If you require viewer-side authorization, set a playback secret and restart so playback sessions are validated.
- Expose the playback HTTP endpoint your players will use. In a typical Docker deployment, HLS and HTTP-FLV are served on TCP 8080 unless you’ve remapped the port.
Note: Protocol bindings and ports are connectivity surfaces only; they don’t imply end-to-end performance or availability.
Failure modes you should plan for
- License gate disables ABR: When NH_ABR=on is set but your license is insufficient or unset, ABR is disabled at startup. Outcome: only non-ABR behavior; plan logs will note the disablement.
- Unknown variant names: Any variant outside the supported list is skipped during startup. Outcome: fewer rungs than intended. Fix the names and restart.
- Signed playback missing/invalid: When a playback secret is set, missing or invalid tokens on playback are rejected. Outcome: players fail to start playback until correct tokens are used.
- Variant token mismatch: A token generated for mystream does not authorize mystream_360p. Outcome: variant playback fails; generate the token for the exact stream key used by the player.
- Internal transcoder exemption: Loopback requests are only exempt from token checks when ABR is actually enabled. Outcome: if you expect ABR but it is disabled by licensing, do not assume internal fetches will be exempted.
Verification checklist (actionable)
- Licensing and startup
- Start the container with your intended license and NH_ABR=on. Inspect logs for any message that ABR was requested but disabled due to licensing. If present, resolve licensing before proceeding.
- Confirm that only supported variants are present; fix any “unknown variant” messages.
- Signed playback
- If enforcing signed playback, set the playback secret and restart. Confirm in logs that signed playback is enforced for HLS.
- Use the helper to sign two URLs: one for mystream and one for mystream_720p. Attempt playback with each. Confirm that tokens are bound to exactly what you signed.
- Player requests and ports
- Ensure your player points at the correct HTTP endpoint (default 8080 unless remapped) and uses the intended path and stream key (with _720p, etc., when testing variants).
- End-to-end sanity
- Publish a test stream. Verify that the expected variant playlists/outputs are addressable. If a variant fails, check for a skipped/unknown-variant log or licensing disablement.
- With signed playback on, attempt an unsigned playback and confirm it is rejected; then try with a valid, unexpired token and confirm it succeeds.
Notes and trade-offs
- Only the documented variants are recognized; this keeps configuration predictable but limits arbitrary rung definitions.
- Signed playback adds an application-layer check to playback paths. It helps gate access but does not guarantee overall security, delivery, latency, or throughput.
- Port exposure and protocol bindings control connectivity. They do not imply any specific quality metrics.
For broader configuration details and operational sections (Installation & Updates, Configuration & Ports, Publishing & Playback, Recording & Features, Management APIs, Licensing, Troubleshooting), see /server-docs.