Media Prepare
Getting Started
FFmpeg presets and declarative builder for CMAF + HLS streaming
@shelby-protocol/media-prepare provides FFmpeg presets and a declarative builder for generating
multi-bitrate adaptive streaming content with HLS playlists and CMAF segments.
Key Features
- Declarative API - Fluent builder pattern for defining transcoding plans
- Platform Agnostic - Works with native FFmpeg (Node.js) or FFmpeg.wasm (browser)
- Adaptive Bitrate - Built-in support for multi-rung video ladders
- CMAF + HLS - Generates fragmented MP4 segments with HLS playlists
- Type Safe - Full TypeScript support with Zod validation
Installation
npm install @shelby-protocol/media-prepareSystem Requirements
Node.js: Requires FFmpeg 7.0+ with libx264 support. Install via brew install ffmpeg (macOS) or your system package manager.
Browser: Requires @ffmpeg/ffmpeg, @ffmpeg/core, and @ffmpeg/util as peer dependencies.
Quick Start
Create a transcoding plan
Use the CmafPlanBuilder to define your encoding settings:
import {
CmafPlanBuilder,
videoLadderPresets,
} from "@shelby-protocol/media-prepare/core";
const plan = new CmafPlanBuilder()
.withInput("input.mp4")
.withOutputDir("output")
.withVideoLadder(videoLadderPresets.vodHd_1080p)
.withVideoCodec({ kind: "x264", preset: "medium" })
.addAudioTrack({
language: "eng",
bitrateBps: 128_000,
default: true,
})
.withSegmentDuration(4)
.withHlsOutput()
.build();Execute with FFmpeg
Use the Node.js executor to run the plan:
import { NodeCmafPlanExecutor } from "@shelby-protocol/media-prepare/node";
const executor = new NodeCmafPlanExecutor();
await executor.execute(plan);Output structure
The executor creates HLS playlists and CMAF segments:
output/
├── master.m3u8 # Master playlist
├── 1080p/
│ ├── playlist.m3u8 # Variant playlist
│ └── segment-*.m4s # Video segments
├── 720p/
│ └── ...
└── audio-eng/
└── ...Package Exports
The library provides three subpath exports for different use cases:
| Export | Description |
|---|---|
@shelby-protocol/media-prepare/core | Platform-agnostic builder, schemas, and codecs |
@shelby-protocol/media-prepare/node | Node.js executor with native FFmpeg |
@shelby-protocol/media-prepare/browser | Browser executor with FFmpeg.wasm |