mkvpeek 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 6lvkro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# mkvpeek
+
+Looks at the tracks of a Matroska container without demuxing the whole of it.
+
+```text
+Measured on a 2.2 GB file on a local NVMe drive
+
+ffprobe -show_streams video.mkv                      1.2 MB read   21 ms
+peekTracks("video.mkv")                              135 KB read   0.6 ms
+
+ffmpeg -i video.mkv -map 0:s:0 -c:s copy out.ass     2.2 GB read   609 ms
+peekSubtitles("video.mkv")                           1.6 MB read   60 ms
+```
+
+The two `peek` lines are calls made from a Node process that is already running; the two tools are timed from being spawned as a subprocess to their exit.
+
+It performs well when both hold: a low-latency link and the fast path (see [path selection](#constraints-and-read-path-selection)).
+
+## When to use it
+
+- You want the track list and the container info without an external demuxer
+- You need to read a container in the browser with no WASM dependency
+- The container sits on a server that allows Range requests
+- You need a subtitle track as a whole, not as a stream of events
+- You want a subtitle track extracted quickly, with fewer reads (or less transfer)
+
+Assembling a body is, for now, the subtitle track's alone, and it supports the `ASS` / `SSA` / `SRT` / `VTT` formats.
+
+## Install
+
+```sh
+npm install mkvpeek
+```
+
+Node 22.1 or later, no other dependencies.
+
+## Usage
+
+There are two entry points, and a refusal answers with a code instead of throwing.
+
+`peekTracks` reads only the header and returns every kind of track; `peekSubtitles` returns subtitle tracks with their bodies.
+
+```ts
+import { peekSubtitles, peekTracks, urlSource } from "mkvpeek";
+
+// A file path (Node only)
+await peekTracks("video.mkv");
+await peekSubtitles("video.mkv");
+
+// A URL, when the server allows Range requests
+await peekTracks("https://host/video.mkv");
+
+// A Uint8Array or an ArrayBuffer
+await peekTracks(bytes);
+
+// For options the package cannot predefine, open the source yourself; whoever opens it closes it.
+const source = await urlSource(url, { headers });
+try {
+  await peekTracks(source);
+} finally {
+  await source.close?.();
+}
+```
+
+If the bytes are already in hand, just pass them.
+
+But **reading a file up front only to pass it in throws away the benefit of reading just what is needed.**
+The links where that benefit is worth giving up are discussed at the end of [path selection](#constraints-and-read-path-selection).
+
+```ts
+import { peekSubtitles } from "mkvpeek/browser";
+
+// A source that reads a File lazily
+await peekSubtitles({
+  size: () => Promise.resolve(file.size),
+  read: async (at, n) => new Uint8Array(await file.slice(at, at + n).arrayBuffer()),
+});
+```
+
+In the browser, `mkvpeek/browser` is the same reader minus file paths.
+
+## Constraints and read path selection
+
+> The read path does not apply to `peekTracks`, which reads only the header; it applies only when subtitle bodies are involved.
+
+Matroska containers usually carry `Cues`, a list of frame positions, but the list can be short or wrong.
+So that a subtitle body the caller asked for is not silently lost when the list falls short,
+the default is to back off the fast path (`index`) and retry along the slow path (`walk`), which visits every cluster.
+
+Even with `walk`, though, the range of containers this handles falls short of the external tools.
+If an external tool is available, the recommendation is to use the fast path (`index`) explicitly and hand refused files to that tool.
+On containers where `index` works, both speed and transfer come out well ahead of the binaries, and that alone makes it worth it.
+
+```ts
+import { peekSubtitles, worthFallback } from "mkvpeek";
+
+const { code, tracks } = await peekSubtitles(path, { via: "index" });
+if (worthFallback(code)) await demux(path);
+```
+
+On a high-latency network link the slow path (`walk`) loses much of its speed to round trips,
+so accepting the transfer, downloading the whole file once on the consumer side and passing the bytes can be faster.
+
+The package does not provide a download path of its own, and it refuses any response to a Range request other than 206.
+
+## Oracle
+
+Expected output is verified against ffprobe and ffmpeg, and the deliberate exceptions are, so far, these two.
+
+- **When a track does not state its `language`**
+  ffprobe emits `eng` as a default; the package emits `null`.
+
+- **When a frame in the body does not state its `duration`**
+  ffmpeg uses a derived value; the package uses 0.
+
+If something the spec defines is distorted or lost in a non-refused return, outside these two, it can be treated as a bug.
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,12 @@
+export { peekSubtitles, peekTracks } from "./entry/browser.js";
+export type { Source, Trip } from "./io/source.js";
+export type { UrlOptions } from "./io/url.js";
+export { urlSource } from "./io/url.js";
+export type { PeekOptions, PeekOutcome } from "./peek/contract.js";
+export type { Target } from "./peek/target.js";
+export type { SubtitleOptions, SubtitlePreset, SubtitleProgress, SubtitleTuning, SubtitleVia, } from "./subtitle/options.js";
+export type { Track, TrackType } from "./tracks/core.js";
+export type { ListedTrack } from "./tracks/list.js";
+export type { SubtitleTrack } from "./tracks/subtitle.js";
+export type { Attachment, ContainerInfo, PeekCode, RefusalCode, SubtitleFinder, TrackFlags, TrackTag, } from "./vocabulary.js";
+export { isRefusalCode, worthFallback } from "./vocabulary.js";

package/dist/browser.js

@@ -0,0 +1,3 @@
+export { peekSubtitles, peekTracks } from "./entry/browser.js";
+export { urlSource } from "./io/url.js";
+export { isRefusalCode, worthFallback } from "./vocabulary.js";

package/dist/ebml.d.ts

@@ -0,0 +1,168 @@
+export interface Element {
+    id: number;
+    size: number;
+    body: number;
+    next: number;
+}
+/** An element that states no size. */
+export interface OpenElement {
+    id: number;
+    body: number;
+    open: true;
+}
+/**
+ * A view of part of the file.
+ *
+ * Every coordinate is absolute, so it carries where it came from and how far the file goes.
+ */
+export interface Window {
+    readonly at: number;
+    readonly bytes: Uint8Array;
+    readonly fileSize: number;
+}
+interface Vint {
+    value: number;
+    length: number;
+    /** The all-ones shape that means the size is unknown. */
+    allOnes: boolean;
+}
+/** Nothing could be read at some position. */
+type Unread = "unread";
+/**
+ * Thrown where a walk that stopped quietly
+ * would turn a damaged list into a short one that looks whole.
+ *
+ * {@linkcode isGrammarError} tells which it was.
+ */
+export declare class GrammarError extends Error {
+}
+export declare const DEFAULT_TIMESTAMP_SCALE = 1000000;
+/**
+ * The widest a vint gets.
+ *
+ * Every header-size constant downstream derives from this number.
+ */
+export declare const MAX_VINT_BYTES = 8;
+/**
+ * The element ids this reader knows.
+ *
+ * @see {@link https://www.matroska.org/technical/elements.html}
+ */
+export declare const ID: {
+    readonly root: {
+        readonly EBML: 440786851;
+        readonly SEGMENT: 408125543;
+    };
+    readonly segment: {
+        readonly SEEK_HEAD: 290298740;
+        readonly INFO: 357149030;
+        readonly TRACKS: 374648427;
+        readonly TAGS: 307544935;
+        readonly CUES: 475249515;
+        readonly CLUSTER: 524531317;
+        readonly CHAPTERS: 272869232;
+        readonly ATTACHMENTS: 423732329;
+    };
+    readonly seek: {
+        readonly ENTRY: 19899;
+        readonly ID: 21419;
+        readonly POSITION: 21420;
+    };
+    readonly info: {
+        readonly TIMESTAMP_SCALE: 2807729;
+        readonly TITLE: 31657;
+        readonly MUXING_APP: 19840;
+        readonly WRITING_APP: 22337;
+        readonly DURATION: 17545;
+    };
+    readonly track: {
+        readonly ENTRY: 174;
+        readonly NUMBER: 215;
+        readonly UID: 29637;
+        readonly TYPE: 131;
+        readonly CODEC_ID: 134;
+        readonly CODEC_PRIVATE: 25506;
+        readonly CODEC_DELAY: 22186;
+        readonly LANGUAGE: 2274716;
+        readonly LANGUAGE_IETF: 2274717;
+        readonly NAME: 21358;
+        readonly FLAG_DEFAULT: 136;
+        readonly FLAG_FORCED: 21930;
+        readonly FLAG_ENABLED: 185;
+        readonly FLAG_HEARING_IMPAIRED: 21931;
+        readonly FLAG_VISUAL_IMPAIRED: 21932;
+        readonly FLAG_TEXT_DESCRIPTIONS: 21933;
+        readonly FLAG_ORIGINAL: 21934;
+        readonly FLAG_COMMENTARY: 21935;
+        readonly CONTENT_ENCODINGS: 28032;
+    };
+    readonly attachment: {
+        readonly FILE: 24999;
+        readonly FILE_NAME: 18030;
+        readonly FILE_MIME: 18016;
+        readonly FILE_DESCRIPTION: 18046;
+        readonly FILE_DATA: 18012;
+        readonly FILE_UID: 18094;
+    };
+    readonly tag: {
+        readonly ENTRY: 29555;
+        readonly TARGETS: 25536;
+        readonly TRACK_UID: 25541;
+        readonly SIMPLE: 26568;
+        readonly NAME: 17827;
+        readonly STRING: 17543;
+    };
+    readonly cue: {
+        readonly POINT: 187;
+        readonly TRACK_POSITIONS: 183;
+        readonly TRACK: 247;
+        readonly CLUSTER_POSITION: 241;
+        readonly RELATIVE_POSITION: 240;
+    };
+    readonly cluster: {
+        readonly TIMESTAMP: 231;
+        readonly SIMPLE_BLOCK: 163;
+        readonly BLOCK_GROUP: 160;
+        readonly POSITION: 167;
+        readonly PREV_SIZE: 171;
+        readonly SILENT_TRACKS: 22612;
+        readonly ENCRYPTED_BLOCK: 175;
+    };
+    readonly blockGroup: {
+        readonly BLOCK: 161;
+        readonly BLOCK_DURATION: 155;
+    };
+    readonly global: {
+        readonly CRC32: 191;
+        readonly VOID: 236;
+    };
+};
+/** Decoded as a sized element. */
+export declare const decoded: (el: Element | OpenElement | Unread) => el is Element;
+/** Decoded as a sized element that ends within its parent. */
+export declare const fits: (el: Element | OpenElement | Unread, end: number) => el is Element;
+export declare const covers: (window: Window, at: number, length: number) => boolean;
+export declare const reachOf: (window: Window) => number;
+export declare const isGrammarError: (error: unknown) => boolean;
+export declare const decodeUtf8: (bytes: Uint8Array) => string;
+export declare const uintFits: (size: number) => boolean;
+export declare function readVint(window: Window, at: number, as: "id" | "size"): Vint | Unread;
+export declare function vintLength(lead: number): number;
+/**
+ * The value of a vint whose length is known.
+ *
+ * `id` keeps the marker bit so the value compares to the constants as is; `size` drops it.
+ */
+export declare function vintValue(bytes: Uint8Array, start: number, length: number, as: "id" | "size"): number;
+/** The all-ones shape of a size vint, which means the size is unknown. */
+export declare function vintAllOnes(bytes: Uint8Array, start: number, length: number): boolean;
+export declare function uintAt(bytes: Uint8Array, start: number, size: number): number;
+export declare function readElement(window: Window, at: number): Element | OpenElement | Unread;
+export declare function children(window: Window, body: number, size: number): Generator<Element>;
+export declare function readFloat(window: Window, el: Element): number | null;
+export declare function readUint(window: Window, el: Element): number | null;
+export declare function readUid(window: Window, el: Element): string | null;
+export declare function readAscii(window: Window, el: Element): string;
+export declare function readUtf8(window: Window, el: Element): string;
+export declare function readBytes(window: Window, at: number, length: number): Uint8Array;
+export {};

package/dist/ebml.js

@@ -0,0 +1,224 @@
+export class GrammarError extends Error {
+}
+export const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
+export const MAX_VINT_BYTES = 8;
+export const ID = {
+    root: {
+        EBML: 0x1a45dfa3,
+        SEGMENT: 0x18538067,
+    },
+    segment: {
+        SEEK_HEAD: 0x114d9b74,
+        INFO: 0x1549a966,
+        TRACKS: 0x1654ae6b,
+        TAGS: 0x1254c367,
+        CUES: 0x1c53bb6b,
+        CLUSTER: 0x1f43b675,
+        CHAPTERS: 0x1043a770,
+        ATTACHMENTS: 0x1941a469,
+    },
+    seek: {
+        ENTRY: 0x4dbb,
+        ID: 0x53ab,
+        POSITION: 0x53ac,
+    },
+    info: {
+        TIMESTAMP_SCALE: 0x2ad7b1,
+        TITLE: 0x7ba9,
+        MUXING_APP: 0x4d80,
+        WRITING_APP: 0x5741,
+        DURATION: 0x4489,
+    },
+    track: {
+        ENTRY: 0xae,
+        NUMBER: 0xd7,
+        UID: 0x73c5,
+        TYPE: 0x83,
+        CODEC_ID: 0x86,
+        CODEC_PRIVATE: 0x63a2,
+        CODEC_DELAY: 0x56aa,
+        LANGUAGE: 0x22b59c,
+        LANGUAGE_IETF: 0x22b59d,
+        NAME: 0x536e,
+        FLAG_DEFAULT: 0x88,
+        FLAG_FORCED: 0x55aa,
+        FLAG_ENABLED: 0xb9,
+        FLAG_HEARING_IMPAIRED: 0x55ab,
+        FLAG_VISUAL_IMPAIRED: 0x55ac,
+        FLAG_TEXT_DESCRIPTIONS: 0x55ad,
+        FLAG_ORIGINAL: 0x55ae,
+        FLAG_COMMENTARY: 0x55af,
+        CONTENT_ENCODINGS: 0x6d80,
+    },
+    attachment: {
+        FILE: 0x61a7,
+        FILE_NAME: 0x466e,
+        FILE_MIME: 0x4660,
+        FILE_DESCRIPTION: 0x467e,
+        FILE_DATA: 0x465c,
+        FILE_UID: 0x46ae,
+    },
+    tag: {
+        ENTRY: 0x7373,
+        TARGETS: 0x63c0,
+        TRACK_UID: 0x63c5,
+        SIMPLE: 0x67c8,
+        NAME: 0x45a3,
+        STRING: 0x4487,
+    },
+    cue: {
+        POINT: 0xbb,
+        TRACK_POSITIONS: 0xb7,
+        TRACK: 0xf7,
+        CLUSTER_POSITION: 0xf1,
+        RELATIVE_POSITION: 0xf0,
+    },
+    cluster: {
+        TIMESTAMP: 0xe7,
+        SIMPLE_BLOCK: 0xa3,
+        BLOCK_GROUP: 0xa0,
+        POSITION: 0xa7,
+        PREV_SIZE: 0xab,
+        SILENT_TRACKS: 0x5854,
+        ENCRYPTED_BLOCK: 0xaf,
+    },
+    blockGroup: {
+        BLOCK: 0xa1,
+        BLOCK_DURATION: 0x9b,
+    },
+    global: {
+        CRC32: 0xbf,
+        VOID: 0xec,
+    },
+};
+export const decoded = (el) => typeof el !== "string" && !("open" in el);
+export const fits = (el, end) => decoded(el) && el.next <= end;
+export const covers = (window, at, length) => offsetOf(window, at, length) >= 0;
+export const reachOf = (window) => window.at + window.bytes.length;
+export const isGrammarError = (error) => error instanceof GrammarError;
+export const decodeUtf8 = (bytes) => UTF8.decode(bytes);
+export const uintFits = (size) => size <= MAX_VINT_BYTES;
+export function readVint(window, at, as) {
+    const start = offsetOf(window, at, 1);
+    if (start < 0)
+        return "unread";
+    const length = vintLength(window.bytes[start]);
+    if (length > MAX_VINT_BYTES)
+        return "unread";
+    if (offsetOf(window, at, length) < 0)
+        return "unread";
+    const value = vintValue(window.bytes, start, length, as);
+    const allOnes = vintAllOnes(window.bytes, start, length);
+    return { value, length, allOnes };
+}
+export function vintLength(lead) {
+    let length = 1;
+    while (length <= MAX_VINT_BYTES && (lead & (0x80 >> (length - 1))) === 0) {
+        length += 1;
+    }
+    return length;
+}
+export function vintValue(bytes, start, length, as) {
+    const lead = bytes[start];
+    let value = as === "id" ? lead : lead & (ALL_BITS >> length);
+    for (let i = 1; i < length; i++) {
+        value = value * 256 + bytes[start + i];
+    }
+    return value;
+}
+export function vintAllOnes(bytes, start, length) {
+    const leadValueBits = ALL_BITS >> length;
+    if ((bytes[start] & leadValueBits) !== leadValueBits)
+        return false;
+    for (let i = 1; i < length; i++) {
+        if (bytes[start + i] !== ALL_BITS)
+            return false;
+    }
+    return true;
+}
+export function uintAt(bytes, start, size) {
+    let value = 0;
+    for (let i = 0; i < size; i++) {
+        value = value * 256 + bytes[start + i];
+    }
+    return value;
+}
+export function readElement(window, at) {
+    const { fileSize } = window;
+    const id = readVint(window, at, "id");
+    if (typeof id === "string")
+        return id;
+    const size = readVint(window, at + id.length, "size");
+    if (typeof size === "string")
+        return size;
+    const body = at + id.length + size.length;
+    if (size.allOnes) {
+        if (id.value !== ID.root.SEGMENT && id.value !== ID.segment.CLUSTER)
+            return "unread";
+        return { id: id.value, body, open: true };
+    }
+    if (body + size.value > fileSize)
+        return "unread";
+    return { id: id.value, size: size.value, body, next: body + size.value };
+}
+export function* children(window, body, size) {
+    let at = body;
+    const end = body + size;
+    while (at < end) {
+        const el = readElement(window, at);
+        const invalidGrammar = typeof el === "string" || "open" in el || el.next > end;
+        if (invalidGrammar)
+            throw new GrammarError();
+        yield el;
+        at = el.next;
+    }
+}
+export function readFloat(window, el) {
+    const bytes = readBytes(window, el.body, el.size);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (el.size === 4)
+        return view.getFloat32(0);
+    if (el.size === 8)
+        return view.getFloat64(0);
+    return null;
+}
+export function readUint(window, el) {
+    if (!uintFits(el.size))
+        return null;
+    const start = offsetOf(window, el.body, el.size);
+    if (start < 0)
+        throw new GrammarError();
+    return uintAt(window.bytes, start, el.size);
+}
+export function readUid(window, el) {
+    let hex = "";
+    for (const byte of readBytes(window, el.body, el.size)) {
+        hex += byte.toString(16).padStart(2, "0");
+    }
+    const trimmed = hex.replace(/^0+/, "");
+    return trimmed === "" ? null : trimmed;
+}
+export function readAscii(window, el) {
+    let out = "";
+    for (const byte of readBytes(window, el.body, el.size)) {
+        out += String.fromCharCode(byte);
+    }
+    return out.replace(/\0+$/, "");
+}
+export function readUtf8(window, el) {
+    return decodeUtf8(readBytes(window, el.body, el.size));
+}
+export function readBytes(window, at, length) {
+    const start = offsetOf(window, at, length);
+    if (start < 0) {
+        throw new GrammarError();
+    }
+    return window.bytes.subarray(start, start + length);
+}
+const ALL_BITS = 0xff;
+const KEEPS_BOM = { ignoreBOM: true };
+const UTF8 = new TextDecoder("utf-8", KEEPS_BOM);
+function offsetOf(window, at, length) {
+    const start = at - window.at;
+    return start < 0 || start + length > window.bytes.length ? -1 : start;
+}

package/dist/entry/browser.d.ts

@@ -0,0 +1,44 @@
+import type { PeekOptions, PeekOutcome } from "../peek/contract.js";
+import { type Target } from "../peek/target.js";
+import type { SubtitleOptions } from "../subtitle/options.js";
+import type { ListedTrack } from "../tracks/list.js";
+import type { SubtitleTrack } from "../tracks/subtitle.js";
+/**
+ * Peeks at a container's subtitles.
+ *
+ * @example
+ * // Bytes already in memory (an upload body, a queue message)
+ * const { code, tracks } = await peekSubtitles(bytes);
+ *
+ * @example
+ * // A URL, when the server allows Range requests
+ * const { code, tracks } = await peekSubtitles(url);
+ *
+ * @example
+ * // Options the package cannot predefine: open the source yourself, and close what you opened.
+ * const source = await urlSource(url, { headers });
+ * try {
+ *   const { code, tracks } = await peekSubtitles(source);
+ * } finally {
+ *   await source.close?.();
+ * }
+ *
+ * @example
+ * // Without loading an uploaded File into memory
+ * const source: Source = {
+ *   size: () => Promise.resolve(file.size),
+ *   read: async (at, n) => new Uint8Array(await file.slice(at, at + n).arrayBuffer()),
+ * };
+ * const { code, tracks } = await peekSubtitles(source);
+ */
+export declare function peekSubtitles(target: Target, options?: SubtitleOptions): Promise<PeekOutcome<SubtitleTrack>>;
+/**
+ * Peeks at a container's track list
+ *
+ * Track-level facts only, every kind flat in one array.
+ *
+ * @example
+ * const { tracks } = await peekTracks(url);
+ * const dubbed = tracks.filter((t) => t.type === "audio" && t.language !== null);
+ */
+export declare function peekTracks(target: Target, options?: PeekOptions): Promise<PeekOutcome<ListedTrack>>;

package/dist/entry/browser.js

@@ -0,0 +1,9 @@
+import { peekTracksFrom } from "../peek/engine.js";
+import { overTarget } from "../peek/target.js";
+import { peekSubtitlesFrom } from "../subtitle/peek.js";
+export function peekSubtitles(target, options = {}) {
+    return overTarget(target, options, peekSubtitlesFrom);
+}
+export function peekTracks(target, options = {}) {
+    return overTarget(target, options, peekTracksFrom);
+}

package/dist/entry/node.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The entry point that also takes file paths.
+ *
+ * The browser bundle takes only URLs and bytes, on a surface of the same names.
+ */
+import type { PeekOptions, PeekOutcome } from "../peek/contract.js";
+import { type Target } from "../peek/target.js";
+import type { SubtitleOptions } from "../subtitle/options.js";
+import type { ListedTrack } from "../tracks/list.js";
+import type { SubtitleTrack } from "../tracks/subtitle.js";
+/**
+ * Peeks at a container's subtitles.
+ *
+ * For examples beyond file paths, see the same name in `mkvpeek/browser`.
+ *
+ * @example
+ * const { code, tracks } = await peekSubtitles(path);
+ *
+ * @example
+ * // The list alone, one read of the head and no bodies. Bodies cost the index or a walk.
+ * const { code, tracks } = await peekSubtitles(path, { text: false });
+ */
+export declare function peekSubtitles(target: Target, options?: SubtitleOptions): Promise<PeekOutcome<SubtitleTrack>>;
+/**
+ * Peeks at a container's track list
+ *
+ * Track-level facts only, every kind flat in one array.
+ *
+ * For examples beyond file paths, see the same name in `mkvpeek/browser`.
+ *
+ * @example
+ * const { tracks, info, attachments } = await peekTracks(path, {
+ *   info: true,
+ *   attachments: true,
+ * });
+ */
+export declare function peekTracks(target: Target, options?: PeekOptions): Promise<PeekOutcome<ListedTrack>>;

package/dist/entry/node.js

@@ -0,0 +1,38 @@
+import { fileSource } from "../io/file.js";
+import { isHttpUrl, namesAuthority } from "../io/url.js";
+import { urlSource } from "../io/url-node.js";
+import { peekTracksFrom } from "../peek/engine.js";
+import { overTarget, urlRefusal } from "../peek/target.js";
+import { peekSubtitlesFrom } from "../subtitle/peek.js";
+export function peekSubtitles(target, options = {}) {
+    return overTarget(target, options, peekSubtitlesFrom, viaPath);
+}
+export function peekTracks(target, options = {}) {
+    return overTarget(target, options, peekTracksFrom, viaPath);
+}
+const viaPath = async (target, signal) => {
+    if (isHttpUrl(target))
+        return urlSource(target, { signal });
+    if (namesAuthority(target)) {
+        const parsed = URL.parse(target);
+        if (parsed !== null) {
+            const refusal = urlRefusal(parsed);
+            if (refusal !== null)
+                return refusal;
+        }
+    }
+    try {
+        return await fileSource(target);
+    }
+    catch (error) {
+        const parsed = URL.parse(target);
+        const intendedAsUrl = parsed !== null &&
+            (parsed.protocol === "file:" || parsed.search !== "" || parsed.hash !== "");
+        if (intendedAsUrl) {
+            const refusal = urlRefusal(parsed);
+            if (refusal !== null)
+                return refusal;
+        }
+        throw error;
+    }
+};