Class

Input

Represents input media, backed by a single file or multiple files depending on the format.

This is the root object from which all media read operations start.

Extends: EventEmitter

Implements: Disposable

Used by

• Conversion.input
• ConversionOptions.input
• InputAudioTrack.input
• InputOptions.initInput
• InputTrack.input
• InputVideoTrack.input

Type parameters

Input<
	S extends Source = Source,
>

See Source.

Constructor

constructor(
	options: InputOptions<S>,
): Input;

Creates a new input file from the specified options. No reading operations will be performed until methods are called on this instance.

See InputOptions.

Properties

disposed

get disposed(): boolean;

True if the input has been disposed.

source

get source(): S;

Returns the source from which this input file reads data for the root path.

Methods

canRead()

canRead(): Promise<boolean>;

Returns true if the format of the input file is known and the file can be read, false otherwise.

computeDuration()

computeDuration(
	tracks?: InputTrack[],
	options?: PacketRetrievalOptions,
): Promise<number>;

Computes the duration of the input file, in seconds. More precisely, returns the largest end timestamp among all tracks.

Optionally, you can pass in the list of tracks for which you want to compute the duration.

This method can be potentially expensive depending on the underlying file format, because it returns the most accurate duration possible and must check all tracks. Use getDurationFromMetadata for a faster but less accurate estimate of duration.

By default, when any track in the underlying media is live, this method will only resolve once the live stream ends. If you want to query the current duration of the media, set PacketRetrievalOptions.skipLiveWait to true in the options.

See InputTrack.

dispose()

dispose(): void;

Disposes this input and frees connected resources. When an input is disposed, ongoing read operations will be canceled, all future read operations will fail, any open decoders will be closed, and all ongoing media sink operations will be canceled. Disallowed and canceled operations will throw an InputDisposedError.

You are expected not to use an input after disposing it. While some operations may still work, it is not specified and may change in any future update.

getAudioTracks()

getAudioTracks(
	query?: InputTrackQuery<InputAudioTrack>,
): Promise<InputAudioTrack[]>;

Returns the list of all audio tracks of this input file. An optional query can be provided.

See InputTrackQuery and InputAudioTrack.

getDurationFromMetadata()

getDurationFromMetadata(
	tracks?: InputTrack[],
	options?: DurationMetadataRequestOptions,
): Promise<number | null>;

Gets the duration (end timestamp) in seconds of the input file from metadata stored in the file. This value may be approximate or diverge from the actual, precise duration returned by .computeDuration(), but compared to that method, this method is cheaper. When the duration cannot be determined from the file metadata, null is returned.

Optionally, you can pass in the list of tracks for which you want to get the duration from metadata.

By default, when the underlying media is live, this method will only resolve once the live stream ends. If you want to query the current duration of the media, set DurationMetadataRequestOptions.skipLiveWait to true in the options.

See InputTrack.

getFirstTimestamp()

getFirstTimestamp(
	tracks?: InputTrack[],
): Promise<number>;

Returns the timestamp at which the input file starts. More precisely, returns the smallest starting timestamp among all tracks.

Optionally, you can pass in the list of tracks for which you want to compute the starting timestamp.

Note that this method is potentially expensive for inputs with many tracks (such as HLS manifests), since it probes every track.

See InputTrack.

getFormat()

getFormat(): Promise<InputFormat>;

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).

getMetadataTags()

getMetadataTags(): Promise<MetadataTags>;

Returns descriptive metadata tags about the media file, such as title, author, date, cover art, or other attached files.

See MetadataTags.

getMimeType()

getMimeType(): Promise<string>;

Returns the full MIME type of this input file, including track codecs.

getPrimaryAudioTrack()

getPrimaryAudioTrack(
	query?: InputTrackQuery<InputAudioTrack>,
): Promise<InputAudioTrack | null>;

Returns the primary audio track of this input file, or null if there are no audio tracks.

Multiple factors determine which track is considered primary, including its position in the file, disposition, bitrate (higher bitrate is preferred), and if it can be paired with the primary video track.

See InputTrackQuery and InputAudioTrack.

getPrimaryVideoTrack()

getPrimaryVideoTrack(
	query?: InputTrackQuery<InputVideoTrack>,
): Promise<InputVideoTrack | null>;

Returns the primary video track of this input file, or null if there are no video tracks.

Multiple factors determine which track is considered primary, including its position in the file, disposition, bitrate (higher bitrate is preferred), and if it can be paired with an audio track.

See InputTrackQuery and InputVideoTrack.

getTracks()

getTracks(
	query?: InputTrackQuery<InputTrack>,
): Promise<InputTrack[]>;

Returns the list of all tracks of this input file in the order in which they appear in the file. An optional query can be provided.

See InputTrackQuery and InputTrack.

getVideoTracks()

getVideoTracks(
	query?: InputTrackQuery<InputVideoTrack>,
): Promise<InputVideoTrack[]>;

Returns the list of all video tracks of this input file. An optional query can be provided.

See InputTrackQuery and InputVideoTrack.

on()

on(
	event: K,
	listener: (data: TEvents[K]) => unknown,
	options?: EventListenerOptions,
): () => void;

Registers a listener for the given event.

See EventListenerOptions.

[Symbol.dispose]()

[Symbol.dispose](): void;

Calls .dispose() on the input, implementing the Disposable interface for use with JavaScript Explicit Resource Management features.