Input Management

/**
 * Add input file or stream to command
 * @param source - File path or readable stream
 * @returns FfmpegCommand instance for chaining
 */
input(source) // → FfmpegCommand
// Aliases: addInput, mergeAdd

const ffmpeg = require('fluent-ffmpeg');

// File input
ffmpeg('video.mp4').save('output.mp4');

// Stream input
const fs = require('fs');
const inputStream = fs.createReadStream('input.avi');
ffmpeg(inputStream).save('output.mp4');

// Multiple inputs
ffmpeg()
  .input('video1.mp4')
  .input('video2.mp4')
  .input('audio.mp3')
  .save('combined.mp4');

/**
 * Specify input format for the last added input
 * @param format - Input format name (e.g., 'avi', 'mov', 'rawvideo')
 * @returns FfmpegCommand instance for chaining
 */
inputFormat(format) // → FfmpegCommand
// Aliases: withInputFormat, fromFormat

// Raw video input
ffmpeg('rawvideo.yuv')
  .inputFormat('rawvideo')
  .inputFps(25)
  .size('640x480')
  .save('output.mp4');

// Specify format for ambiguous files
ffmpeg('data.bin')
  .inputFormat('h264')
  .save('output.mp4');

/**
 * Set input frame rate (for raw video formats)
 * @param fps - Input frames per second
 * @returns FfmpegCommand instance for chaining
 */
inputFps(fps) // → FfmpegCommand
// Aliases: withInputFps, withInputFPS, withFpsInput, withFPSInput, 
//          inputFPS, fpsInput, FPSInput

// Raw video with specific FPS
ffmpeg('raw_video.yuv')
  .inputFormat('rawvideo')
  .inputFps(30)
  .size('1920x1080')
  .save('output.mp4');

// Override detected frame rate
ffmpeg('variable_fps.avi')
  .inputFps(25)
  .save('constant_fps.mp4');

/**
 * Use native framerate for input (no frame rate conversion)
 * @returns FfmpegCommand instance for chaining
 */
native() // → FfmpegCommand
// Aliases: nativeFramerate, withNativeFramerate

// Preserve original frame rate
ffmpeg('variable_fps_video.mp4')
  .native()
  .videoCodec('libx264')
  .save('output.mp4');

/**
 * Set input seek time (start processing from specific position)
 * @param seek - Time in seconds or '[hh:[mm:]]ss[.xxx]' format
 * @returns FfmpegCommand instance for chaining
 */
seekInput(seek) // → FfmpegCommand
// Aliases: setStartTime

// Seek to 30 seconds
ffmpeg('long_video.mp4')
  .seekInput(30)
  .duration(60)  // Take 60 seconds from that position
  .save('clip.mp4');

// Seek using time format
ffmpeg('movie.mkv')
  .seekInput('01:30:00')  // Start at 1 hour 30 minutes
  .save('from_middle.mp4');

// Precise seeking with milliseconds
ffmpeg('video.mp4')
  .seekInput('00:02:30.500')  // 2 minutes 30.5 seconds
  .save('precise_clip.mp4');

/**
 * Loop over input (repeat input stream)
 * @param duration - Optional loop duration
 * @returns FfmpegCommand instance for chaining
 */
loop(duration?) // → FfmpegCommand

// Loop indefinitely until other constraints stop it
ffmpeg('short_clip.mp4')
  .loop()
  .duration(300)  // Loop for 5 minutes total
  .save('looped_output.mp4');

// Loop with specific duration
ffmpeg('logo.png')
  .loop(60)  // Loop the image for 60 seconds
  .fps(25)
  .save('logo_video.mp4');

/**
 * Add custom input options
 * @param options - Option string(s) or array of option strings
 * @returns FfmpegCommand instance for chaining
 */
inputOptions(...options) // → FfmpegCommand
// Aliases: addInputOption, addInputOptions, withInputOption, 
//          withInputOptions, inputOption

// Hardware decoding
ffmpeg('input.mp4')
  .inputOptions([
    '-hwaccel', 'cuda',
    '-hwaccel_output_format', 'cuda'
  ])
  .save('output.mp4');

// Custom pixel format
ffmpeg('input.yuv')
  .inputOptions('-pix_fmt', 'yuv420p')
  .inputFormat('rawvideo')
  .save('output.mp4');

// Multiple custom options
ffmpeg('rtsp://camera.local/stream')
  .inputOptions([
    '-rtsp_transport', 'tcp',
    '-fflags', '+genpts',
    '-thread_queue_size', '512'
  ])
  .save('recorded.mp4');

/**
 * Supported input source types
 */
type InputSource = string | ReadableStream;

/**
 * Input format names (common examples)
 */
type InputFormat = 
  | 'avi' | 'mp4' | 'mkv' | 'mov' | 'wmv' | 'flv'     // Video containers
  | 'mp3' | 'aac' | 'wav' | 'flac' | 'ogg'           // Audio formats  
  | 'rawvideo' | 'yuv4mpegpipe' | 'image2'           // Raw/image formats
  | 'h264' | 'hevc' | 'mpeg2video'                   // Video codecs
  | string;                                           // Any FFmpeg format

/**
 * Time specification formats
 */
type TimeSpec = number | string; // Seconds as number or 'HH:MM:SS.mmm' format