tessl/npm-fluent-ffmpeg

A fluent API to FFMPEG for audio and video manipulation with chainable methods

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Video Processing

Name: tessl/npm-fluent-ffmpeg
Author: tessl

Comprehensive video manipulation capabilities including codecs, bitrates, size, filters, and frame rate control.

Capabilities

Video Codec Configuration

Set the video codec for output streams.

/**
 * Set video codec for output
 * @param codec - Video codec name
 * @returns FfmpegCommand instance for chaining
 */
videoCodec(codec) // → FfmpegCommand
// Aliases: withVideoCodec

Usage Examples:

// Common video codecs
ffmpeg('input.avi').videoCodec('libx264').save('h264.mp4');
ffmpeg('input.mov').videoCodec('libx265').save('hevc.mp4');  
ffmpeg('input.mp4').videoCodec('libvpx-vp9').save('vp9.webm');

// Hardware encoding
ffmpeg('input.mp4')
  .videoCodec('h264_nvenc')  // NVIDIA GPU encoding
  .save('hw_encoded.mp4');

Video Bitrate

Configure video bitrate for quality and file size control.

/**
 * Set video bitrate
 * @param bitrate - Bitrate in kbps
 * @param constant - Optional: enforce constant bitrate
 * @returns FfmpegCommand instance for chaining
 */
videoBitrate(bitrate, constant?) // → FfmpegCommand
// Aliases: withVideoBitrate

Usage Examples:

// Variable bitrate (default)
ffmpeg('input.avi').videoBitrate('1000k').save('1mbps.mp4');

// Constant bitrate
ffmpeg('input.mov')
  .videoBitrate('2000k', true)  // CBR encoding
  .save('constant_bitrate.mp4');

// High quality encoding
ffmpeg('source.mov')
  .videoBitrate('10000k')  // 10 Mbps
  .videoCodec('libx264')
  .save('high_quality.mp4');

Frame Rate Control

Set output frame rate and frame processing.

/**
 * Set output frame rate
 * @param fps - Frames per second
 * @returns FfmpegCommand instance for chaining
 */
fps(fps) // → FfmpegCommand
// Aliases: withOutputFps, withOutputFPS, withFpsOutput, withFPSOutput,
//          withFps, withFPS, outputFPS, outputFps, fpsOutput, FPSOutput, FPS

/**
 * Limit number of output frames
 * @param frames - Maximum frame count
 * @returns FfmpegCommand instance for chaining  
 */
frames(frames) // → FfmpegCommand
// Aliases: takeFrames, withFrames

Usage Examples:

// Change frame rate
ffmpeg('30fps_video.mp4').fps(24).save('24fps_cinema.mp4');
ffmpeg('variable_fps.avi').fps(25).save('constant_25fps.mp4');

// Limit frames for short clips
ffmpeg('long_video.mp4')
  .fps(30)
  .frames(300)  // Only 10 seconds at 30fps
  .save('short_clip.mp4');

// Create slow motion
ffmpeg('normal_speed.mp4')
  .fps(60)      // Higher output fps
  .videoFilters('setpts=2*PTS')  // Double duration
  .save('slow_motion.mp4');

Remove Video

Disable video in output (audio-only output).

/**
 * Remove video from output
 * @returns FfmpegCommand instance for chaining
 */
noVideo() // → FfmpegCommand
// Aliases: withNoVideo

Usage Example:

// Extract audio only
ffmpeg('music_video.mp4')
  .noVideo()
  .audioCodec('libmp3lame')
  .save('audio_only.mp3');

Video Size and Scaling

Control output video dimensions and aspect ratio.

/**
 * Set output video size
 * @param size - Size specification
 * @returns FfmpegCommand instance for chaining
 */
size(size) // → FfmpegCommand
// Aliases: withSize, setSize

/**
 * Set aspect ratio
 * @param aspect - Aspect ratio as number or 'X:Y' string
 * @returns FfmpegCommand instance for chaining
 */
aspect(aspect) // → FfmpegCommand
// Aliases: withAspect, withAspectRatio, setAspect, setAspectRatio, aspectRatio

Size Specification Formats:

'X%' - Percentage of original (e.g., '50%')
'WxH' - Width x Height (e.g., '1920x1080')
'Wx?' - Width with computed height (e.g., '1280x?')
'?xH' - Height with computed width (e.g., '?x720')

Usage Examples:

// Common resolutions
ffmpeg('input.avi').size('1920x1080').save('fullhd.mp4');
ffmpeg('input.mov').size('1280x720').save('hd.mp4');
ffmpeg('input.mp4').size('854x480').save('sd.mp4');

// Percentage scaling
ffmpeg('large_video.mp4').size('50%').save('half_size.mp4');

// Maintain aspect ratio
ffmpeg('input.avi').size('1280x?').save('width_1280.mp4');
ffmpeg('input.mov').size('?x720').save('height_720.mp4');

// Aspect ratio control
ffmpeg('input.avi')
  .aspect('16:9')
  .size('1920x1080')
  .save('widescreen.mp4');

Auto-padding

Add padding to maintain aspect ratio without distortion.

/**
 * Enable auto-padding to maintain aspect ratio
 * @param pad - Enable/disable padding (default: true)
 * @param color - Pad color (default: 'black')
 * @returns FfmpegCommand instance for chaining
 */
autopad(pad?, color?) // → FfmpegCommand
// Aliases: applyAutopadding, applyAutoPadding, applyAutopad, applyAutoPad,
//          withAutopadding, withAutoPadding, withAutopad, withAutoPad, autoPad

/**
 * Maintain display aspect ratio
 * @returns FfmpegCommand instance for chaining
 */
keepDAR() // → FfmpegCommand
// Aliases: keepPixelAspect, keepDisplayAspect, keepDisplayAspectRatio

Usage Examples:

// Letterboxing for aspect ratio mismatch
ffmpeg('4x3_video.avi')
  .size('1920x1080')  // 16:9 target
  .autopad(true, 'black')  // Add black bars
  .save('letterboxed.mp4');

// Custom pad color
ffmpeg('square_video.mov')
  .size('1920x1080')
  .autopad(true, 'white')
  .save('white_padded.mp4');

// Preserve display aspect ratio
ffmpeg('anamorphic_video.mov')
  .keepDAR()
  .save('correct_aspect.mp4');

Video Filters

Apply video filters for effects, corrections, and transformations.

/**
 * Apply video filters
 * @param filters - Filter specifications (string, array, or objects)
 * @returns FfmpegCommand instance for chaining
 */
videoFilters(...filters) // → FfmpegCommand
// Aliases: withVideoFilter, withVideoFilters, videoFilter

Usage Examples:

// Basic filters
ffmpeg('input.mp4')
  .videoFilters('scale=1280:720')  // Resize
  .save('resized.mp4');

// Multiple filters
ffmpeg('shaky_video.mp4')
  .videoFilters([
    'deshake',                    // Stabilization
    'unsharp=5:5:1.0:5:5:0.0',   // Sharpening
    'eq=brightness=0.1'          // Brightness adjustment
  ])
  .save('stabilized.mp4');

// Object-style filters
ffmpeg('input.avi')
  .videoFilters([
    { filter: 'scale', options: { w: 1920, h: 1080 } },
    { filter: 'fade', options: 't=in:st=0:d=2' },
    { filter: 'fade', options: 't=out:st=28:d=2' }
  ])
  .save('with_fades.mp4');

// Color correction
ffmpeg('washed_out.mp4')
  .videoFilters([
    'eq=contrast=1.2:brightness=0.1:saturation=1.1',
    'curves=vintage'
  ])
  .save('color_corrected.mp4');

// Overlay and composition  
ffmpeg('background.mp4')
  .input('overlay.png')
  .videoFilters([
    '[0:v][1:v]overlay=10:10'  // Position overlay at 10,10
  ])
  .save('with_overlay.mp4');

Advanced Video Processing

Complex Video Filters

Use complex filtergraphs for advanced processing.

/**
 * Set complex filtergraph
 * @param spec - Filter specification (string or object array)
 * @param map - Optional output stream mappings
 * @returns FfmpegCommand instance for chaining
 */
complexFilter(spec, map?) // → FfmpegCommand
// Aliases: filterGraph

Usage Examples:

// Picture-in-picture
ffmpeg()
  .input('main_video.mp4')
  .input('pip_video.mp4')
  .complexFilter([
    '[1:v]scale=320:240[pip]',
    '[0:v][pip]overlay=main_w-overlay_w-10:10'
  ])
  .save('pip_output.mp4');

// Side-by-side comparison
ffmpeg()
  .input('video1.mp4')
  .input('video2.mp4') 
  .complexFilter([
    '[0:v]scale=960:540[left]',
    '[1:v]scale=960:540[right]',
    '[left][right]hstack'
  ])
  .save('side_by_side.mp4');

Video Stream Selection

/**
 * Select specific video stream using map
 * @param spec - Stream specification (e.g., '0:v:0' for first video stream)
 * @returns FfmpegCommand instance for chaining
 */
map(spec) // → FfmpegCommand

Usage Example:

// Select specific video track from multi-stream file
ffmpeg('multi_angle.mkv')
  .map('0:v:1')    // Second video stream
  .map('0:a:0')    // First audio stream
  .save('angle2.mp4');

Video Types

/**
 * Common video codec names
 */
type VideoCodec = 
  | 'libx264'           // H.264 (most compatible)
  | 'libx265'           // H.265/HEVC (better compression)
  | 'libvpx'            // VP8 (WebM)
  | 'libvpx-vp9'        // VP9 (WebM)
  | 'libav1'            // AV1 (next-gen codec)
  | 'mpeg4'             // MPEG-4 Part 2
  | 'libxvid'           // Xvid
  | 'h264_nvenc'        // NVIDIA hardware H.264
  | 'hevc_nvenc'        // NVIDIA hardware H.265
  | 'h264_qsv'          // Intel QuickSync H.264
  | 'prores'            // Apple ProRes
  | 'dnxhd'             // Avid DNxHD
  | 'copy'              // Stream copy (no re-encoding)
  | string;             // Any FFmpeg video codec

/**
 * Video bitrate specification
 */
type VideoBitrate = number | string; // kbps as number or with 'k'/'M' suffix

/**
 * Video size specification formats
 */
type VideoSize = 
  | string              // 'WxH', 'W%', 'Wx?', '?xH' formats
  | 'hd480'  | 'hd720'  | 'hd1080'    // Standard resolutions
  | 'qvga'   | 'vga'    | 'svga'      // Legacy resolutions
  | '480p'   | '720p'   | '1080p'     // Progressive resolutions
  | '4k'     | 'uhd'    | '8k';       // Ultra HD resolutions

/**
 * Aspect ratio specification
 */
type AspectRatio = number | string; // Decimal ratio or 'W:H' format

/**
 * Video filter specification  
 */
type VideoFilter = 
  | string                           // Filter string 'filter=param:value'
  | {                               // Filter object
      filter: string;               // Filter name
      options?: string | Object;     // Filter parameters
      inputs?: string[];            // Input streams (complex filters)
      outputs?: string[];           // Output streams (complex filters)
    };