mkvpeek 0.1.0

package/dist/subtitle/tuning.js

@@ -0,0 +1,76 @@
+import { MAX_SPAN_BYTES } from "../io/source.js";
+export function knobsForIndex(source, options) {
+    const given = options.overrides;
+    const shipped = shippedFor(source, options);
+    return {
+        gapBytes: clampedKnob(given?.gapBytes, shipped.gapBytes, "gapBytes"),
+        cueAheadBytes: clampedKnob(given?.cueAheadBytes, shipped.cueAheadBytes, "cueAheadBytes"),
+        concurrency: clampedKnob(given?.concurrency, INDEX_CONCURRENCY, "concurrency"),
+    };
+}
+export function knobsForWalk(source, options) {
+    const given = options.overrides;
+    const shipped = shippedFor(source, options);
+    return {
+        blockAheadBytes: clampedKnob(given?.blockAheadBytes, shipped.blockAheadBytes, "blockAheadBytes"),
+        concurrency: clampedKnob(given?.concurrency, shipped.concurrency, "concurrency"),
+    };
+}
+const DEFAULT_PRESET = "balanced";
+const INDEX_CONCURRENCY = 16;
+const TRIP_BLIND = {
+    gapBytes: 0,
+    cueAheadBytes: 256,
+    blockAheadBytes: 0,
+    concurrency: 16,
+};
+const LOCAL_KNOBS = {
+    gapBytes: 8 * 1024,
+    cueAheadBytes: 256,
+    blockAheadBytes: 2 * 1024 ** 2,
+    concurrency: 2,
+};
+const MOUNT_KNOBS = {
+    gapBytes: 16 * 1024,
+    cueAheadBytes: 256,
+    blockAheadBytes: 128,
+    concurrency: 16,
+};
+const REMOTE_KNOBS = {
+    gapBytes: 64 * 1024,
+    cueAheadBytes: 1024,
+    blockAheadBytes: 8 * 1024,
+    concurrency: 16,
+};
+const TUNING = {
+    leanest: { local: TRIP_BLIND, mount: TRIP_BLIND, remote: TRIP_BLIND },
+    balanced: { local: LOCAL_KNOBS, mount: MOUNT_KNOBS, remote: REMOTE_KNOBS },
+    fastest: {
+        local: LOCAL_KNOBS,
+        mount: { ...MOUNT_KNOBS, blockAheadBytes: 16 * 1024 },
+        remote: { ...REMOTE_KNOBS, blockAheadBytes: 64 * 1024 },
+    },
+};
+const KNOB_MIN = {
+    gapBytes: 0,
+    cueAheadBytes: 16,
+    blockAheadBytes: 0,
+    concurrency: 1,
+};
+const KNOB_MAX = {
+    gapBytes: Number.POSITIVE_INFINITY,
+    cueAheadBytes: MAX_SPAN_BYTES / 4,
+    blockAheadBytes: MAX_SPAN_BYTES,
+    concurrency: 64,
+};
+const clampedKnob = (given, shipped, key) => given !== undefined && Number.isInteger(given) && given >= KNOB_MIN[key]
+    ? Math.min(given, KNOB_MAX[key])
+    : shipped;
+function shippedFor(source, options) {
+    const trip = source.trip;
+    const column = trip !== undefined && Object.hasOwn(TUNING[DEFAULT_PRESET], trip) ? trip : "mount";
+    const row = options.preset !== undefined && Object.hasOwn(TUNING, options.preset)
+        ? options.preset
+        : DEFAULT_PRESET;
+    return TUNING[row][column];
+}

package/dist/subtitle/walked.d.ts

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

package/dist/subtitle/walked.js

@@ -0,0 +1,28 @@
+import { walkFrames } from "../matroska/clusters.js";
+import { isNumbered } from "../tracks/subtitle.js";
+import { eventOf } from "./assemble.js";
+import { assembleTrack, planFrom } from "./conclude.js";
+export async function readByWalk(source, knobs, header, watch) {
+    const plan = planFrom(header);
+    if (typeof plan === "string")
+        return plan;
+    const { wanted, timeline } = plan;
+    const pass = { source, segment: header.segment, head: header.head, signal: watch.signal };
+    const numberedEntries = wanted.map((t) => [t.number, isNumbered(t)]);
+    const numberedByTrack = new Map(numberedEntries);
+    const framesByTrack = await walkFrames(pass, numberedByTrack, knobs, watch);
+    if (framesByTrack === null)
+        return "unreadable";
+    const out = new Map();
+    for (const track of wanted) {
+        const frames = framesByTrack.get(track.number);
+        if (frames === undefined || frames.length === 0)
+            return "unreadable";
+        const events = frames.map((frame) => eventOf(frame, timeline));
+        const assembled = assembleTrack(track, events, "whole");
+        if (typeof assembled === "string")
+            return assembled;
+        out.set(track.streamIndex, assembled.text);
+    }
+    return out;
+}

package/dist/tracks/core.d.ts

@@ -0,0 +1,25 @@
+import type { TrackEntry, TracksHeader } from "../matroska/header.js";
+import type { TrackFlags, TrackTag } from "../vocabulary.js";
+export type TrackType = "video" | "audio" | "complex" | "logo" | "subtitle" | "buttons" | "control" | "metadata" | "unknown";
+export interface Track<T extends TrackType = TrackType> {
+    type: T;
+    /**
+     * The position in the track list.
+     *
+     * The same count as ffmpeg's `0:N`.
+     */
+    index: number;
+    /** The container's TrackNumber. */
+    number: number;
+    uid: string | null;
+    codecId: string;
+    /** Exactly what the container states, unnormalised; only no statement is null. */
+    language: string | null;
+    languageIetf: string | null;
+    name: string | null;
+    flags: TrackFlags;
+    codecDelayNs: number;
+    tags: TrackTag[];
+}
+export declare const kindOf: (track: TrackEntry) => TrackType;
+export declare const trackCore: <T extends TrackType>(track: TrackEntry, header: TracksHeader, type: T) => Track<T>;

package/dist/tracks/core.js

@@ -0,0 +1,24 @@
+export const kindOf = (track) => KIND_BY_TYPE.get(track.type) ?? "unknown";
+export const trackCore = (track, header, type) => ({
+    type: type,
+    index: track.streamIndex,
+    number: track.number,
+    uid: track.uid,
+    codecId: track.codecId,
+    language: track.language,
+    languageIetf: track.languageIetf,
+    name: track.name,
+    flags: { ...track.flags },
+    codecDelayNs: track.codecDelayNs,
+    tags: track.uid === null ? [] : (header.trackTags.get(track.uid) ?? []).map((tag) => ({ ...tag })),
+});
+const KIND_BY_TYPE = new Map([
+    [1, "video"],
+    [2, "audio"],
+    [3, "complex"],
+    [16, "logo"],
+    [17, "subtitle"],
+    [18, "buttons"],
+    [32, "control"],
+    [33, "metadata"],
+]);

package/dist/tracks/list.d.ts

@@ -0,0 +1,8 @@
+import type { TracksHeader } from "../matroska/header.js";
+import { type Track, type TrackType } from "./core.js";
+import { type SubtitleTrack } from "./subtitle.js";
+export type ListedTrack = SubtitleTrack | Track<Exclude<TrackType, SpecializedType>>;
+/** The track types that have a specialised shape beyond the core. */
+type SpecializedType = "subtitle";
+export declare const allTracks: (header: TracksHeader) => ListedTrack[];
+export {};

package/dist/tracks/list.js

@@ -0,0 +1,6 @@
+import { kindOf, trackCore } from "./core.js";
+import { subtitleTrack } from "./subtitle.js";
+export const allTracks = (header) => header.trackEntries.map((track) => {
+    const kind = kindOf(track);
+    return kind === "subtitle" ? subtitleTrack(track, header) : trackCore(track, header, kind);
+});

package/dist/tracks/subtitle.d.ts

@@ -0,0 +1,45 @@
+import type { TrackEntry, TracksHeader } from "../matroska/header.js";
+import type { SubtitleFinder } from "../vocabulary.js";
+import { type Track } from "./core.js";
+export interface SubtitleTrack extends Track<"subtitle"> {
+    /** Its `null` state and {@linkcode unsupported} are mutually exclusive. */
+    format: "ass" | "srt" | "vtt" | null;
+    /**
+     * The subtitle track's body.
+     *
+     * null when it was not served, for one of the reasons below.
+     *
+     * - `SubtitleOptions.text===false`: bodies were explicitly not requested
+     *
+     * - {@linkcode unsupported}: this reader does not handle the track
+     *
+     * - `RefusalCode`: the read was refused
+     */
+    text: string | null;
+    /**
+     * The finder that served the body.
+     *
+     * It goes with {@linkcode text}: when the body is null, so is this.
+     */
+    servedBy: SubtitleFinder | null;
+    /**
+     * Describes what this reader does not handle, not a verdict on the track itself.
+     *
+     * - `codec`: PGS image subtitles, S_TEXT/USF, D_WEBVTT/METADATA and the like
+     *
+     * - `content-encoded`: the container says the frames are zlib-compressed,
+     *   header-stripped or encrypted
+     *
+     * - `null`: a kind the reader handles, which **does not guarantee it is always served**
+     */
+    unsupported: "codec" | "content-encoded" | null;
+}
+type SubtitleFormat = NonNullable<SubtitleTrack["format"]>;
+export declare const SUPPORTED_CODECS: ReadonlyMap<string, SubtitleFormat>;
+export declare const subtitleTracks: (header: TracksHeader) => SubtitleTrack[];
+export declare const subtitleEntries: (header: TracksHeader) => TrackEntry[];
+export declare const isSupported: (track: TrackEntry) => boolean;
+export declare const isNumbered: (track: TrackEntry) => boolean;
+export declare function subtitleTrack(track: TrackEntry, header: TracksHeader): SubtitleTrack;
+export declare function statedFrameCount(header: TracksHeader, track: TrackEntry): number | null;
+export {};

package/dist/tracks/subtitle.js

@@ -0,0 +1,38 @@
+import { kindOf, trackCore } from "./core.js";
+export const SUPPORTED_CODECS = new Map([
+    ["S_TEXT/ASS", "ass"],
+    ["S_TEXT/SSA", "ass"],
+    ["S_SSA", "ass"],
+    ["S_ASS", "ass"],
+    ["S_TEXT/UTF8", "srt"],
+    ["D_WEBVTT/SUBTITLES", "vtt"],
+    ["D_WEBVTT/CAPTIONS", "vtt"],
+]);
+export const subtitleTracks = (header) => subtitleEntries(header).map((track) => subtitleTrack(track, header));
+export const subtitleEntries = (header) => header.trackEntries.filter((track) => kindOf(track) === "subtitle");
+export const isSupported = (track) => unsupportedReason(track) === null;
+export const isNumbered = (track) => SUPPORTED_CODECS.get(track.codecId) === "ass";
+export function subtitleTrack(track, header) {
+    const unsupported = unsupportedReason(track);
+    return {
+        ...trackCore(track, header, "subtitle"),
+        format: unsupported === null ? (SUPPORTED_CODECS.get(track.codecId) ?? null) : null,
+        text: null,
+        servedBy: null,
+        unsupported,
+    };
+}
+export function statedFrameCount(header, track) {
+    if (track.uid === null)
+        return null;
+    const stated = header.trackTags.get(track.uid)?.find((tag) => tag.name === "NUMBER_OF_FRAMES");
+    if (stated === undefined)
+        return null;
+    const parsed = stated.value.trim() === "" ? Number.NaN : Number(stated.value);
+    return Number.isInteger(parsed) ? parsed : null;
+}
+function unsupportedReason(track) {
+    if (!SUPPORTED_CODECS.has(track.codecId))
+        return "codec";
+    return track.encoded ? "content-encoded" : null;
+}

package/dist/vocabulary.d.ts

@@ -0,0 +1,88 @@
+/** The words below the parser boundary: refusals and codes, delivery requests, container facts. */
+/**
+ * The flags whose structure the spec dictates.
+ *
+ * enabled, default and forced are effective values with the spec defaults (1, 1, 0) applied;
+ * the other five have no default.
+ */
+export interface TrackFlags {
+    enabled: boolean;
+    default: boolean;
+    forced: boolean;
+    hearingImpaired: boolean | null;
+    visualImpaired: boolean | null;
+    textDescriptions: boolean | null;
+    original: boolean | null;
+    commentary: boolean | null;
+}
+export interface ContainerInfo {
+    title: string | null;
+    muxingApp: string | null;
+    writingApp: string | null;
+    durationMs: number | null;
+    timestampScale: number;
+}
+export interface Attachment {
+    fileName: string | null;
+    mimeType: string | null;
+    description: string | null;
+    size: number;
+    uid: string | null;
+}
+export interface TrackTag {
+    name: string;
+    value: string;
+}
+/** What was asked to be delivered in the envelope. */
+export interface Wants {
+    info: boolean;
+    attachments: boolean;
+}
+/**
+ * The reasons a requested read could not be completed.
+ *
+ * - `not-matroska`: there is no EBML header.
+ *
+ * - `malformed`: the container does not conform.
+ *
+ * - `unreadable`: the container conforms, but this reader's path could not do it.
+ *
+ * - `source-failed`: the bytes did not arrive; retry, or check the transport.
+ *
+ * - `invalid-target`: the input itself cannot be opened; fix the call.
+ *
+ * - `cancelled`: the caller's signal fired.
+ */
+export type RefusalCode = "not-matroska" | "malformed" | "unreadable" | "source-failed" | "invalid-target" | "cancelled";
+/**
+ * Completion is the one code `served`.
+ *
+ * The refusal side can grow,
+ * so a branch on codes should leave room for a code that does not exist yet.
+ */
+export type PeekCode = "served" | RefusalCode;
+/** The two paths of a subtitle read. */
+export type SubtitleFinder = "index" | "walk";
+/**
+ * Whether the outcome is a refusal rather than a serve.
+ *
+ * @example
+ * const { code } = await peekSubtitles(path);
+ * if (isRefusalCode(code)) throw new Error(code);
+ */
+export declare const isRefusalCode: (code: PeekCode) => code is RefusalCode;
+/**
+ * Whether a file this reader refused is worth handing to another tool, ffmpeg say
+ *
+ * The test is whether another tool could do better with the same source,
+ * and a true is no guarantee of its success.
+ * A refusal that read the container is true;
+ * one where the bytes did not arrive or the call was wrong is false.
+ *
+ * @example
+ * const { code, tracks } = await peekSubtitles(path);
+ * if (!isRefusalCode(code)) return tracks;
+ * if (worthFallback(code)) return demux(path);
+ * throw new Error(code);
+ */
+export declare const worthFallback: (code: PeekCode) => boolean;

package/dist/vocabulary.js

@@ -0,0 +1,10 @@
+export const isRefusalCode = (code) => Object.hasOwn(REFUSALS, code);
+export const worthFallback = (code) => isRefusalCode(code) && REFUSALS[code].worthFallback;
+const REFUSALS = {
+    "not-matroska": { worthFallback: true },
+    malformed: { worthFallback: true },
+    unreadable: { worthFallback: true },
+    "source-failed": { worthFallback: false },
+    "invalid-target": { worthFallback: false },
+    cancelled: { worthFallback: false },
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "mkvpeek",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Matroska tracks, container info and subtitle text with no ffmpeg, no native module, and a fraction of the file read",
+  "keywords": [
+    "matroska",
+    "mkv",
+    "demux",
+    "ebml",
+    "subtitles",
+    "ass",
+    "ssa",
+    "srt",
+    "vtt",
+    "webvtt",
+    "ffmpeg",
+    "ffprobe"
+  ],
+  "author": "6lvkro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/6lvkro/mkvpeek.git"
+  },
+  "bugs": {
+    "url": "https://github.com/6lvkro/mkvpeek/issues"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "browser": {
+        "types": "./dist/browser.d.ts",
+        "default": "./dist/browser.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.1"
+  },
+  "scripts": {
+    "build": "tsx build.ts",
+    "lint": "biome check --error-on-warnings . && tsc -p tsconfig.json",
+    "format": "biome check --write .",
+    "check:package": "publint --strict && attw --pack . --profile esm-only",
+    "prepublishOnly": "pnpm run lint && pnpm run build && pnpm run check:package"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.5.12",
+    "@types/node": "^22.20.1",
+    "publint": "^0.3.24",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3"
+  },
+  "packageManager": "pnpm@12.3.4"
+}