Output Management

/**
 * Add output target (file or stream)
 * @param target - Output file path or writable stream
 * @param pipeopts - Optional pipe options for streams
 * @returns FfmpegCommand instance for chaining
 */
output(target?, pipeopts?) // → FfmpegCommand
// Aliases: addOutput

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

// File output
ffmpeg('input.avi')
  .output('output.mp4')
  .run();

// Stream output
const outputStream = fs.createWriteStream('stream_output.mp4');
ffmpeg('input.avi')
  .output(outputStream)
  .run();

// Multiple outputs
ffmpeg('input.mkv')
  .output('high_quality.mp4').videoBitrate('5000k')
  .output('low_quality.mp4').videoBitrate('1000k')
  .run();

// Output with pipe options
ffmpeg('input.avi')
  .output(outputStream, { end: true })
  .run();

/**
 * Set output format/container
 * @param format - Format name (e.g., 'mp4', 'avi', 'mkv')
 * @returns FfmpegCommand instance for chaining
 */
format(format) // → FfmpegCommand
// Aliases: toFormat, withOutputFormat, outputFormat

// Explicit format specification
ffmpeg('input.avi').format('mp4').save('output.mp4');
ffmpeg('input.mp4').format('webm').save('output.webm');

// Format override (when filename doesn't match)
ffmpeg('input.mov')
  .format('mp4')  // Force MP4 container
  .save('output.video');  // Extension doesn't matter

// Streaming formats
ffmpeg('input.mp4')
  .format('flv')
  .save('rtmp://server/live/stream');

/**
 * Set output seek time (skip beginning of output)
 * @param seek - Time in seconds or '[hh:[mm:]]ss[.xxx]' format
 * @returns FfmpegCommand instance for chaining
 */
seek(seek) // → FfmpegCommand
// Aliases: seekOutput

/**
 * Set maximum output duration
 * @param duration - Duration in seconds or time format
 * @returns FfmpegCommand instance for chaining
 */
duration(duration) // → FfmpegCommand
// Aliases: withDuration, setDuration

// Extract middle portion
ffmpeg('long_video.mp4')
  .seekInput(60)    // Start from 1 minute in input
  .duration(30)     // Take 30 seconds
  .save('clip.mp4');

// Skip first part of output
ffmpeg('input.avi')
  .seek(10)         // Skip first 10 seconds of output
  .save('trimmed.mp4');

// Precise timing
ffmpeg('presentation.mp4')
  .seek('00:02:30.500')      // Start at 2:30.5
  .duration('00:05:00')      // 5 minutes duration
  .save('segment.mp4');

// Time-based splitting
ffmpeg('movie.mkv')
  .seek(0).duration(1800)    // First 30 minutes
  .output('part1.mp4')
  .seek(1800).duration(1800) // Second 30 minutes  
  .output('part2.mp4')
  .run();

/**
 * Add stream mapping
 * @param spec - Stream specification (e.g., '0:v:0', '1:a', '-1:s')
 * @returns FfmpegCommand instance for chaining
 */
map(spec) // → FfmpegCommand

// Select specific streams
ffmpeg('movie.mkv')
  .map('0:v:0')     // First video stream
  .map('0:a:1')     // Second audio stream
  .map('0:s:0')     // First subtitle stream
  .save('remapped.mp4');

// Multiple audio tracks
ffmpeg('multilang.mkv')
  .map('0:v')       // All video streams
  .map('0:a:0')     // English audio
  .map('0:a:2')     // Spanish audio
  .save('dual_audio.mp4');

// Exclude streams
ffmpeg('input.mkv')
  .map('0')         // Map all streams
  .map('-1:s')      // Exclude subtitles
  .save('no_subs.mp4');

// Complex mapping with multiple inputs
ffmpeg()
  .input('video.mp4')      // Input 0
  .input('audio.mp3')      // Input 1
  .input('subtitles.srt')  // Input 2
  .map('0:v')              // Video from input 0
  .map('1:a')              // Audio from input 1
  .map('2:s')              // Subtitles from input 2
  .save('combined.mkv');

/**
 * Run flvtool2/flvmeta on output FLV files
 * @returns FfmpegCommand instance for chaining
 */
flvmeta() // → FfmpegCommand
// Aliases: updateFlvMetadata

// Create FLV with proper metadata
ffmpeg('input.mp4')
  .format('flv')
  .flvmeta()  // Add keyframe metadata for seeking
  .save('output.flv');

/**
 * Add custom output options
 * @param options - Option string(s) or array of option strings  
 * @returns FfmpegCommand instance for chaining
 */
outputOptions(...options) // → FfmpegCommand
// Aliases: addOutputOption, addOutputOptions, addOption, addOptions,
//          withOutputOption, withOutputOptions, withOption, withOptions, outputOption

// Custom encoding options
ffmpeg('input.avi')
  .outputOptions([
    '-crf', '18',           // Constant rate factor
    '-preset', 'slow',      // Encoding preset
    '-profile:v', 'high',   // H.264 profile
    '-level', '4.1'         // H.264 level
  ])
  .save('high_quality.mp4');

// Streaming options
ffmpeg('input.mp4')
  .outputOptions([
    '-movflags', '+faststart',  // Web-optimized MP4
    '-pix_fmt', 'yuv420p'       // Compatibility pixel format
  ])
  .save('web_ready.mp4');

// Custom container options
ffmpeg('input.avi')
  .outputOptions([
    '-avoid_negative_ts', 'make_zero',
    '-fflags', '+genpts'
  ])
  .format('mp4')
  .save('fixed_timing.mp4');

// Multi-pass encoding
ffmpeg('input.avi')
  .outputOptions([
    '-pass', '1',
    '-b:v', '2000k',
    '-f', 'null'
  ])
  .output('/dev/null')  // First pass
  .run()
  .then(() => {
    return ffmpeg('input.avi')
      .outputOptions([
        '-pass', '2', 
        '-b:v', '2000k'
      ])
      .save('2pass_output.mp4');
  });

/**
 * Apply codec options to specific streams using output options
 */
outputOptions(['-c:v:0', 'libx264', '-c:a:0', 'aac']) // → FfmpegCommand

// Different codecs for multiple streams
ffmpeg('input.mkv')
  .outputOptions([
    '-c:v:0', 'libx264',    // H.264 for first video
    '-c:v:1', 'libx265',    // H.265 for second video
    '-c:a:0', 'aac',        // AAC for first audio
    '-c:a:1', 'mp3'         // MP3 for second audio
  ])
  .save('multi_codec.mkv');

// Per-stream bitrates
ffmpeg('input.avi')
  .outputOptions([
    '-b:v:0', '2000k',      // 2Mbps for video
    '-b:a:0', '128k',       // 128kbps for audio
    '-maxrate:v:0', '2500k', // Max video bitrate
    '-bufsize:v:0', '5000k'  // Buffer size
  ])
  .save('bitrate_controlled.mp4');

const command = ffmpeg('input.mp4');

// Add outputs conditionally
if (needHighQuality) {
  command.output('hq_output.mp4').videoBitrate('5000k');
}

if (needLowQuality) {
  command.output('lq_output.mp4').videoBitrate('1000k');
}

command.run();

/**
 * Output target types
 */
type OutputTarget = string | WritableStream;

/**
 * Pipe options for stream outputs
 */
interface PipeOptions {
  end?: boolean;        // End stream when ffmpeg finishes (default: true)
}

/**
 * Common output format names
 */
type OutputFormat = 
  | 'mp4' | 'avi' | 'mkv' | 'mov' | 'wmv'     // Video containers
  | 'mp3' | 'aac' | 'wav' | 'flac' | 'ogg'    // Audio formats
  | 'webm' | 'ogv'                            // Web formats
  | 'flv' | 'f4v'                             // Flash formats  
  | 'ts' | 'mpegts'                           // Transport streams
  | 'hls' | 'dash'                            // Adaptive streaming
  | 'null'                                    // Null output (testing)
  | string;                                   // Any FFmpeg format

/**
 * Stream mapping specification
 */
type StreamSpec = string; // Format: 'input:type:index' or variations

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