Open Source • TypeScript • FFmpeg

DeclarativeFFmpeg for Node.js

Transform complex FFmpeg operations into clean, chainable pipelines with real-time progress tracking and TypeScript-native developer experience.

View Documentation

Zero Config

Type Safe

Production Ready

MediaX Pipeline

 1import { MediaX } from 'mediax-sdk';
 2
 3const mx = new MediaX();
 4const pipeline = new mx.pipeline()
 5  .convert("output.mkv", "matroska")
 6  .compress("output_compressed.mkv", "800k")
 7  .extractAudio("audio.aac", "aac")
 8  .thumbnail("thumb.png", "00:00:05")
 9  .run("sample.mp4")
10  .on("progress", (percent, jobIndex, total, eta) =>
11    console.log(`Pipeline: ${percent.toFixed(1)}% (Job ${jobIndex}/${total}) ETA: ${eta?.toFixed(1)}s`)
12  )
13  .on("done", () => console.log("Pipeline completed successfully"))

Pipeline Progress87%

SDK Overview

FFmpeg TypeScript SDK

A Node.js/TypeScript wrapper for FFmpeg operations with declarative pipeline architecture, real-time progress tracking, and type-safe API design for media processing workflows.

TypeScript First

Strongly Typed

Native TypeScript implementation with comprehensive type definitions, generic constraints, and full IntelliSense integration.

TypedEmitter<Events> • Generic Pipelines • Type Guards

Event-Driven Progress

EventEmitter Based

Real-time progress events with FFmpeg parsing, frame-based progress calculation, and customizable progress handlers.

Progress Events • ETA Calculation • Frame Parsing

Pipeline Architecture

Functional API

Declarative job orchestration with method chaining, error propagation, and concurrent execution support.

Method Chaining • Job Queue • Error Bubbling

API Reference

Video Operations

convert

(input: string, output: string, options?: ConvertOptions)

compress

(input: string, output: string, quality: number)

clip

(input: string, output: string, start: number, duration: number)

concat

(inputs: string[], output: string)

Media Processing

thumbnail

(input: string, output: string, timestamp?: number)

watermark

(input: string, watermark: string, output: string)

extractAudio

(input: string, output: string)

replaceAudio

(video: string, audio: string, output: string)

Batch & Advanced

frames

(input: string, outputDir: string, options?: FrameOptions)

toGif

(input: string, output: string, options?: GifOptions)

process

(pipeline: Pipeline): Promise<JobResult[]>

queue

(jobs: Job[], options?: QueueOptions)

SDK Architecture

Core Classes

Primary SDK components and their responsibilities

MediaX

Main processor class with method-based API

Pipeline

Job orchestration and workflow management

Job

Individual task wrapper with progress tracking

ProgressInfo

Typed progress data structure

Progress System

Real-time tracking and event system

FFmpeg Parser

Parse FFmpeg output for progress data

Event Emitters

TypedEmitter for progress/error events

ETA Calculator

Time estimation algorithms

Frame Counter

Frame-based progress calculation

Process Management

FFmpeg process handling and optimization

Process Pool

Concurrent FFmpeg process management

Memory Monitor

Resource usage tracking and cleanup

Error Handler

FFmpeg error parsing and recovery

Stream Manager

Input/output stream optimization

Technical Requirements

Runtime

Node.js 16+

Language

TypeScript 4.5+

Engine

FFmpeg 4.0+

npm install mediax-sdk

Getting Started

Start Building with MediaX

Follow these steps to integrate MediaX into your project and start processing media files with TypeScript-native, event-driven workflows.

installation.sh

bash

Installation

Get started with MediaX in seconds with zero configuration

1 of 5

Available Methods

compress

Reduce file size

extractAudio

Get audio track

thumbnail

Generate preview

clip

Extract segment

toGif

Create animated GIF

concat

Merge videos

addWatermark

Add overlay

extractFrames

Export frames

metadata

Get video info

replaceAudio

Swap audio track

Need Detailed Documentation?

Explore the full docs to master MediaX's capabilities and advanced features.

Visit Docs

Open Source • Community Driven

Let's Build Together

MediaX is my journey as a student developer learning to build tools that matter. While I strive for quality, there are undoubtedly bugs to fix, optimizations to make, and features to add.

Your contributions don't just improve MediaX—they help create better tools for the entire developer community working with media processing.

Join the Community

Every contribution, no matter how small, makes a difference in building better tools for developers worldwide.

Active Project

MIT Licensed

Ways to Make an Impact

Bug Hunting

Help identify issues and edge cases

FFmpeg crashes

Memory leaks

Progress errors

Code Enhancement

Improve performance and add features

New operations

Optimizations

Error handling

Documentation

Make MediaX easier to understand

Tutorials

API docs

Examples

Innovation

Suggest new ideas and improvements

Feature ideas

Architecture

DX improvements

Ready to Contribute?

Whether you're fixing a typo or adding a major feature, every contribution helps build better tools for the developer community.

Explore Repository

Report Issues