media-processing
The WebCodecs API and a full HLS encoder — one isomorphic library that runs the same code in Node.js and the browser.
---
> **The browser's `VideoEncoder`, `VideoDecoder`, `VideoFrame`, and `MediaStream` — in Node.js**, backed by FFmpeg child processes (no WASM, no native addons, no build step).
> **Plus a complete HLS encoder** — MPEG-TS and fMP4/CMAF, LL-HLS, encryption, captions, subtitles, ABR ladders, HDR, ad markers — and an **HLS parser** for reading playlists back.
> Write once. Run in Node (over FFmpeg) or in the browser (over native WebCodecs).
---
## Table of Contents
1. [Why media-processing?](#-why-media-processing)
2. [Install & loading](#-install--loading)
3. [Quick start](#-quick-start)
4. [Browser-compatible API](#-browser-compatible-api)
5. [Node.js API](#-nodejs-api)
6. [HLS](#-hls)
7. [Bitstream utilities](#-bitstream-utilities)
8. [Supported codecs & containers](#-supported-codecs--containers)
9. [Hardware acceleration](#-hardware-acceleration)
10. [Comparison with other libraries](#-comparison-with-other-libraries)
11. [Use cases](#-use-cases)
12. [Project structure](#-project-structure)
13. [Roadmap](#-roadmap)
14. [Limitations & tradeoffs](#️-limitations--tradeoffs)
15. [Compatibility matrix](#-compatibility-matrix)
16. [How it works](#️-how-it-works)
17. [License](#-license)
## 🧠 Why media-processing?
Two problems, one library:
1. **Node.js has no built-in media encoding/decoding**, and existing solutions need native C++ bindings (complex builds) or WASM (slow startup, big bundles). None give you the browser's clean `VideoEncoder` / `VideoDecoder` API.
2. **Producing HLS used to require a server.** Multi-bitrate, encrypted streams with captions and ad markers meant operating a transcode fleet — even when the content originated in the browser.
media-processing solves both, and does it the same way on both sides of the wire:
- **`npm install` and go** — zero native bindings, zero build step on the Node side.
- **Browser-compatible API** — the same `VideoEncoder`, `VideoDecoder`, `VideoFrame`, `MediaStream` classes you use in Chrome.
- **A real HLS encoder built in** — take `VideoFrame` / `AudioData`, get HLS segments and playlists. TS or fMP4, LL-HLS parts, AES-128, CEA-608 captions, WebVTT/IMSC subtitles, ABR ladders, I-frame playlists, HDR, ID3, SCTE-35, Interstitials.
- **HLS reading too** — `parseMediaPlaylist` / `parseMasterPlaylist` turn an `.m3u8` back into structured objects (the exact inverse of the writers).
- **Isomorphic** — in Node, encoding runs through FFmpeg child processes; in the browser, through native WebCodecs. The library code above that line is identical.
- **Realtime-first** — designed for WebRTC, streaming, conferencing: SVC temporal layers, error-resilient encoding, frame pacing, backpressure.
### What "isomorphic" means here
The library implements the same **class names, method signatures, and data flow** as the W3C WebCodecs spec. The engine underneath differs by environment:
- **In the browser**, `VideoEncoder` / `AudioEncoder` are the platform's native WebCodecs — hardware-accelerated, zero process overhead.
- **In Node.js**, they're a polyfill backed by FFmpeg child processes (`spawn('ffmpeg', …)` over pipes). Same inputs, same outputs, same callbacks.
Higher-level pieces — the HLS muxer, playlist builders/parsers, bitstream utilities — are pure JavaScript and behave identically in both. The one place you choose an engine is the **codec seam** (see [the seam](#the-codec-seam-how-isomorphism-works)).
Caveats for the Node/FFmpeg engine specifically: force-keyframe is implemented by restarting FFmpeg (~50 ms one-frame latency; browsers do it internally), per-frame quantizer is applied as a global CRF, alpha is `'discard'`-only, and first-frame latency is ~100 ms for process startup (steady-state is codec-bound, not pipe-bound).
## 📦 Install & loading
### Node.js
```bash
npm install media-processing
```
> **FFmpeg** is required for the Node engine. If it isn't on your PATH:
> ```bash
> npm install ffmpeg-static
> ```
> media-processing auto-detects `ffmpeg-static` and `@ffmpeg-installer/ffmpeg` — no configuration. GStreamer is optional (camera capture only).
```js
import { VideoEncoder, HLSEncoder, parseMediaPlaylist } from 'media-processing';
```
### Browser
The browser build ships **two bundles**, so every loading style is covered:
| File | Format | How you load it |
|---|---|---|
| `media-processing.esm.js` | ES module | `import { … } from './media-processing.esm.js'` |
| `media-processing.umd.js` | UMD | `
```
**Method 2 — global via `
```
**Method 3 — `require()` / AMD** (Node consumers of the browser build, or legacy loaders):
```js
const MP = require('./media-processing.umd.js');
```
> Note: the package declares `"type": "module"`, so Node treats bare `.js` as ESM. To `require` the UMD build inside this package, give it a `.cjs` extension (or consume it from a non-`type:module` context). In the browser the extension is irrelevant — the `