mediabunny/dist/mediabunny.d.ts

Pure TypeScript media toolkit for reading, writing, and converting media files, directly in the browser.

/// <reference types="dom-mediacapture-transform" />
/// <reference types="dom-webcodecs" />

/**
 * List of all input format singletons. If you don't need to support all input formats, you should specify the
 * formats individually for better tree shaking.
 * @public
 */
export declare const ALL_FORMATS: InputFormat[];

/**
 * List of all track types.
 * @public
 */
export declare const ALL_TRACK_TYPES: readonly ["video", "audio", "subtitle"];

/**
 * Sync or async iterable.
 * @public
 */
export declare type AnyIterable<T> = Iterable<T> | AsyncIterable<T>;

/**
 * List of known audio codecs, ordered by encoding preference.
 * @public
 */
export declare const AUDIO_CODECS: readonly ["aac", "opus", "mp3", "vorbis", "flac", "pcm-s16", "pcm-s16be", "pcm-s24", "pcm-s24be", "pcm-s32", "pcm-s32be", "pcm-f32", "pcm-f32be", "pcm-f64", "pcm-f64be", "pcm-u8", "pcm-s8", "ulaw", "alaw"];

/**
 * A sink that retrieves decoded audio samples from an audio track and converts them to AudioBuffers. This is often
 * more useful than directly retrieving audio samples, as AudioBuffers can be directly used with the Web Audio API.
 * @public
 */
export declare class AudioBufferSink {
    constructor(audioTrack: InputAudioTrack);
    /**
     * Retrieves the audio buffer corresponding to the given timestamp, in seconds. More specifically, returns
     * the last audio buffer (in presentation order) with a start timestamp less than or equal to the given timestamp.
     * Returns null if the timestamp is before the track's first timestamp.
     *
     * @param timestamp - The timestamp used for retrieval, in seconds.
     */
    getBuffer(timestamp: number): Promise<WrappedAudioBuffer | null>;
    /**
     * Creates an async iterator that yields audio buffers of this track in presentation order. This method
     * will intelligently pre-decode a few buffers ahead to enable fast iteration.
     *
     * @param startTimestamp - The timestamp in seconds at which to start yielding buffers (inclusive).
     * @param endTimestamp - The timestamp in seconds at which to stop yielding buffers (exclusive).
     */
    buffers(startTimestamp?: number, endTimestamp?: number): AsyncGenerator<WrappedAudioBuffer, void, unknown>;
    /**
     * Creates an async iterator that yields an audio buffer for each timestamp in the argument. This method
     * uses an optimized decoding pipeline if these timestamps are monotonically sorted, decoding each packet at most
     * once, and is therefore more efficient than manually getting the buffer for every timestamp. The iterator may
     * yield null if no buffer is available for a given timestamp.
     *
     * @param timestamps - An iterable or async iterable of timestamps in seconds.
     */
    buffersAtTimestamps(timestamps: AnyIterable<number>): AsyncGenerator<WrappedAudioBuffer | null, void, unknown>;
}

/**
 * This source can be used to add audio data from an AudioBuffer to the output track. This is useful when working with
 * the Web Audio API.
 * @public
 */
export declare class AudioBufferSource extends AudioSource {
    constructor(encodingConfig: AudioEncodingConfig);
    /**
     * Converts an AudioBuffer to audio samples, encodes them and adds them to the output. The first AudioBuffer will
     * be played at timestamp 0, and any subsequent AudioBuffer will have a timestamp equal to the total duration of
     * all previous AudioBuffers.
     *
     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
     * to respect writer and encoder backpressure.
     */
    add(audioBuffer: AudioBuffer): Promise<void[]>;
}

/**
 * Union type of known audio codecs.
 * @public
 */
export declare type AudioCodec = typeof AUDIO_CODECS[number];

/**
 * Configuration object that controls audio encoding. Can be used to set codec, quality, and more.
 * @public
 */
export declare type AudioEncodingConfig = {
    /** The audio codec that should be used for encoding the audio samples. */
    codec: AudioCodec;
    /**
     * The target bitrate for the encoded audio, in bits per second. Alternatively, a subjective Quality can
     * be provided. Required for compressed audio codecs, unused for PCM codecs.
     */
    bitrate?: number | Quality;
    /**
     * The full codec string as specified in the WebCodecs Codec Registry. This string must match the codec
     * specified in `codec`. When not set, a fitting codec string will be constructed automatically by the library.
     */
    fullCodecString?: string;
    /** Called for each successfully encoded packet. Both the packet and the encoding metadata are passed. */
    onEncodedPacket?: (packet: EncodedPacket, meta: EncodedAudioChunkMetadata | undefined) => unknown;
    /** Called when the internal encoder config, as used by the WebCodecs API, is created. */
    onEncoderConfig?: (config: AudioEncoderConfig) => unknown;
};

/**
 * Represents a raw, unencoded audio sample. Mainly used as an expressive wrapper around WebCodecs API's AudioData,
 * but can also be used standalone.
 * @public
 */
export declare class AudioSample {
    /** The audio sample format. */
    readonly format: AudioSampleFormat;
    /** The audio sample rate in hertz. */
    readonly sampleRate: number;
    /**
     * The number of audio frames in the sample, per channel. In other words, the length of this audio sample in frames.
     */
    readonly numberOfFrames: number;
    /** The number of audio channels. */
    readonly numberOfChannels: number;
    /** The timestamp of the sample in seconds. */
    readonly duration: number;
    /**
     * The presentation timestamp of the sample in seconds. May be negative. Samples with negative end timestamps should
     * not be presented.
     */
    readonly timestamp: number;
    /** The presentation timestamp of the sample in microseconds. */
    get microsecondTimestamp(): number;
    /** The duration of the sample in microseconds. */
    get microsecondDuration(): number;
    constructor(init: AudioData | AudioSampleInit);
    /** Returns the number of bytes required to hold the audio sample's data as specified by the given options. */
    allocationSize(options: AudioSampleCopyToOptions): number;
    /** Copies the audio sample's data to an ArrayBuffer or ArrayBufferView as specified by the given options. */
    copyTo(destination: AllowSharedBufferSource, options: AudioSampleCopyToOptions): void;
    /** Clones this audio sample. */
    clone(): AudioSample;
    /**
     * Closes this audio sample, releasing held resources. Audio samples should be closed as soon as they are not
     * needed anymore.
     */
    close(): void;
    /**
     * Converts this audio sample to an AudioData for use with the WebCodecs API. The AudioData returned by this
     * method *must* be closed separately from this audio sample.
     */
    toAudioData(): AudioData;
    /** Convert this audio sample to an AudioBuffer for use with the Web Audio API. */
    toAudioBuffer(): AudioBuffer;
    /** Sets the presentation timestamp of this audio sample, in seconds. */
    setTimestamp(newTimestamp: number): void;
    /**
     * Creates AudioSamples from an AudioBuffer, starting at the given timestamp in seconds. Typically creates exactly
     * one sample, but may create multiple if the AudioBuffer is exceedingly large.
     */
    static fromAudioBuffer(audioBuffer: AudioBuffer, timestamp: number): AudioSample[];
}

/**
 * Options used for copying audio sample data.
 * @public
 */
export declare type AudioSampleCopyToOptions = {
    /**
     * The index identifying the plane to copy from. This must be 0 if using a non-planar (interleaved) output format.
     */
    planeIndex: number;
    /** The output format for the destination data. Defaults to the AudioSample's format. */
    format?: AudioSampleFormat;
    /** An offset into the source plane data indicating which frame to begin copying from. Defaults to 0. */
    frameOffset?: number;
    /**
     * The number of frames to copy. If not provided, the copy will include all frames in the plane beginning
     * with frameOffset.
     */
    frameCount?: number;
};

/**
 * Metadata used for AudioSample initialization.
 * @public
 */
export declare type AudioSampleInit = {
    /** The audio data for this sample. */
    data: AllowSharedBufferSource;
    /** The audio sample format. */
    format: AudioSampleFormat;
    /** The number of audio channels. */
    numberOfChannels: number;
    /** The audio sample rate in hertz. */
    sampleRate: number;
    /** The presentation timestamp of the sample in seconds. */
    timestamp: number;
};

/**
 * Sink for retrieving decoded audio samples from an audio track.
 * @public
 */
export declare class AudioSampleSink extends BaseMediaSampleSink<AudioSample> {
    constructor(audioTrack: InputAudioTrack);
    /**
     * Retrieves the audio sample corresponding to the given timestamp, in seconds. More specifically, returns
     * the last audio sample (in presentation order) with a start timestamp less than or equal to the given timestamp.
     * Returns null if the timestamp is before the track's first timestamp.
     *
     * @param timestamp - The timestamp used for retrieval, in seconds.
     */
    getSample(timestamp: number): Promise<AudioSample | null>;
    /**
     * Creates an async iterator that yields the audio samples of this track in presentation order. This method
     * will intelligently pre-decode a few samples ahead to enable fast iteration.
     *
     * @param startTimestamp - The timestamp in seconds at which to start yielding samples (inclusive).
     * @param endTimestamp - The timestamp in seconds at which to stop yielding samples (exclusive).
     */
    samples(startTimestamp?: number, endTimestamp?: number): AsyncGenerator<AudioSample, void, unknown>;
    /**
     * Creates an async iterator that yields an audio sample for each timestamp in the argument. This method
     * uses an optimized decoding pipeline if these timestamps are monotonically sorted, decoding each packet at most
     * once, and is therefore more efficient than manually getting the sample for every timestamp. The iterator may
     * yield null if no sample is available for a given timestamp.
     *
     * @param timestamps - An iterable or async iterable of timestamps in seconds.
     */
    samplesAtTimestamps(timestamps: AnyIterable<number>): AsyncGenerator<AudioSample | null, void, unknown>;
}

/**
 * This source can be used to add raw, unencoded audio samples to an output audio track. These samples will
 * automatically be encoded and then piped into the output.
 * @public
 */
export declare class AudioSampleSource extends AudioSource {
    constructor(encodingConfig: AudioEncodingConfig);
    /**
     * Encodes an audio sample and then adds it to the output.
     *
     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
     * to respect writer and encoder backpressure.
     */
    add(audioSample: AudioSample): Promise<void>;
}

/**
 * Base class for audio sources - sources for audio tracks.
 * @public
 */
export declare abstract class AudioSource extends MediaSource_2 {
    constructor(codec: AudioCodec);
}

/**
 * Additional metadata for audio tracks.
 * @public
 */
export declare type AudioTrackMetadata = BaseTrackMetadata & {};

/**
 * Base class for decoded media sample sinks.
 * @public
 */
export declare abstract class BaseMediaSampleSink<MediaSample extends VideoSample | AudioSample> {
}

/**
 * Base track metadata, applicable to all tracks.
 * @public
 */
export declare type BaseTrackMetadata = {
    /** The three-letter, ISO 639-2/T language code specifying the language of this track. */
    languageCode?: string;
};

/**
 * A source backed by a Blob. Since Files are also Blobs, this is the source to use when reading files off the disk.
 * @public
 */
export declare class BlobSource extends Source {
    constructor(blob: Blob);
}

/**
 * A source backed by an ArrayBuffer or ArrayBufferView, with the entire file held in memory.
 * @public
 */
declare class BufferSource_2 extends Source {
    constructor(buffer: ArrayBuffer | Uint8Array);
}
export { BufferSource_2 as BufferSource }

/**
 * A target that writes data directly into an ArrayBuffer in memory. Great for performance, but not suitable for very
 * large files. The buffer will be available once the output has been finalized.
 * @public
 */
export declare class BufferTarget extends Target {
    /** Stores the final output buffer. Until the output is finalized, this will be null. */
    buffer: ArrayBuffer | null;
}

/**
 * Checks if the browser is able to encode the given codec.
 * @public
 */
export declare const canEncode: (codec: MediaCodec) => Promise<boolean>;

/**
 * Checks if the browser is able to encode the given audio codec with the given parameters.
 * @public
 */
export declare const canEncodeAudio: (codec: AudioCodec, { numberOfChannels, sampleRate, bitrate }?: {
    numberOfChannels?: number;
    sampleRate?: number;
    bitrate?: number | Quality;
}) => Promise<boolean>;

/**
 * Checks if the browser is able to encode the given subtitle codec.
 * @public
 */
export declare const canEncodeSubtitles: (codec: SubtitleCodec) => Promise<boolean>;

/**
 * Checks if the browser is able to encode the given video codec with the given parameters.
 * @public
 */
export declare const canEncodeVideo: (codec: VideoCodec, { width, height, bitrate }?: {
    width?: number;
    height?: number;
    bitrate?: number | Quality;
}) => Promise<boolean>;

/**
 * A sink that renders video samples (frames) of the given video track to canvases. This is often more useful than
 * directly retrieving frames, as it comes with common preprocessing steps such as resizing or applying rotation
 * metadata.
 *
 * This sink will yield HTMLCanvasElements when in a DOM context, and OffscreenCanvases otherwise.
 * @public
 */
export declare class CanvasSink {
    constructor(videoTrack: InputVideoTrack, options?: CanvasSinkOptions);
    /**
     * Retrieves a canvas with the video frame corresponding to the given timestamp, in seconds. More specifically,
     * returns the last video frame (in presentation order) with a start timestamp less than or equal to the given
     * timestamp. Returns null if the timestamp is before the track's first timestamp.
     *
     * @param timestamp - The timestamp used for retrieval, in seconds.
     */
    getCanvas(timestamp: number): Promise<WrappedCanvas | null>;
    /**
     * Creates an async iterator that yields canvases with the video frames of this track in presentation order. This
     * method will intelligently pre-decode a few frames ahead to enable fast iteration.
     *
     * @param startTimestamp - The timestamp in seconds at which to start yielding canvases (inclusive).
     * @param endTimestamp - The timestamp in seconds at which to stop yielding canvases (exclusive).
     */
    canvases(startTimestamp?: number, endTimestamp?: number): AsyncGenerator<WrappedCanvas, void, unknown>;
    /**
     * Creates an async iterator that yields a canvas for each timestamp in the argument. This method uses an optimized
     * decoding pipeline if these timestamps are monotonically sorted, decoding each packet at most once, and is
     * therefore more efficient than manually getting the canvas for every timestamp. The iterator may yield null if
     * no frame is available for a given timestamp.
     *
     * @param timestamps - An iterable or async iterable of timestamps in seconds.
     */
    canvasesAtTimestamps(timestamps: AnyIterable<number>): AsyncGenerator<WrappedCanvas | null, void, unknown>;
}

/**
 * Options for constructing a CanvasSink.
 * @public
 */
export declare type CanvasSinkOptions = {
    /**
     * The width of the output canvas in pixels, defaulting to the display width of the video track. If height is not
     * set, it will be deduced automatically based on aspect ratio.
     */
    width?: number;
    /**
     * The height of the output canvas in pixels, defaulting to the display height of the video track. If width is not
     * set, it will be deduced automatically based on aspect ratio.
     */
    height?: number;
    /**
     * The fitting algorithm in case both width and height are set.
     *
     * - 'fill' will stretch the image to fill the entire box, potentially altering aspect ratio.
     * - 'contain' will contain the entire image within the box while preserving aspect ratio. This may lead to
     * letterboxing.
     * - 'cover' will scale the image until the entire box is filled, while preserving aspect ratio.
     */
    fit?: 'fill' | 'contain' | 'cover';
    /**
     * The clockwise rotation by which to rotate the raw video frame. Defaults to the rotation set in the file metadata.
     * Rotation is applied before resizing.
     */
    rotation?: Rotation;
    /**
     * When set, specifies the number of canvases in the pool. These canvases will be reused in a ring buffer /
     * round-robin type fashion. This keeps the amount of allocated VRAM constant and relieves the browser from
     * constantly allocating/deallocating canvases. A pool size of 0 or `undefined` disables the pool and means a new
     * canvas is created each time.
     */
    poolSize?: number;
};

/**
 * This source can be used to add video frames to the output track from a fixed canvas element. Since canvases are often
 * used for rendering, this source provides a convenient wrapper around VideoSampleSource.
 * @public
 */
export declare class CanvasSource extends VideoSource {
    constructor(canvas: HTMLCanvasElement | OffscreenCanvas, encodingConfig: VideoEncodingConfig);
    /**
     * Captures the current canvas state as a video sample (frame), encodes it and adds it to the output.
     *
     * @param timestamp - The timestamp of the sample, in seconds.
     * @param duration - The duration of the sample, in seconds.
     *
     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
     * to respect writer and encoder backpressure.
     */
    add(timestamp: number, duration?: number, encodeOptions?: VideoEncoderEncodeOptions): Promise<void>;
}

/**
 * Represents a media file conversion process, used to convert one media file into another. In addition to conversion,
 * this class can be used to resize and rotate video, resample audio, drop tracks, or trim to a specific time range.
 * @public
 */
export declare class Conversion {
    /** The input file. */
    readonly input: Input;
    /** The output file. */
    readonly output: Output;
    /**
     * A callback that is fired whenever the conversion progresses. Returns a number between 0 and 1, indicating the
     * completion of the conversion. Note that a progress of 1 doesn't necessarily mean the conversion is complete;
     * the conversion is complete once `execute` resolves.
     *
     * In order for progress to be computed, this property must be set before `execute` is called.
     */
    onProgress?: (progress: number) => unknown;
    /** The list of tracks that are included in the output file. */
    readonly utilizedTracks: InputTrack[];
    /** The list of tracks from the input file that have been discarded, alongside the discard reason. */
    readonly discardedTracks: {
        /** The track that was discarded. */
        track: InputTrack;
        /** The reason for discarding the track. */
        reason: 'discarded_by_user' | 'max_track_count_reached' | 'max_track_count_of_type_reached' | 'unknown_source_codec' | 'undecodable_source_codec' | 'no_encodable_target_codec';
    }[];
    /** Initializes a new conversion process without starting the conversion. */
    static init(options: ConversionOptions): Promise<Conversion>;
    private constructor();
    /** Executes the conversion process. Resolves once conversion is complete. */
    execute(): Promise<void>;
    /** Cancels the conversion process. Does nothing if the conversion is already complete. */
    cancel(): Promise<void>;
}

/**
 * Audio-specific options.
 * @public
 */
export declare type ConversionAudioOptions = {
    /** If true, all audio tracks will be discarded and will not be present in the output. */
    discard?: boolean;
    /** The desired channel count of the output audio. */
    numberOfChannels?: number;
    /** The desired sample rate of the output audio, in hertz. */
    sampleRate?: number;
    /** The desired output audio codec. */
    codec?: AudioCodec;
    /** The desired bitrate of the output audio. */
    bitrate?: AudioEncodingConfig['bitrate'];
    /** When true, audio will always be re-encoded instead of directly copying over the encoded samples. */
    forceTranscode?: boolean;
};

/**
 * The options for media file conversion.
 * @public
 */
export declare type ConversionOptions = {
    /** The input file. */
    input: Input;
    /** The output file. */
    output: Output;
    /**
     * Video-specific options. When passing an object, the same options are applied to all video tracks. When passing a
     * function, it will be invoked for each video track and is expected to return or resolve to the options
     * for that specific track. The function is passed an instance of `InputVideoTrack` as well as a number `n`, which
     * is the 1-based index of the track in the list of all video tracks.
     */
    video?: ConversionVideoOptions | ((track: InputVideoTrack, n: number) => MaybePromise<ConversionVideoOptions | undefined>);
    /**
     * Audio-specific options. When passing an object, the same options are applied to all audio tracks. When passing a
     * function, it will be invoked for each audio track and is expected to return or resolve to the options
     * for that specific track. The function is passed an instance of `InputAudioTrack` as well as a number `n`, which
     * is the 1-based index of the track in the list of all audio tracks.
     */
    audio?: ConversionAudioOptions | ((track: InputAudioTrack, n: number) => MaybePromise<ConversionAudioOptions | undefined>);
    /** Options to trim the input file. */
    trim?: {
        /** The time in the input file in seconds at which the output file should start. Must be less than `end`.  */
        start: number;
        /** The time in the input file in seconds at which the output file should end. Must be greater than `start`. */
        end: number;
    };
};

/**
 * Video-specific options.
 * @public
 */
export declare type ConversionVideoOptions = {
    /** If true, all video tracks will be discarded and will not be present in the output. */
    discard?: boolean;
    /**
     * The desired width of the output video in pixels, defaulting to the video's natural display width. If height
     * is not set, it will be deduced automatically based on aspect ratio.
     */
    width?: number;
    /**
     * The desired height of the output video in pixels, defaulting to the video's natural display height. If width
     * is not set, it will be deduced automatically based on aspect ratio.
     */
    height?: number;
    /**
     * The fitting algorithm in case both width and height are set.
     *
     * - 'fill' will stretch the image to fill the entire box, potentially altering aspect ratio.
     * - 'contain' will contain the entire image within the box while preserving aspect ratio. This may lead to
     * letterboxing.
     * - 'cover' will scale the image until the entire box is filled, while preserving aspect ratio.
     */
    fit?: 'fill' | 'contain' | 'cover';
    /**
     * The angle in degrees to rotate the input video by, clockwise. Rotation is applied before resizing. This
     * rotation is _in addition to_ the natural rotation of the input video as specified in input file's metadata.
     */
    rotate?: Rotation;
    /**
     * The desired frame rate of the output video, in hertz. If not specified, the original input frame rate will
     * be used (which may be variable).
     */
    frameRate?: number;
    /** The desired output video codec. */
    codec?: VideoCodec;
    /** The desired bitrate of the output video. */
    bitrate?: VideoEncodingConfig['bitrate'];
    /** When true, video will always be re-encoded instead of directly copying over the encoded samples. */
    forceTranscode?: boolean;
};

/**
 * Base class for custom audio decoders. To add your own custom audio decoder, extend this class, implement the
 * abstract methods and static `supports` method, and register the decoder using `registerDecoder`.
 * @public
 */
export declare abstract class CustomAudioDecoder {
    /** The input audio's codec. */
    readonly codec: AudioCodec;
    /** The input audio's decoder config. */
    readonly config: AudioDecoderConfig;
    /** The callback to call when a decoded AudioSample is available. */
    readonly onSample: (sample: AudioSample) => unknown;
    /** Returns true iff the decoder can decode the given codec configuration. */
    static supports(codec: AudioCodec, config: AudioDecoderConfig): boolean;
    /** Called after decoder creation; can be used for custom initialization logic. */
    abstract init(): Promise<void> | void;
    /** Decodes the provided encoded packet. */
    abstract decode(packet: EncodedPacket): Promise<void> | void;
    /** Decodes all remaining packets and then resolves. */
    abstract flush(): Promise<void> | void;
    /** Called when the decoder is no longer needed and its resources can be freed. */
    abstract close(): Promise<void> | void;
}

/**
 * Base class for custom audio encoders. To add your own custom audio encoder, extend this class, implement the
 * abstract methods and static `supports` method, and register the encoder using `registerEncoder`.
 * @public
 */
export declare abstract class CustomAudioEncoder {
    /** The codec with which to encode the audio. */
    readonly codec: AudioCodec;
    /** Config for the encoder. */
    readonly config: AudioEncoderConfig;
    /** The callback to call when an EncodedPacket is available. */
    readonly onPacket: (packet: EncodedPacket, meta?: EncodedAudioChunkMetadata) => unknown;
    /** Returns true iff the encoder can encode the given codec configuration. */
    static supports(codec: AudioCodec, config: AudioEncoderConfig): boolean;
    /** Called after encoder creation; can be used for custom initialization logic. */
    abstract init(): Promise<void> | void;
    /** Encodes the provided audio sample. */
    abstract encode(audioSample: AudioSample): Promise<void> | void;
    /** Encodes all remaining audio samples and then resolves. */
    abstract flush(): Promise<void> | void;
    /** Called when the encoder is no longer needed and its resources can be freed. */
    abstract close(): Promise<void> | void;
}

/**
 * Base class for custom video decoders. To add your own custom video decoder, extend this class, implement the
 * abstract methods and static `supports` method, and register the decoder using `registerDecoder`.
 * @public
 */
export declare abstract class CustomVideoDecoder {
    /** The input video's codec. */
    readonly codec: VideoCodec;
    /** The input video's decoder config. */
    readonly config: VideoDecoderConfig;
    /** The callback to call when a decoded VideoSample is available. */
    readonly onSample: (sample: VideoSample) => unknown;
    /** Returns true iff the decoder can decode the given codec configuration. */
    static supports(codec: VideoCodec, config: VideoDecoderConfig): boolean;
    /** Called after decoder creation; can be used for custom initialization logic. */
    abstract init(): Promise<void> | void;
    /** Decodes the provided encoded packet. */
    abstract decode(packet: EncodedPacket): Promise<void> | void;
    /** Decodes all remaining packets and then resolves. */
    abstract flush(): Promise<void> | void;
    /** Called when the decoder is no longer needed and its resources can be freed. */
    abstract close(): Promise<void> | void;
}

/**
 * Base class for custom video encoders. To add your own custom video encoder, extend this class, implement the
 * abstract methods and static `supports` method, and register the encoder using `registerEncoder`.
 * @public
 */
export declare abstract class CustomVideoEncoder {
    /** The codec with which to encode the video. */
    readonly codec: VideoCodec;
    /** Config for the encoder. */
    readonly config: VideoEncoderConfig;
    /** The callback to call when an EncodedPacket is available. */
    readonly onPacket: (packet: EncodedPacket, meta?: EncodedVideoChunkMetadata) => unknown;
    /** Returns true iff the encoder can encode the given codec configuration. */
    static supports(codec: VideoCodec, config: VideoEncoderConfig): boolean;
    /** Called after encoder creation; can be used for custom initialization logic. */
    abstract init(): Promise<void> | void;
    /** Encodes the provided video sample. */
    abstract encode(videoSample: VideoSample, options: VideoEncoderEncodeOptions): Promise<void> | void;
    /** Encodes all remaining video samples and then resolves. */
    abstract flush(): Promise<void> | void;
    /** Called when the encoder is no longer needed and its resources can be freed. */
    abstract close(): Promise<void> | void;
}

/**
 * The most basic audio source; can be used to directly pipe encoded packets into the output file.
 * @public
 */
export declare class EncodedAudioPacketSource extends AudioSource {
    constructor(codec: AudioCodec);
    /**
     * Adds an encoded packet to the output audio track. Packets must be added in *decode order*.
     *
     * @param meta - Additional metadata from the encoder. You should pass this for the first call, including a valid
     * decoder config.
     *
     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
     * to respect writer and encoder backpressure.
     */
    add(packet: EncodedPacket, meta?: EncodedAudioChunkMetadata): Promise<void>;
}

/**
 * Represents an encoded chunk of media. Mainly used as an expressive wrapper around WebCodecs API's EncodedVideoChunk
 * and EncodedAudioChunk, but can also be used standalone.
 * @public
 */
export declare class EncodedPacket {
    /** The encoded data of this packet. */
    readonly data: Uint8Array;
    /** The type of this packet. */
    readonly type: PacketType;
    /**
     * The presentation timestamp of this packet in seconds. May be negative. Samples with negative end timestamps
     * should not be presented.
     */
    readonly timestamp: number;
    /** The duration of this packet in seconds. */
    readonly duration: number;
    /**
     * The sequence number indicates the decode order of the packets. Packet A  must be decoded before packet B if A
     * has a lower sequence number than B. If two packets have the same sequence number, they are the same packet.
     * Otherwise, sequence numbers are arbitrary and are not guaranteed to have any meaning besides their relative
     * ordering. Negative sequence numbers mean the sequence number is undefined.
     */
    readonly sequenceNumber: number;
    /**
     * The actual byte length of the data in this packet. This field is useful for metadata-only packets where the
     * `data` field contains no bytes.
     */
    readonly byteLength: number;
    constructor(
    /** The encoded data of this packet. */
    data: Uint8Array, 
    /** The type of this packet. */
    type: PacketType, 
    /**
     * The presentation timestamp of this packet in seconds. May be negative. Samples with negative end timestamps
     * should not be presented.
     */
    timestamp: number, 
    /** The duration of this packet in seconds. */
    duration: number, 
    /**
     * The sequence number indicates the decode order of the packets. Packet A  must be decoded before packet B if A
     * has a lower sequence number than B. If two packets have the same sequence number, they are the same packet.
     * Otherwise, sequence numbers are arbitrary and are not guaranteed to have any meaning besides their relative
     * ordering. Negative sequence numbers mean the sequence number is undefined.
     */
    sequenceNumber?: number, byteLength?: number);
    /** If this packet is a metadata-only packet. Metadata-only packets don't contain their packet data. */
    get isMetadataOnly(): boolean;
    /** The timestamp of this packet in microseconds. */
    get microsecondTimestamp(): number;
    /** The duration of this packet in microseconds. */
    get microsecondDuration(): number;
    /** Converts this packet to an EncodedVideoChunk for use with the WebCodecs API. */
    toEncodedVideoChunk(): EncodedVideoChunk;
    /** Converts this packet to an EncodedAudioChunk for use with the WebCodecs API. */
    toEncodedAudioChunk(): EncodedAudioChunk;
    /**
     * Creates an EncodedPacket from an EncodedVideoChunk or EncodedAudioChunk. This method is useful for converting
     * chunks from the WebCodecs API to EncodedPackets.
     */
    static fromEncodedChunk(chunk: EncodedVideoChunk | EncodedAudioChunk): EncodedPacket;
    /** Clones this packet while optionally updating timing information. */
    clone(options?: {
        /** The timestamp of the cloned packet in seconds. */
        timestamp?: number;
        /** The duration of the cloned packet in seconds. */
        duration?: number;
    }): EncodedPacket;
}

/**
 * Sink for retrieving encoded packets from an input track.
 * @public
 */
export declare class EncodedPacketSink {
    constructor(track: InputTrack);
    /**
     * Retrieves the track's first packet (in decode order), or null if it has no packets. The first packet is very
     * likely to be a key packet.
     */
    getFirstPacket(options?: PacketRetrievalOptions): Promise<EncodedPacket | null>;
    /**
     * Retrieves the packet corresponding to the given timestamp, in seconds. More specifically, returns the last packet
     * (in presentation order) with a start timestamp less than or equal to the given timestamp. This method can be
     * used to retrieve a track's last packet using `getPacket(Infinity)`. The method returns null if the timestamp
     * is before the first packet in the track.
     *
     * @param timestamp - The timestamp used for retrieval, in seconds.
     */
    getPacket(timestamp: number, options?: PacketRetrievalOptions): Promise<EncodedPacket | null>;
    /**
     * Retrieves the packet following the given packet (in decode order), or null if the given packet is the
     * last packet.
     */
    getNextPacket(packet: EncodedPacket, options?: PacketRetrievalOptions): Promise<EncodedPacket | null>;
    /**
     * Retrieves the key packet corresponding to the given timestamp, in seconds. More specifically, returns the last
     * key packet (in presentation order) with a start timestamp less than or equal to the given timestamp. A key packet
     * is a packet that doesn't require previous packets to be decoded. This method can be used to retrieve a track's
     * last key packet using `getKeyPacket(Infinity)`. The method returns null if the timestamp is before the first
     * key packet in the track.
     *
     * To ensure that the returned packet is guaranteed to be a real key frame, enable `options.verifyKeyPackets`.
     *
     * @param timestamp - The timestamp used for retrieval, in seconds.
     */
    getKeyPacket(timestamp: number, options?: PacketRetrievalOptions): Promise<EncodedPacket | null>;
    /**
     * Retrieves the key packet following the given packet (in decode order), or null if the given packet is the last
     * key packet.
     *
     * To ensure that the returned packet is guaranteed to be a real key frame, enable `options.verifyKeyPackets`.
     */
    getNextKeyPacket(packet: EncodedPacket, options?: PacketRetrievalOptions): Promise<EncodedPacket | null>;
    /**
     * Creates an async iterator that yields the packets in this track in decode order. To enable fast iteration, this
     * method will intelligently preload packets based on the speed of the consumer.
     *
     * @param startPacket - (optional) The packet from which iteration should begin. This packet will also be yielded.
     * @param endTimestamp - (optional) The timestamp at which iteration should end. This packet will _not_ be yielded.
     */
    packets(startPacket?: EncodedPacket, endPacket?: EncodedPacket, options?: PacketRetrievalOptions): AsyncGenerator<EncodedPacket, void, unknown>;
}

/**
 * The most basic video source; can be used to directly pipe encoded packets into the output file.
 * @public
 */
export declare class EncodedVideoPacketSource extends VideoSource {
    constructor(codec: VideoCodec);
    /**
     * Adds an encoded packet to the output video track. Packets must be added in *decode order*, while a packet's
     * timestamp must be its *presentation timestamp*. B-frames are handled automatically.
     *
     * @param meta - Additional metadata from the encoder. You should pass this for the first call, including a valid
     * decoder config.
     *
     * @returns A Promise that resolves once the output is ready to receive more samples. You should await this Promise
     * to respect writer and encoder backpressure.
     */
    add(packet: EncodedPacket, meta?: EncodedVideoChunkMetadata): Promise<void>;
}

/**
 * Returns the list of all audio codecs that can be encoded by the browser.
 * @public
 */
export declare const getEncodableAudioCodecs: (checkedCodecs?: AudioCodec[], options?: {
    numberOfChannels?: number;
    sampleRate?: number;
    bitrate?: number | Quality;
}) => Promise<AudioCodec[]>;

/**
 * Returns the list of all media codecs that can be encoded by the browser.
 * @public
 */
export declare const getEncodableCodecs: () => Promise<MediaCodec[]>;

/**
 * Returns the list of all subtitle codecs that can be encoded by the browser.
 * @public
 */
export declare const getEncodableSubtitleCodecs: (checkedCodecs?: SubtitleCodec[]) => Promise<SubtitleCodec[]>;

/**
 * Returns the list of all video codecs that can be encoded by the browser.
 * @public
 */
export declare const getEncodableVideoCodecs: (checkedCodecs?: VideoCodec[], options?: {
    width?: number;
    height?: number;
    bitrate?: number | Quality;
}) => Promise<VideoCodec[]>;

/**
 * Returns the first audio codec from the given list that can be encoded by the browser.
 * @public
 */
export declare const getFirstEncodableAudioCodec: (checkedCodecs: AudioCodec[], options?: {
    numberOfChannels?: number;
    sampleRate?: number;
    bitrate?: number | Quality;
}) => Promise<AudioCodec | null>;

/**
 * Returns the first subtitle codec from the given list that can be encoded by the browser.
 * @public
 */
export declare const getFirstEncodableSubtitleCodec: (checkedCodecs: SubtitleCodec[]) => Promise<SubtitleCodec | null>;

/**
 * Returns the first video codec from the given list that can be encoded by the browser.
 * @public
 */
export declare const getFirstEncodableVideoCodec: (checkedCodecs: VideoCodec[], options?: {
    width?: number;
    height?: number;
    bitrate?: number | Quality;
}) => Promise<VideoCodec | null>;

/**
 * Specifies an inclusive range of integers.
 * @public
 */
export declare type InclusiveIntegerRange = {
    /** The integer cannot be less than this. */
    min: number;
    /** The integer cannot be greater than this. */
    max: number;
};

/**
 * Represents an input media file. This is the root object from which all media read operations start.
 * @public
 */
export declare class Input<S extends Source = Source> {
    constructor(options: InputOptions<S>);
    /**
     * Returns the source from which this input file reads its data. This is the same source that was passed to the
     * constructor.
     */
    get source(): S;
    /**
     * Returns the format of the input file. You can compare this result directly to the InputFormat singletons or use
     * `instanceof` checks for subset-aware logic (for example, `format instanceof MatroskaInputFormat` is true for
     * both MKV and WebM).
     */
    getFormat(): Promise<InputFormat>;
    /**
     * Computes the duration of the input file, in seconds. More precisely, returns the largest end timestamp among
     * all tracks.
     */
    computeDuration(): Promise<number>;
    /** Returns the list of all tracks of this input file. */
    getTracks(): Promise<InputTrack[]>;
    /** Returns the list of all video tracks of this input file. */
    getVideoTracks(): Promise<InputVideoTrack[]>;
    /** Returns the primary video track of this input file, or null if there are no video tracks. */
    getPrimaryVideoTrack(): Promise<InputVideoTrack | null>;
    /** Returns the list of all audio tracks of this input file. */
    getAudioTracks(): Promise<InputAudioTrack[]>;
    /** Returns the primary audio track of this input file, or null if there are no audio tracks. */
    getPrimaryAudioTrack(): Promise<InputAudioTrack | null>;
    /** Returns the full MIME type of this input file, including track codecs. */
    getMimeType(): Promise<string>;
}

/**
 * Represents an audio track in an input file.
 * @public
 */
export declare class InputAudioTrack extends InputTrack {
    get type(): TrackType;
    get codec(): AudioCodec | null;
    /** The number of audio channels in the track. */
    get numberOfChannels(): number;
    /** The track's audio sample rate in hertz. */
    get sampleRate(): number;
    /**
     * Returns the decoder configuration for decoding the track's packets using an AudioDecoder. Returns null if the
     * track's codec is unknown.
     */
    getDecoderConfig(): Promise<AudioDecoderConfig | null>;
    getCodecParameterString(): Promise<string | null>;
    canDecode(): Promise<boolean>;
    determinePacketType(packet: EncodedPacket): Promise<PacketType | null>;
}

/**
 * Base class representing an input media file format.
 * @public
 */
export declare abstract class InputFormat {
    /** Returns the name of the input format. */
    abstract get name(): string;
    /** Returns the typical base MIME type of the input format. */
    abstract get mimeType(): string;
}

/**
 * The options for creating an Input object.
 * @public
 */
export declare type InputOptions<S extends Source = Source> = {
    /** A list of supported formats. If the source file is not of one of these formats, then it cannot be read. */
    formats: InputFormat[];
    /** The source from which data will be read. */
    source: S;
};

/**
 * Represents a media track in an input file.
 * @public
 */
export declare abstract class InputTrack {
    /** The type of the track. */
    abstract get type(): TrackType;
    /** The codec of the track's packets. */
    abstract get codec(): MediaCodec | null;
    /** Returns the full codec parameter string for this track. */
    abstract getCodecParameterString(): Promise<string | null>;
    /** Checks if this track's packets can be decoded by the browser. */
    abstract canDecode(): Promise<boolean>;
    /**
     * For a given packet of this track, this method determines the actual type of this packet (key/delta) by looking
     * into its bitstream. Returns null if the type couldn't be determined.
     */
    abstract determinePacketType(packet: EncodedPacket): Promise<PacketType | null>;
    /** Returns true iff this track is a video track. */
    isVideoTrack(): this is InputVideoTrack;
    /** Returns true iff this track is an audio track. */
    isAudioTrack(): this is InputAudioTrack;
    /** The unique ID of this track in the input file. */
    get id(): number;
    /** The ISO 639-2/T language code for this track. If the language is unknown, this field is 'und' (undetermined). */
    get languageCode(): string;
    /**
     * A positive number x such that all timestamps and durations of all packets of this track are
     * integer multiples of 1/x.
     */
    get timeResolution(): number;
    /**
     * Returns the start timestamp of the first packet of this track, in seconds. While often near zero, this value
     * may be positive or even negative. A negative starting timestamp means the track's timing has been offset. Samples
     * with a negative timestamp should not be presented.
     */
    getFirstTimestamp(): Promise<number>;
    /** Returns the end timestamp of the last packet of this track, in seconds. */
    computeDuration(): Promise<number>;
    /**
     * Computes aggregate packet statistics for this track, such as average packet rate or bitrate.
     *
     * @param targetPacketCount - This optional parameter sets a target for how many packets this method must have
     * looked at before it can return early; this means, you can use it to aggregate only a subset (prefix) of all
     * packets. This is very useful for getting a great estimate of video frame rate without having to scan through the
     * entire file.
     */
    computePacketStats(targetPacketCount?: number): Promise<PacketStats>;
}

/**
 * Represents a video track in an input file.
 * @public
 */
export declare class InputVideoTrack extends InputTrack {
    get type(): TrackType;
    get codec(): "avc" | "hevc" | "vp9" | "av1" | "vp8" | null;
    /** The width in pixels of the track's coded samples, before any transformations or rotations. */
    get codedWidth(): number;
    /** The height in pixels of the track's coded samples, before any transformations or rotations. */
    get codedHeight(): number;
    /** The angle in degrees by which the track's frames should be rotated (clockwise). */
    get rotation(): Rotation;
    /** The width in pixels of the track's frames after rotation. */
    get displayWidth(): number;
    /** The height in pixels of the track's frames after rotation. */
    get displayHeight(): number;
    /** Returns the color space of the track's samples. */
    getColorSpace(): Promise<VideoColorSpaceInit>;
    /** If this method returns true, the track's samples use a high dynamic range (HDR). */
    hasHighDynamicRange(): Promise<boolean>;
    /**
     * Returns the decoder configuration for decoding the track's packets using a VideoDecoder. Returns null if the
     * track's codec is unknown.
     */
    getDecoderConfig(): Promise<VideoDecoderConfig | null>;
    getCodecParameterString(): Promise<string | null>;
    canDecode(): Promise<boolean>;
    determinePacketType(packet: EncodedPacket): Promise<PacketType | null>;
}

/**
 * Format representing files compatible with the ISO base media file format (ISOBMFF), like MP4 or MOV files.
 * @public
 */
export declare abstract class IsobmffInputFormat extends InputFormat {
}

/**
 * Format representing files compatible with the ISO base media file format (ISOBMFF), like MP4 or MOV files.
 * @public
 */
export declare abstract class IsobmffOutputFormat extends OutputFormat {
    constructor(options?: IsobmffOutputFormatOptions);
    getSupportedTrackCounts(): TrackCountLimits;
    get supportsVideoRotationMetadata(): boolean;
}

/**
 * ISOBMFF-specific output options.
 * @public
 */
export declare type IsobmffOutputFormatOptions = {
    /**
     * Controls the placement of metadata in the file. Placing metadata at the start of the file is known as "Fast
     * Start", which results in better playback at the cost of more required processing or memory.
     *
     * Use `false` to disable Fast Start, placing the metadata at the end of the file. Fastest and uses the least
     * memory.
     *
     * Use `'in-memory'` to produce a file with Fast Start by keeping all media chunks in memory until the file is
     * finalized. This produces a high-quality and compact output at the cost of a more expensive finalization step and
     * higher memory requirements. Data will be written monotonically (in order) when this option is set.
     *
     * Use `'fragmented'` to place metadata at the start of the file by creating a fragmented file (fMP4). In a
     * fragmented file, chunks of media and their metadata are written to the file in "fragments", eliminating the need
     * to put all metadata in one place. Fragmented files are useful for streaming contexts, as each fragment can be
     * played individually without requiring knowledge of the other fragments. Furthermore, they remain lightweight to
     * create even for very large files, as they don't require all media to be kept in memory. However, fragmented files
     * are not as widely and wholly supported as regular MP4/MOV files. Data will be written monotonically (in order)
     * when this option is set.
     *
     * When this field is not defined, either `false` or `'in-memory'` will be used, automatically determined based on
     * the type of output target used.
     */
    fastStart?: false | 'in-memory' | 'fragmented';
    /**
     * When using `fastStart: 'fragmented'`, this field controls the minimum duration of each fragment, in seconds.
     * New fragments will only be created when the current fragment is longer than this value. Defaults to 1 second.
     */
    minimumFragmentDuration?: number;
    /**
     * Will be called once the ftyp (File Type) box of the output file has been written.
     *
     * @param data - The raw bytes.
     * @param position - The byte offset of the data in the file.
     */
    onFtyp?: (data: Uint8Array, position: number) => unknown;
    /**
     * Will be called once the moov (Movie) box of the output file has been written.
     *
     * @param data - The raw bytes.
     * @param position - The byte offset of the data in the file.
     */
    onMoov?: (data: Uint8Array, position: number) => unknown;
    /**
     * Will be called for each finalized mdat (Media Data) box of the output file. Usage of this callback is not
     * recommended when not using `fastStart: 'fragmented'`, as there will be one monolithic mdat box which might
     * r