mkvpeek 0.1.0

package/dist/peek/target.js

@@ -0,0 +1,56 @@
+import { memorySource } from "../io/memory.js";
+import { abortReason } from "../io/source.js";
+import { urlSource, whyCredentialed, whyInadmissible } from "../io/url.js";
+import { absent, refused, wantsOf } from "./contract.js";
+export const urlRefusal = (parsed) => whyInadmissible(parsed) === null ? null : "invalid-target";
+export async function overTarget(target, options, work, open = viaUrl) {
+    const wants = wantsOf(options);
+    const absentAnswer = absent(wants);
+    if (typeof target !== "string") {
+        if (target instanceof ArrayBuffer || ArrayBuffer.isView(target)) {
+            let fromBytes;
+            try {
+                fromBytes = memorySource(target);
+            }
+            catch {
+                return refused("invalid-target", absentAnswer);
+            }
+            return work(fromBytes, options);
+        }
+        const readsAndSizes = target !== null &&
+            target !== undefined &&
+            typeof target.read === "function" &&
+            typeof target.size === "function";
+        if (readsAndSizes)
+            return work(target, options);
+        return refused("invalid-target", absentAnswer);
+    }
+    const parsed = URL.parse(target);
+    const secret = parsed === null ? null : whyCredentialed(parsed);
+    if (parsed !== null && secret !== null) {
+        return refused("invalid-target", absentAnswer);
+    }
+    let source;
+    try {
+        source = await open(target, options.signal);
+    }
+    catch {
+        if (abortReason(options.signal) !== null)
+            return refused("cancelled", absentAnswer);
+        return refused("source-failed", absentAnswer);
+    }
+    if (typeof source === "string")
+        return refused(source, absentAnswer);
+    try {
+        return await work(source, options);
+    }
+    finally {
+        await source.close?.().catch(() => { });
+    }
+}
+const viaUrl = async (target, signal) => {
+    const parsed = URL.parse(target);
+    if (parsed === null)
+        return "invalid-target";
+    return urlRefusal(parsed) ?? urlSource(target, { signal });
+};

package/dist/subtitle/assemble.d.ts

@@ -0,0 +1,21 @@
+export interface Event {
+    readOrder: number | null;
+    startMs: number;
+    durationMs: number;
+    payload: string;
+}
+export interface Timeline {
+    msPerTick: number;
+    shiftMs: number;
+}
+interface TickedFrame {
+    readOrder: number | null;
+    startTicks: number;
+    durationTicks: number | null;
+    payload: string;
+}
+export declare const eventOf: (frame: TickedFrame, timeline: Timeline) => Event;
+export declare function assembleAss(codecPrivate: string, events: readonly Event[]): string;
+export declare function assembleVtt(events: readonly Event[]): string;
+export declare function assembleSrt(events: readonly Event[]): string;
+export {};

package/dist/subtitle/assemble.js

@@ -0,0 +1,114 @@
+export const eventOf = (frame, timeline) => ({
+    readOrder: frame.readOrder,
+    startMs: frame.startTicks * timeline.msPerTick + timeline.shiftMs,
+    durationMs: (frame.durationTicks ?? 0) * timeline.msPerTick,
+    payload: frame.payload,
+});
+export function assembleAss(codecPrivate, events) {
+    const script = codecPrivate.replace(/\r\n/g, "\n");
+    const headEnd = assHeadEnd(script);
+    const ssaMode = /^\[V4 Styles\]/m.test(script);
+    const head = script.slice(0, headEnd);
+    const trailer = script.slice(headEnd);
+    let body = "";
+    for (const e of events) {
+        const { layer: raw, middle, text } = splitAssPayload(e.payload);
+        const marked = raw === "" ? "0" : raw;
+        const layer = ssaMode ? `Marked=${marked}` : raw;
+        const startCs = toCentiseconds(e.startMs);
+        body += `Dialogue: ${layer},${assTime(startCs)},${assTime(startCs + toCentiseconds(e.durationMs))},${middle},${text}\n`;
+    }
+    const separator = head.endsWith("\n") ? "" : "\r\n";
+    const written = `${head}${separator}${body === "" ? "\n" : body}${trailer}`;
+    return written.endsWith("\n") ? written : `${written}\n`;
+}
+export function assembleVtt(events) {
+    let body = "";
+    for (const e of events) {
+        const lines = e.payload.replace(/\r\n?/g, "\n").split("\n");
+        const whole = lines.length >= 3;
+        const id = whole ? lines[0] : "";
+        const settings = whole ? lines[1] : "";
+        const text = (whole ? lines.slice(2) : lines).join("\n").replace(/\n$/, "");
+        const start = Math.round(e.startMs);
+        const at = `${vttTime(start)} --> ${vttTime(start + Math.round(e.durationMs))}`;
+        const head = id === "" ? "" : `${id}\n`;
+        body += `\n${head}${at}${settings === "" ? "" : ` ${settings}`}\n${text}\n`;
+    }
+    return `WEBVTT\n${body === "" ? "\n\n" : body}`;
+}
+export function assembleSrt(events) {
+    let body = "";
+    let sequence = 0;
+    for (const e of events) {
+        sequence += 1;
+        const start = Math.round(e.startMs);
+        const text = e.payload.replace(/\r\n/g, "\n").replace(/\n$/, "");
+        body += `${String(sequence)}\n${srtTime(start)} --> ${srtTime(start + Math.round(e.durationMs))}\n${text}\n\n`;
+    }
+    return body;
+}
+const DIALOGUE_LAYER_FIELD = 1;
+const DIALOGUE_TEXT_FIELD = 8;
+const MS_PER_SECOND = 1000;
+const CS_PER_SECOND = 100;
+const toCentiseconds = (ms) => Math.round(ms / 10);
+const padded = (n, width = 2) => String(n).padStart(width, "0");
+const padded2 = (n) => (n < 10 ? `0${String(n)}` : String(n));
+function splitAssPayload(payload) {
+    const afterReadOrder = payload.indexOf(",");
+    const afterLayer = payload.indexOf(",", afterReadOrder + 1);
+    if (afterLayer < 0)
+        return { layer: payload.slice(afterReadOrder + 1), middle: "", text: "" };
+    let afterEffect = afterLayer;
+    for (let field = DIALOGUE_LAYER_FIELD + 1; field < DIALOGUE_TEXT_FIELD; field++) {
+        const next = payload.indexOf(",", afterEffect + 1);
+        if (next < 0) {
+            return {
+                layer: payload.slice(afterReadOrder + 1, afterLayer),
+                middle: payload.slice(afterLayer + 1),
+                text: "",
+            };
+        }
+        afterEffect = next;
+    }
+    return {
+        layer: payload.slice(afterReadOrder + 1, afterLayer),
+        middle: payload.slice(afterLayer + 1, afterEffect),
+        text: payload.slice(afterEffect + 1),
+    };
+}
+function assHeadEnd(script) {
+    const events = script.indexOf("\n[Events]");
+    if (events < 0)
+        return script.length;
+    const format = script.indexOf("Format:", events);
+    if (format < 0)
+        return script.length;
+    const eol = script.indexOf("\n", format);
+    return eol < 0 ? script.length : eol + 1;
+}
+function clockFields(duration, perSecond) {
+    const at = Math.max(0, duration);
+    const perMinute = 60 * perSecond;
+    const perHour = 60 * perMinute;
+    return {
+        hours: Math.floor(at / perHour),
+        minutes: Math.floor((at % perHour) / perMinute),
+        seconds: Math.floor((at % perMinute) / perSecond),
+        fraction: at % perSecond,
+    };
+}
+function assTime(cs) {
+    const { hours, minutes, seconds, fraction } = clockFields(cs, CS_PER_SECOND);
+    return `${String(hours)}:${padded2(minutes)}:${padded2(seconds)}.${padded2(fraction)}`;
+}
+function vttTime(ms) {
+    const { hours, minutes, seconds, fraction } = clockFields(ms, MS_PER_SECOND);
+    const belowHours = `${padded(minutes)}:${padded(seconds)}.${padded(fraction, 3)}`;
+    return hours === 0 ? belowHours : `${padded(hours)}:${belowHours}`;
+}
+function srtTime(ms) {
+    const { hours, minutes, seconds, fraction } = clockFields(ms, MS_PER_SECOND);
+    return `${padded(hours)}:${padded(minutes)}:${padded(seconds)},${padded(fraction, 3)}`;
+}

package/dist/subtitle/conclude.d.ts

@@ -0,0 +1,20 @@
+import type { TimedHeader, TrackEntry } from "../matroska/header.js";
+import type { RefusalCode } from "../vocabulary.js";
+import { type Event, type Timeline } from "./assemble.js";
+export type TrackTexts = Map<number, string>;
+export interface ReadPlan {
+    wanted: readonly TrackEntry[];
+    timeline: Timeline;
+}
+interface TrackBody {
+    text: string;
+}
+/**
+ * Whether the events handed over can be shown to be every frame of the track.
+ *
+ * A list cut at the front looks whole and answers the first frame wrongly.
+ */
+type Completeness = "whole" | "may-be-short";
+export declare function planFrom(header: TimedHeader): ReadPlan | RefusalCode;
+export declare function assembleTrack(track: TrackEntry, events: readonly Event[], completeness: Completeness): TrackBody | RefusalCode;
+export {};

package/dist/subtitle/conclude.js

@@ -0,0 +1,57 @@
+import { kindOf } from "../tracks/core.js";
+import { isNumbered, isSupported, SUPPORTED_CODECS, subtitleEntries } from "../tracks/subtitle.js";
+import { assembleAss, assembleSrt, assembleVtt } from "./assemble.js";
+export function planFrom(header) {
+    const wanted = subtitleEntries(header).filter(isSupported);
+    const timeline = timelineOf(header);
+    if (typeof timeline === "string")
+        return timeline;
+    return { wanted, timeline };
+}
+export function assembleTrack(track, events, completeness) {
+    const format = SUPPORTED_CODECS.get(track.codecId);
+    const numbered = isNumbered(track);
+    const ordered = orderedAndChecked(events, numbered, completeness);
+    if (typeof ordered === "string")
+        return ordered;
+    if (format === "ass")
+        return { text: assembleAss(track.codecPrivate, ordered) };
+    if (format === "vtt")
+        return { text: assembleVtt(ordered) };
+    void format;
+    return { text: assembleSrt(ordered) };
+}
+const NS_PER_MS = 1_000_000;
+const TIMELINE_KINDS = new Set(["video", "audio", "complex"]);
+function timelineOf(header) {
+    const shiftMs = timelineShift(header);
+    if (shiftMs === null) {
+        return "malformed";
+    }
+    return { msPerTick: header.info.timestampScale / NS_PER_MS, shiftMs };
+}
+function timelineShift(header) {
+    const delayNs = header.trackEntries.reduce((most, t) => Math.max(most, t.codecDelayNs), 0);
+    const delayMs = Math.round(delayNs / NS_PER_MS);
+    if (!header.trackEntries.some((t) => TIMELINE_KINDS.has(kindOf(t))))
+        return delayMs;
+    if (header.firstClusterTicks === null)
+        return null;
+    return delayMs - (header.firstClusterTicks * header.info.timestampScale) / NS_PER_MS;
+}
+function sortEvents(events, numbered) {
+    const ordered = [...events];
+    if (numbered)
+        ordered.sort((a, b) => (a.readOrder ?? 0) - (b.readOrder ?? 0));
+    else
+        ordered.sort((a, b) => a.startMs - b.startMs);
+    return ordered;
+}
+function orderedAndChecked(events, numbered, completeness) {
+    const ordered = sortEvents(events, numbered);
+    if (numbered && ordered.some((e) => e.readOrder === null))
+        return "malformed";
+    if (completeness === "may-be-short" && ordered[0]?.durationMs === 0)
+        return "unreadable";
+    return ordered;
+}

package/dist/subtitle/indexed.d.ts

@@ -0,0 +1,5 @@
+import { type IndexFetch, type Source, type Watch } from "../io/source.js";
+import type { IndexedHeader } from "../matroska/header.js";
+import type { RefusalCode } from "../vocabulary.js";
+import { type TrackTexts } from "./conclude.js";
+export declare function readByIndex(source: Source, knobs: IndexFetch, header: IndexedHeader, watch: Watch): Promise<TrackTexts | RefusalCode>;

package/dist/subtitle/indexed.js

@@ -0,0 +1,172 @@
+import { available, stopIfAborted, } from "../io/source.js";
+import { coalesce, fetchRanges, fetchSpans, WindowIndex } from "../io/windows.js";
+import { planRanges, planShortfall, readFrame } from "../matroska/cues.js";
+import { isNumbered, statedFrameCount } from "../tracks/subtitle.js";
+import { eventOf } from "./assemble.js";
+import { assembleTrack, planFrom } from "./conclude.js";
+export async function readByIndex(source, knobs, header, watch) {
+    const plan = planFrom(header);
+    if (typeof plan === "string")
+        return plan;
+    const collected = await followIndex(source, knobs, header, plan, watch);
+    if (!(collected instanceof Map))
+        return collected;
+    const out = new Map();
+    for (const track of plan.wanted) {
+        const events = collected.get(track.number) ?? [];
+        const vouched = anchorless(events) ? "may-be-short" : "whole";
+        const assembled = assembleTrack(track, events, vouched);
+        if (typeof assembled === "string")
+            return assembled;
+        out.set(track.streamIndex, assembled.text);
+    }
+    return out;
+}
+const FRAMES_PER_ROUND = 4096;
+const unheld = (ranges, headBytes, fileSize) => ranges.flatMap((range) => {
+    const length = available(range.at, range.length, fileSize);
+    if (length === 0 || range.at + length <= headBytes)
+        return [];
+    return [{ at: range.at, length }];
+});
+async function followIndex(source, knobs, header, plan, watch) {
+    const planned = planFrames(header, plan.wanted);
+    if (!Array.isArray(planned))
+        return planned;
+    const headBytes = header.head.bytes.length;
+    const rounds = [];
+    for (let start = 0; start < planned.length; start += FRAMES_PER_ROUND) {
+        const slice = planned.slice(start, start + FRAMES_PER_ROUND);
+        const cues = slice.map((p) => p.cue);
+        const wanted = planRanges(cues, knobs.cueAheadBytes);
+        const bought = unheld(wanted, headBytes, header.fileSize);
+        const spans = coalesce(bought, knobs);
+        const beyondHead = (sum, span) => sum + (span.at + span.length - Math.max(span.at, headBytes));
+        const round = { slice, cues, spans, bytes: spans.reduce(beyondHead, 0) };
+        rounds.push(round);
+    }
+    const totalBytes = headBytes + rounds.reduce((sum, r) => sum + r.bytes, 0);
+    watch.onProgress(headBytes, totalBytes);
+    const round = {
+        sized: { source, fileSize: header.fileSize },
+        knobs,
+        timeline: plan.timeline,
+        head: header.head,
+    };
+    const progressBytes = { headBytes, totalBytes };
+    const collected = await collectByRound(round, rounds, progressBytes, watch);
+    if (!Array.isArray(collected))
+        return collected;
+    return vouchedRuns(header, plan.wanted, collected);
+}
+function planFrames(header, wanted) {
+    const planned = [];
+    for (const track of wanted) {
+        const cues = header.cues.get(track.number);
+        if (cues === undefined || cues.length === 0) {
+            return "unreadable";
+        }
+        if (repeatedPosition(cues)) {
+            return "unreadable";
+        }
+        const numbered = isNumbered(track);
+        for (const cue of cues)
+            planned.push({ track, numbered, cue });
+    }
+    planned.sort((a, b) => a.cue.clusterPos - b.cue.clusterPos || a.cue.relPos - b.cue.relPos);
+    return planned;
+}
+function vouchedRuns(header, wanted, collected) {
+    const out = new Map();
+    for (const track of wanted) {
+        const events = collected.filter((e) => e.track === track.number).map((e) => e.event);
+        if (brokenRun(events))
+            return "unreadable";
+        const frames = statedFrameCount(header, track);
+        if (frames !== null && frames !== events.length) {
+            return "unreadable";
+        }
+        if (frames === null && !isNumbered(track)) {
+            return "unreadable";
+        }
+        if (frames === null && anchorless(events)) {
+            return "unreadable";
+        }
+        out.set(track.number, events);
+    }
+    return out;
+}
+function repeatedPosition(cues) {
+    const seen = new Map();
+    for (const { clusterPos, relPos } of cues) {
+        const inCluster = seen.get(clusterPos);
+        if (inCluster === undefined) {
+            const first = new Set([relPos]);
+            seen.set(clusterPos, first);
+            continue;
+        }
+        if (inCluster.has(relPos))
+            return true;
+        inCluster.add(relPos);
+    }
+    return false;
+}
+async function collectByRound(round, rounds, { headBytes, totalBytes }, { onProgress, signal }) {
+    const events = [];
+    let doneBytes = headBytes;
+    for (const { slice, cues, spans, bytes } of rounds) {
+        stopIfAborted(signal);
+        const first = await fetchSpans(round.sized, spans, round.knobs.concurrency, signal);
+        const index = new WindowIndex(first, round.head);
+        const missing = planShortfall(index, cues);
+        const shortfall = unheld(missing, headBytes, round.sized.fileSize);
+        const rest = await fetchRanges(round.sized, shortfall, round.knobs, signal);
+        const windows = new WindowIndex([...first, ...rest], round.head);
+        const roundEvents = await readRound(round.timeline, windows, slice);
+        if (!Array.isArray(roundEvents))
+            return roundEvents;
+        events.push(...roundEvents);
+        doneBytes += bytes;
+        onProgress(doneBytes, totalBytes);
+    }
+    stopIfAborted(signal);
+    return events;
+}
+async function readRound(timeline, windows, planned) {
+    const events = [];
+    const memo = { last: null };
+    for (const { track, numbered, cue: point } of planned) {
+        const frame = await readFrame(windows, point, track.number, numbered, memo);
+        if (typeof frame === "string")
+            return "unreadable";
+        const attributed = { track: track.number, event: eventOf(frame, timeline) };
+        events.push(attributed);
+    }
+    return events;
+}
+function anchorless(events) {
+    return (events.length > 0 &&
+        events.every((e) => e.readOrder !== null) &&
+        !events.some((e) => e.readOrder === 0));
+}
+function brokenRun(events) {
+    let low = Number.POSITIVE_INFINITY;
+    let high = Number.NEGATIVE_INFINITY;
+    let tally = 0;
+    const distinct = new Set();
+    for (const { readOrder } of events) {
+        if (readOrder === null)
+            break;
+        low = Math.min(low, readOrder);
+        high = Math.max(high, readOrder);
+        distinct.add(readOrder);
+        tally += 1;
+    }
+    if (tally === events.length && tally > 0) {
+        if (distinct.size !== tally)
+            return true;
+        if (high - low + 1 !== tally)
+            return true;
+    }
+    return false;
+}

package/dist/subtitle/options.d.ts

@@ -0,0 +1,76 @@
+import type { IndexFetch, WalkFetch } from "../io/source.js";
+import type { PeekOptions } from "../peek/contract.js";
+import type { SubtitleFinder } from "../vocabulary.js";
+export type FetchKnobs = IndexFetch & WalkFetch;
+/** What a caller can say about the cost of a read. */
+export interface SubtitleTuning {
+    preset?: SubtitlePreset;
+    overrides?: Partial<FetchKnobs>;
+}
+/**
+ * - `balanced`: (default) the knee of the time-transfer curve
+ *
+ * - `fastest`: minimises time.
+ *
+ * - `leanest`: minimises transfer.
+ */
+export type SubtitlePreset = "balanced" | "fastest" | "leanest";
+/**
+ * The policy for finding a subtitle track's frames.
+ *
+ * - `index`: follows the container's Cues and picks up only the frames.
+ * Fast, but a muxer may have written no index, so it accepts fewer containers than `walk`.
+ *
+ * - `walk`: visits every cluster. Slow, reading block by block, but it answers without an index.
+ *
+ * - `both`: (default) `index` first,
+ *   falling back to `walk` only when what made it back off was the index or the source.
+ *   When the container is at fault `walk` would do the same, so it ends.
+ */
+export type SubtitleVia = "both" | SubtitleFinder;
+/** The options of `peekSubtitles`. */
+export interface SubtitleOptions extends PeekOptions, SubtitleTuning {
+    /**
+     * An explicit `false` reads the header alone and returns early with no bodies.
+     *
+     * The finding half ({@linkcode via}, the tuning, {@linkcode onProgress}) is ignored then.
+     */
+    text?: boolean;
+    via?: SubtitleVia;
+    /**
+     * @example
+     * await peekSubtitles(path, {
+     *   onProgress: ({ done, total, finder }) => bar.set(finder, done / total),
+     * });
+     *
+     * @example
+     * // A budget, aborting past a per-path cap
+     * const stop = new AbortController();
+     * const most = { index: 100 * 1024 ** 2, walk: 1024 ** 3 };
+     * await peekSubtitles(path, {
+     *   via: "both",
+     *   signal: stop.signal,
+     *   onProgress: (p) => { if (p.total > most[p.finder]) stop.abort(); },
+     * });
+     */
+    onProgress?: (progress: SubtitleProgress) => void;
+}
+/**
+ * One progress report, which {@linkcode SubtitleOptions.onProgress} receives.
+ */
+export interface SubtitleProgress {
+    /**
+     * The path doing the reading.
+     *
+     * Under {@linkcode SubtitleVia} `both`, a `walk` here means `index` backed off.
+     */
+    finder: SubtitleFinder;
+    doneBytes: number;
+    /**
+     * - `index`: the bytes the plan means to fetch
+     *
+     * - `walk`: the file size
+     */
+    totalBytes: number;
+}
+export declare const DEFAULT_VIA: SubtitleVia;

package/dist/subtitle/options.js

@@ -0,0 +1 @@
+export const DEFAULT_VIA = "both";

package/dist/subtitle/peek.d.ts

@@ -0,0 +1,5 @@
+import type { Source } from "../io/source.js";
+import { type PeekOutcome } from "../peek/contract.js";
+import type { SubtitleTrack } from "../tracks/subtitle.js";
+import { type SubtitleOptions } from "./options.js";
+export declare function peekSubtitlesFrom(source: Source, options?: SubtitleOptions): Promise<PeekOutcome<SubtitleTrack>>;

package/dist/subtitle/peek.js

@@ -0,0 +1,107 @@
+import { abortReason } from "../io/source.js";
+import { readContainer } from "../matroska/header.js";
+import { absent, answerOf, refused, served, wantsOf } from "../peek/contract.js";
+import { fromHeader, thrownRefusal } from "../peek/engine.js";
+import { subtitleTracks } from "../tracks/subtitle.js";
+import { readByIndex } from "./indexed.js";
+import { DEFAULT_VIA } from "./options.js";
+import { knobsForIndex, knobsForWalk } from "./tuning.js";
+import { readByWalk } from "./walked.js";
+export async function peekSubtitlesFrom(source, options = {}) {
+    if (options.text === false)
+        return fromHeader(source, options, subtitleTracks);
+    const viaAsked = options.via;
+    const via = viaAsked !== undefined && Object.hasOwn(VIA_ROUTES, viaAsked) ? viaAsked : DEFAULT_VIA;
+    const wants = wantsOf(options);
+    let carried = null;
+    if (via === "index" || via === "both") {
+        const indexed = await attempt(source, options, wants, INDEX);
+        if (indexed.refusal === null)
+            return enveloped(indexed, wants);
+        const worthWalking = indexed.refusal === "unreadable" || indexed.refusal === "source-failed";
+        if (via === "index" || !worthWalking)
+            return enveloped(indexed, wants);
+        carried = indexed.header;
+    }
+    const walked = await attempt(source, options, wants, WALK, carried);
+    return enveloped(walked, wants);
+}
+const VIA_ROUTES = { both: true, index: true, walk: true };
+const INDEX = {
+    open: (source, wants, concurrency, signal) => {
+        const readOptions = { ...wants, concurrency, signal };
+        return readContainer(source, "indexed", readOptions);
+    },
+    knobsFor: knobsForIndex,
+    find: readByIndex,
+    finder: "index",
+};
+const WALK = {
+    open: (source, wants, concurrency, signal) => {
+        const readOptions = { ...wants, concurrency, signal };
+        return readContainer(source, "timed", readOptions);
+    },
+    knobsFor: knobsForWalk,
+    find: readByWalk,
+    finder: "walk",
+};
+const tracksWith = (header, text, servedBy) => subtitleTracks(header).map((track) => {
+    const body = text?.get(track.index) ?? null;
+    return { ...track, text: body, servedBy: body === null ? null : servedBy };
+});
+function reporter(listener, finder) {
+    if (listener === undefined)
+        return () => { };
+    return (doneBytes, totalBytes) => {
+        try {
+            listener({ finder, doneBytes, totalBytes });
+        }
+        catch { }
+    };
+}
+async function attempt(source, options, wants, route, carried = null) {
+    const signal = options.signal;
+    if (abortReason(signal) !== null)
+        return stopped(carried);
+    const watch = { onProgress: reporter(options.onProgress, route.finder), signal };
+    const knobs = route.knobsFor(source, options);
+    const header = carried ??
+        (await route
+            .open(source, wants, knobs.concurrency, signal)
+            .catch((error) => thrownRefusal(error, "malformed", signal)));
+    if (typeof header === "string")
+        return { refusal: header, header: null };
+    if (abortReason(signal) !== null)
+        return stopped(header);
+    const listed = tracksWith(header, null, null);
+    if (listed.every((track) => track.unsupported !== null)) {
+        return { refusal: null, header, tracks: listed };
+    }
+    try {
+        const texts = await route.find(source, knobs, header, watch);
+        if (typeof texts === "string")
+            return { refusal: texts, header, tracks: listed };
+        const tracks = tracksWith(header, texts, route.finder);
+        return { refusal: null, header, tracks };
+    }
+    catch (error) {
+        const refusal = thrownRefusal(error, "unreadable", signal);
+        return { refusal, header, tracks: listed };
+    }
+}
+function enveloped(tried, wants) {
+    const absentAnswer = absent(wants);
+    if (tried.header === null)
+        return refused(tried.refusal, absentAnswer);
+    const answer = answerOf(tried.header, tried.tracks, wants);
+    if (tried.refusal === null)
+        return served(answer);
+    return refused(tried.refusal, answer);
+}
+function stopped(header) {
+    const refusal = "cancelled";
+    if (header === null)
+        return { refusal, header: null };
+    const tracks = tracksWith(header, null, null);
+    return { refusal, header, tracks };
+}

package/dist/subtitle/tuning.d.ts

@@ -0,0 +1,4 @@
+import type { IndexFetch, Source, WalkFetch } from "../io/source.js";
+import type { SubtitleTuning } from "./options.js";
+export declare function knobsForIndex(source: Source, options: SubtitleTuning): IndexFetch;
+export declare function knobsForWalk(source: Source, options: SubtitleTuning): WalkFetch;