isobmff-inspector
Version:
Simple ISOBMFF parser, compatible with JavaScript and Node.JS
265 lines • 10.6 kB
TypeScript
/**
* Create a field-aware box reader.
*
* The idea is to instanciate the `BoxReader` with a buffer that is already
* bounded to a box's content start (after its size and name) and ending at its
* content's end.
*
* The `BoxReader` has methods allowing to define the fields of the current box
* or just to parse the next N bytes into the wanted format.
*
* The BoxReader is generic over the struct associated to a box's data. Methods
* properly typecheck that added fields respect that type.
*
* @template {{ [k: string]: unknown }} T
*/
export default class BoxReader<T extends {
[k: string]: unknown;
}> {
/**
* @param {Uint8Array} buffer
* @param {number=} baseOffset
*/
constructor(buffer: Uint8Array, baseOffset?: number | undefined);
/**
* Get the number of bytes that are not yet read.
* @returns {number}
*/
getRemainingLength(): number;
/**
* If `true`, the current box is already fully parsed.
* @returns {boolean}
*/
isFinished(): boolean;
/**
* Returns the total length of the current box in bytes.
* @returns {number}
*/
getTotalLength(): number;
/**
* Returns the current byte position in the box payload.
* @returns {number}
*/
getCurrentOffset(): number;
/**
* Read the next `nbBytes` bytes, convert it into the corresponding
* unsigned integer and store it as a field named `key` for the current box.
*
* Throws if less that `nbBytes` bytes remain in the current box.
*
* Throws if 8 bytes or more is read. If you need to read 8 bytes, use
* `fieldUint64` (which creates a bigint).
*
* @template {NumberKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {number}
*/
fieldUint<K extends NumberKeys<T>>(key: K, nbBytes: number, meta?: string | ParsedBoxFieldMetadata): number;
/**
* Read the next 8 bytes, convert it into the corresponding
* unsigned bigint and store it as a field named `key` for the current box.
*
* Throws if less that 8 bytes remain in the current box.
*
* @template {BigIntKeys<T>} K
* @param {K} key
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {bigint}
*/
fieldUint64<K extends BigIntKeys<T>>(key: K, meta?: string | ParsedBoxFieldMetadata): bigint;
/**
* Read the next 8 bytes, convert it into the corresponding
* **signed** bigint and store it as a field named `key` for the current box.
*
* Throws if less that 8 bytes remain in the current box.
*
* @template {BigIntKeys<T>} K
* @param {K} key
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {bigint}
*/
fieldInt64<K extends BigIntKeys<T>>(key: K, meta?: string | ParsedBoxFieldMetadata): bigint;
/**
* @template {NumberKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {number}
*/
fieldSignedInt<K extends NumberKeys<T>>(key: K, nbBytes: number, meta?: string | ParsedBoxFieldMetadata): number;
/**
* @template {BytesKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {Uint8Array}
*/
fieldBytes<K extends BytesKeys<T>>(key: K, nbBytes: number, meta?: string | ParsedBoxFieldMetadata): Uint8Array;
/**
* @template {StringKeys<T>} K
* @param {K} key
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {string}
*/
fieldNullTerminatedAscii<K extends StringKeys<T>>(key: K, meta?: string | ParsedBoxFieldMetadata): string;
/**
* @template {StringKeys<T>} K
* @param {K} key
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {string}
*/
fieldNullTerminatedUtf8<K extends StringKeys<T>>(key: K, meta?: string | ParsedBoxFieldMetadata): string;
/**
* Decode the next 4 bytes into a string if printable ASCII, or the
* corresponding 32 bit integer if not, and set it as a field named
* `key` on the current box.
*
* Throws if less than 4 are remaining in the buffer.
*
* @template {StringKeys<T>} K
* @param {K} key
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {string|number}
*/
fieldFourCc<K extends StringKeys<T>>(key: K, meta?: string | ParsedBoxFieldMetadata): string | number;
/**
* @template {FixedPointKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {number} fractionalBits
* @param {string} format
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {import("./types.js").ParsedFixedPointField}
*/
fieldFixedPoint<K extends FixedPointKeys<T>>(key: K, nbBytes: number, fractionalBits: number, format: string, meta?: string | ParsedBoxFieldMetadata): import("./types.js").ParsedFixedPointField;
/**
* @template {FixedPointKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {number} bits
* @param {number} fractionalBits
* @param {string} format
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {import("./types.js").ParsedFixedPointField}
*/
fieldSignedFixedPoint<K extends FixedPointKeys<T>>(key: K, nbBytes: number, bits: number, fractionalBits: number, format: string, meta?: string | ParsedBoxFieldMetadata): import("./types.js").ParsedFixedPointField;
/**
* @template {DateKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {import("./types.js").ParsedDateField}
*/
fieldMacDate<K extends DateKeys<T>>(key: K, nbBytes: number, meta?: string | ParsedBoxFieldMetadata): import("./types.js").ParsedDateField;
/**
* @template {BitsKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {import("./types.js").ParsedBitsFieldPartDefinition[]} parts
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {number}
*/
fieldBits<K extends BitsKeys<T>>(key: K, nbBytes: number, parts: import("./types.js").ParsedBitsFieldPartDefinition[], meta?: string | ParsedBoxFieldMetadata): number;
/**
* @template {FlagsKeys<T>} K
* @param {K} key
* @param {number} nbBytes
* @param {Record<string, number>} flags
* @param {string|ParsedBoxFieldMetadata} [meta]
* @returns {number}
*/
fieldFlags<K extends FlagsKeys<T>>(key: K, nbBytes: number, flags: Record<string, number>, meta?: string | ParsedBoxFieldMetadata): number;
/**
* @template V
* @template {KeysForValue<T, V>} K
* @param {K} key
* @param {V} value
* @param {string | ParsedBoxFieldMetadata=} [meta]
* @returns {V}
*/
addField<V, K extends KeysForValue<T, V>>(key: K, value: V, meta?: (string | ParsedBoxFieldMetadata) | undefined): V;
/**
* @param {"warning" | "error"} severity
* @param {string} message
* @returns {void}
*/
addIssue(severity: "warning" | "error", message: string): void;
/**
* Read the next `nbBytes` bytes and returns the corresponding
* unsigned integer.
*
* Throws if less that `nbBytes` bytes remain in the current box.
*
* Throws if 8 bytes or more is read. If you need to read 8 bytes, use
* `fieldUint64` (which creates a bigint).
* @param {number} nbBytes
* @returns {number}
*/
readUint(nbBytes: number): number;
/**
* Read the next 8 bytes and returns the corresponding bigint.
*
* Throws if less that 8 bytes remain in the current box.
*
* @returns {bigint}
*/
readUint64(): bigint;
/**
* Parse the next 4 bytes as a **signed** (two's complement) 64-bit integer
* into a bigint.
*
* Throws if less than 8 bytes are remaining in the buffer.
*
* @returns {bigint}
*/
readInt64(): bigint;
/**
* Read the next bytes and return it as an Uint8Array.
*
* Throws if less than `nbBytes` bytes are remaining in the buffer.
*
* @param {number} nbBytes
* @returns {Uint8Array}
*/
readBytes(nbBytes: number): Uint8Array;
/**
* Decode the next `nbBytes` as UTF-8 text.
*
* Throws if less than `nbBytes` bytes are remaining in the buffer.
*
* @param {number} nbBytes
* @returns {string}
*/
readAsUtf8(nbBytes: number): string;
/**
* Decode the next 4 bytes into a string if printable ASCII, or the
* corresponding 32 bit integer if not.
*
* Throws if less than 4 are remaining in the buffer.
*
* @returns {string|number}
*/
readFourCc(): string | number;
/** @returns {import("./types.js").ParsedBoxValue[]} */
getValues(): import("./types.js").ParsedBoxValue[];
/** @returns {import("./types.js").ParsedBoxIssue[]} */
getIssues(): import("./types.js").ParsedBoxIssue[];
#private;
}
export type ParsedBoxFieldMetadata = {
description?: string | undefined;
offset?: number | undefined;
byteLength?: number | undefined;
};
export type KeysForValue<T, V> = { [K in Extract<keyof T, string>]: V extends T[K] ? K : never; }[Extract<keyof T, string>];
export type NumberKeys<T> = { [K in Extract<keyof T, string>]: number extends T[K] ? K : never; }[Extract<keyof T, string>];
export type BigIntKeys<T> = { [K in Extract<keyof T, string>]: bigint extends T[K] ? K : never; }[Extract<keyof T, string>];
export type StringKeys<T> = { [K in Extract<keyof T, string>]: string extends T[K] ? K : never; }[Extract<keyof T, string>];
export type BytesKeys<T> = { [K in Extract<keyof T, string>]: Uint8Array extends T[K] ? K : never; }[Extract<keyof T, string>];
export type FixedPointKeys<T> = { [K in Extract<keyof T, string>]: import("./types.js").ParsedFixedPointField extends T[K] ? K : never; }[Extract<keyof T, string>];
export type DateKeys<T> = { [K in Extract<keyof T, string>]: import("./types.js").ParsedDateField extends T[K] ? K : never; }[Extract<keyof T, string>];
export type BitsKeys<T> = { [K in Extract<keyof T, string>]: import("./types.js").ParsedBitsField extends T[K] ? K : never; }[Extract<keyof T, string>];
export type FlagsKeys<T> = { [K in Extract<keyof T, string>]: import("./types.js").ParsedFlagsField extends T[K] ? K : never; }[Extract<keyof T, string>];
//# sourceMappingURL=BoxReader.d.ts.map