@overwolf/ow-electron-packages-types/types.d.ts

Type definition file for autocompletion and documentation purposes for ow-electron packages

import { overwolf } from '@overwolf/ow-electron';
import {
  BrowserWindow,
  BrowserWindowConstructorOptions,
  Size,
  WebContents,
  Display,
  Rectangle
} from 'electron';

import { EventEmitter } from 'events';

// -----------------------------------------------------------------------------

// --- modules\utility.d.ts ---
/**
 * @packageDocumentation
 *
 * This module provides utility methods for tracking and managing game-related events
 * such as game launch, exit, and scanning for installed games. It is used to enable 
 * event-driven behavior based on a user's game activity.
 *
 * @example
 * ```ts
 * const utility: IOverwolfUtilityApi = new OverwolfUtility();
 *
 * utility.trackGames({ includeUnsupported: true });
 *
 * utility.on('game-launched', (gameInfo) => {
 *   console.log('Game launched:', gameInfo.name);
 * });
 *
 * utility.on('game-exit', (gameInfo) => {
 *   console.log('Game exited:', gameInfo.name);
 * });
 *
 * const installedGames = await utility.scan();
 * console.log('Installed games:', installedGames);
 * ```
 */

/**
 * Defines the API for managing game launch and utility operations.
 */
interface IOverwolfUtilityApi {
  /**
   * Register games you want to track.
   *
   * Once a game that matches the filter is launched or exited, the appropriate
   * event listeners will be triggered.
   *
   * @param filter - Configuration specifying which games to register and whether to include unsupported titles.
   */
  trackGames(filter: GamesFilter): Promise<void>;

  /**
   * Scans the system for installed games that match the provided filter.
   *
   * @param filter - Optional. Configuration specifying which games to include in the scan.
   * @returns A promise that resolves to an array of `InstalledGameInfo` objects representing the installed games.
   */
  scan(filter?: GamesFilter): Promise<InstalledGameInfo[]>;

  /**
   * Fires when a tracked game is launched.
   *
   * @param eventName - The name of the event ('game-launched').
   * @param listener - A callback that receives the `GameInfo` of the launched game.
   * @returns The current instance for method chaining.
   */
  on(eventName: 'game-launched', listener: (gameInfo: GameInfo) => void): this;

  /**
   * Fires when a tracked game is exited.
   *
   * @param eventName - The name of the event ('game-exit').
   * @param listener - A callback that receives the `GameInfo` of the exited game.
   * @returns The current instance for method chaining.
   */
  on(eventName: 'game-exit', listener: (gameInfo: GameInfo) => void): this;
}


// --- modules\recorder.d.ts ---
/**
 * 
 * The Overwolf Electron recording APIs integrate recording into the Overwolf Electron framework allowing you to record both audio and video.
 * 
 * The recoding API supports many different encoders and provides two recording modes so that you can create dynamic recording apps.
 * 
 * ## Recording modes
 * The recording feature supports two types of recording modes:
 * 
 * - Standard—all video is recorded from start to finish when stopped and is saved to storage.
 * - Replay—records based on a provided time frame (cached sliding buffer). Specify total buffer time and how much time to record before and/or after the recording starts. Once recording is complete the video will be saved to your storage.
 * 
 * ## Recorder package features
 * 
 * ### Capture Audio / Video
 * - Capture video from a specific display device or capture from a running game.
 * - Capture any audio input or output device, such as speakers, a microphone, or the game sound alone.
 * - Split capture into separate video files on-demand or using a timer.
 * - Multiple audio and video encoders supported.
 * - Multiple output formats supported.
 * - Control bitrate and encoding rate.
 * - Options to allocate specific audio tracks to specific audio devices.
 * 
 * ### Replays Capture
 * 
 * - Record a buffer of X seconds to memory without saving to disk.
 * - Allow for on-demand video capture to disk with a portion or all of the in-memory buffer.
 * - For example, when a highlight is detected while the replay is running, capture can be turned on to run for a timer, using X seconds already captured by the replay.
 * 
 * ### Game Listener
 * 
 * - Using the recording package, we can register for general events from supported games, such as game launch or exit.
 * - This can be used to trigger seamless recording as the game is loaded or alternately to start a replay and later trigger capture during appropriate moments.
 * 
 * ### Usage stats
 * 
 * While the recorder is actively recording, usage stats are provided such as:
 * 
 * - CPU & memory usage.
 * - Available disk space.
 * - Active FPS.
 * - Dropped frames information.
 * 
 * ## Example
 * 
 * Use the recording APIs with game events supplied by the [Game Events Provider](../../../live-game-data-gep/live-game-data-gep-intro.mdx) to create apps that can record video game play based on game events. This [sample app](https://github.com/overwolf/ow-electron-packages-sample) has a recording feature.
 * 
 * @packageDocumentation
 */

/**
 * Defines a rectangle by specifying its top-left coordinates and dimensions.
 *
 * Typically used for representing positions and sizes of elements or windows.
 *
 * @property top - The vertical coordinate of the top edge of the rectangle.
 * @property left - The horizontal coordinate of the left edge of the rectangle.
 * @property width - The width of the rectangle.
 * @property height - The height of the rectangle.
 *
 * @example
 * const rect: Rect = { top: 100, left: 50, width: 300, height: 200 };
 */
type Rect = { top: number; left: number; width: number; height: number };



/**
 * Defines the type of an audio device.
 * 
 * Defined as either and **input** device (e.g., microphone)
 * or an **output** device (e.g., speakers or headphones).
 *
 * @example
 * function setDevice(type: AudioDeviceType) {
 *   if (type === 'input') {
 *     console.log('Microphone selected');
 *   } else {
 *     console.log('Speaker selected');
 *   }
 * }
 */
type AudioDeviceType = 'input' | 'output';



/**
 * All available supported encoder types for video recording or streaming.
 *
 * These encoder identifiers are used to configure the encoding backend for tools like OBS.
 * Note that older `jim_*` encoder types were deprecated as of OBS version 0.31.0
 * and have been replaced by the `obs_nvenc_*` family of encoders.
 *
 * @remarks
 * This type includes software-based encoders (like `obs_x264`) and
 * hardware-accelerated encoders for various platforms (e.g., NVENC, QSV, AMF).
 *
 * @example
 * const encoder: kSupportedEncodersTypes = 'obs_nvenc_h264_tex';
 */
type kSupportedEncodersTypes =
/**
   * Software AV1 encoder using Intel's SVT-AV1 via FFmpeg.
   */
  | 'ffmpeg_svt_av1'
  /**
   * Software AV1 encoder using AOMedia's libaom via FFmpeg.
   */
  | 'ffmpeg_aom_av1'
  /**
   * Software H.264 encoder using the x264 library (CPU-based).
   */
  | 'obs_x264'
  /**
   * Hardware-accelerated H.264 encoder using AMD's AMF with texture input.
   */
  | 'h264_texture_amf'
  /**
   * Hardware-accelerated H.265 (HEVC) encoder using AMD's AMF with texture input.
   */
  | 'h265_texture_amf'
  /**
   * Hardware-accelerated AV1 encoder using AMD's AMF with texture input.
   */
  | 'av1_texture_amf'
  /**
   * Hardware-accelerated H.264 encoder using Intel's QSV 1.1 API.
   */
  | 'obs_qsv11_v2'
  /**
   * Hardware-accelerated H.265 (HEVC) encoder using Intel's QSV 1.1 API.
   */
  | 'obs_qsv11_hevc'
  /**
   * Hardware-accelerated AV1 encoder using Intel's QSV 1.1 API.
   */
  | 'obs_qsv11_av1'
  /**
   * Hardware-accelerated H.264 encoder using NVIDIA's NVENC with texture input.
   */
  | 'obs_nvenc_h264_tex'
  /**
   * Hardware-accelerated H.265 (HEVC) encoder using NVIDIA's NVENC with texture input.
   */
  | 'obs_nvenc_hevc_tex'
  /**
   * Hardware-accelerated AV1 encoder using NVIDIA's NVENC with texture input.
   */
  | 'obs_nvenc_av1_tex';


/**
 * List of audio encoder types available via FFmpeg.
 *
 * Typically used for exporting or streaming audio content in different formats.
 * Each variant maps to a specific FFmpeg audio codec.
 *
 * @remarks
 * If a custom encoder is used that is not in this predefined list, it can be specified as a `string`.
 *
 * @example
 * const audioEncoder: kKnownAudioEncodersTypes = 'ffmpeg_opus';
 */
type kKnownAudioEncodersTypes =
   /**
   * AAC (Advanced Audio Coding) encoder using FFmpeg.
   * Widely supported across platforms; good balance of quality and compression.
   */
  | 'ffmpeg_aac'

  /**
   * Opus encoder using FFmpeg.
   * High-efficiency codec commonly used for voice and streaming (e.g., Discord, WebRTC).
   */
  | 'ffmpeg_opus'

  /**
   * PCM (Pulse-code Modulation) 16-bit signed little-endian.
   * Uncompressed audio with moderate file size; excellent compatibility.
   */
  | 'ffmpeg_pcm_s16le'

  /**
   * PCM 24-bit signed little-endian.
   * Higher-resolution uncompressed audio format, often used in professional audio applications.
   */
  | 'ffmpeg_pcm_s24le'

  /**
   * PCM 32-bit floating-point little-endian.
   * Offers high dynamic range; used for precision in audio processing workflows.
   */
  | 'ffmpeg_pcm_f32le'

  /**
   * Apple Lossless Audio Codec (ALAC) encoder via FFmpeg.
   * Provides lossless compression; typically used in the Apple ecosystem.
   */
  | 'ffmpeg_alac'

  /**
   * FLAC (Free Lossless Audio Codec) encoder via FFmpeg.
   * Popular open-source lossless format with good compression and widespread support.
   */
  | 'ffmpeg_flac'

  /**
   * Custom or unknown encoder type represented as a string.
   */
  | string;

/**
 * Fixed audio sample rate of 48kHz.
 *
 * Commonly used in professional audio and video recording, broadcasting,
 * and streaming. Offers a balance between quality and performance, and is
 * often the default sample rate in real-time communication systems.
 *
 * @example
 * const sampleRate: kSampleRate48kHz = 48000;
 */
type kSampleRate48kHz = 48000;

/**
 * Fixed audio sample rate of 44.1 kHz.
 *
 * This is the standard sample rate used for audio CDs and is commonly used
 * in music production and general-purpose audio playback.
 *
 * @example
 * const sampleRate: kSampleRate441kHz = 44100;
 */
type kSampleRate441kHz = 44100;



/**
 * Supported speaker layout configurations.
 *
 * These layout identifiers correspond to common channel arrangements used in audio output systems.
 * They are typically used to configure spatial audio or multichannel playback environments.
 *
 * @example
 * const layout: kSpeakerLayout = 'SPEAKERS_5POINT1';
 */
type kSpeakerLayout =
   /**
   * Mono output — single audio channel.
   */
  | 'SPEAKERS_MONO'
  /**
   * Stereo output — standard left and right channels.
   */
  | 'SPEAKERS_STEREO'
  /**
   * 2.1 output — stereo plus one subwoofer (LFE) channel.
   */
  | 'SPEAKERS_2POINT1'
  /**
   * 4.0 output — quadraphonic layout with front and rear left/right channels.
   */
  | 'SPEAKERS_4POINT0'
  /**
   * 4.1 output — quadraphonic layout plus one subwoofer channel.
   */
  | 'SPEAKERS_4POINT1'
  /**
   * 5.1 surround — front left/right, center, rear left/right, and subwoofer (LFE).
   */
  | 'SPEAKERS_5POINT1'
  /**
   * 7.1 surround — front left/right, center, rear left/right, side left/right, and subwoofer (LFE).
   */


/**
 * A utility class for defining named color constants.
 *
 * This example class provides predefined color values
 * that can be reused across the application.
 *
 * @example
 * const color = Colors.Red;
 */
  declare class Colors {
  /**
   * Represents the color red.
   */  
  public static readonly Red = 'Red';
}

/**
 * Audio track selection flags.
 *
 * Each value corresponds to a specific audio track using a bitmask format.
 * You can combine tracks using bitwise OR operations. For example, `Track1 | Track2` is `3`.
 *
 * @remarks
 * - This format is useful when routing or encoding specific audio channels.
 * - The `number` type is included to allow for custom or combined values not explicitly listed.
 *
 * @example
 * const tracks: AudioTracks = 1 | 2; // Track1 and Track2
 */
type AudioTracks =
/**
   * No audio track selected.
   */
  | 0
  /**
   * Select audio Track 1.
   */
  | 1
  /**
   * Select audio Track 2.
   */
  | 2
  /**
   * Select audio Track 3.
   */
  | 4
  /**
   * Select audio Track 4.
   */
  | 8
  /**
   * Select audio Track 5.
   */
  | 16
  /**
   * Select audio Track 6.
   */
  | 32
  /**
   * Select all available tracks (bitmask 0xff).
   */
  | 0xff
  /**
   * Any custom or combined track.
   */
  | number;



/**
 * Available methods for capturing the display in screen recording or streaming.
 *
 * These values determine the underlying capture technology used for grabbing screen content.
 * Selection may depend on hardware support, performance, or compatibility.
 *
 * @example
 * const captureType: DisplayCaptureType = "DXGI";
 */
type DisplayCaptureType = 
  /**
   * Automatically select the best capture method based on the system's capabilities.
   */
  | "Auto"
  /**
   * Use DXGI (DirectX Graphics Infrastructure) for capturing. Offers high performance on supported systems.
   */
  | "DXGI"
  /**
   * Use BitBlt (Bit Block Transfer), a legacy GDI-based capture method. May be less performant.
   */
  | "BitBlt"
  /**
   * Use Windows Graphics Capture (WGC), available on Windows 10+ with improved performance and stability.
   */
  | "WGC";

/**
 * Type of window capture method.
 */
type WindowCaptureType =
  /**
   * Automatically select the best window capture method.
   */
  "Auto"
  /**
   * Use BitBlt (Bit Block Transfer), a legacy GDI-based capture method. May be less performant.
   */
  | "BitBlt"
  /**
   * Use Windows Graphics Capture (WGC), available on Windows 10+ with improved performance and stability.
   */
  | "WGC";

/**
 * Type of source to capture during screen recording or streaming.
 *
 * These source types determine what part of the system the capture engine will target.
 *
 * @example
 * const source: CaptureSourceType = 'Game';
 */
type CaptureSourceType =
  /**
   * Capture the entire display (monitor/screen).
   */
  | 'Display'
  /**
   * Capture a game process or window, often using optimized game capture methods.
   */
  | 'Game'
  /**
   * Capture a specific application window.
   */
  | 'Window';



/**
 * Audio device available on the system.
 *
 * This interface is used to describe both input (e.g., microphones)
 * and output (e.g., speakers, headphones) audio devices.
 *
 * @example
 * const device: AudioDevice = {
 *   type: 'output',
 *   id: 'speakers-1',
 *   name: 'Realtek High Definition Audio',
 *   isDefault: true
 * };
 */
interface AudioDevice {
  /**
     * The type of the audio device (input or output).
     */
  readonly type: AudioDeviceType;

  /**
   * A unique identifier for the audio device.
   */
  readonly id: string;

  /**
   * A human-readable name for the audio device.
   */
  readonly name: string;

  /**
   * Whether this device is currently set as the system default.
   */
  readonly isDefault: boolean;
}

/**
 * The base `structure for an encoder, including codec and display name.
 *
 * This interface provides essential metadata about an encoder, typically used
 * to represent supported encoding options in a recording or streaming application.
 *
 * @example
 * const encoder: EncoderInfoBase = {
 *   codec: 'h264',
 *   name: 'NVIDIA NVENC H.264'
 * };
 */
interface EncoderInfoBase {
  /**
   * The codec identifier (e.g., `h264`, `aac`, `av1`) supported by the encoder.
   */
  readonly codec: string;

  /**
   * A human-readable name for the encoder (e.g., shown in UI).
   */
  readonly name: string;
}

/**
 * Configurable property of an encoder.
 *
 * Used to describe encoder settings such as bitrates, presets, or modes.
 * Provides metadata to help display options in a UI or validate configuration.
 *
 * @example
 * const bitrateProperty: EncoderProperty = {
 *   default: 4500,
 *   description: 'Target video bitrate in kbps.',
 *   values: {
 *     3000: 'Low quality',
 *     4500: 'Medium quality (default)',
 *     6000: 'High quality'
 *   }
 * };
 */
interface EncoderProperty {
  /**
   * The default value for this encoder property.
   */
  readonly default?: any;

  /**
   * A human-readable explanation of the property's purpose.
   */
  readonly description: string;

  /**
   * Optional array of possible values for this property.
   * Useful for dropdowns or presets.
   */
  readonly values?: (string | number)[];

  /**
   * Optional array of descriptions corresponding to the `values` array.
   * Helps provide additional context for each option.
   */
  readonly valuesDesc?: string[];
}

/**
 * Supported audio encoder information.
 *
 * Extends the base encoder information with a specific encoder type identifier.
 * Useful for populating encoder selection menus or configuring audio output.
 *
 * @extends EncoderInfoBase
 *
 * @example
 * const audioEncoder: AudioEncoderInfo = {
 *   codec: 'aac',
 *   name: 'FFmpeg AAC Encoder',
 *   type: 'ffmpeg_aac'
 * };
 */
interface AudioEncoderInfo extends EncoderInfoBase {
  /**
   * The identifier for the specific audio encoder type.
   * 
   * @see {@link kKnownAudioEncodersTypes}
   */
  readonly type: kKnownAudioEncodersTypes;
}



/**
 * Information for a supported video encoder.
 *
 * This interface extends `EncoderInfoBase` and adds specific information
 * about the video encoder type and any configurable encoder properties.
 *
 * @extends EncoderInfoBase
 *
 * @example
 * const encoderInfo: VideoEncoderInfo = {
 *   codec: 'h264',
 *   name: 'NVIDIA NVENC H.264',
 *   type: 'obs_nvenc_h264_tex',
 *   properties: {
 *     bitrate: {
 *       default: 6000,
 *       description: 'Target video bitrate in kbps.',
 *       values: {
 *         4000: 'Low quality',
 *         6000: 'Medium quality',
 *         8000: 'High quality'
 *       }
 *     }
 *   }
 * };
 */
interface VideoEncoderInfo extends EncoderInfoBase {
  /**
   * The identifier for the specific video encoder type.
   * 
   * @see {@link kSupportedEncodersTypes}
   */
  readonly type: kSupportedEncodersTypes;

  /**
   * Optional map of encoder-specific configuration properties.
   * Each property defines a setting that can be adjusted,
   * such as bitrate, profile, or keyframe interval.
   * 
   * @see {@link EncoderProperty}
   */
  readonly properties?: Record<string, EncoderProperty>;
}


/**
 * Information about a GPU adapter (graphics device).
 *
 * This structure provides metadata such as adapter name, driver, and
 * hardware-accelerated GPU scheduling (HAGS) support.
 *
 * @example
 * const adapter: AdapterInfo = {
 *   index: 0,
 *   name: 'NVIDIA GeForce RTX 3080',
 *   driver: '546.33',
 *   hagsEnabled: true,
 *   hagsEnabledByDefault: false
 * };
 */
interface AdapterInfo {
  /**
   * The index of the adapter (usually starts at 0 for the primary GPU).
   */
  readonly index: number;

  /**
   * The display name of the GPU adapter.
   */
  readonly name: string;

  /**
   * The version of the GPU driver currently installed.
   */
  readonly driver: string;

  /**
   * Indicates whether Hardware-Accelerated GPU Scheduling (HAGS) is currently enabled.
   */
  readonly hagsEnabled: boolean;

  /**
   * Indicates whether HAGS is enabled by default on this adapter.
   */
  readonly hagsEnabledByDefault: boolean;
}


/**
 * Information about the complete audio configuration,
 * including input/output devices and supported audio encoders.
 *
 * Useful for initializing or inspecting audio capture and encoding settings
 * in applications such as screen recorders or streaming tools.
 *
 * @example
 * const audioInfo: AudioInformation = {
 *   inputDevices: [...],
 *   outputDevices: [...],
 *   encoders: [...],
 *   defaultEncoder: 'ffmpeg_aac'
 * };
 */
interface AudioInformation {
  /**
   * A list of available input audio devices (e.g., microphones).
   * 
   * @see {@link AudioDevice}
   */
  readonly inputDevices: AudioDevice[];

  /**
   * A list of available output audio devices (e.g., speakers, headphones).
   * 
   * @see {@link AudioDevice}
   */
  readonly outputDevices: AudioDevice[];

  /**
   * A list of supported audio encoders available for use.
   * 
   * @see {@link AudioEncoderInfo}
   */
  readonly encoders: AudioEncoderInfo[];

  /**
   * The identifier of the default audio encoder.
   * 
   * @see {@link kKnownAudioEncodersTypes}
   */
  readonly defaultEncoder: kKnownAudioEncodersTypes;
}


/**
 * Information about a display monitor connected to the system.
 *
 * This interface provides technical and user facing properties such as DPI,
 * resolution, display identifiers, and whether it is the primary monitor.
 *
 * @example
 * const monitor: MonitorInfo = {
 *   adapterIndex: 0,
 *   id: 'MONITOR\\GSM5B10\\{4d36e96e-e325-11ce-bfc1-08002be10318}_0',
 *   altId: 'DISPLAY1',
 *   dpi: 96,
 *   attachedToDesktop: true,
 *   friendlyName: 'LG UltraFine 4K',
 *   refreshRate: 60,
 *   rect: { top: 0, left: 0, width: 3840, height: 2160 },
 *   isPrimary: true,
 *   displayIndex: 0
 * };
 */
interface MonitorInfo {
  /**
   * Index of the GPU adapter this monitor is connected to.
   */
  readonly adapterIndex: number;

  /**
   * The full device path or system identifier for the monitor.
   */
  readonly id: string;

  /**
   * An alternative, usually simplified, identifier (e.g., DISPLAY1).
   */
  readonly altId: string;

  /**
   * The DPI (dots per inch) value of the monitor.
   */
  readonly dpi: number;

  /**
   * Indicates whether the monitor is currently attached to the desktop.
   */
  readonly attachedToDesktop: boolean;

  /**
   * A user-friendly name for the monitor (e.g., model name).
   */
  readonly friendlyName: string;

  /**
   * The refresh rate of the monitor in Hz.
   */
  readonly refreshRate: number;

  /**
   * The bounding rectangle of the monitor on the virtual screen.
   */
  readonly rect: Rect;

  /**
   * Whether this monitor is set as the system’s primary display.
   */
  readonly isPrimary: boolean;

  /**
   * The display index assigned to this monitor by the system.
   */
  readonly displayIndex: number;
}

/**
 * Information about the complete video configuration available in the system,
 * including supported video encoders and GPU adapters.
 *
 * Useful for configuring video recording or streaming pipelines,
 * and for providing user-selectable encoder and adapter options.
 *
 * @example
 * const videoInfo: VideoInformation = {
 *   encoders: [...],
 *   adapters: [...],
 *   defaultEncoder: 'obs_nvenc_h264_tex'
 * };
 * 
 */
interface VideoInformation {
  /**
   * A list of supported video encoders that can be used for recording or streaming.
   *
   * @see VideoEncoderInfo
   */
  readonly encoders: VideoEncoderInfo[];

  /**
   * A list of GPU adapters available on the system.
   *
   * @see AdapterInfo
   */
  readonly adapters: AdapterInfo[];

  /**
   * The identifier of the default video encoder selected by the system.
   *
   * @see kSupportedEncodersTypes
   */
  readonly defaultEncoder: kSupportedEncodersTypes;
}

/**
 * Information about the complete recording configuration for the current system.
 *
 * This includes audio device and encoder information, video encoder and GPU adapter details,
 * and connected monitor metadata. Useful for setting up and validating a full recording session.
 *
 * @example
 * const config: RecordingInformation = {
 *   audio: { ... },
 *   video: { ... },
 *   monitors: [ ... ]
 * };
 *
 */
interface RecordingInformation {
  /**
   * Audio-related configuration, including input/output devices and encoders.
   *
   * @see AudioInformation
   */
  audio: AudioInformation;

  /**
   * Video-related configuration, including available encoders and GPU adapters.
   *
   * @see VideoInformation
   */
  video: VideoInformation;

  /**
   * A list of monitors currently connected to the system.
   *
   * @see MonitorInfo
   */
  monitors: MonitorInfo[];
}




/**
 * Video file format options used for recording or exporting.
 *
 * Each format may offer different tradeoffs in terms of compatibility, streaming support,
 * compression, or support for advanced features like fragmentation or hybrid modes.
 *
 * @example
 * const format: kFileFormat = 'mp4';
 */
type kFileFormat =
  /**
   * Fragmented MP4 — Ideal for adaptive streaming and progressive download scenarios.
   */
  | 'fragmented_mp4'

  /**
   * Fragmented MOV — Similar to fragmented MP4 but uses the .mov container format.
   */
  | 'fragmented_mov'

  /**
   * Standard MP4 — Widely supported container for high-quality compressed video and audio.
   */
  | 'mp4'

  /**
   * FLV — Flash Video format, legacy support for some live streaming services.
   */
  | 'flv'

  /**
   * MKV — Matroska container supporting multiple audio, video, and subtitle tracks.
   */
  | 'mkv'

  /**
   * MOV — Apple's QuickTime format, often used in macOS video workflows.
   */
  | 'mov'

  /**
   * MPEG-TS — Transport stream format suitable for broadcasting or continuous streaming.
   */
  | 'mpegts'

  /**
   * HLS — HTTP Live Streaming; produces a playlist with segmented video chunks.
   */
  | 'hls'

  /**
   * Hybrid MP4 — A format combining fragmented and standard MP4 traits for compatibility.
   */
  | 'hybrid_mp4';

/**
 * Supported video color formats used during video encoding or capture.
 *
 * Each format defines how color and luminance information is represented in memory.
 * Choice of format can affect performance, quality, and hardware compatibility.
 *
 * @example
 * const colorFormat: kVideoColorFormat = 'NV12';
 */
type kVideoColorFormat =
  /**
   * NV12 — 8-bit YUV format with planar Y and interleaved UV planes.
   * Commonly used in hardware-accelerated video processing.
   */
  | 'NV12'

  /**
   * I420 — 8-bit planar YUV format with 4:2:0 chroma subsampling.
   * Widely supported and efficient for compression.
   */
  | 'I420'

  /**
   * I444 — 8-bit planar YUV format with full 4:4:4 chroma (no subsampling).
   * Offers highest color fidelity, useful for post-production.
   */
  | 'I444'

  /**
   * P010 — 10-bit packed YUV 4:2:0 format.
   * Suitable for high dynamic range (HDR) workflows.
   */
  | 'P010'

  /**
   * I010 — 10-bit planar YUV 4:2:0 format.
   * Provides better color depth while retaining planar layout.
   */
  | 'I010'

  /**
   * P216 — 16-bit packed YUV 4:2:2 format.
   * Offers higher color resolution, used in professional capture scenarios.
   */
  | 'P216'

  /**
   * P416 — 16-bit packed YUV 4:4:4 format.
   * Ideal for precise color reproduction and advanced editing.
   */
  | 'P416'

  /**
   * BGRA — 8-bit packed RGB format with alpha channel.
   * Used in real-time rendering and desktop capture.
   */
  | 'BGRA';


/**
 * Defines the color specification used for encoding or rendering video.
 *
 * These color specs represent standardized color spaces and transfer functions
 * used in video encoding pipelines. Choosing the appropriate spec impacts color
 * accuracy and display compatibility, especially for HDR or broadcast workflows.
 *
 * @example
 * const colorSpec: kVideoColorSpec = '709';
 */
type kVideoColorSpec =
  /**
   * sRGB — Standard RGB color space used for web content and computer monitors.
   * Matches the typical display profile of non-HDR screens.
   */
  | 'sRGB'

  /**
   * 709 — Rec. 709 color space used for HDTV and most modern video production.
   * Offers better color range and gamma than older standards.
   */
  | '709'

  /**
   * 601 — Rec. 601 color space used in standard-definition television (SDTV).
   * Suitable for legacy content or older broadcast systems.
   */
  | '601'

  /**
   * 2100PQ — Rec. 2100 color spec using PQ (Perceptual Quantizer) transfer function.
   * Used for HDR10 and other HDR video delivery standards.
   */
  | '2100PQ'

  /**
   * 2100HLG — Rec. 2100 color spec using HLG (Hybrid Log-Gamma) transfer function.
   * HDR-compatible and backward-compatible with SDR displays.
   */
  | '2100HLG';

/**
 * Specifies the color range used during video capture or encoding.
 *
 * This setting determines how color values are scaled, which impacts brightness
 * and contrast. It is important to match the color range to the target display
 * or encoder to avoid washed-out or crushed colors.
 *
 * @example
 * const range: kVideoColorRange = 'Full';
 */
type kVideoColorRange =
  /**
   * Partial — Uses limited color range (typically 16–235 for luma),
   * common in broadcast and traditional video content.
   */
  | 'Partial'

  /**
   * Full — Uses the full color range (0–255),
   * typical for computer monitors and PC gaming content.
   */
  | 'Full';

/**
 * Defines supported AMD encoder rate control methods.
 *
 * Rate control modes determine how bitrate is managed during video encoding,
 * affecting quality, file size, and encoding performance.
 * These values are specific to AMD's video encoding capabilities.
 *
 * @example
 * const rateControl: kAMDEncoderRateControl = 'CBR';
 */
type kAMDEncoderRateControl =
  /**
   * CBR — Constant Bitrate.
   * Maintains a fixed bitrate for consistent file size and streaming bandwidth.
   */
  | 'CBR'

  /**
   * CQP — Constant Quantization Parameter.
   * Uses a fixed quantizer value, offering consistent visual quality but variable bitrate.
   */
  | 'CQP'

  /**
   * VBR — Variable Bitrate.
   * Bitrate adjusts based on complexity of the content, balancing quality and size.
   */
  | 'VBR'

  /**
   * VBR_LAT — Variable Bitrate with low-latency tuning.
   * Optimized for low-latency scenarios like real-time streaming.
   */
  | 'VBR_LAT'

  /**
   * QVBR — Quality-defined Variable Bitrate.
   * Maintains a target visual quality level rather than a specific bitrate.
   */
  | 'QVBR'

  /**
   * HQVBR — High-Quality Variable Bitrate.
   * Prioritizes visual fidelity while allowing variable bitrate.
   */
  | 'HQVBR'

  /**
   * HQCBR — High-Quality Constant Bitrate.
   * Delivers consistent bitrate while maximizing encoding quality.
   */
  | 'HQCBR';

/**
 * Specifies the encoding performance preset for AMD hardware encoders.
 *
 * These presets control the balance between encoding speed and visual quality.
 * Useful when tuning encoder behavior for different use cases such as streaming or local recording.
 *
 * @example
 * const preset: kAMDEncoderPreset = 'balanced';
 */
type kAMDEncoderPreset =
  /**
   * `quality` — Prioritizes the best possible image quality.
   * May result in slower encoding speeds.
   */
  | 'quality'

  /**
   * `balanced` — Offers a tradeoff between quality and speed.
   * Suitable for most general-purpose use cases.
   */
  | 'balanced'

  /**
   * `speed` — Optimized for fastest encoding performance.
   * May reduce image quality in favor of lower latency and CPU/GPU usage.
   */
  | 'speed';

/**
 * Defines available encoding presets for AMD AV1 hardware encoders.
 *
 * This type extends the standard AMD encoder presets with an additional
 * `highQuality` option, specific to AV1 encoding, providing enhanced quality settings.
 *
 * Useful for selecting the appropriate tradeoff between encoding speed and visual fidelity
 * when using the AV1 codec on supported AMD hardware.
 *
 * @example
 * const preset: kAMDEncoderPresetAV1 = 'highQuality';
 *
 * @see kAMDEncoderPreset
 */
type kAMDEncoderPresetAV1 = kAMDEncoderPreset | 'highQuality';

/**
 * Specifies the AV1 encoding profile for AMD hardware encoders.
 *
 * Encoding profiles define the set of coding tools and constraints used during video compression.
 * The `main` profile is currently the primary and most widely supported AV1 profile.
 *
 * @example
 * const profile: kAMDEncoderProfileAV1 = 'main';
 */
type kAMDEncoderProfileAV1 = 'main';



/**
 * Specifies the H.264 encoding profiles supported by AMD hardware encoders.
 *
 * Encoding profiles define the feature set and capabilities used during compression,
 * impacting compatibility, quality, and efficiency. This type includes standard H.264 profiles,
 * as well as the AV1 `main` profile reused for structural consistency.
 *
 * @example
 * const profile: kAMDEncoderProfile264 = 'high';
 *
 * @see kAMDEncoderProfileAV1
 */
type kAMDEncoderProfile264 =
  /**
   * `main` — The AV1 main profile reused here for structural consistency.
   * Typically not used with H.264 but may appear in shared configuration types.
   */
  | kAMDEncoderProfileAV1

  /**
   * `high` — Offers the best visual quality and compression efficiency.
   * Commonly used for high-definition video applications.
   */
  | 'high'

  /**
   * `baseline` — Provides the most basic H.264 features.
   * Suitable for low-complexity or real-time encoding scenarios.
   */
  | 'baseline';

/**
 * Specifies the rate control modes supported by NVIDIA's NVENC encoder.
 *
 * Rate control modes define how the encoder manages bitrate and quality.
 * Choosing the appropriate mode depends on the desired balance between quality, file size, and real-time performance.
 *
 * @example
 * const rateControl: kNVENCEncoderRateControl = 'CQP';
 */
type kNVENCEncoderRateControl =
  /**
   * `CBR` — Constant Bitrate. Maintains a consistent bitrate throughout the recording.
   * Useful for streaming and bandwidth-limited scenarios.
   */
  | 'CBR'

  /**
   * `CQP` — Constant Quantization Parameter. Prioritizes visual quality by keeping a consistent quantization level.
   * File sizes may vary significantly.
   */
  | 'CQP'

  /**
   * `VBR` — Variable Bitrate. Adjusts bitrate dynamically based on scene complexity.
   * Provides better compression but less predictability in file size.
   */
  | 'VBR'

  /**
   * `Lossless` — Encodes without compression loss.
   * Produces very high-quality output at the cost of large file sizes.
   */
  | 'Lossless';

/**
 * Specifies the multipass encoding mode for NVIDIA's NVENC encoder.
 *
 * Multipass encoding improves visual quality by analyzing the video in multiple passes
 * to better allocate bitrate and compression decisions.
 *
 * @example
 * const multipass: kNVENCEncoderMultipass = 'qres';
 */
type kNVENCEncoderMultipass =
  /**
   * `qres` — Quarter-resolution first pass followed by full-resolution encoding.
   * Offers a good balance between speed and improved quality.
   */
  | 'qres'

  /**
   * `fullres` — Full-resolution multipass encoding.
   * Produces the highest quality results but increases encoding time.
   */
  | 'fullres'

  /**
   * `disabled` — Multipass is turned off.
   * Results in faster encoding at the potential cost of lower quality.
   */
  | 'disabled';

/**
 * Specifies tuning presets for NVIDIA's NVENC encoder.
 *
 * Tuning presets allow the encoder to optimize for specific use cases like high quality or low latency,
 * adjusting internal settings accordingly.
 *
 * @example
 * const tuning: kNVENCEncoderTuning = 'll';
 */
type kNVENCEncoderTuning =
  /**
   * `hq` — High Quality. Prioritizes visual quality over latency.
   * Ideal for recording or broadcasting when minimal delay is not critical.
   */
  | 'hq'

  /**
   * `ll` — Low Latency. Balances quality and latency.
   * Suitable for interactive streaming and real-time applications.
   */
  | 'll'

  /**
   * `ull` — Ultra Low Latency. Minimizes delay as much as possible.
   * Best used in competitive gaming or remote control scenarios.
   */
  | 'ull';

/**
 * Controls the H.264 bitstream profile used by NVENC,
 * affecting decoder compatibility and compression efficiency. `main` is the
 * broad-compatibility choice and is commonly the default in OBS for NVENC.
 */
type kNVENCEncoderProfile = 'main';

/**
 * Specifies the supported H.264 encoding profiles for NVIDIA's NVENC encoder.
 *
 * These profiles determine the features used in encoding and the compatibility of the resulting stream or file.
 * This type extends the base `kNVENCEncoderProfile` and includes commonly used H.264 profiles.
 *
 * @example
 * const profile: kNVENCEncoderProfile264 = 'high';
 *
 * @see kNVENCEncoderProfile
 */
type kNVENCEncoderProfile264 =
  /**
   * `kNVENCEncoderProfile` — Base set of encoder profiles (e.g., `main`).
   * May include additional shared or AV1-specific variants.
   */
  | kNVENCEncoderProfile

  /**
   * `high` — Supports the most advanced H.264 features.
   * Recommended for high-definition video with better compression efficiency.
   */
  | 'high'

  /**
   * `baseline` — Basic H.264 profile with minimal compression features.
   * Best for low-latency and real-time video applications.
   */
  | 'baseline';

/**
 * Specifies the supported HEVC (H.265) encoding profiles for NVIDIA's NVENC encoder.
 *
 * These profiles determine the compression capabilities, color depth, and compatibility of the HEVC stream.
 * This type extends `kNVENCEncoderProfile` and includes 10-bit support via `main10`.
 *
 * @example
 * const profile: kNVENCEncoderProfileHEVC = 'main10';
 *
 * @see kNVENCEncoderProfile
 */
type kNVENCEncoderProfileHEVC =
  /**
   * `kNVENCEncoderProfile` — Base HEVC profile, typically includes `main`.
   * Suitable for standard 8-bit HEVC encoding.
   */
  | kNVENCEncoderProfile

  /**
   * `main10` — Enables 10-bit color depth for enhanced video quality and HDR compatibility.
   */
  | 'main10';

/**
 * Specifies the available rate control modes for the x264 encoder.
 *
 * Rate control modes determine how the encoder manages bitrate and quality over time.
 * Each mode offers a different balance between output file size, quality, and encoding speed.
 *
 * @example
 * const rateControl: kX264EncoderRateControl = 'CRF';
 */
type kX264EncoderRateControl =
  /**
   * `CBR` — Constant Bitrate. Maintains a fixed bitrate throughout encoding.
   * Useful for streaming where bandwidth predictability is important.
   */
  | 'CBR'

  /**
   * `ABR` — Average Bitrate. Tries to maintain a target average bitrate across the whole stream.
   * Balances quality and file size over long durations.
   */
  | 'ABR'

  /**
   * `VBR` — Variable Bitrate. Allows the bitrate to vary depending on frame complexity.
   * Offers better quality at lower file sizes, but less predictable bandwidth usage.
   */
  | 'VBR'

  /**
   * `CRF` — Constant Rate Factor. Targets a consistent visual quality instead of bitrate.
   * Ideal for scenarios where quality is more important than file size.
   */
  | 'CRF';

/**
 * Specifies the H.264 encoding profiles available for the x264 encoder.
 *
 * Encoding profiles define the set of features used for compression and compatibility
 * with various playback devices and streaming platforms.
 *
 * @example
 * const profile: kX264EncoderProfile = 'high';
 */
type kX264EncoderProfile =
  /**
   * `''` — Default profile. Lets the encoder decide which profile to use automatically.
   */
  | ''

  /**
   * `baseline` — Provides basic H.264 features.
   * Suitable for low-complexity, real-time, or legacy device compatibility scenarios.
   */
  | 'baseline'

  /**
   * `main` — Supports interlaced video and enhanced compression.
   * Recommended for general-purpose encoding with balanced quality and performance.
   */
  | 'main'

  /**
   * `high` — Enables advanced compression features for better video quality.
   * Ideal for HD content, streaming, or high-quality recording.
   */
  | 'high';



/**
 * Specifies the tuning presets for the x264 encoder.
 *
 * Tuning options help optimize the encoder's performance for specific types of content or use cases.
 * These settings adjust internal compression behavior and rate-distortion tradeoffs.
 *
 * @example
 * const tune: kX264EncoderTune = 'animation';
 */
type kX264EncoderTune =
  /**
   * `''` — Default. No tuning applied; encoder uses standard compression behavior.
   */
  | ''

  /**
   * `film` — Optimizes for live-action, natural footage.
   * Preserves fine grain and cinematic detail.
   */
  | 'film'

  /**
   * `animation` — Optimizes for animated content.
   * Enhances compression of solid colors and repetitive patterns.
   */
  | 'animation'

  /**
   * `grain` — Preserves film grain.
   * Reduces temporal blurring at the cost of larger file sizes.
   */
  | 'grain'

  /**
   * `stillimage` — Optimizes for individual image compression.
   * Suitable for slideshow or low-motion content.
   */
  | 'stillimage'

  /**
   * `psnr` — Optimizes for peak signal-to-noise ratio (PSNR).
   * Prioritizes objective video quality metrics.
   */
  | 'psnr'

  /**
   * `ssim` — Optimizes for structural similarity index (SSIM).
   * Targets better perceptual quality over raw pixel accuracy.
   */
  | 'ssim'

  /**
   * `fastdecode` — Reduces computational load on decoders.
   * Disables features that are hard to decode quickly.
   */
  | 'fastdecode'

  /**
   * `zerolatency` — Minimizes latency for real-time streaming.
   * Reduces buffering and introduces faster frame delivery.
   */
  | 'zerolatency';

/**
 * Specifies the encoding speed and compression efficiency preset for the x264 encoder.
 *
 * Faster presets use less CPU but result in lower compression efficiency (larger files),
 * while slower presets use more CPU to produce better compression and quality.
 *
 * @example
 * const preset: kX264EncoderPreset = 'veryfast';
 */
type kX264EncoderPreset =
  /**
   * `ultrafast` — Lowest CPU usage and fastest encoding speed.
   * Produces larger file sizes and lower compression quality.
   */
  | 'ultrafast'

  /**
   * `superfast` — Very fast encoding with slightly better compression than `ultrafast`.
   */
  | 'superfast'

  /**
   * `veryfast` — A good balance between speed and quality.
   * Commonly used default setting.
   */
  | 'veryfast'

  /**
   * `faster` — Slightly slower than `veryfast` with improved compression.
   */
  | 'faster'

  /**
   * `fast` — Offers better compression efficiency than `faster` at the cost of more CPU.
   */
  | 'fast'

  /**
   * `medium` — Default preset for x264.
   * Balances speed and quality effectively.
   */
  | 'medium'

  /**
   * `slow` — Slower encoding for better compression and video quality.
   */
  | 'slow'

  /**
   * `slower` — Even better compression at the cost of more processing time.
   */
  | 'slower'

  /**
   * `veryslow` — Maximizes compression efficiency and visual quality.
   * Suitable for archival or final delivery.
   */
  | 'veryslow'

  /**
   * `placebo` — Insanely slow with minimal improvement over `veryslow`.
   * Generally not recommended due to diminishing returns.
   */
  | 'placebo';


/**
 * Specifies the supported HEVC (H.265) encoder profiles for Intel Quick Sync Video.
 * 
 * This is an alias of `kNVENCEncoderProfileHEVC` to maintain compatibility
 * across encoder configurations while reusing the same profile definitions.
 *
 * @see kNVENCEncoderProfileHEVC
 *
 * @example
 * const profile: kQuickSyncEncoderProfileHEVC = 'main10';
 */
type kQuickSyncEncoderProfileHEVC = kNVENCEncoderProfileHEVC;

/**
 * Specifies the supported H.264 encoder profiles for Intel Quick Sync Video.
 * 
 * This type is an alias of `kNVENCEncoderProfile264`, reusing the same profile definitions 
 * to ensure consistency across encoder implementations.
 *
 * @see kNVENCEncoderProfile264
 *
 * @example
 * const profile: kQuickSyncEncoderProfile264 = 'high';
 */
type kQuickSyncEncoderProfile264 = kNVENCEncoderProfile264;




/**
 * Target usage modes for Intel Quick Sync Video encoders.
 * 
 * Target usage defines a trade-off between encoding speed and output quality.
 * Lower TU values result in better quality but slower performance, while higher values favor speed.
 *
 * @example
 * const usage: kQuickSyncTargetUsage = 'TU4'; // Balanced
 */
type kQuickSyncTargetUsage =
  /** `TU1` — Slowest encoding, best possible quality. */
  | 'TU1'
  /** `TU2` — Slower encoding with slightly reduced quality. */
  | 'TU2'
  /** `TU3` — Slow encoding with good quality. */
  | 'TU3'
  /** `TU4` — Balanced setting offering medium quality and speed. */
  | 'TU4'
  /** `TU5` — Fast encoding with reduced quality. */
  | 'TU5'
  /** `TU6` — Faster encoding with further quality tradeoffs. */
  | 'TU6'
  /** `TU7` — Fastest encoding, lowest quality. */
  | 'TU7';


 // Fastest (Best Speed)

/**
 * Defines the supported rate control modes for Intel Quick Sync Video encoders.
 * 
 * Rate control determines how the bitrate is managed during encoding, impacting quality, file size, and performance.
 *
 * @example
 * const rateControl: kQuickSyncEncoderRateControl = 'CBR';
 */
type kQuickSyncEncoderRateControl =
  /** `CBR` — Constant Bitrate. Maintains a fixed bitrate for predictable file sizes. */
  | 'CBR'
  /** `CQP` — Constant Quantization Parameter. Prioritizes consistent quality over bitrate. */
  | 'CQP'
  /** `VBR` — Variable Bitrate. Adjusts bitrate dynamically for efficient encoding with acceptable quality. */
  | 'VBR'
  /** `ICQ` — Intelligent Constant Quality. Balances quality and bitrate automatically using an internal algorithm. */
  | 'ICQ';

/**
 * Defines the methods available for splitting video recordings.
 * 
 * Splitting can be useful for managing file sizes, organizing segments, or controlling recording behavior dynamically.
 *
 * @example
 * const splitType: VideoRecordingSplitType = 'bySize';
 */
type VideoRecordingSplitType =
  /** `byTime` — Automatically splits the recording into segments based on elapsed time. */
  | 'byTime'
  /** `bySize` — Automatically splits the recording once a specific file size limit is reached. */
  | 'bySize'
  /** `manual` — Splitting is controlled programmatically or by user input. */
  | 'manual';

/**
 * The base configuration for an audio processing filter.
 * 
 * This interface serves as a blueprint for all audio filters within the system,
 * ensuring they have a unique identifier and a flexible container for settings.
 * * @example
 * ```typescript
 * const lowPass: AudioFilterBase = {
 * id: 'low-pass-001',
 * parameters: {
 * cutoff: 500,
 * resonance: 1.2
 * }
 * };
 * ```
 */
export interface AudioFilterBase {
  /**
   * A unique identifier for the filter instance.
   */
  id: string;

  /**
   * A collection of key-value pairs representing the filter's configuration.
   * 
   */
  parameters?: Record<string, number | string>;
}

/**
 * A specialized filter for dynamic range compression.
 * * @example
 * ```typescript
 * const vocalComp: AudioCompressorFilter = {
 * id: 'compressor_filter',
 * parameters: {
 * ratio: 4,
 * threshold: -20
 * }
 * };
 * ```
 */
export interface AudioCompressorFilter extends AudioFilterBase {
  /**
   * A unique identifier for the filter instance.
   */
  id: 'compressor_filter';

  /**
   * Configuration settings specific to the compressor.
   */
  parameters?: {
    /**
     * The amount of gain reduction applied once the signal exceeds the threshold.
     * Valid range: [1.00, 32.00]
     */
    ratio?: number;

    /**
     * The level (in dB) above which compression begins.
     * Valid range: [-60.0, 0.00]
     */
    threshold?: number;

    /**
     * How quickly (in ms) the compressor reduces the volume.
     * Valid range: [1, 500]
     */
    attack_time?: number;

    /**
     * How quickly (in ms) the compressor returns to normal volume after the signal drops.
     * Valid range: [1, 1000]
     */
    release_time?: number;

    /**
     * The gain (in dB) applied to the signal after compression to compensate for volume loss.
     * Valid range: [-32.00, 32.00]
     */
    output_gain?: number;
  };
}

/**
 * A specialized filter for dynamic range expansion or noise gating.
 * * @example
 * ```typescript
 * const noiseGate: AudioExpanderFilter = {
 * id: 'expander_filter',
 * parameters: {
 * presets: 'gate',
 * threshold: -40,
 * detector: 'peak'
 * }
 * };
 * ```
 */
export interface AudioExpanderFilter extends AudioFilterBase {
  /**
   * A unique identifier for the filter instance.
   */
  id: 'expander_filter';

  /**
   * Configuration settings specific to the expander/gate.
   */
  parameters?: {
    /**
     * Pre-defined configuration modes for common expansion tasks.
     */
    presets?: 'expander' | 'gate';

    /**
     * The ratio of expansion. Higher values result in more aggressive reduction 
     * of signals below the threshold.
     * Valid range: [1.00, 20.00]
     */
    ratio?: number;

    /**
     * The level (in dB) below which expansion or gating begins.
     * Valid range: [-60.00, 0.00]
     */
    threshold?: number;

    /**
     * How quickly (in ms) the expander reduces the volume once the signal drops below threshold.
     * Valid range: [1, 100]
     */
    attack_time?: number;

    /**
     * How quickly (in ms) the expander returns to unity gain once the signal rises above threshold.
     * Valid range: [1, 1000]
     */
    release_time?: number;

    /**
     * The gain (in dB) applied to the signal after processing.
     * Valid range: [-32.00, 32.00]
     */
    output_gain?: number;

    /**
     * The method used to calculate the signal level.
     * - `RMS`: Root Mean Square (average power).
     * - `peak`: Highest instantaneous signal level.
     */
    detector?: 'RMS' | 'peak';
  };
}

/**
 * A simple filter used to adjust the volume or amplitude of an audio signal.
 * * @example
 * ```typescript
 * const boost: AudioGainFilter = {
 * id: 'gain_filter',
 * parameters: {
 * db: 6.5
 * }
 * };
 * ```
 */
export interface AudioGainFilter extends AudioFilterBase {
  /**
   * A unique identifier for the filter instance.
   */
  id: 'gain_filter';

  /**
   * Configuration settings for gain adjustment.
   */
  parameters?: {
    /**
     * The amount of gain to apply to the signal, measured in decibels (dB).
     * Positive values amplify the signal, while negative values attenuate it.
     * * Valid range: [-30.00, 30.00]
     */
    db?: number;
  };
}

/**
 * A utility filter that flips the phase of the audio signal by 180 degrees.
 * * @example
 * ```typescript
 * const phaseFlip: AudioInvertPolarityFilter