mkvpeek 0.1.0

package/dist/matroska/clusters.js

@@ -0,0 +1,232 @@
+import * as E from "../ebml.js";
+import { HaltableQueue, joinOrAbort } from "../io/lanes.js";
+import { available, stopIfAborted, } from "../io/source.js";
+import { windowAt, windowPool } from "../io/windows.js";
+import { BLOCK_HEAD_BYTES, BLOCK_REFUSAL, frameIn, } from "./block.js";
+import { CLUSTER_PROBE_BYTES, FRAME_IDS, hopTopLevel, readClusterTime, } from "./chain.js";
+export async function walkFrames(pass, tracks, knobs, { onProgress, signal }) {
+    const fileSize = pass.head.fileSize;
+    onProgress(0, fileSize);
+    const slotBytes = Math.min(knobs.blockAheadBytes, fileSize);
+    const pool = windowPool(slotBytes, knobs.concurrency + 4);
+    const sized = { source: pass.source, fileSize };
+    const walk = { sized, tracks, knobs, head: pass.head };
+    let done = 0;
+    let refused = false;
+    const walked = new Map();
+    const record = (index, span, outcome) => {
+        if (typeof outcome === "string") {
+            refused = true;
+            return false;
+        }
+        walked.set(index, outcome.frames);
+        done += outcome.end - span.at;
+        onProgress(done, fileSize);
+        return true;
+    };
+    const queue = new HaltableQueue();
+    let count = 0;
+    const feed = async () => {
+        let seed;
+        try {
+            let pos = pass.segment.body;
+            while (!queue.halted) {
+                let openCluster = null;
+                for await (const { at, el, window } of hopTopLevel(pass, pos)) {
+                    if (queue.halted)
+                        return;
+                    if (!TOP_LEVEL_IDS.has(el.id)) {
+                        refused = true;
+                        queue.halt();
+                        return;
+                    }
+                    if (el.id !== E.ID.segment.CLUSTER)
+                        continue;
+                    if ("open" in el) {
+                        openCluster = { index: count++, span: { at, el, end: pass.segment.end }, window };
+                        break;
+                    }
+                    const queued = { index: count++, span: { at, el, end: el.next }, window };
+                    queue.push(queued);
+                }
+                if (openCluster === null)
+                    break;
+                const outcome = await walkCluster(walk, openCluster.span, pool, seed ?? openCluster.window);
+                if (!record(openCluster.index, openCluster.span, outcome)) {
+                    queue.halt();
+                    return;
+                }
+                if (seed !== undefined && outcome.carried !== seed)
+                    seed.release?.();
+                seed = outcome.carried;
+                pos = outcome.end;
+            }
+        }
+        catch (error) {
+            queue.halt();
+            if (!E.isGrammarError(error))
+                throw error;
+            refused = true;
+        }
+        finally {
+            queue.close();
+            seed?.release?.();
+        }
+    };
+    const eachCluster = async (item) => {
+        const outcome = await walkCluster(walk, item.span, pool, item.window);
+        const kept = record(item.index, item.span, outcome);
+        if (kept)
+            outcome.carried.release?.();
+        return kept;
+    };
+    const feeding = feed();
+    if (knobs.concurrency < 2) {
+        await feeding.then(() => { }, () => { });
+    }
+    const laneCount = Math.max(1, knobs.concurrency - 1);
+    const draining = queue.drain(laneCount, eachCluster, signal);
+    await joinOrAbort([feeding, draining], signal);
+    stopIfAborted(signal);
+    if (refused || count === 0)
+        return null;
+    onProgress(fileSize, fileSize);
+    return merged(walked);
+}
+const CLUSTER_CHILD_IDS = new Set([
+    ...Object.values(E.ID.cluster),
+    ...Object.values(E.ID.global),
+]);
+const CLUSTER_END_IDS = new Set(Object.values(E.ID.segment));
+const TOP_LEVEL_IDS = new Set([...CLUSTER_END_IDS, ...Object.values(E.ID.global)]);
+const STRAY_IDS = new Set(Object.values(E.ID.blockGroup));
+async function walkCluster(walk, span, pool, seed) {
+    const ledger = new Set();
+    let outcome;
+    try {
+        const loans = { pool, ledger };
+        outcome = await walkSpan(walk, span, loans, seed);
+    }
+    catch (error) {
+        releaseAll(ledger, true);
+        throw error;
+    }
+    if (typeof outcome !== "string")
+        ledger.delete(outcome.carried);
+    releaseAll(ledger, false);
+    return outcome;
+}
+function releaseAll(ledger, swallow) {
+    let first = null;
+    for (const window of ledger) {
+        try {
+            window.release?.();
+        }
+        catch (error) {
+            first ??= error;
+        }
+    }
+    if (first !== null && !swallow)
+        throw first;
+}
+async function walkSpan({ sized, tracks, knobs, head }, span, { pool, ledger }, seed) {
+    const widthFor = (at, need) => {
+        if (knobs.blockAheadBytes === 0)
+            return need;
+        const bound = Math.min(knobs.blockAheadBytes, span.end - at);
+        return Math.max(need, bound);
+    };
+    const first = widthFor(span.at, CLUSTER_PROBE_BYTES);
+    const fetchWindow = async (at, width) => {
+        const bounded = available(at, width, sized.fileSize);
+        if (E.covers(head, at, bounded))
+            return head;
+        const lease = pool.borrow(width);
+        if (lease === null)
+            return windowAt(sized, at, width);
+        let window;
+        try {
+            window = await windowAt(sized, at, width, lease.bytes);
+        }
+        catch (error) {
+            lease.release();
+            throw error;
+        }
+        if (window.bytes.buffer !== lease.bytes.buffer) {
+            lease.release();
+            return window;
+        }
+        const owned = { ...window, release: lease.release };
+        ledger.add(owned);
+        return owned;
+    };
+    const seeded = available(span.at, first, sized.fileSize);
+    const adopted = seed !== undefined && E.covers(seed, span.at, seeded) ? seed : null;
+    let carried = adopted ?? (await fetchWindow(span.at, first));
+    const clusterTime = readClusterTime(carried, span.el);
+    if (clusterTime === null)
+        return BLOCK_REFUSAL.noClusterTime;
+    const frames = new Map();
+    let pos = span.el.body;
+    const supply = async (at, need) => {
+        if (E.covers(carried, at, need))
+            return carried;
+        const width = widthFor(at, need);
+        const window = await fetchWindow(at, width);
+        if (E.reachOf(window) > E.reachOf(carried)) {
+            carried = window;
+        }
+        return window;
+    };
+    const claim = (track) => tracks.get(track) ?? null;
+    while (pos < span.end) {
+        const need = Math.min(BLOCK_HEAD_BYTES, span.end - pos);
+        const window = await supply(pos, need);
+        const el = E.readElement(window, pos);
+        if (typeof el === "string")
+            return BLOCK_REFUSAL.notAnElement;
+        if ("open" in el) {
+            if ("open" in span.el)
+                return { frames, end: pos, carried };
+            return BLOCK_REFUSAL.runsPastCluster;
+        }
+        if (STRAY_IDS.has(el.id))
+            return BLOCK_REFUSAL.strayBlock;
+        if (!CLUSTER_CHILD_IDS.has(el.id)) {
+            if ("open" in span.el && CLUSTER_END_IDS.has(el.id))
+                return { frames, end: pos, carried };
+            return BLOCK_REFUSAL.stranger;
+        }
+        if (el.next > span.end)
+            return BLOCK_REFUSAL.runsPastCluster;
+        if (FRAME_IDS.has(el.id)) {
+            const attributed = await frameIn(el, clusterTime, window, claim, supply);
+            if (typeof attributed === "string")
+                return attributed;
+            if (attributed !== null) {
+                const list = frames.get(attributed.track);
+                if (list === undefined)
+                    frames.set(attributed.track, [attributed.frame]);
+                else
+                    list.push(attributed.frame);
+            }
+        }
+        pos = el.next;
+    }
+    return { frames, end: span.end, carried };
+}
+function merged(walked) {
+    const chunks = new Map();
+    const sorted = [...walked.entries()].sort(([a], [b]) => a - b);
+    for (const [, found] of sorted) {
+        for (const [track, frames] of found) {
+            const list = chunks.get(track);
+            if (list === undefined)
+                chunks.set(track, [frames]);
+            else
+                list.push(frames);
+        }
+    }
+    const flattened = [...chunks].map(([track, lists]) => [track, lists.flat()]);
+    return new Map(flattened);
+}

package/dist/matroska/cues.d.ts

@@ -0,0 +1,23 @@
+import type { Element, Window } from "../ebml.js";
+import type { Range } from "../io/source.js";
+import type { WindowIndex } from "../io/windows.js";
+import { type BlockClause, type Frame } from "./block.js";
+import type { CuePosition } from "./header.js";
+/**
+ * The cluster the previous point named.
+ *
+ * Points naming the same cluster in a row share its element, its time and the last window.
+ */
+export interface ClusterMemo {
+    last: LastCluster | null;
+}
+interface LastCluster {
+    clusterPos: number;
+    cluster: Element;
+    clusterTime: number | null;
+    window: Window;
+}
+export declare function planRanges(points: readonly CuePosition[], cueAheadBytes: number): Range[];
+export declare function planShortfall(windows: WindowIndex, points: readonly CuePosition[]): Range[];
+export declare function readFrame(windows: WindowIndex, point: CuePosition, trackNumber: number, numbered: boolean, memo?: ClusterMemo): Promise<Frame | BlockClause>;
+export {};

package/dist/matroska/cues.js

@@ -0,0 +1,93 @@
+import * as E from "../ebml.js";
+import { BLOCK_REFUSAL, frameIn, } from "./block.js";
+import { CLUSTER_PROBE_BYTES, ELEMENT_HEADER_BYTES, FRAME_IDS, headerNeed, readClusterTime, } from "./chain.js";
+export function planRanges(points, cueAheadBytes) {
+    const ranges = [];
+    const clusters = new Set();
+    for (const { clusterPos, relPos } of points) {
+        if (!clusters.has(clusterPos)) {
+            clusters.add(clusterPos);
+            ranges.push({ at: clusterPos, length: CLUSTER_PROBE_BYTES });
+        }
+        ranges.push({
+            at: clusterPos + relPos,
+            length: MAX_CLUSTER_HEADER_BYTES + cueAheadBytes,
+        });
+    }
+    return ranges;
+}
+export function planShortfall(windows, points) {
+    const ranges = [];
+    const memo = { last: null };
+    for (const point of points) {
+        const pointed = locateBlock(windows, point, memo);
+        if (typeof pointed === "string")
+            continue;
+        const { window, blockAt, outer } = pointed;
+        const covered = E.reachOf(window);
+        if (outer.next > covered) {
+            ranges.push({ at: blockAt, length: outer.next - blockAt });
+        }
+    }
+    return ranges;
+}
+export async function readFrame(windows, point, trackNumber, numbered, memo = { last: null }) {
+    const pointed = locateBlock(windows, point, memo);
+    if (typeof pointed === "string")
+        return pointed;
+    const { clusterTime, window, outer } = pointed;
+    if (clusterTime === null)
+        return BLOCK_REFUSAL.noClusterTime;
+    const claim = (track) => (track === trackNumber ? numbered : null);
+    const supply = (at, need) => {
+        const window = windows.find(at, need);
+        if (window === null)
+            throw new E.GrammarError();
+        return Promise.resolve(window);
+    };
+    try {
+        const claimed = await frameIn(outer, clusterTime, window, claim, supply);
+        if (claimed === null)
+            return BLOCK_REFUSAL.notThisTrack;
+        return typeof claimed === "string" ? claimed : claimed.frame;
+    }
+    catch (error) {
+        if (!E.isGrammarError(error))
+            throw error;
+        return BLOCK_REFUSAL.notFetched;
+    }
+}
+const MAX_CLUSTER_HEADER_BYTES = 4 + E.MAX_VINT_BYTES;
+function locateBlock(windows, { clusterPos, relPos }, memo) {
+    let last = memo.last;
+    if (last === null || last.clusterPos !== clusterPos) {
+        const head = windows.find(clusterPos, ELEMENT_HEADER_BYTES);
+        if (head === null)
+            return BLOCK_REFUSAL.notFetched;
+        const cluster = E.readElement(head, clusterPos);
+        if (typeof cluster === "string" || cluster.id !== E.ID.segment.CLUSTER) {
+            return BLOCK_REFUSAL.notACluster;
+        }
+        if ("open" in cluster)
+            return BLOCK_REFUSAL.openCluster;
+        const clusterTime = readClusterTime(head, cluster);
+        last = { clusterPos, cluster, clusterTime, window: head };
+        memo.last = last;
+    }
+    const { cluster, clusterTime } = last;
+    if (relPos >= cluster.size)
+        return BLOCK_REFUSAL.pastTheCluster;
+    const blockAt = cluster.body + relPos;
+    const bound = headerNeed(blockAt, cluster.next);
+    const held = last.window;
+    const window = E.covers(held, blockAt, bound) ? held : windows.find(blockAt, bound);
+    if (window === null)
+        return BLOCK_REFUSAL.notFetched;
+    last.window = window;
+    const outer = E.readElement(window, blockAt);
+    if (!E.fits(outer, cluster.next))
+        return BLOCK_REFUSAL.runsPastCluster;
+    if (!FRAME_IDS.has(outer.id))
+        return BLOCK_REFUSAL.notABlock;
+    return { clusterTime, window, blockAt, outer };
+}

package/dist/matroska/header.d.ts

@@ -0,0 +1,52 @@
+import type { Window } from "../ebml.js";
+import { type Source } from "../io/source.js";
+import type { Attachment, ContainerInfo, RefusalCode, TrackFlags, TrackTag, Wants } from "../vocabulary.js";
+import { type Segment } from "./chain.js";
+export interface TrackEntry {
+    streamIndex: number;
+    number: number;
+    uid: string | null;
+    codecId: string;
+    codecPrivate: string;
+    codecDelayNs: number;
+    type: number;
+    language: string | null;
+    languageIetf: string | null;
+    name: string | null;
+    flags: TrackFlags;
+    encoded: boolean;
+}
+export interface CuePosition {
+    clusterPos: number;
+    relPos: number;
+}
+/** @see {@linkcode readContainer|readContainer(source, "tracks")} */
+export interface TracksHeader {
+    segment: Segment;
+    trackEntries: TrackEntry[];
+    fileSize: number;
+    trackTags: Map<string, TrackTag[]>;
+    info: ContainerInfo;
+    attachments: Attachment[];
+}
+/** @see {@linkcode readContainer|readContainer(source, "timed")} */
+export interface TimedHeader extends TracksHeader {
+    head: Window;
+    firstClusterTicks: number | null;
+}
+/** @see {@linkcode readContainer|readContainer(source, "indexed")} */
+export interface IndexedHeader extends TimedHeader {
+    cues: Map<number, CuePosition[]>;
+}
+interface ContainerReadOptions extends Wants {
+    concurrency?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+export declare function readContainer(source: Source, depth: "tracks", options: ContainerReadOptions): Promise<TracksHeader | RefusalCode>;
+export declare function readContainer(source: Source, depth: "timed", options: ContainerReadOptions & {
+    concurrency: number;
+}): Promise<TimedHeader | RefusalCode>;
+export declare function readContainer(source: Source, depth: "indexed", options: ContainerReadOptions & {
+    concurrency: number;
+}): Promise<IndexedHeader | RefusalCode>;
+export {};