Stream Specifiers and Mappings

Stream specifiers are used by the library to create explicit names for streams from input files and filter chains.

When an FFmpegInput is added to the FFmpegCommand object, the order of addition is tracked, and its positional index is used as an identifier in any stream specifiers requested for it. Stream specifiers on inputs mapped to a FilterChain are added to the beginning of the string representation of the filter chain, and those mapped to an FFmpegOutput are used with the -map ffmpeg option.

Similarly, when a stream specifier is requested for a FilterChain output pad, the positional index of that filter chain within the FFmpegCommand's FilterGraph object is used to generate a unique output pad name. That pad name is then appended to the end of the string representation of that filter chain, and is used with the -map option to map the output stream from that filter into that output file.

If no stream specifiers are requested, no explicit names will be added to the command, allowing ffmpeg to use its implicit mapping capabilities.

For example, if we create the following objects:

const cmd = new FFmpegCommand();
const videoInput = new FFmpegInput('/path/to/some/video.mov', {/*...*/});
const videoFilters = new FilterChain([
  new FilterNode('edgedetect', { mode: 'colormix', high: 0 })
]);
const output = new FFmpegOutput('/path/to/output.mp4', {/*...*/});

Then in the following code, we use explicit mappings:

  • we request a stream specifier for videoInput's video stream
  • we request a stream specifier for the output of videoFilters

Those stream specifiers are used in the filter graph and mappings of the resulting command.

videoFilters.addInput(videoInput.streamSpecifier('v'));

output.addStreams(videoFilters.streamSpecifier());

cmd.addInput(videoInput);
cmd.addFilterChain(videoFilters);
cmd.addOutput(output);

console.log(cmd.toString());

This would result in the following ffmpeg command, with the label 0 applied to videoInput and the label 1 applied to audioInput, in the order they were added to the command, and a generated name [chain0_edgedetect_0] for the single output pad of the video filter chain videoFilters.

ffmpeg -i "/path/to/some/video.mov" -filter_complex "[0:v]edgedetect=mode=colormix:high=0[chain0_edgedetect_0]" -map "[chain0_edgedetect_0]" "/path/to/output.mp4"

In contrast, the following code, using the same objects above, requests no stream specifiers and specifies no explicit mappings.

cmd.addInput(videoInput);
cmd.addFilterChain(videoFilters)
cmd.addOutput(output);
console.log(cmd.toString());

This would result in the command:

ffmpeg -i "/path/to/input.mov" -filter_complex "edgedetect=mode=colormix:high=0" "/path/to/output.mp4"

We recommend using explicit mappings for clarity where possible.