node-fluent-ffmpeg

Fluent ffmpeg-API for node.js

Fluent-ffmpeg is now deprecated

This library is no longer maintained and no longer works properly with recent ffmpeg versions. Use it as your own risk, this repository is readonly and does not accept issues or PRs.

About

This library abstracts the complex command-line usage of ffmpeg into a fluent, easy to use node.js module. In order to be able to use this module, make sure you have ffmpeg installed on your system (including all necessary encoding libraries like libmp3lame or libx264).

This is the documentation for fluent-ffmpeg 2.x. You can still access the code and documentation for fluent-ffmpeg 1.7 here.

Installation

Via npm:

$ npm install fluent-ffmpeg

Or as a submodule:

$ git submodule add git://github.com/schaermu/node-fluent-ffmpeg.git vendor/fluent-ffmpeg

Usage

You will find a lot of usage examples (including a real-time streaming example using flowplayer and express!) in the examples folder.

Prerequisites

ffmpeg and ffprobe

fluent-ffmpeg requires ffmpeg >= 0.9 to work. It may work with previous versions but several features won't be available (and the library is not tested with lower versions anylonger).

If the FFMPEG_PATH environment variable is set, fluent-ffmpeg will use it as the full path to the ffmpeg executable. Otherwise, it will attempt to call ffmpeg directly (so it should be in your PATH). You must also have ffprobe installed (it comes with ffmpeg in most distributions). Similarly, fluent-ffmpeg will use the FFPROBE_PATH environment variable if it is set, otherwise it will attempt to call it in the PATH.

Most features should work when using avconv and avprobe instead of ffmpeg and ffprobe, but they are not officially supported at the moment.

Windows users: most probably ffmpeg and ffprobe will not be in your %PATH, so you must set %FFMPEG_PATH and %FFPROBE_PATH.

Debian/Ubuntu users: the official repositories have the ffmpeg/ffprobe executable in the libav-tools package, and they are actually rebranded avconv/avprobe executables (avconv is a fork of ffmpeg). They should be mostly compatible, but should you encounter any issue, you may want to use the real ffmpeg instead. You can either compile it from source or find a pre-built .deb package at https://ffmpeg.org/download.html (For Ubuntu, the ppa:mc3man/trusty-media PPA provides recent builds).

flvtool2 or flvmeta

If you intend to encode FLV videos, you must have either flvtool2 or flvmeta installed and in your PATH or fluent-ffmpeg won't be able to produce streamable output files. If you set either the FLVTOOL2_PATH or FLVMETA_PATH, fluent-ffmpeg will try to use it instead of searching in the PATH.

Setting binary paths manually

Alternatively, you may set the ffmpeg, ffprobe and flvtool2/flvmeta binary paths manually by using the following API commands:

• Ffmpeg.setFfmpegPath(path) Argument path is a string with the full path to the ffmpeg binary.
• Ffmpeg.setFfprobePath(path) Argument path is a string with the full path to the ffprobe binary.
• Ffmpeg.setFlvtoolPath(path) Argument path is a string with the full path to the flvtool2 or flvmeta binary.

Creating an FFmpeg command

The fluent-ffmpeg module returns a constructor that you can use to instanciate FFmpeg commands.

var FfmpegCommand = require('fluent-ffmpeg');
var command = new FfmpegCommand();

You can also use the constructor without the new operator.

var ffmpeg = require('fluent-ffmpeg');
var command = ffmpeg();

You may pass an input file name or readable stream, a configuration object, or both to the constructor.

var command = ffmpeg('/path/to/file.avi');
var command = ffmpeg(fs.createReadStream('/path/to/file.avi'));
var command = ffmpeg({ option: "value", ... });
var command = ffmpeg('/path/to/file.avi', { option: "value", ... });

The following options are available:

• source: input file name or readable stream (ignored if an input file is passed to the constructor)
• timeout: ffmpeg timeout in seconds (defaults to no timeout)
• preset or presets: directory to load module presets from (defaults to the lib/presets directory in fluent-ffmpeg tree)
• niceness or priority: ffmpeg niceness value, between -20 and 20; ignored on Windows platforms (defaults to 0)
• logger: logger object with debug(), info(), warn() and error() methods (defaults to no logging)
• stdoutLines: maximum number of lines from ffmpeg stdout/stderr to keep in memory (defaults to 100, use 0 for unlimited storage)

Specifying inputs

You can add any number of inputs to an Ffmpeg command. An input can be:

• a file name (eg. /path/to/file.avi);
• an image pattern (eg. /path/to/frame%03d.png);
• a readable stream; only one input stream may be used for a command, but you can use both an input stream and one or several file names.

// Note that all fluent-ffmpeg methods are chainable
ffmpeg('/path/to/input1.avi')
  .input('/path/to/input2.avi')
  .input(fs.createReadStream('/path/to/input3.avi'));

// Passing an input to the constructor is the same as calling .input()
ffmpeg()
  .input('/path/to/input1.avi')
  .input('/path/to/input2.avi');

// Most methods have several aliases, here you may use addInput or mergeAdd instead
ffmpeg()
  .addInput('/path/to/frame%02d.png')
  .addInput('/path/to/soundtrack.mp3');

ffmpeg()
  .mergeAdd('/path/to/input1.avi')
  .mergeAdd('/path/to/input2.avi');

Input options

The following methods enable passing input-related options to ffmpeg. Each of these methods apply on the last input added (including the one passed to the constructor, if any). You must add an input before calling those, or an error will be thrown.

inputFormat(format): specify input format

Aliases: fromFormat(), withInputFormat().

This is only useful for raw inputs, as ffmpeg can determine the input format automatically.

ffmpeg()
  .input('/dev/video0')
  .inputFormat('mov')
  .input('/path/to/file.avi')
  .inputFormat('avi');

Fluent-ffmpeg checks for format availability before actually running the command, and throws an error when a specified input format is not available.

inputFPS(fps): specify input framerate

Aliases: withInputFps(), withInputFPS(), withFpsInput(), withFPSInput(), inputFps(), fpsInput(), FPSInput().

This is only valid for raw inputs, as ffmpeg can determine the input framerate automatically.

ffmpeg('/dev/video0').inputFPS(29.7);

native(): read input at native framerate

Aliases: nativeFramerate(), withNativeFramerate().

ffmpeg('/path/to/file.avi').native();

seekInput(time): set input start time

Alias: setStartTime().

Seeks an input and only start decoding at given time offset. The time argument may be a number (in seconds) or a timestamp string (with format [[hh:]mm:]ss[.xxx]).

ffmpeg('/path/to/file.avi').seekInput(134.5);
ffmpeg('/path/to/file.avi').seekInput('2:14.500');

loop([duration]): loop over input

ffmpeg('/path/to/file.avi').loop();
ffmpeg('/path/to/file.avi').loop(134.5);
ffmpeg('/path/to/file.avi').loop('2:14.500');

inputOptions(option...): add custom input options

Aliases: inputOption(), addInputOption(), addInputOptions(), withInputOption(), withInputOptions().

This method allows passing any input-related option to ffmpeg. You can call it with a single argument to pass a single option, optionally with a space-separated parameter:

/* Single option */
ffmpeg('/path/to/file.avi').inputOptions('-someOption');

/* Single option with parameter */
ffmpeg('/dev/video0').inputOptions('-r 24');

You may also pass multiple options at once by passing an array to the method:

ffmpeg('/path/to/file.avi').inputOptions([
  '-option1',
  '-option2 param2',
  '-option3',
  '-option4 param4'
]);

Finally, you may also directly pass command line tokens as separate arguments to the method:

ffmpeg('/path/to/file.avi').inputOptions(
  '-option1',
  '-option2', 'param2',
  '-option3',
  '-option4', 'param4'
);

Audio options

The following methods change the audio stream(s) in the produced output.

noAudio(): disable audio altogether

Aliases: withNoAudio().

Disables audio in the output and remove any previously set audio option.

ffmpeg('/path/to/file.avi').noAudio();

audioCodec(codec): set audio codec

Aliases: withAudioCodec().

ffmpeg('/path/to/file.avi').audioCodec('libmp3lame');

Fluent-ffmpeg checks for codec availability before actually running the command, and throws an error when a specified audio codec is not available.

audioBitrate(bitrate): set audio bitrate

Aliases: withAudioBitrate().

Sets the audio bitrate in kbps. The bitrate parameter may be a number or a string with an optional k suffix. This method is used to enforce a constant bitrate; use audioQuality() to encode using a variable bitrate.

ffmpeg('/path/to/file.avi').audioBitrate(128);
ffmpeg('/path/to/file.avi').audioBitrate('128');
ffmpeg('/path/to/file.avi').audioBitrate('128k');

audioChannels(count): set audio channel count

Aliases: withAudioChannels().

ffmpeg('/path/to/file.avi').audioChannels(2);

audioFrequency(freq): set audio frequency

Aliases: withAudioFrequency().

The freq parameter specifies the audio frequency in Hz.

ffmpeg('/path/to/file.avi').audioFrequency(22050);

audioQuality(quality): set audio quality

Aliases: withAudioQuality().

This method fixes a quality factor for the audio codec (VBR encoding). The quality scale depends on the actual codec used.

ffmpeg('/path/to/file.avi')
  .audioCodec('libmp3lame')
  .audioQuality(0);

audioFilters(filter...): add custom audio filters

Aliases: audioFilter(), withAudioFilter(), withAudioFilters().

This method enables adding custom audio filters. You may add multiple filters at once by passing either several arguments or an array. See the Ffmpeg documentation for available filters and their syntax.

Each filter pased to this method can be either a filter string (eg. volume=0.5) or a filter specification object with the following keys:

• filter: filter name
• options: optional; either an option string for the filter (eg. n=-50dB:d=5), an options array for unnamed options (eg. ['-50dB', 5]) or an object mapping option names to values (eg. { n: '-50dB', d: 5 }). When options is not specified, the filter will be added without any options.

…

Video options

The following methods change the video stream(s) in the produced output.

noVideo(): disable video altogether

Aliases: withNoVideo().

This method disables video output and removes any previously set video option.

ffmpeg('/path/to/file.avi').noVideo();

videoCodec(codec): set video codec

Aliases: withVideoCodec().

ffmpeg('/path/to/file.avi').videoCodec('libx264');

Fluent-ffmpeg checks for codec availability before actually running the command, and throws an error when a specified video codec is not available.

videoBitrate(bitrate[, constant=false]): set video bitrate

Aliases: withVideoBitrate().

Sets the target video bitrate in kbps. The bitrate argument may be a number or a string with an optional k suffix. The constant argument specifies whether a constant bitrate should be enforced (defaults to false).

Keep in mind that, depending on the codec used, enforcing a constant bitrate often comes at the cost of quality. The best way to have a constant video bitrate without losing too much quality is to use 2-pa