Node-Media-Server: RTMP and HTTP-FLV Live Streaming Server in Node.js

What Node-Media-Server Solves

Most live streaming workflows need an ingest point that accepts a publisher's RTMP stream (from OBS, FFmpeg, or a mobile app) and a delivery mechanism that serves that stream to viewers. Node-Media-Server provides both in a single Node.js process. It accepts RTMP and RTMPS for publishing and serves the content over HTTP-FLV, WS-FLV, RTMP, and RTMPS. This covers common use cases: an OBS broadcaster publishes to RTMP, and viewers watch via HTTP-FLV in a browser using a compatible player. The server also handles recording streams to FLV files and can serve those recordings as video-on-demand when the static file server is enabled. Version 4 is designed specifically to handle newer video codecs: HEVC, VP9, and AV1 through the enhanced FLV v1 specification, expanding coverage beyond the H.264+AAC combination that legacy FLV supported. The package is published on npm as node-media-server and the current version is 4.4.3. Node.js 20 or later is required.

Protocol Support Matrix and v4 Breaking Changes

Version 4 introduces two deliberate compatibility breaks. First, it drops support for the cn_cdn extension ID flv_265 standard, which was a non-standard way of embedding HEVC in FLV used by some Chinese CDN deployments. Second, it removes support for the Flash Player RTMP protocol, meaning older Flash-based players and some legacy encoders will not work with v4. The README is explicit: v4 is incompatible with v2 and cross-major-version upgrades are unsupported. The codec support matrix shows which clients handle which codecs. OBS 29.1 and later supports H.264, HEVC, and AV1. FFmpeg and FFplay 6.1 and later support all four codecs including VP9. NodePlayer.js 1.0 and later handles H.264 and HEVC. NodeMediaClient 3.0 and later also handles H.264 and HEVC. VP9 and AV1 require FFmpeg on the client side. A free Android live streaming app named QLive from the NodeMedia ecosystem also publishes to Node-Media-Server and is listed in the README as a tested client for mobile publishing workflows.

Installing and Running Node-Media-Server

Install globally via npm and run immediately:

npm install node-media-server -g

Or run without installing:

npx node-media-server

The CLI accepts several flags to override configuration file values:

Options:
  -c, --config <path>    Path to the config file (default: bin/config.json)
  -b, --bind <addr>      Bind address, overrides the "bind" config value
      --rtmp-port <n>    RTMP port, overrides rtmp.port
      --http-port <n>    HTTP/WebSocket port, overrides http.port
      --https-port <n>   HTTPS/WSS port, overrides https.port
      --record-path <p>  Record output directory, overrides record.path
      --record-auto      Enable auto recording, forces

For Docker, the Dockerfile exposes ports 1935 (RTMP), 8000 (HTTP/WS), and 8443 (HTTPS/WSS). The Docker build uses a two-stage process: a Node.js Alpine image builds the Web Admin UI, and the runtime image copies the built admin assets and server source. Node.js 20 or later is required.

REST API, Web Admin UI, and Session Management

Version 4.2.0 added a REST API secured with JWT-based authentication using a challenge-response login flow. The API covers stream and session management, relay task management, real-time monitoring, and health statistics. Version 4.3.0 expanded this significantly with a Web Admin UI that provides a dashboard, stream list, recordings browser, history search, relay configuration, and server settings. Authentication uses username and password hashed with scrypt, with login rate limiting to resist brute-force attempts. The admin password can be changed via the API. Session deletion allows an operator to terminate a live stream programmatically. History search accepts filters by stream path, client IP address, and time range. The configuration management API validates settings before applying them, and a graceful shutdown endpoint stops the server cleanly without dropping active sessions mid-stream.

Recording and Static File Serving

The server can record every published stream to an FLV file automatically or on demand. The record configuration block specifies the output path and whether recording starts automatically:

"record": {
    "path": "./html/record",
    "auto": true
}

Set auto to false to disable automatic recording; individual streams can then be recorded on demand via the Web Admin UI or the POST /api/v1/streams/{app}/{name}/record endpoint. When the static file server is enabled and recordings are stored in its serving directory, the server doubles as a video-on-demand endpoint accessible at a URL like http://server_ip:8000/record/live/stream/unix_time.flv. Version 4.3.0 added record session resume: if a publisher reconnects within a grace period, the recording resumes to the same file rather than starting a new one. Record file downloads are also available through the Web Admin UI.

Limitations and Alternatives

Node-Media-Server does not produce HLS (HTTP Live Streaming) or DASH output natively. It delivers over HTTP-FLV and WebSocket-FLV, which require a player that supports FLV (such as NodePlayer.js or flv.js). Browsers do not play FLV natively, so a JavaScript player is mandatory on the client side. There is no adaptive bitrate streaming: the server relays the stream at the bitrate the publisher sends, with no transcoding to multiple quality levels. For workflows that need HLS output, multi-bitrate ladders, or DVR-style playback with wide device compatibility, a media server like SRS (Simple Realtime Server) or nginx-rtmp-module with FFmpeg transcoding is a better architectural fit. SRS is written in C++, targets higher concurrency, and outputs HLS and RTMP with explicit support for CDN origin-edge topologies, which Node-Media-Server does not address.

The supported client list in the README shows a significant gap: NodePlayer.js and NodeMediaClient only support H.264 and HEVC, not VP9 or AV1. This means the enhanced codec support in v4 is practically useful only when both the publisher and the player run FFmpeg 6.1 or later. Streams published at HEVC but played back through NodePlayer.js 1.0 work; streams published at VP9 or AV1 and viewed through NodePlayer.js do not. For consumer-facing applications where the player is not controlled, H.264 remains the only broadly supported codec across all listed clients. The Notification feature in the server allows webhooks to fire when streams are published, played, or stopped, enabling external systems to react to streaming events without polling the REST API.

Editorial conclusion

Node-Media-Server v4 is a solid choice for teams that need a self-hosted live streaming ingest and relay server with Node.js, do not require adaptive bitrate streaming, and accept FLV as the delivery format for HEVC and newer codecs. The v4 breaking changes from v2 make in-place upgrades across major versions unsupported; read the changelog before upgrading. Teams that need HLS or DASH output, adaptive bitrate ladders, or production-grade origin-edge scaling should evaluate a dedicated media server. The project is actively developed: the last push was on 2026-09-10 and the package is on npm at node-media-server.

Frequently asked questions

Official sources

1. illuspas/Node-Media-Server on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README