async-ffmpeg

Node interaction with ffmpeg in Node.js promise style.

Installation

npm install async-ffmpeg

yarn add async-ffmpeg

Prerequisites

Make sure you have ffmpeg and ffprobe installed on your system:

• Ubuntu/Debian: sudo apt install ffmpeg
• macOS: brew install ffmpeg
• Windows: Download from ffmpeg.org

Usage

Basic FFmpeg Operations

import { ffmpeg } from 'async-ffmpeg';

// Basic video conversion
await ffmpeg({
  input: 'input.mp4',
  output: 'output.avi',
  videoCodec: 'libx264',
});

// Convert with specific parameters
await ffmpeg({
  input: 'input.mov',
  output: 'output.mp4',
  videoCodec: 'libx264',
  audioCodec: 'aac',
  audioBitrate: '128k',
  videoFilter: 'scale=1920:1080',
});

FFprobe - Media Information

import { ffprobe } from 'async-ffmpeg/ffprobe';

// Get media information
const mediaInfo = await ffprobe('video.mp4');
console.log('Duration:', mediaInfo.format.duration);
console.log(
  'Video streams:',
  mediaInfo.streams.filter((s) => s.codec_type === 'video'),
);
console.log(
  'Audio streams:',
  mediaInfo.streams.filter((s) => s.codec_type === 'audio'),
);

// Works with streams too
import { createReadStream } from 'fs';
const stream = createReadStream('video.mp4');
const streamInfo = await ffprobe(stream);

Screen Capture (Linux)

import { X11ScreenCapture } from 'async-ffmpeg/screen-capture';

const screenCapture = X11ScreenCapture({
  display: ':0',
  width: 1920,
  height: 1080,
  framerate: 30,
  x: 0,
  y: 0,
  output: 'screen-recording.mp4',
});

// Start recording
await screenCapture.startRecording();

// Stop after 10 seconds
setTimeout(async () => {
  await screenCapture.stopRecording();
}, 10000);

API Reference

ffmpeg(params)

Main function for executing FFmpeg operations.

Parameters

Parameter	Type	Description
input	string | Readable	Input file path or readable stream
output	string	Output file path
audio	string	Additional audio input file
audioCodec	string	Audio codec (e.g., 'aac', 'mp3', 'flac')
audioBitrate	string | number	Audio bitrate (e.g., '128k' or 128)
videoCodec	string	Video codec (e.g., 'libx264', 'libx265')
codec	string	General codec setting
duration	Time	Duration to process
framerate	number	Video framerate
inputSeeking	Time	Seek to position in input
outputSeeking	Time	Seek to position in output
videoFilter	string	Video filter string
pixelFormat	string	Pixel format (e.g., 'yuv420p')
map	string | string[]	Stream mapping
videoFrames	number	Number of video frames to output
loop	number	Loop input
noVideo	boolean	Disable video output
outputFormat	string	Output format
logLevel	string	FFmpeg log level
extra	string[]	Additional FFmpeg parameters
debug	boolean	Enable debug output

Time Format

The Time type accepts:

• Numbers (seconds): 30, 120.5
• Time strings: '00:01:30', '1:30', '90'

ffprobe(input)

Get detailed information about media files.

Parameters

Parameter	Type	Description
input	string | Stream	File path or readable stream

Returns

Returns a FfprobeData object containing:

• streams: Array of stream information
• format: Format information (duration, bitrate, etc.)
• chapters: Chapter information

X11ScreenCapture(params)

Screen capture functionality for Linux systems.

Parameters

Parameter	Type	Description
display	string	Display number (e.g., ':0')
width	number	Capture width
height	number	Capture height
framerate	number	Recording framerate
x	number	X position to start capture
y	number	Y position to start capture
output	string	Output file path

Returns

Object with methods:

• startRecording(): Start screen recording
• stopRecording(): Stop screen recording

Examples

Video Processing

// Extract audio from video
await ffmpeg({
  input: 'video.mp4',
  output: 'audio.mp3',
  noVideo: true,
  audioCodec: 'mp3',
});

// Create thumbnail
await ffmpeg({
  input: 'video.mp4',
  output: 'thumbnail.jpg',
  inputSeeking: '00:00:10',
  videoFrames: 1,
});

// Resize video
await ffmpeg({
  input: 'input.mp4',
  output: 'resized.mp4',
  videoFilter: 'scale=640:480',
  videoCodec: 'libx264',
});

Working with Streams

import { createReadStream, createWriteStream } from 'fs';

// Process stream input
const inputStream = createReadStream('input.mp4');
await ffmpeg({
  input: inputStream,
  output: 'output.mp4',
  videoCodec: 'libx264',
});

Advanced Usage

// Multiple inputs with mapping
await ffmpeg({
  input: 'video.mp4',
  audio: 'audio.mp3',
  output: 'combined.mp4',
  map: ['0:v:0', '1:a:0'], // Use video from first input, audio from second
  videoCodec: 'libx264',
  audioCodec: 'aac',
});

// Custom filters and parameters
await ffmpeg({
  input: 'input.mp4',
  output: 'filtered.mp4',
  videoFilter: 'scale=1920:1080,fps=30',
  extra: ['-preset', 'fast', '-crf', '23'],
  debug: true, // Show FFmpeg command
});

Error Handling

All functions return promises, so use try/catch for error handling:

try {
  await ffmpeg({
    input: 'input.mp4',
    output: 'output.mp4',
  });
  console.log('Conversion completed successfully');
} catch (error) {
  console.error('FFmpeg error:', error.message);
}

TypeScript Support

The package includes full TypeScript definitions:

import { ffmpeg, ffprobe, type FFmpegParams, type FfprobeData } from 'async-ffmpeg';

const params: FFmpegParams = {
  input: 'input.mp4',
  output: 'output.mp4',
  videoCodec: 'libx264',
};

const mediaInfo: FfprobeData = await ffprobe('video.mp4');

Requirements

• Node.js 14+ (ES modules support)
• FFmpeg installed and accessible in PATH
• Linux system for screen capture functionality

License

MIT © Simone Gauli

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

https://github.com/Pnlvfx/async-ffmpeg