Fluent-FFmpeg is a Node.js library that provides a fluent API wrapper for FFmpeg, enabling audio and video manipulation through chainable JavaScript methods. It abstracts complex FFmpeg command-line usage into an intuitive JavaScript interface with comprehensive event handling and streaming support.
npm install fluent-ffmpegconst ffmpeg = require('fluent-ffmpeg');ES6 modules:
import ffmpeg from 'fluent-ffmpeg';const ffmpeg = require('fluent-ffmpeg');
// Basic video conversion
ffmpeg('input.avi')
.output('output.mp4')
.on('end', () => console.log('Processing finished'))
.on('error', (err) => console.error('Error:', err))
.run();
// Audio extraction with format conversion
ffmpeg('video.mp4')
.noVideo()
.audioCodec('libmp3lame')
.save('audio.mp3');
// Video processing with size and codec options
ffmpeg('input.mov')
.videoCodec('libx264')
.size('640x480')
.fps(25)
.audioBitrate('128k')
.save('output.mp4');Fluent-FFmpeg is built around several key components:
Configure input sources, formats, and processing parameters.
// Add input source (file path or stream)
input(source) // → FfmpegCommand
// Aliases: addInput, mergeAdd
// Specify input format
inputFormat(format) // → FfmpegCommand
// Aliases: withInputFormat, fromFormat
// Set input seeking position
seekInput(seek) // → FfmpegCommand
// Aliases: setStartTimeComplete audio manipulation including codecs, bitrates, channels, and filters.
// Audio codec configuration
audioCodec(codec) // → FfmpegCommand
// Aliases: withAudioCodec
// Audio quality settings
audioBitrate(bitrate) // → FfmpegCommand
audioChannels(channels) // → FfmpegCommand
audioFrequency(freq) // → FfmpegCommand
// Audio filters
audioFilters(...filters) // → FfmpegCommand
// Aliases: withAudioFilter, withAudioFilters, audioFilterComprehensive video manipulation including codecs, bitrates, size, and filters.
// Video codec configuration
videoCodec(codec) // → FfmpegCommand
// Aliases: withVideoCodec
// Video quality and format
videoBitrate(bitrate, constant?) // → FfmpegCommand
fps(fps) // → FfmpegCommand
frames(frames) // → FfmpegCommand
// Video filters
videoFilters(...filters) // → FfmpegCommand
// Aliases: withVideoFilter, withVideoFilters, videoFilterConfigure output destinations, formats, and processing parameters.
// Add output target
output(target?, pipeopts?) // → FfmpegCommand
// Aliases: addOutput
// Output format and seeking
format(format) // → FfmpegCommand
seek(seek) // → FfmpegCommand
duration(duration) // → FfmpegCommand
// Stream mapping
map(spec) // → FfmpegCommandExecute commands with full control over the FFmpeg process.
// Execute command
run() // → FfmpegCommand
// Save to file
save(output) // → FfmpegCommand
// Aliases: saveToFile
// Pipe to stream
pipe(stream?, options?) // → WritableStream
// Aliases: stream, writeToStream
// Process control
kill(signal?) // → FfmpegCommandAdvanced functionality including screenshots, concatenation, and metadata analysis.
// Generate screenshots
screenshots(config, folder?) // → FfmpegCommand
// Aliases: takeScreenshots, thumbnail, thumbnails, screenshot
// Concatenate inputs
concat(target, options?) // → FfmpegCommand
// Aliases: concatenate, mergeToFile
// Probe input metadata
ffprobe(index?, options?, callback) // → voidBinary paths, capability queries, and preset management.
// Binary path configuration
setFfmpegPath(path) // → FfmpegCommand
setFfprobePath(path) // → FfmpegCommand
setFlvtoolPath(path) // → FfmpegCommand
// Capability queries
availableFilters(callback) // → void
availableCodecs(callback) // → void
availableFormats(callback) // → void
// Preset application
preset(preset) // → FfmpegCommand
// Aliases: usingPreset/**
* Main FFmpeg command class
* @extends EventEmitter
*/
class FfmpegCommand extends EventEmitter {
constructor(input?, options?)
}
/**
* Logger interface for debugging and monitoring
*/
interface Logger {
debug(message: string): void;
info(message: string): void;
warn(message: string): void;
error(message: string): void;
}
/**
* Constructor options
*/
interface FfmpegOptions {
logger?: Logger; // Logger with debug/info/warn/error methods
niceness?: number; // Process niceness (-20 to 20)
priority?: number; // Alias for niceness
presets?: string; // Preset directory path
preset?: string; // Alias for presets
stdoutLines?: number; // Max stdout lines (default: 100)
timeout?: number; // Processing timeout in seconds
source?: string|ReadableStream; // Alias for input parameter
}
/**
* Progress information emitted during processing
*/
interface ProgressInfo {
frames: number; // Transcoded frames
currentFps: number; // Current FPS
currentKbps: number; // Current speed (kbps)
targetSize: number; // Output size in KB
timemark: string; // Current time (HH:MM:SS.ms)
percent: number; // Progress percentage
}
/**
* Filter specification object
*/
interface FilterSpec {
filter: string; // Filter name
options?: string|Object; // Filter parameters
inputs?: string[]; // Input stream specifiers (complex filters)
outputs?: string[]; // Output stream specifiers (complex filters)
}FfmpegCommand inherits from EventEmitter and emits the following events:
(commandLine) - FFmpeg process started with command line(progress: ProgressInfo) - Processing progress update(line: string) - FFmpeg stderr output line(data) - Input codec information detected(error, stdout, stderr) - Error occurred during processing(stdout, stderr) - Processing completed successfully(filenames: string[]) - Screenshot filenames (screenshots only)