Node-Media-Server v4: RTMP and HTTP-FLV streaming in Node.js

What Node-Media-Server solves, and who it is for

Most RTMP servers are C or C++ daemons you deploy as an opaque binary. Node-Media-Server takes the opposite position: the origin is a Node.js package, so the ingest path, the HTTP surface and the web admin console all live in JavaScript you can read and patch. The README describes it as a "high-performance/low-latency/open-source Live Streaming Server developed based on Nodejs".

The audience is narrow but real. If you already run Node.js services and need an RTMP ingest endpoint that also serves HTTP-FLV and WebSocket-FLV playback, this removes a second runtime from your stack. If you need RTMPS or HTTPS/WSS, the CLI exposes dedicated ports for both. The project also ships a static file server, so recorded FLV files can be served back as video on demand from the same process.

It is not a general-purpose media framework. There is no transcoding, no HLS or DASH packaging mentioned, and no adaptive bitrate logic. You push one codec profile in, and clients pull that same profile out.

How v4 handles HEVC, VP9 and AV1 over RTMP and FLV

The central design decision in v4 is codec carriage. Classic RTMP and FLV were built around H.264 and AAC. The README states that v4 "is design to implement enhanced RTMP FLV v1 support for native HEVC, VP9, AV1", meaning the FLV container is extended rather than wrapped. That choice has a direct consequence: the README also states v4 "is no longer compatible with the cn_cdn extension id flv_265 standard". A previously common way of signalling H.265 is gone.

The supported client table in the README makes the compatibility cost concrete. OBS 29.1 and newer is listed with H.264, HEVC and AV1 support but not VP9. FFmpeg and FFplay 6.1 and newer are listed with all four. NodePlayer.js 1.0 and NodeMediaClient 3.0 are listed with H.264 and HEVC only. So publishing AV1 from OBS works, but playing it back in the vendor's own JavaScript player does not, according to that table.

Internally the repository is organised around src/, bin/, webadmin/ and test/. The package exposes bin/app.js as the executable and src/index.js as the main entry, which is the shape you would expect if you want to embed the server in a larger Node process rather than run it as a daemon.

Installing Node-Media-Server and publishing a first stream

The README gives two install paths. The global install puts the node-media-server binary on your PATH. The npx form runs it without a global install. Node.js 20.0.0 or newer is required according to the engines field in package.json.

npm install node-media-server -g

Alternatively, run it directly without installing:

npx node-media-server

With the server running, point a publisher at the default RTMP port. The Dockerfile exposes 1935 for RTMP, 8000 for HTTP/WebSocket and 8443 for HTTPS/WSS, which tells you which ports the container expects to be reachable. In OBS, the server URL would be rtmp://localhost:1935/live and the stream key would be your stream name.

Playback over HTTP-FLV follows the static file pattern shown in the README. Recorded files land under the configured record path with a unix timestamp in the filename:

http://server_ip:8000/record/live/stream/unix_time.flv

The README lists a Web Admin UI among its features. If you want a container instead of a host install, the Dockerfile builds the webadmin console in a separate stage and then copies only bin, src and the built dist into the runtime image, with npm ci --omit=dev for dependencies.

Auto-recording, the admin console and where the defaults bite

Two config blocks in the README deserve attention before you expose the server. The first is recording. With "auto": true, every published stream is written to disk. The README is explicit that setting "auto": false disables auto-recording of every published stream, and that streams can then be recorded on demand through the webadmin streams page or POST /api/v1/streams/{app}/{name}/record. On a public ingest endpoint, recording everything is a disk-filling failure mode, not a convenience.

The second is the admin surface. The README documents a web admin UI with Dashboard, Streams, Records, History, Relay and Settings, plus username and password login with scrypt hashing and login rate limiting. That is a meaningful amount of privileged functionality behind one HTTP port. If you are running this behind a load balancer, decide early whether the admin console is reachable from the internet. Use HTTPS for production admin logins: the upstream API documentation says the password is sent in the login request, even though stored passwords are hashed.

Authentication is separate from the admin login. The README lists JWT-based authentication as a v4.2.0 feature.

The v2 to v4 upgrade is a migration, not an upgrade

This is the limitation that will decide the project for many teams. The README states plainly that "v4 is incompatible with v2" and adds "Do not upgrade across major versions." There is no documented migration path, no compatibility shim and no deprecation window described. If you are running v2 in production, v4 is a separate deployment you would run alongside it, not a version bump.

The codec story carries a second cost. Enhanced RTMP FLV v1 support for HEVC, VP9 and AV1 is only useful if both ends of the chain speak it. The README's own client table shows gaps: NodePlayer.js and NodeMediaClient list no VP9 or AV1 support. A publisher using FFmpeg 6.1 can push AV1, but a viewer on the vendor's JavaScript player cannot decode it according to that same table. Mixed fleets will need to standardise on H.264 or HEVC.

Finally, the README does not document rollback behaviour, and the only GitHub release is v3.0.0 from 2019. Version 4.4.6 appears in package.json, so pinning that exact version is the only concrete anchor available if you need reproducibility.

How Node-Media-Server compares with nginx-rtmp and MediaMTX

The obvious alternative for RTMP ingest is the nginx-rtmp module. The difference in approach is not performance, it is extensibility. nginx-rtmp lives inside an nginx worker process configured through nginx.conf directives; adding custom logic means writing a C module or bolting on callbacks. Node-Media-Server puts the same ingest role in JavaScript, with a REST API, a web admin UI and relay tasks defined as data rather than directives. If your team writes Node.js and wants to hook stream events, the second model is closer to hand.

MediaMTX (formerly rtsp-simple-server) is the other common choice, and the contrast is protocol coverage. MediaMTX is built around RTSP, RTMP, HLS, WebRTC and SRT in a single Go binary. Node-Media-Server's README lists RTMP/RTMPS, HTTP/HTTP2-FLV and WS/WSS-FLV, with RTSP appearing only as a pull source for relay tasks, not as a listening protocol. If you need WebRTC playback or SRT ingest, the README points to the commercial NodeMediaServer v3 rather than this server.

The trade-off runs the other way on codecs. Node-Media-Server v4 targets enhanced RTMP FLV with native HEVC, VP9 and AV1. Whether a given alternative matches that depends on its own release notes, which are outside this review.

Licence and the cost of keeping it current

The project is licensed under Apache-2.0, stated in both the README and package.json. That is a permissive licence with an explicit patent grant, which matters for a media server because codec handling is where patent questions tend to surface. Apache-2.0 does not grant you codec patent rights, and it does not cover the licensing of HEVC or AV1 implementations you might bundle alongside it. This is a description of the licence text, not legal advice; if you ship a commercial product, that question belongs with counsel.

The upgrade cost is shaped by the version policy rather than by dependency churn. The runtime dependency list is short: cors, express, express-jwt, express-rate-limit, http2-express, jsonwebtoken and ws. Those are ordinary npm packages that move on their own schedule, and express 5 plus express-jwt 8 are recent majors. The larger cost is the major-version boundary itself. Because the README forbids cross-major upgrades, every v4 release line you adopt becomes a deployment decision rather than an npm update. The repository includes test/ and a node --test based test script, so a fork or a pinned deployment can at least run the project's own suite before you commit to a version.

Editorial conclusion

Adopt Node-Media-Server if you want a self-hosted RTMP and HTTP-FLV origin that runs on Node.js 20 or newer and you are comfortable with a v4 that deliberately breaks from v2. Do not adopt it if you need a stable upgrade path from v2, since the README states v4 is incompatible with v2 and that you must not upgrade across major versions. Before deploying, verify the config keys you rely on against bin/config.json, confirm your players support the codecs you intend to publish, and check how authentication is configured in your setup.

Frequently asked questions

Official sources

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