mkvpeek 0.1.0

package/dist/io/url.d.ts

@@ -0,0 +1,21 @@
+/** URL policy and the fetch transport. */
+import { type RangeOptions } from "./range.js";
+import type { Source } from "./source.js";
+export interface UrlOptions extends RangeOptions {
+    headers?: Readonly<Record<string, string>>;
+    fetch?: typeof globalThis.fetch;
+}
+export declare const TRANSPORT_OWNED_HEADERS: ReadonlySet<string>;
+export declare const whyCredentialed: (parsed: URL) => string | null;
+export declare const namesAuthority: (target: string) => boolean;
+export declare function withoutHeaders(headers: Readonly<Record<string, string>>, names: ReadonlySet<string>): Record<string, string>;
+/**
+ * An HTTP source over `fetch`.
+ *
+ * A server answering a Range request with anything but 206 is not read;
+ * the read throws, which the envelope reports as `source-failed`.
+ */
+export declare function urlSource(url: string, options?: UrlOptions): Promise<Source>;
+export declare function isHttpUrl(target: string): boolean;
+export declare function httpTarget(url: string): URL;
+export declare function whyInadmissible(parsed: URL): string | null;

package/dist/io/url.js

@@ -0,0 +1,80 @@
+import { bytesRange, rangeSource } from "./range.js";
+export const TRANSPORT_OWNED_HEADERS = new Set([
+    "host",
+    "accept-encoding",
+    "range",
+]);
+export const whyCredentialed = (parsed) => parsed.username !== "" || parsed.password !== ""
+    ? "carries credentials in its URL, and this reader takes them as headers"
+    : null;
+export const namesAuthority = (target) => /^[a-z][a-z0-9+.-]*:\/\//i.test(target);
+export function withoutHeaders(headers, names) {
+    const kept = Object.entries(headers).filter(([name]) => !names.has(name.toLowerCase()));
+    return Object.fromEntries(kept);
+}
+export async function urlSource(url, options = {}) {
+    const transport = fetchTransport(url, options);
+    return rangeSource(url, transport, options);
+}
+export function isHttpUrl(target) {
+    const parsed = URL.parse(target);
+    return parsed !== null && speaksHttp(parsed);
+}
+export function httpTarget(url) {
+    const parsed = URL.parse(url);
+    if (parsed === null)
+        throw new Error(`${url} is not a URL`);
+    const why = whyInadmissible(parsed);
+    if (why !== null)
+        throw new Error(`${url} ${why}`);
+    return parsed;
+}
+export function whyInadmissible(parsed) {
+    const secret = whyCredentialed(parsed);
+    if (secret !== null)
+        return secret;
+    if (!speaksHttp(parsed))
+        return `names ${parsed.protocol}, and this reader speaks http(s)`;
+    return null;
+}
+async function* chunksOf(reader) {
+    if (reader === undefined)
+        return;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return;
+        yield value;
+    }
+}
+function fetchTransport(url, options) {
+    const { headers = {}, fetch: fetchImpl = globalThis.fetch } = options;
+    httpTarget(url);
+    const withRange = (from, to) => {
+        const out = new Headers(withoutHeaders(headers, TRANSPORT_OWNED_HEADERS));
+        const range = bytesRange(from, to);
+        out.set("Range", range);
+        return out;
+    };
+    return async (from, to, signal) => {
+        const init = {
+            ...(signal === undefined ? {} : { signal }),
+            headers: withRange(from, to),
+        };
+        const response = await fetchImpl(url, init);
+        const reader = response.body?.getReader();
+        const cancel = async () => {
+            const releasing = reader === undefined ? response.body?.cancel() : reader.cancel();
+            await releasing?.catch?.(() => { });
+        };
+        return {
+            status: response.status,
+            header: (name) => response.headers.get(name),
+            body: chunksOf(reader),
+            cancel,
+        };
+    };
+}
+function speaksHttp(parsed) {
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+}

package/dist/io/windows.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The plumbing of windows.
+ *
+ * Makes windows from a source, indexes them, and reuses them.
+ */
+import type { Window } from "../ebml.js";
+import { type IndexFetch, type Range, type SizedSource, type Source } from "./source.js";
+/** The window buffers the walk reuses. */
+export interface WindowPool {
+    /**
+     * A lease when the width fits the threshold and a slot.
+     *
+     * Otherwise null, which is the fresh-allocation path.
+     */
+    borrow(width: number): Lease | null;
+}
+/**
+ * The lease of one slot.
+ *
+ * `release` is one-shot; a second call throws.
+ */
+interface Lease {
+    readonly bytes: Uint8Array;
+    release: () => void;
+}
+export declare class WindowIndex {
+    #private;
+    constructor(windows: readonly Window[], head?: Window);
+    find(at: number, length: number): Window | null;
+}
+export declare function fetchRanges(sized: SizedSource, ranges: readonly Range[], options: Pick<IndexFetch, "gapBytes" | "concurrency">, signal?: AbortSignal): Promise<Window[]>;
+export declare function fetchSpans(sized: SizedSource, spans: readonly Range[], concurrency: number, signal?: AbortSignal): Promise<Window[]>;
+export declare function coalesce(ranges: readonly Range[], options: Pick<IndexFetch, "gapBytes">): Range[];
+export declare function windowPool(slotBytes: number, slots: number): WindowPool;
+export declare function windowOver(source: Source, at: number, length: number, held: Window): Promise<Window>;
+export declare function windowAt({ source, fileSize }: SizedSource, at: number, length: number, into?: Uint8Array): Promise<Window>;
+export {};

package/dist/io/windows.js

@@ -0,0 +1,105 @@
+import * as E from "../ebml.js";
+import { inParallel } from "./lanes.js";
+import { available, LARGE_READ_BYTES, MAX_SPAN_BYTES, } from "./source.js";
+export class WindowIndex {
+    #sorted;
+    #widestSorted;
+    #head;
+    constructor(windows, head) {
+        this.#sorted = [...windows].sort((a, b) => a.at - b.at);
+        this.#widestSorted = this.#sorted.reduce((max, w) => Math.max(max, w.bytes.length), 0);
+        this.#head = head;
+    }
+    find(at, length) {
+        let low = 0;
+        let high = this.#sorted.length;
+        while (low < high) {
+            const mid = (low + high) >>> 1;
+            if (this.#sorted[mid].at <= at) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        let best = this.#head !== undefined && E.covers(this.#head, at, length) ? this.#head : null;
+        for (let i = low - 1; i >= 0; i--) {
+            const window = this.#sorted[i];
+            if (at - window.at > this.#widestSorted)
+                break;
+            if (!E.covers(window, at, length))
+                continue;
+            if (best === null || E.reachOf(window) > E.reachOf(best)) {
+                best = window;
+            }
+        }
+        return best;
+    }
+}
+export async function fetchRanges(sized, ranges, options, signal) {
+    const spans = coalesce(ranges, options);
+    return fetchSpans(sized, spans, options.concurrency, signal);
+}
+export async function fetchSpans(sized, spans, concurrency, signal) {
+    const windowFor = (span) => windowAt(sized, span.at, span.length);
+    return inParallel(spans, concurrency, windowFor, signal);
+}
+export function coalesce(ranges, options) {
+    const sorted = [...ranges].filter((r) => r.length > 0).sort((a, b) => a.at - b.at);
+    const spans = [];
+    for (const range of sorted) {
+        const last = spans[spans.length - 1];
+        if (last === undefined) {
+            spans.push({ ...range });
+            continue;
+        }
+        const lastEnd = last.at + last.length;
+        const merged = Math.max(lastEnd, range.at + range.length) - last.at;
+        if (range.at - lastEnd <= options.gapBytes && merged <= MAX_SPAN_BYTES) {
+            last.length = merged;
+            continue;
+        }
+        spans.push({ ...range });
+    }
+    return spans;
+}
+export function windowPool(slotBytes, slots) {
+    const free = [];
+    let unbuilt = slotBytes >= LARGE_READ_BYTES ? slots : 0;
+    const lease = (slot, width) => {
+        let released = false;
+        const release = () => {
+            if (released)
+                throw new Error();
+            released = true;
+            free.push(slot);
+        };
+        return { bytes: slot.subarray(0, width), release: release };
+    };
+    const borrow = (width) => {
+        if (width < LARGE_READ_BYTES || width > slotBytes)
+            return null;
+        let slot = free.pop() ?? null;
+        if (slot === null && unbuilt > 0) {
+            unbuilt -= 1;
+            const owned = new ArrayBuffer(slotBytes);
+            slot = new Uint8Array(owned);
+        }
+        return slot === null ? null : lease(slot, width);
+    };
+    return { borrow };
+}
+export async function windowOver(source, at, length, held) {
+    const need = available(at, length, held.fileSize);
+    if (E.covers(held, at, need))
+        return held;
+    const heldSource = { source, fileSize: held.fileSize };
+    return windowAt(heldSource, at, length);
+}
+export async function windowAt({ source, fileSize }, at, length, into) {
+    const bytes = await source.read(at, length, into);
+    const expected = available(at, length, fileSize);
+    if (bytes.length < expected)
+        throw new Error();
+    return { at, bytes, fileSize };
+}

package/dist/matroska/block.d.ts

@@ -0,0 +1,47 @@
+import type { Element, Window } from "../ebml.js";
+export interface Frame {
+    readOrder: number | null;
+    startTicks: number;
+    durationTicks: number | null;
+    payload: string;
+}
+/**
+ * The hand that supplies bytes.
+ *
+ * The walk buys them, the index finds them in held windows; failing that, a GrammarError.
+ */
+export type BytesSupply = (at: number, need: number) => Promise<Window>;
+/** For a claimed track, whether it is numbered; otherwise null. */
+export type TrackClaim = (track: number) => boolean | null;
+interface ClaimedFrame {
+    track: number;
+    frame: Frame;
+}
+/** The definitions that name which rule stood at a refusal. */
+export declare const BLOCK_REFUSAL: {
+    readonly notThisTrack: "not-this-track";
+    readonly notACluster: "not-a-cluster";
+    readonly openCluster: "open-cluster";
+    readonly noClusterTime: "no-cluster-time";
+    readonly runsPastCluster: "runs-past-cluster";
+    readonly notAnElement: "not-an-element";
+    readonly pastTheCluster: "past-the-cluster";
+    readonly notABlock: "not-a-block";
+    readonly notFetched: "not-fetched";
+    readonly groupChildren: "group-children";
+    readonly groupEmpty: "group-empty";
+    readonly strayBlock: "stray-block";
+    readonly stranger: "stranger";
+    readonly blockHead: "block-head";
+    readonly laced: "laced";
+    readonly shortHead: "short-head";
+};
+export type BlockClause = (typeof BLOCK_REFUSAL)[keyof typeof BLOCK_REFUSAL];
+export declare const BLOCK_HEAD_BYTES = 32;
+/**
+ * One block element as a frame.
+ *
+ * An unclaimed track is null, and a rule that stands is its clause.
+ */
+export declare function frameIn(outer: Element, clusterTicks: number, held: Window, claim: TrackClaim, supply: BytesSupply): Promise<ClaimedFrame | null | BlockClause>;
+export {};

package/dist/matroska/block.js

@@ -0,0 +1,114 @@
+import * as E from "../ebml.js";
+import { headerNeed } from "./chain.js";
+export const BLOCK_REFUSAL = {
+    notThisTrack: "not-this-track",
+    notACluster: "not-a-cluster",
+    openCluster: "open-cluster",
+    noClusterTime: "no-cluster-time",
+    runsPastCluster: "runs-past-cluster",
+    notAnElement: "not-an-element",
+    pastTheCluster: "past-the-cluster",
+    notABlock: "not-a-block",
+    notFetched: "not-fetched",
+    groupChildren: "group-children",
+    groupEmpty: "group-empty",
+    strayBlock: "stray-block",
+    stranger: "stranger",
+    blockHead: "block-head",
+    laced: "laced",
+    shortHead: "short-head",
+};
+export const BLOCK_HEAD_BYTES = 32;
+export async function frameIn(outer, clusterTicks, held, claim, supply) {
+    let window = held;
+    let body = outer.body;
+    let size = outer.size;
+    let durationTicks = null;
+    if (outer.id === E.ID.cluster.BLOCK_GROUP) {
+        const probe = Math.min(outer.size, BLOCK_GROUP_PROBE_BYTES);
+        if (!E.covers(window, outer.body, probe)) {
+            window = await supply(outer.body, probe);
+        }
+        let inner = null;
+        let pos = outer.body;
+        while (pos < outer.next) {
+            const need = headerNeed(pos, outer.next);
+            if (!E.covers(window, pos, need)) {
+                window = await supply(pos, need);
+            }
+            const field = E.readElement(window, pos);
+            if (!E.fits(field, outer.next))
+                return BLOCK_REFUSAL.groupChildren;
+            if (field.id === E.ID.blockGroup.BLOCK) {
+                inner = field;
+            }
+            else if (field.id === E.ID.blockGroup.BLOCK_DURATION) {
+                const buys = E.uintFits(field.size) && !E.covers(window, field.body, field.size);
+                const covering = buys ? await supply(field.body, field.size) : window;
+                durationTicks = E.readUint(covering, field);
+            }
+            pos = field.next;
+        }
+        if (inner === null)
+            return BLOCK_REFUSAL.groupEmpty;
+        body = inner.body;
+        size = inner.size;
+    }
+    const need = Math.min(BLOCK_FIELD_BYTES, size);
+    if (!E.covers(window, body, need)) {
+        window = await supply(body, need);
+    }
+    const head = readBlockHead(window, body, size);
+    if (typeof head === "string")
+        return head;
+    const numbered = claim(head.track);
+    if (numbered === null)
+        return null;
+    const fault = blockFault(head);
+    if (fault !== null)
+        return fault;
+    const covering = E.covers(window, head.payloadAt, head.payloadSize)
+        ? window
+        : await supply(head.payloadAt, head.payloadSize);
+    const payload = E.readBytes(covering, head.payloadAt, head.payloadSize);
+    const frameFields = { payload: E.decodeUtf8(payload), clusterTicks, durationTicks, numbered };
+    const frame = frameOf(head, frameFields);
+    return { track: head.track, frame };
+}
+const TIME_AND_FLAGS_BYTES = 3;
+const BLOCK_FIELD_BYTES = E.MAX_VINT_BYTES + TIME_AND_FLAGS_BYTES;
+const BLOCK_GROUP_PROBE_BYTES = 256;
+const LACING_MASK = 0x06;
+function readBlockHead(window, body, size) {
+    const track = E.readVint(window, body, "size");
+    if (typeof track === "string")
+        return BLOCK_REFUSAL.blockHead;
+    const bytesAt = body + track.length;
+    if (!E.covers(window, bytesAt, TIME_AND_FLAGS_BYTES))
+        return BLOCK_REFUSAL.blockHead;
+    const bytes = E.readBytes(window, bytesAt, TIME_AND_FLAGS_BYTES);
+    const relTicks = (((bytes[0] << 8) | bytes[1]) << 16) >> 16;
+    return {
+        track: track.value,
+        relTicks,
+        laced: (bytes[2] & LACING_MASK) !== 0,
+        payloadAt: bytesAt + TIME_AND_FLAGS_BYTES,
+        payloadSize: size - (track.length + TIME_AND_FLAGS_BYTES),
+    };
+}
+function blockFault(block) {
+    if (block.laced)
+        return BLOCK_REFUSAL.laced;
+    if (block.payloadSize < 0)
+        return BLOCK_REFUSAL.shortHead;
+    return null;
+}
+function frameOf(head, { payload, clusterTicks, durationTicks, numbered }) {
+    const lead = numbered ? /^(\d+),/.exec(payload) : null;
+    return {
+        readOrder: lead === null ? null : Number(lead[1]),
+        startTicks: clusterTicks + head.relTicks,
+        durationTicks,
+        payload,
+    };
+}

package/dist/matroska/chain.d.ts

@@ -0,0 +1,55 @@
+import type { Element, OpenElement, Window } from "../ebml.js";
+import { type Source } from "../io/source.js";
+export interface Segment {
+    /**
+     * The absolute offset of the Segment's first child.
+     *
+     * Every Seek and Cue position is relative to it.
+     */
+    body: number;
+    end: number;
+}
+export interface SegmentPass {
+    source: Source;
+    segment: Segment;
+    head: Window;
+    signal: AbortSignal | undefined;
+}
+/**
+ * An element and the window its head was read from.
+ *
+ * For a cluster the window reaches the Timestamp.
+ */
+interface TopLevelHop {
+    at: number;
+    el: Element | OpenElement;
+    window: Window;
+}
+/** Enough for any element's header. */
+export declare const ELEMENT_HEADER_BYTES: number;
+/** Enough to read a cluster's header and its Timestamp. */
+export declare const CLUSTER_PROBE_BYTES = 64;
+/** The cluster children that carry frames. */
+export declare const FRAME_IDS: ReadonlySet<number>;
+export declare const pastSegment: (el: Element, segment: Segment) => boolean;
+export declare const headerNeed: (at: number, end: number) => number;
+/**
+ * The one door for reads past the head.
+ *
+ * The signal is asked here and nowhere else.
+ */
+export declare function readPastHead(pass: SegmentPass, at: number, length: number, held: Window): Promise<Window>;
+export declare function hopTopLevel(pass: SegmentPass, 
+/**
+ * The end of a sizeless cluster is the walk's discovery.
+ *
+ * The hop that resumes after it passes it here.
+ */
+from?: number): AsyncGenerator<TopLevelHop>;
+/**
+ * A cluster's Timestamp.
+ *
+ * In a sizeless cluster the search goes as far as the window reaches.
+ */
+export declare function readClusterTime(window: Window, cluster: Element | OpenElement): number | null;
+export {};

package/dist/matroska/chain.js

@@ -0,0 +1,47 @@
+import * as E from "../ebml.js";
+import { stopIfAborted } from "../io/source.js";
+import { windowOver } from "../io/windows.js";
+export const ELEMENT_HEADER_BYTES = 2 * E.MAX_VINT_BYTES;
+export const CLUSTER_PROBE_BYTES = 64;
+export const FRAME_IDS = new Set([
+    E.ID.cluster.SIMPLE_BLOCK,
+    E.ID.cluster.BLOCK_GROUP,
+]);
+export const pastSegment = (el, segment) => el.next > segment.end;
+export const headerNeed = (at, end) => Math.min(ELEMENT_HEADER_BYTES, end - at);
+export function readPastHead(pass, at, length, held) {
+    stopIfAborted(pass.signal);
+    return windowOver(pass.source, at, length, held);
+}
+export async function* hopTopLevel(pass, from = pass.segment.body) {
+    let pos = from;
+    while (pos < pass.segment.end) {
+        const window = await readPastHead(pass, pos, CLUSTER_PROBE_BYTES, pass.head);
+        const el = E.readElement(window, pos);
+        if (typeof el === "string")
+            throw new E.GrammarError();
+        const isOpen = "open" in el;
+        if (isOpen ? el.id !== E.ID.segment.CLUSTER : pastSegment(el, pass.segment)) {
+            throw new E.GrammarError();
+        }
+        yield { at: pos, el, window };
+        if (isOpen)
+            return;
+        pos = el.next;
+    }
+}
+export function readClusterTime(window, cluster) {
+    const end = "open" in cluster ? E.reachOf(window) : cluster.next;
+    try {
+        for (const field of E.children(window, cluster.body, end - cluster.body)) {
+            if (field.id === E.ID.cluster.TIMESTAMP)
+                return E.readUint(window, field);
+            if (FRAME_IDS.has(field.id))
+                return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}

package/dist/matroska/clusters.d.ts

@@ -0,0 +1,4 @@
+import { type WalkFetch, type Watch } from "../io/source.js";
+import { type Frame } from "./block.js";
+import { type SegmentPass } from "./chain.js";
+export declare function walkFrames(pass: SegmentPass, tracks: ReadonlyMap<number, boolean>, knobs: WalkFetch, { onProgress, signal }: Watch): Promise<Map<number, Frame[]> | null>;