FFmpeg Class

The main class for video/audio processing operations.

Constructor

new FFmpeg(options?: FFmpegConstructorOptions)

Creates a new FFmpeg instance.

Options:

Property	Type	Description
ffmpegPath	string?	Custom path to FFmpeg binary
ffprobePath	string?	Custom path to FFprobe binary

Example:

import { FFmpeg } from 'ffmpeg-forge';

// Auto-detect FFmpeg
const ffmpeg = new FFmpeg();

// Custom paths
const ffmpeg = new FFmpeg({
  ffmpegPath: '/usr/local/bin/ffmpeg',
  ffprobePath: '/usr/local/bin/ffprobe',
});

---

Static Methods

setFFmpegPath

static setFFmpegPath(path: string): void

Set global FFmpeg binary path for all instances.

Parameters:

• path - Absolute path to FFmpeg binary

Example:

FFmpeg.setFFmpegPath('/opt/ffmpeg/bin/ffmpeg');

---

setFFprobePath

static setFFprobePath(path: string): void

Set global FFprobe binary path for all instances.

---

getVersion

static async getVersion(): Promise<FFmpegVersionInfo>

Get FFmpeg version information and configuration.

Returns:

interface FFmpegVersionInfo {
  version: string;              // "4.4.2"
  major: number;                // 4
  minor: number;                // 4
  patch: number;                // 2
  configuration: string[];      // Build configuration flags
  libavutil: string;
  libavcodec: string;
  libavformat: string;
  libavdevice: string;
  libavfilter: string;
  libswscale: string;
  libswresample: string;
}

Example:

const version = await FFmpeg.getVersion();
console.log(`FFmpeg ${version.version}`);

---

getFormats

static async getFormats(): Promise<{ demuxing: string[]; muxing: string[] }>

Get all supported input and output formats.

Returns:

• demuxing - Input formats (container formats FFmpeg can read)
• muxing - Output formats (container formats FFmpeg can write)

Example:

const { demuxing, muxing } = await FFmpeg.getFormats();
console.log('Can output MP4:', muxing.includes('mp4'));

---

getCodecs

static async getCodecs(): Promise<FFmpegCapabilities>

Get all available encoders and decoders.

Returns:

interface FFmpegCapabilities {
  video: {
    encoders: string[];        // ['libx264', 'h264_nvenc', ...]
    decoders: string[];        // ['h264', 'hevc', ...]
  };
  audio: {
    encoders: string[];        // ['aac', 'libmp3lame', ...]
    decoders: string[];        // ['aac', 'mp3', ...]
  };
  subtitle: {
    encoders: string[];
    decoders: string[];
  };
}

Example:

const codecs = await FFmpeg.getCodecs();
const hasNVENC = codecs.video.encoders.includes('h264_nvenc');

---

getCapabilities

static async getCapabilities(): Promise<FFmpegCapabilities>

Alias for getCodecs().

---

canOutputFormat

static async canOutputFormat(format: string, throwOnError?: boolean): Promise<boolean>

Check if FFmpeg supports outputting to a specific format.

Parameters:

• format - Format name (e.g., "mp4", "webm")
• throwOnError - Throw error if not supported (default: false)

Example:

if (await FFmpeg.canOutputFormat('mp4')) {
  console.log('MP4 output supported');
}

---

canEncodeWithCodec

static async canEncodeWithCodec(
  codec: string,
  type?: StreamType,
  acceleration?: HardwareAccelerationValue,
  throwOnError?: boolean
): Promise<boolean>

Check if FFmpeg can encode with a specific codec.

Parameters:

• codec - Codec name (e.g., "libx264", "h264_nvenc")
• type - Stream type (default: VIDEO)
• acceleration - Required hardware acceleration
• throwOnError - Throw error if not supported

Example:

const hasNVENC = await FFmpeg.canEncodeWithCodec(
  'h264_nvenc',
  StreamType.VIDEO,
  HardwareAcceleration.NVIDIA
);

---

canDecodeWithCodec

static async canDecodeWithCodec(
  codec: string,
  type?: StreamType,
  acceleration?: HardwareAccelerationValue,
  throwOnError?: boolean
): Promise<boolean>

Check if FFmpeg can decode a specific codec.

---

verifyOutputSupport

static async verifyOutputSupport(options: {
  format?: string;
  videoCodec?: string;
  audioCodec?: string;
  acceleration?: HardwareAccelerationValue;
}): Promise<{
  supported: boolean;
  details: {
    format?: { supported: boolean; name: string };
    videoCodec?: { supported: boolean; name: string };
    audioCodec?: { supported: boolean; name: string };
  };
}>

Verify if a combination of format/codecs is supported.

Example:

const support = await FFmpeg.verifyOutputSupport({
  format: 'mp4',
  videoCodec: 'h264_nvenc',
  audioCodec: 'aac',
  acceleration: HardwareAcceleration.NVIDIA,
});

if (!support.supported) {
  console.error('Configuration not supported');
}

---

getAvailableHardwareAcceleration

static async getAvailableHardwareAcceleration(): Promise<HardwareAccelerationInfo[]>

Detect available hardware acceleration methods.

Returns:

interface HardwareAccelerationInfo {
  type: HardwareAccelerationValue;
  available: boolean;
  codecs: string[];
}

Example:

const hwAccel = await FFmpeg.getAvailableHardwareAcceleration();
for (const hw of hwAccel) {
  if (hw.available) {
    console.log(`${hw.type}: ${hw.codecs.join(', ')}`);
  }
}

---

getEncodersByAcceleration

static async getEncodersByAcceleration(
  acceleration?: HardwareAccelerationValue,
  type?: StreamType
): Promise<string[]>

Get available encoders for specific hardware acceleration.

Example:

const nvencEncoders = await FFmpeg.getEncodersByAcceleration(
  HardwareAcceleration.NVIDIA,
  StreamType.VIDEO
);
// ['h264_nvenc', 'hevc_nvenc', 'av1_nvenc']

---

getDecodersByAcceleration

static async getDecodersByAcceleration(
  acceleration?: HardwareAccelerationValue,
  type?: StreamType
): Promise<string[]>

Get available decoders for specific hardware acceleration.

---

Instance Methods

Metadata Methods

getMetadata

async getMetadata(input: InputSource): Promise<MediaMetadata>

Extract complete metadata from media file.

Parameters:

• input - File path, Buffer, or ReadStream

Returns:

interface MediaMetadata {
  format: FormatMetadata;
  streams: StreamMetadata[];
  chapters: ChapterMetadata[];
}

Example:

const metadata = await ffmpeg.getMetadata('video.mp4');
console.log(`Duration: ${metadata.format.duration}s`);
console.log(`Streams: ${metadata.streams.length}`);

---

getVideoMetadata

async getVideoMetadata(input: InputSource): Promise<VideoMetadata>

Extract video-specific metadata.

Returns:

interface VideoMetadata {
  duration: number;              // Duration in seconds
  width: number;                 // Video width
  height: number;                // Video height
  aspectRatio: string;           // "16:9"
  frameRate: number;             // Frames per second
  videoCodec: string;            // Codec name
  audioCodec: string | null;     // Audio codec if present
  bitrate: number;               // Total bitrate
  videoBitrate: number;          // Video bitrate
  audioBitrate: number;          // Audio bitrate
  format: string;                // Container format
  hasAudio: boolean;
  hasVideo: boolean;
  pixelFormat: string;           // "yuv420p"
}

Example:

const video = await ffmpeg.getVideoMetadata('video.mp4');
console.log(`${video.width}x${video.height} @ ${video.frameRate}fps`);

---

getImageMetadata

async getImageMetadata(input: InputSource): Promise<ImageMetadata>

Extract image metadata.

---

getDuration

async getDuration(input: InputSource): Promise<number>

Get media duration in seconds.

Example:

const duration = await ffmpeg.getDuration('video.mp4');
console.log(`Duration: ${duration}s`);

---

getResolution

async getResolution(input: InputSource): Promise<{ width: number; height: number }>

Get video resolution.

---

getFrameRate

async getFrameRate(input: InputSource): Promise<number>

Get video frame rate.

---

isVideo

async isVideo(input: InputSource): Promise<boolean>

Check if input is a video file.

---

isImage

async isImage(input: InputSource): Promise<boolean>

Check if input is an image file.

---

Conversion Methods

convert

convert(config: ConversionConfig): ConversionResult

Convert media file with event-based progress tracking.

Returns:

interface ConversionResult {
  promise: Promise<void>;
  events: ConversionEvents;
  cancel: () => void;
  getProgress: () => ProgressInfo | null;
}

interface ConversionEvents {
  start: (callback: (command: string) => void) => void;
  progress: (callback: (progress: ProgressInfo) => void) => void;
  end: (callback: () => void) => void;
  error: (callback: (error: Error) => void) => void;
}

Example:

const conversion = ffmpeg.convert({
  input: 'input.mp4',
  output: 'output.mp4',
  video: { codec: VideoCodec.H264, bitrate: '2M' },
});

conversion.events.start((command) => {
  console.log('Starting:', command);
});

conversion.events.progress((progress) => {
  console.log(`Progress: ${progress.percent}%`);
});

conversion.events.end(() => {
  console.log('Done!');
});

conversion.events.error((error) => {
  console.error('Error:', error);
});

await conversion.promise;

---

convertToBuffer

convertToBuffer(config: Omit<ConversionConfig, 'output'>): ConversionResultBuffer

Convert and return output as Buffer (in-memory).

Returns:

interface ConversionResultBuffer {
  promise: Promise<Buffer>;
  events: ConversionEvents;
  cancel: () => void;
  getProgress: () => ProgressInfo | null;
}

Example:

const conversion = ffmpeg.convertToBuffer({
  input: 'video.mp4',
  video: { codec: VideoCodec.H264, size: '640x480' },
  format: OutputFormat.MP4,
});

const buffer = await conversion.promise;
// Use buffer (upload to S3, etc.)

---

convertBatch

async convertBatch(
  configs: ConversionConfig[],
  callbacks?: BatchConversionCallbacks
): Promise<void>

Convert multiple files sequentially.

Example:

await ffmpeg.convertBatch([
  { input: 'video1.mp4', output: 'out1.mp4', video: { codec: VideoCodec.H264 } },
  { input: 'video2.mp4', output: 'out2.mp4', video: { codec: VideoCodec.H264 } },
]);

---

convertBatchParallel

async convertBatchParallel(
  configs: ConversionConfig[],
  maxConcurrent?: number,
  callbacks?: BatchConversionCallbacks
): Promise<void>

Convert multiple files in parallel.

Parameters:

• configs - Array of conversion configurations
• maxConcurrent - Maximum concurrent conversions (default: 2)

Example:

await ffmpeg.convertBatchParallel(configs, 4); // Run 4 at a time

---

Media Extraction Methods

extractScreenshot

async extractScreenshot(config: ScreenshotConfig): Promise<string>

Extract a single screenshot from video.

See Screenshots & Thumbnails for details.

---

extractScreenshots

async extractScreenshots(config: ScreenshotsConfig): Promise<ScreenshotResult>

Extract multiple screenshots from video.

---

extractThumbnails

async extractThumbnails(config: ThumbnailConfig): Promise<ThumbnailResult>

Generate thumbnails from video.

---

generateTrailer

async generateTrailer(config: TrailerConfig): Promise<TrailerResult>

Generate a video trailer.

---

Multi-Input Methods

concatenate

async concatenate(config: ConcatenationConfig): Promise<ConcatenationResult>

Concatenate multiple videos into one.

Example:

await ffmpeg.concatenate({
  inputs: ['part1.mp4', 'part2.mp4', 'part3.mp4'],
  output: 'full-video.mp4',
});

---

merge

async merge(config: MergeConfig): Promise<string>

Merge video and audio streams.

Example:

await ffmpeg.merge({
  videoInput: 'video.mp4',
  audioInput: 'audio.mp3',
  output: 'merged.mp4',
});

---

pictureInPicture

async pictureInPicture(config: PictureInPictureConfig): Promise<string>

Create picture-in-picture effect.

Example:

await ffmpeg.pictureInPicture({
  mainInput: 'main.mp4',
  overlayInput: 'webcam.mp4',
  output: 'pip.mp4',
  position: 'top-right',
  overlayScale: 0.25,
});

---

sideBySide

async sideBySide(config: SideBySideConfig): Promise<string>

Place two videos side by side.

Example:

await ffmpeg.sideBySide({
  leftInput: 'video1.mp4',
  rightInput: 'video2.mp4',
  output: 'side-by-side.mp4',
});

---

Helper Methods

validateConfig

validateConfig(config: ConversionConfig): { valid: boolean; errors: string[] }

Validate conversion configuration.

Example:

const validation = ffmpeg.validateConfig(config);
if (!validation.valid) {
  console.error('Invalid config:', validation.errors);
}

---

buildCommand

buildCommand(config: ConversionConfig): string

Build FFmpeg command line from configuration (for debugging).

Example:

const command = ffmpeg.buildCommand(config);
console.log('Would run:', command);

---

Recommendation Methods

getConversionSuggestions

async getConversionSuggestions(input: InputSource): Promise<ConversionSuggestion>

Get recommended conversion settings for input file.

Returns:

interface ConversionSuggestion {
  recommendedCodecs: {
    video: string[];
    audio: string[];
  };
  recommendedFormats: string[];
  currentQuality: 'low' | 'medium' | 'high';
  targetQuality: 'low' | 'medium' | 'high';
}

---

checkConversionCompatibility

async checkConversionCompatibility(
  input: InputSource,
  targetFormat: string,
  targetVideoCodec: string,
  targetAudioCodec?: string
): Promise<ConversionCompatibility>

Check if conversion settings are compatible.

---

getConversionRecommendation

async getConversionRecommendation(
  input: InputSource,
  useCase?: 'web' | 'mobile' | 'quality' | 'size' | 'compatibility'
): Promise<ConversionRecommendation>

Get recommended settings for specific use case.

Example:

const recommendation = await ffmpeg.getConversionRecommendation(
  'video.mp4',
  'web'
);

const conversion = ffmpeg.convert({
  input: 'video.mp4',
  output: 'optimized.mp4',
  ...recommendation.config,
});

---

canRemux

async canRemux(input: InputSource, targetFormat: string): Promise<boolean>

Check if video can be remuxed without re-encoding.

---

getRemuxableFormats

async getRemuxableFormats(input: InputSource): Promise<string[]>

Get list of formats that can be remuxed without re-encoding.

---

See Also

• Conversion Configuration
• Video Configuration
• Audio Configuration
• Filters
• Enums