Audio Processing

/**
 * Set audio codec for output
 * @param codec - Audio codec name
 * @returns FfmpegCommand instance for chaining
 */
audioCodec(codec) // → FfmpegCommand
// Aliases: withAudioCodec

// Common audio codecs
ffmpeg('input.wav').audioCodec('libmp3lame').save('output.mp3');
ffmpeg('input.flac').audioCodec('aac').save('output.m4a');
ffmpeg('input.mp3').audioCodec('pcm_s16le').save('output.wav');

// High-quality audio encoding
ffmpeg('input.wav')
  .audioCodec('libvorbis')
  .audioBitrate('320k')
  .save('output.ogg');

/**
 * Set audio bitrate
 * @param bitrate - Bitrate in kbps (with optional 'k' suffix)
 * @returns FfmpegCommand instance for chaining
 */
audioBitrate(bitrate) // → FfmpegCommand
// Aliases: withAudioBitrate

// Standard bitrates
ffmpeg('input.wav').audioBitrate('128k').save('output.mp3');
ffmpeg('input.flac').audioBitrate(320).save('high_quality.mp3');

// Variable bitrate with quality
ffmpeg('input.wav')
  .audioCodec('libmp3lame')
  .audioBitrate('256k')
  .audioQuality(2)  // VBR quality
  .save('output.mp3');

/**
 * Set number of audio channels
 * @param channels - Number of audio channels (1=mono, 2=stereo, etc.)
 * @returns FfmpegCommand instance for chaining
 */
audioChannels(channels) // → FfmpegCommand
// Aliases: withAudioChannels

// Convert stereo to mono
ffmpeg('stereo.wav').audioChannels(1).save('mono.wav');

// Convert to stereo
ffmpeg('mono.wav').audioChannels(2).save('stereo.wav');

// 5.1 surround sound
ffmpeg('multichannel.wav').audioChannels(6).save('surround.wav');

/**
 * Set audio sample rate
 * @param freq - Frequency in Hz (e.g., 44100, 48000)
 * @returns FfmpegCommand instance for chaining
 */
audioFrequency(freq) // → FfmpegCommand  
// Aliases: withAudioFrequency

// Standard sample rates
ffmpeg('input.wav').audioFrequency(44100).save('cd_quality.wav');
ffmpeg('input.wav').audioFrequency(48000).save('pro_audio.wav');

// Downsampling for smaller files
ffmpeg('high_res.wav')
  .audioFrequency(22050)
  .audioBitrate('96k')
  .save('compressed.mp3');

/**
 * Set audio quality factor (codec-specific)
 * @param quality - Quality factor (codec-dependent scale)
 * @returns FfmpegCommand instance for chaining
 */
audioQuality(quality) // → FfmpegCommand
// Aliases: withAudioQuality

// MP3 VBR quality (0=best, 9=worst)
ffmpeg('input.wav')
  .audioCodec('libmp3lame')
  .audioQuality(2)  // High quality VBR
  .save('vbr.mp3');

// AAC quality
ffmpeg('input.wav')
  .audioCodec('aac')
  .audioQuality(1)  // High quality
  .save('output.m4a');

/**
 * Remove audio from output
 * @returns FfmpegCommand instance for chaining
 */
noAudio() // → FfmpegCommand
// Aliases: withNoAudio

// Create video-only file
ffmpeg('movie_with_sound.mp4')
  .noAudio()
  .videoCodec('libx264')
  .save('silent_movie.mp4');

/**
 * Apply audio filters
 * @param filters - Filter specifications (string, array, or objects)
 * @returns FfmpegCommand instance for chaining
 */
audioFilters(...filters) // → FfmpegCommand
// Aliases: withAudioFilter, withAudioFilters, audioFilter

// Volume adjustment
ffmpeg('input.mp3')
  .audioFilters('volume=0.5')  // Reduce volume by half
  .save('quieter.mp3');

// Multiple filters
ffmpeg('input.wav')
  .audioFilters([
    'highpass=f=200',      // High-pass filter at 200Hz
    'lowpass=f=8000',      // Low-pass filter at 8kHz  
    'volume=1.5'           // Increase volume
  ])
  .save('filtered.wav');

// Object-style filters
ffmpeg('input.mp3')
  .audioFilters([
    { filter: 'equalizer', options: 'f=1000:width_type=h:width=200:g=5' },
    { filter: 'compand', options: 'attacks=0.3:decays=0.8:points=-80/-80|-45/-15|-27/-9|0/-7|20/-7' }
  ])
  .save('processed.mp3');

// Fade effects
ffmpeg('input.wav')
  .audioFilters([
    'afade=t=in:ss=0:d=3',    // Fade in for 3 seconds
    'afade=t=out:st=57:d=3'   // Fade out starting at 57s for 3s
  ])
  .save('with_fades.wav');

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

// Select second audio track
ffmpeg('movie.mkv')
  .map('0:v:0')    // First video stream
  .map('0:a:1')    // Second audio stream  
  .save('different_audio.mp4');

// Audio-only extraction
ffmpeg('video.mp4')
  .map('0:a')      // All audio streams
  .noVideo()
  .save('audio_only.mp3');

/**
 * Add audio delay using output options
 * @param options - Array of FFmpeg options
 * @returns FfmpegCommand instance for chaining
 */
outputOptions(...options) // → FfmpegCommand

// Delay audio by 500ms
ffmpeg('video.mp4')
  .outputOptions(['-itsoffset', '0.5'])
  .map('0:v')
  .map('0:a')
  .save('audio_delayed.mp4');

/**
 * Common audio codec names
 */
type AudioCodec = 
  | 'libmp3lame'        // MP3 encoding
  | 'aac'               // AAC encoding (built-in)
  | 'libfdk_aac'        // High-quality AAC (external)
  | 'libvorbis'         // Vorbis/OGG encoding
  | 'libopus'           // Opus encoding
  | 'flac'              // FLAC lossless
  | 'pcm_s16le'         // PCM 16-bit little-endian
  | 'pcm_s24le'         // PCM 24-bit little-endian
  | 'pcm_f32le'         // PCM 32-bit float
  | 'ac3'               // AC-3 (Dolby Digital)
  | 'dts'               // DTS
  | string;             // Any FFmpeg audio codec

/**
 * Audio bitrate specification
 */
type AudioBitrate = number | string; // kbps as number or with 'k' suffix

/**
 * Standard audio sample rates
 */
type AudioSampleRate = 
  | 8000 | 11025 | 16000 | 22050    // Low quality/telephony
  | 32000 | 44100 | 48000           // Standard quality
  | 88200 | 96000 | 176400 | 192000 // High resolution
  | number;                         // Any valid sample rate

/**
 * Audio filter specification
 */
type AudioFilter = 
  | 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)
    };