Core Concepts

Pipeline Class

The Pipeline class allows chained media transformations that execute in sequence, providing atomic execution, reduced boilerplate, and automatic dependency handling.

Class Overview

pipeline-basic.ts

typescript

Input Acceptance

Accepts an input file on creation for processing

Method Chaining

Supports method chaining - each transformation queues up a step

Deferred Execution

Execution deferred until .run() is called

Event Emission

Emits progress and error events across the entire pipeline

Constructor

constructor.ts

typescript

Parameters:

inputPath to the source file

Internally creates a job queue where each step is appended for sequential execution.

Methods

Pipeline methods are wrappers around core MediaX methods. Each appends a step to the pipeline:

1. convert

conversion

convert(output, format, options?)

Queue a format conversion

pipeline.convert("converted.mkv", "mkv");

2. compress

optimization

compress(output, bitrate)

Queue a compression step

pipeline.compress("compressed.mp4", "800k");

3. extractAudio

audio

extractAudio(output, format)

Queue audio extraction

pipeline.extractAudio("track.mp3", "mp3");

4. replaceAudio

audio

replaceAudio(audioFile, output)

Queue audio replacement

pipeline.replaceAudio("voiceover.mp3", "dubbed.mp4");

5. thumbnail

image

thumbnail(output, timestamp)

Queue thumbnail capture

pipeline.thumbnail("thumb.png", "00:00:05");

6. clip

editing

clip(output, { start, duration })

Queue video clipping

pipeline.clip("scene.mp4", { start: 20, duration: 8 });

Additional Pipeline Methods

toGif()Queue GIF export

concat()Append concatenation

addWatermark()Overlay watermark

extractFrames()Queue frame extraction

metadata()Queue metadata inspection

run()Execute pipeline

Events

Pipeline extends TypedEmitter, exposing unified events for all steps:

start

triggered when pipeline execution begins

stepStart

emitted when a transformation begins

progress

emitted with cumulative ProgressInfo across steps

stepDone

emitted when a step completes

done

emitted when entire pipeline finishes

error

emitted if any step fails

events-example.ts

typescript

Execution Model

How Pipeline Execution Works:

Sequential Steps: Steps execute in the order they were added
Output Chaining: Each step consumes output from the previous step
Auto Management: Intermediate files are managed automatically
Failure Handling: Failures abort pipeline by default (with cleanup)

Pipeline Flow Example:

✂️

clipExtract intro segment

🏷️

addWatermarkBrand with logo

🗜️

compressOptimize file size

🎬

toGifCreate animation

Error Handling

Pipeline Error Types

PipelineStepErrorfailure in a specific transformation

PipelineValidationErrorinvalid pipeline configuration

PipelineRuntimeErrorruntime execution issues (e.g., missing file)

error-handling.ts

typescript

Properties

steps

array of queued steps

Step[]

input

initial input file

string

currentStep

active step while running

Step | null

isRunning

boolean execution flag

boolean

Complete Usage Example

full-pipeline-example.ts

typescript

This Pipeline Will:

1Extract the first 60 seconds as "intro.mp4"
2Add a logo watermark at position (15, 15)
3Compress the video to 700k bitrate
4Create a 5-second GIF animation

Ready for More Advanced Features?

Now that you understand pipelines, explore advanced topics like progress tracking, error handling, or dive into the complete API reference.

Learn Progress Tracking Error Handling Guide

[2]