@amazon/vinyl-util 3.0.1 → 3.2.0

package/dist/types/current/util/webm/parseWebm.js

@@ -0,0 +1,166 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ValidationError } from '../../error/ValidationError';
+import { ErrorOrigin } from '../../error/ErrorOrigin';
+/**
+ * A minimal EBML/Matroska (WebM) parser: just enough to index a DASH
+ * `SegmentBase` WebM stream — the `Segment` data offset and `TimecodeScale`
+ * from the initialization segment, and the `CuePoint`s from the `Cues` element
+ * (the WebM equivalent of an ISO-BMFF `sidx`).
+ *
+ * @module
+ */
+/** EBML element IDs (with their length-descriptor marker bits intact). */
+const EBML_ID = {
+    Segment: 0x18538067,
+    Info: 0x1549a966,
+    TimecodeScale: 0x2ad7b1,
+    Cues: 0x1c53bb6b,
+    CuePoint: 0xbb,
+    CueTime: 0xb3,
+    CueTrackPositions: 0xb7,
+    CueClusterPosition: 0xf1,
+};
+/** The default `TimecodeScale` (1ms in nanoseconds) when none is present. */
+export const DEFAULT_WEBM_TIMECODE_SCALE = 1_000_000;
+/**
+ * Reads an EBML variable-length integer at `pos`.
+ *
+ * @param keepMarker When true (element ids), the leading length-descriptor
+ * marker bit is retained; when false (sizes/uints), it is stripped to yield the
+ * numeric value, and an all-ones value ("unknown size") yields `null`.
+ */
+function readVint(view, pos, keepMarker) {
+    const first = view.getUint8(pos);
+    let mask = 0x80;
+    let length = 1;
+    while (length <= 8 && (first & mask) === 0) {
+        mask >>= 1;
+        length++;
+    }
+    if (length > 8)
+        throw new ValidationError('invalid EBML variable-length integer', ErrorOrigin.MEDIA);
+    let value = keepMarker ? first : first & (mask - 1);
+    let allOnes = (first & (mask - 1)) === mask - 1;
+    for (let i = 1; i < length; i++) {
+        const byte = view.getUint8(pos + i);
+        allOnes = allOnes && byte === 0xff;
+        // Multiply (not shift) to stay correct beyond 32 bits.
+        value = value * 256 + byte;
+    }
+    return { value: !keepMarker && allOnes ? null : value, length };
+}
+/**
+ * Reads the EBML element header at `pos`.
+ */
+function readElementHeader(view, pos) {
+    const { value: id, length: idLength } = readVint(view, pos, true);
+    const { value: size, length: sizeLength } = readVint(view, pos + idLength, false);
+    const contentStart = pos + idLength + sizeLength;
+    return {
+        id: id,
+        contentStart,
+        size,
+        end: size == null ? null : contentStart + size,
+    };
+}
+/**
+ * Reads the child element headers in `[start, end)`. An unknown-size element
+ * (no bounded end) terminates the list.
+ */
+function childHeaders(view, start, end) {
+    const out = [];
+    let pos = start;
+    while (pos < end) {
+        const el = readElementHeader(view, pos);
+        out.push(el);
+        if (el.end == null)
+            break;
+        pos = el.end;
+    }
+    return out;
+}
+/**
+ * Reads a big-endian unsigned integer of `length` bytes at `pos`.
+ */
+function readUint(view, pos, length) {
+    let value = 0;
+    for (let i = 0; i < length; i++)
+        value = value * 256 + view.getUint8(pos + i);
+    return value;
+}
+/**
+ * Parses a WebM initialization segment for the `Segment` data offset and
+ * `TimecodeScale`. The init segment is everything before the first `Cluster`
+ * (EBML header, `Segment` header, `SeekHead`, `Info`, `Tracks`).
+ */
+export function parseWebmInit(buffer) {
+    const view = new DataView(buffer);
+    const segment = childHeaders(view, 0, view.byteLength).find((el) => el.id === EBML_ID.Segment);
+    if (!segment)
+        throw new ValidationError('WebM init segment missing Segment element', ErrorOrigin.MEDIA);
+    const segmentEnd = Math.min(segment.end ?? view.byteLength, view.byteLength);
+    const info = childHeaders(view, segment.contentStart, segmentEnd).find((el) => el.id === EBML_ID.Info && el.size != null);
+    return {
+        segmentDataStart: segment.contentStart,
+        segmentSize: segment.size,
+        timecodeScale: info
+            ? readTimecodeScale(view, info.contentStart, info.end)
+            : DEFAULT_WEBM_TIMECODE_SCALE,
+    };
+}
+/**
+ * Reads `Info > TimecodeScale`, defaulting when absent.
+ */
+function readTimecodeScale(view, start, end) {
+    const el = childHeaders(view, start, end).find((child) => child.id === EBML_ID.TimecodeScale && child.size);
+    return el
+        ? readUint(view, el.contentStart, el.size)
+        : DEFAULT_WEBM_TIMECODE_SCALE;
+}
+/**
+ * Parses a WebM `Cues` element (as located by a DASH `SegmentBase@indexRange`)
+ * into its cue points, in order.
+ */
+export function parseWebmCues(buffer) {
+    const view = new DataView(buffer);
+    const cues = readElementHeader(view, 0);
+    if (cues.id !== EBML_ID.Cues)
+        throw new ValidationError(`expected WebM 'Cues' element but had id: 0x${cues.id.toString(16)}`, ErrorOrigin.MEDIA);
+    const cuesEnd = Math.min(cues.end ?? view.byteLength, view.byteLength);
+    const cuePoints = [];
+    for (const el of childHeaders(view, cues.contentStart, cuesEnd)) {
+        if (el.id !== EBML_ID.CuePoint || el.size == null)
+            continue;
+        const cuePoint = parseCuePoint(view, el.contentStart, el.end);
+        if (cuePoint)
+            cuePoints.push(cuePoint);
+    }
+    return cuePoints;
+}
+/**
+ * Parses a single `CuePoint` (its `CueTime` and first
+ * `CueTrackPositions > CueClusterPosition`).
+ */
+function parseCuePoint(view, start, end) {
+    let time = null;
+    let clusterPosition = null;
+    for (const el of childHeaders(view, start, end)) {
+        if (el.id === EBML_ID.CueTime && el.size)
+            time = readUint(view, el.contentStart, el.size);
+        else if (el.id === EBML_ID.CueTrackPositions && el.size != null)
+            clusterPosition = readCueClusterPosition(view, el.contentStart, el.end);
+    }
+    return time != null && clusterPosition != null
+        ? { time, clusterPosition }
+        : null;
+}
+/**
+ * Reads `CueTrackPositions > CueClusterPosition`.
+ */
+function readCueClusterPosition(view, start, end) {
+    const el = childHeaders(view, start, end).find((child) => child.id === EBML_ID.CueClusterPosition && child.size);
+    return el ? readUint(view, el.contentStart, el.size) : null;
+}

package/dist/types/ts3.7/index.d.ts

@@ -54,7 +54,6 @@ export * from './network/requesterUtil';
 export * from './network/RequestInterceptor';
 export * from './network/responseUtil';
 export * from './patch/network/fetch';
-export * from './patch/patchTarget';
 export * from './persistence/KeyValuePersistence';
 export * from './persistence/persistenceRef';
 export * from './persistence/PersistentItem';
@@ -116,4 +115,5 @@ export * from './util/string/StringReader';
 export * from './util/string/uid';
 export * from './util/type';
 export * from './util/url/resolveUrl';
+export * from './util/webm/parseWebm';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/ts3.7/network/responseUtil.d.ts

@@ -7,4 +7,25 @@ import { RequestError } from './RequestError';
 export declare function isResponseError(error: any): error is RequestError & {
     readonly info: RequestResponseErrorEvent;
 };
+/**
+ * The body representations {@link readResponseBody} can produce.
+ */
+export type ResponseBodyType = 'arrayBuffer' | 'text' | 'json';
+/**
+ * Reads a response body, classifying a read failure with a service error origin.
+ *
+ * The requester (`requestWithRetry`/`request`) classifies only the `fetch` and
+ * the response status; it returns the {@link Response} before the body is
+ * consumed. Reading the body stream can fail *after* a successful response —
+ * e.g. the connection drops mid-body — rejecting with a bare `TypeError`
+ * ("Failed to fetch") that carries no origin and would otherwise be reported
+ * with {@link ReportableError}'s `internal` default. This reads the body on the
+ * caller's behalf and rethrows such failures as a {@link ReportableError} with a
+ * service origin (mirroring {@link RequestError} origin classification: a 5xx
+ * status is `serviceExternal`, anything else `serviceInternal`). An aborted read
+ * is preserved as a silent error so an intentional cancellation is not reported.
+ */
+export declare function readResponseBody(response: Response, as: 'arrayBuffer'): Promise<ArrayBuffer>;
+export declare function readResponseBody(response: Response, as: 'text'): Promise<string>;
+export declare function readResponseBody(response: Response, as: 'json'): Promise<any>;
 //# sourceMappingURL=responseUtil.d.ts.map

package/dist/types/ts3.7/util/webm/parseWebm.d.ts

@@ -0,0 +1,43 @@
+/** The default `TimecodeScale` (1ms in nanoseconds) when none is present. */
+export declare const DEFAULT_WEBM_TIMECODE_SCALE = 1000000;
+export interface WebmInitInfo {
+    /**
+     * The absolute byte offset (in the file) where the `Segment` element's
+     * content begins. `CueClusterPosition` values are relative to this.
+     */
+    readonly segmentDataStart: number;
+    /**
+     * The `Segment` content size in bytes, or `null` if encoded as unknown.
+     */
+    readonly segmentSize: number | null;
+    /**
+     * The `TimecodeScale` in nanoseconds per tick (cue times are in these ticks).
+     */
+    readonly timecodeScale: number;
+}
+/**
+ * Parses a WebM initialization segment for the `Segment` data offset and
+ * `TimecodeScale`. The init segment is everything before the first `Cluster`
+ * (EBML header, `Segment` header, `SeekHead`, `Info`, `Tracks`).
+ */
+export declare function parseWebmInit(buffer: ArrayBuffer): WebmInitInfo;
+/**
+ * A single WebM cue point: a cluster's start time and its byte offset relative
+ * to the `Segment` data start.
+ */
+export interface WebmCuePoint {
+    /**
+     * The cluster's start time, in `TimecodeScale` ticks.
+     */
+    readonly time: number;
+    /**
+     * The cluster's byte offset relative to the `Segment` data start.
+     */
+    readonly clusterPosition: number;
+}
+/**
+ * Parses a WebM `Cues` element (as located by a DASH `SegmentBase@indexRange`)
+ * into its cue points, in order.
+ */
+export declare function parseWebmCues(buffer: ArrayBuffer): readonly WebmCuePoint[];
+//# sourceMappingURL=parseWebm.d.ts.map

package/dist/types/ts4.1/index.d.ts

@@ -54,7 +54,6 @@ export * from './network/requesterUtil';
 export * from './network/RequestInterceptor';
 export * from './network/responseUtil';
 export * from './patch/network/fetch';
-export * from './patch/patchTarget';
 export * from './persistence/KeyValuePersistence';
 export * from './persistence/persistenceRef';
 export * from './persistence/PersistentItem';
@@ -116,4 +115,5 @@ export * from './util/string/StringReader';
 export * from './util/string/uid';
 export * from './util/type';
 export * from './util/url/resolveUrl';
+export * from './util/webm/parseWebm';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.1/network/responseUtil.d.ts

@@ -7,4 +7,25 @@ import { RequestError } from './RequestError';
 export declare function isResponseError(error: any): error is RequestError & {
     readonly info: RequestResponseErrorEvent;
 };
+/**
+ * The body representations {@link readResponseBody} can produce.
+ */
+export type ResponseBodyType = 'arrayBuffer' | 'text' | 'json';
+/**
+ * Reads a response body, classifying a read failure with a service error origin.
+ *
+ * The requester (`requestWithRetry`/`request`) classifies only the `fetch` and
+ * the response status; it returns the {@link Response} before the body is
+ * consumed. Reading the body stream can fail *after* a successful response —
+ * e.g. the connection drops mid-body — rejecting with a bare `TypeError`
+ * ("Failed to fetch") that carries no origin and would otherwise be reported
+ * with {@link ReportableError}'s `internal` default. This reads the body on the
+ * caller's behalf and rethrows such failures as a {@link ReportableError} with a
+ * service origin (mirroring {@link RequestError} origin classification: a 5xx
+ * status is `serviceExternal`, anything else `serviceInternal`). An aborted read
+ * is preserved as a silent error so an intentional cancellation is not reported.
+ */
+export declare function readResponseBody(response: Response, as: 'arrayBuffer'): Promise<ArrayBuffer>;
+export declare function readResponseBody(response: Response, as: 'text'): Promise<string>;
+export declare function readResponseBody(response: Response, as: 'json'): Promise<any>;
 //# sourceMappingURL=responseUtil.d.ts.map

package/dist/types/ts4.1/util/webm/parseWebm.d.ts

@@ -0,0 +1,43 @@
+/** The default `TimecodeScale` (1ms in nanoseconds) when none is present. */
+export declare const DEFAULT_WEBM_TIMECODE_SCALE = 1000000;
+export interface WebmInitInfo {
+    /**
+     * The absolute byte offset (in the file) where the `Segment` element's
+     * content begins. `CueClusterPosition` values are relative to this.
+     */
+    readonly segmentDataStart: number;
+    /**
+     * The `Segment` content size in bytes, or `null` if encoded as unknown.
+     */
+    readonly segmentSize: number | null;
+    /**
+     * The `TimecodeScale` in nanoseconds per tick (cue times are in these ticks).
+     */
+    readonly timecodeScale: number;
+}
+/**
+ * Parses a WebM initialization segment for the `Segment` data offset and
+ * `TimecodeScale`. The init segment is everything before the first `Cluster`
+ * (EBML header, `Segment` header, `SeekHead`, `Info`, `Tracks`).
+ */
+export declare function parseWebmInit(buffer: ArrayBuffer): WebmInitInfo;
+/**
+ * A single WebM cue point: a cluster's start time and its byte offset relative
+ * to the `Segment` data start.
+ */
+export interface WebmCuePoint {
+    /**
+     * The cluster's start time, in `TimecodeScale` ticks.
+     */
+    readonly time: number;
+    /**
+     * The cluster's byte offset relative to the `Segment` data start.
+     */
+    readonly clusterPosition: number;
+}
+/**
+ * Parses a WebM `Cues` element (as located by a DASH `SegmentBase@indexRange`)
+ * into its cue points, in order.
+ */
+export declare function parseWebmCues(buffer: ArrayBuffer): readonly WebmCuePoint[];
+//# sourceMappingURL=parseWebm.d.ts.map

package/dist/types/ts4.7/index.d.ts

@@ -54,7 +54,6 @@ export * from './network/requesterUtil';
 export * from './network/RequestInterceptor';
 export * from './network/responseUtil';
 export * from './patch/network/fetch';
-export * from './patch/patchTarget';
 export * from './persistence/KeyValuePersistence';
 export * from './persistence/persistenceRef';
 export * from './persistence/PersistentItem';
@@ -116,4 +115,5 @@ export * from './util/string/StringReader';
 export * from './util/string/uid';
 export * from './util/type';
 export * from './util/url/resolveUrl';
+export * from './util/webm/parseWebm';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.7/network/responseUtil.d.ts

@@ -7,4 +7,25 @@ import { RequestError } from './RequestError';
 export declare function isResponseError(error: any): error is RequestError & {
     readonly info: RequestResponseErrorEvent;
 };
+/**
+ * The body representations {@link readResponseBody} can produce.
+ */
+export type ResponseBodyType = 'arrayBuffer' | 'text' | 'json';
+/**
+ * Reads a response body, classifying a read failure with a service error origin.
+ *
+ * The requester (`requestWithRetry`/`request`) classifies only the `fetch` and
+ * the response status; it returns the {@link Response} before the body is
+ * consumed. Reading the body stream can fail *after* a successful response —
+ * e.g. the connection drops mid-body — rejecting with a bare `TypeError`
+ * ("Failed to fetch") that carries no origin and would otherwise be reported
+ * with {@link ReportableError}'s `internal` default. This reads the body on the
+ * caller's behalf and rethrows such failures as a {@link ReportableError} with a
+ * service origin (mirroring {@link RequestError} origin classification: a 5xx
+ * status is `serviceExternal`, anything else `serviceInternal`). An aborted read
+ * is preserved as a silent error so an intentional cancellation is not reported.
+ */
+export declare function readResponseBody(response: Response, as: 'arrayBuffer'): Promise<ArrayBuffer>;
+export declare function readResponseBody(response: Response, as: 'text'): Promise<string>;
+export declare function readResponseBody(response: Response, as: 'json'): Promise<any>;
 //# sourceMappingURL=responseUtil.d.ts.map

package/dist/types/ts4.7/util/webm/parseWebm.d.ts

@@ -0,0 +1,43 @@
+/** The default `TimecodeScale` (1ms in nanoseconds) when none is present. */
+export declare const DEFAULT_WEBM_TIMECODE_SCALE = 1000000;
+export interface WebmInitInfo {
+    /**
+     * The absolute byte offset (in the file) where the `Segment` element's
+     * content begins. `CueClusterPosition` values are relative to this.
+     */
+    readonly segmentDataStart: number;
+    /**
+     * The `Segment` content size in bytes, or `null` if encoded as unknown.
+     */
+    readonly segmentSize: number | null;
+    /**
+     * The `TimecodeScale` in nanoseconds per tick (cue times are in these ticks).
+     */
+    readonly timecodeScale: number;
+}
+/**
+ * Parses a WebM initialization segment for the `Segment` data offset and
+ * `TimecodeScale`. The init segment is everything before the first `Cluster`
+ * (EBML header, `Segment` header, `SeekHead`, `Info`, `Tracks`).
+ */
+export declare function parseWebmInit(buffer: ArrayBuffer): WebmInitInfo;
+/**
+ * A single WebM cue point: a cluster's start time and its byte offset relative
+ * to the `Segment` data start.
+ */
+export interface WebmCuePoint {
+    /**
+     * The cluster's start time, in `TimecodeScale` ticks.
+     */
+    readonly time: number;
+    /**
+     * The cluster's byte offset relative to the `Segment` data start.
+     */
+    readonly clusterPosition: number;
+}
+/**
+ * Parses a WebM `Cues` element (as located by a DASH `SegmentBase@indexRange`)
+ * into its cue points, in order.
+ */
+export declare function parseWebmCues(buffer: ArrayBuffer): readonly WebmCuePoint[];
+//# sourceMappingURL=parseWebm.d.ts.map