Video Processing

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

// 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');

/**
 * 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

// 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');

/**
 * 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

// 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 from output
 * @returns FfmpegCommand instance for chaining
 */
noVideo() // → FfmpegCommand
// Aliases: withNoVideo

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

/**
 * 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

// 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');

/**
 * 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

// 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');

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

// 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');

/**
 * 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

// 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');

/**
 * 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

// 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');

/**
 * 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)
    };