mediamtx-toolkit

A developer toolkit for building real-time video applications on top of MediaMTX. MediaMTX is infrastructure you configure; this toolkit is a framework you build with.

Instead of installing MediaMTX by hand, writing YAML, and calling its Control API directly, you write:

import { MediaServer } from "mediamtx-toolkit";

await MediaServer.install();

const server = await MediaServer.start({
  config: { protocols: { webrtc: { enabled: true } } },
});

server.on("crashed", () => console.log("MediaMTX crashed, restarting..."));

const paths = await server.paths();

Status

This package currently implements Layer 0: Core — the foundation that later, higher-level APIs (a fluent stream API, recording, pipelines, clustering, a dashboard) will build on. Layer 0 covers:

• Downloading and installing the MediaMTX binary
• Managing its process lifecycle, including crash detection and automatic restart
• Generating its YAML configuration from a typed object, with hot reload
• A typed client for MediaMTX's Control API (global config and read-only path listing)

Per-path stream management, recording, snapshots, WebRTC session helpers, pipelines, plugins, clustering, and the dashboard are not implemented yet.

Installation

npm install mediamtx-toolkit

Node.js 18 or later is required (for the global fetch API).

Usage

Installing and starting MediaMTX

import { MediaServer } from "mediamtx-toolkit";

// Downloads the latest MediaMTX release for the current OS/arch and marks
// it as the active version. Safe to call repeatedly; it is a no-op if the
// version is already installed.
await MediaServer.install();

const server = await MediaServer.start({
  config: {
    protocols: {
      rtsp: { enabled: true },
      webrtc: { enabled: true },
      hls: { enabled: true },
    },
    record: { enabled: false },
  },
});

MediaServer.start() resolves once MediaMTX's Control API responds successfully, so the returned server is ready to use immediately.

Events

MediaServer is an EventEmitter:

server.on("started", () => console.log("MediaMTX is up"));
server.on("stopped", () => console.log("MediaMTX stopped"));
server.on("crashed", (info) => console.log("MediaMTX crashed", info));
server.on("stdout", (line) => console.log(line));
server.on("stderr", (line) => console.error(line));

If the MediaMTX process exits unexpectedly, the toolkit automatically restarts it with exponential backoff, up to a bounded number of attempts within a rolling time window. stop() is always safe to call, including while a restart is pending.

Reconfiguring and reloading

server.configure({ record: { enabled: true, path: "./recordings/%path" } });
await server.reload();

reload() rewrites the configuration file and waits until MediaMTX's Control API reflects the change before resolving.

Listing paths

const paths = await server.paths();

Stopping

await server.stop();

API reference

MediaServer

| Method | Description | | --- | --- | | MediaServer.download(options?) | Downloads a MediaMTX release without marking it active. | | MediaServer.install(options?) | Downloads (if needed) and marks a MediaMTX release as active. | | MediaServer.start(options?) | Resolves a binary, writes configuration, spawns the process, and waits for readiness. | | server.configure(partial) | Merges a partial configuration into the in-memory config. | | server.reload() | Writes the current configuration and waits for MediaMTX to pick it up. | | server.paths() | Returns the current list of paths from the Control API. | | server.stop() | Gracefully stops the process and cancels any pending restart. |

See src/index.ts for the full set of exported types, including ToolkitConfig, StartOptions, PathInfo, and the error classes (MediaMTXNotInstalledError, MediaMTXDownloadError, MediaMTXStartError, MediaMTXApiError).

Development

npm install
npm run build
npm test              # unit tests, no network or process spawning
npm run test:integration   # real MediaMTX download and process, requires network
npm run typecheck

License

MIT