MediaX SDK

MediaX SDK is a Node.js TypeScript library for high-level video/audio/media processing built on ffmpeg. It provides a simple, typed interface to convert, compress, extract audio, generate thumbnails, clip, GIF conversion, watermark, frames extraction, and more. It supports real-time progress, accurate percent calculation, and job queues for production-grade pipelines.

Features

• Convert video/audio formats
• Compress videos with bitrate control
• Extract audio tracks
• Replace audio in video
• Generate thumbnails at specific timestamps
• Clip or segment videos
• Convert video segments to GIF
• Concatenate multiple videos
• Add image watermarks
• Extract frames as an image sequence
• Retrieve media metadata
• Real-time progress events with accurate percentage
• Typed events for TypeScript safety
• Job queue support for concurrent processing

Installation

# Using npm
npm install mediax-sdk

# Using pnpm
pnpm add mediax-sdk

Make sure ffmpeg is installed on your system. On Windows, you can download it from FFmpeg.org. On Mac/Linux, you can use brew install ffmpeg or your package manager.

Quick Start

import { MediaX } from "mediax-sdk";

const mx = new MediaX();

// Convert video
const job = mx.convert("input.mp4", "output.mkv");

job.on("start", (cmd) => console.log("Started:", cmd));
job.on("progress", (p) => console.log(`Progress: ${p.percent?.toFixed(1)}%`));
job.on("done", (output) => console.log("Done:", output));
job.on("error", (err) => console.error("Error:", err));

job.start();

Supported Methods

| Method | Description | | ---------------------------------------------------- | --------------------------------------- | | convert(input, output, format?) | Convert video/audio to specified format | | compress(input, output, bitrate?) | Compress video with bitrate | | thumbnail(input, output, time?) | Generate thumbnail at time | | metadata(input) | Get media metadata | | extractAudio(input, output, codec?) | Extract audio track | | replaceAudio(video, audio, output) | Replace audio track in video | | toGif(input, output, { start?, duration? }) | Convert video segment to GIF | | clip(input, output, { start?, duration? }) | Clip video segment | | concat(inputs[], output) | Concatenate multiple videos | | addWatermark(input, watermark, output, { x?, y? }) | Add image watermark | | extractFrames(input, pattern, { fps? }) | Extract frames as images |

Events

Each job emits typed events:

• start(cmdLine: string) → FFmpeg command started
• progress(progress: ProgressInfo) → Progress update with percent, frames, fps, kbps
• done(output?: string) → Job completed
• error(err: Error) → Job failed

job.on("progress", p => console.log(`Percent: ${p.percent?.toFixed(1)}%`));

Job Queue

Run multiple jobs concurrently:

import { Queue } from "mediax-sdk";

const queue = new Queue(2); // 2 concurrent jobs

queue.add(mx.convert("a.mp4", "a_out.mkv"));
queue.add(mx.compress("b.mp4", "b_out.mp4"));
queue.add(mx.toGif("c.mp4", "c.gif", { start: 1, duration: 5 }));

queue.on("jobProgress", (job, progress) => console.log(`${job.opts.input}: ${progress.percent?.toFixed(1)}%`));
queue.on("jobDone", (job) => console.log(`${job.opts.input} done`));
queue.on("empty", () => console.log("All jobs completed"));

ProgressInfo Type

export interface ProgressInfo {
  percent?: number;
  frames?: number;
  currentFps?: number;
  currentKbps?: number;
  time?: string;
}

Development

Clone and build:

git clone https://github.com/ksaurav24/mediax.git
cd mediax/packages/core
pnpm install
pnpm build

Run tests:

pnpm test

Notes

• ffmpeg and ffprobe are automatically configured using @ffmpeg-installer/ffmpeg and @ffprobe-installer/ffprobe.
• Percent progress is accurate using ffprobe to fetch media duration.
• All events are typed for TypeScript, preventing common runtime errors.
• Designed for production pipelines with queue and concurrent processing support.