@mieweb/pulsevault 0.4.2 → 0.6.0

package/dist/lib/web-ready.d.ts

@@ -1,8 +1,52 @@
 import type { PulseVaultLogger } from './request.js';
-export type WebReadyAction = 'none' | 'remuxed' | 'transcoded' | 'skipped';
+/**
+ * Conform uploaded videos to one web-playable format: the one the Pulse app records.
+ *
+ * A video reaches PulseVault from the Pulse app (already in the target format) or from a host's
+ * own file picker: a screen recording, an iPhone HEVC `.mov` (often 10-bit HDR), a WebM from a
+ * browser recorder, a 4K clip. Browsers streaming over progressive HTTP need the `moov` atom at
+ * the front, a codec they all decode, and 8-bit SDR colour; a phone needs a sane size.
+ *
+ * `ensureWebReady` does the least work that gets a file there: nothing when it already
+ * conforms (a Pulse upload keeps its bytes), a lossless remux when only the container or the
+ * `moov` position is off, and otherwise one ffmpeg run that re-encodes only the streams that
+ * are off-target. Fail-open by design: without `ffmpeg`/`ffprobe`, or when a run fails or
+ * times out, the original bytes keep serving and the result says why.
+ */
+/**
+ * The format every video is served in. "Already conforms" checks exactly these properties —
+ * never the orientation: a landscape video stays landscape and a portrait one portrait, with no
+ * crop, pad or stretch.
+ */
+export declare const CONFORM_TARGET: {
+    /** MP4 with the `moov` atom at the front (faststart). */
+    readonly container: "mp4";
+    readonly extension: ".mp4";
+    /**
+     * H.264, 8-bit 4:2:0 in limited range, even width and height, SDR, no rotation tag. HDR (PQ,
+     * HLG) is tone-mapped to BT.709; an SDR source keeps its own colour tags (BT.709 or BT.601),
+     * which browsers honour — so a Pulse upload from any phone keeps its bytes.
+     */
+    readonly videoCodec: "h264";
+    readonly pixelFormat: "yuv420p";
+    /** Default cap on the longest edge, in pixels (`webReady.maxEdge`). */
+    readonly maxEdge: 1920;
+    /** AAC; a video without audio stays silent. */
+    readonly audioCodec: "aac";
+};
+/** The containers the conform step turns into the target: the default video `allowedExtensions`. */
+export declare const CONFORM_VIDEO_EXTENSIONS: readonly string[];
+/**
+ * - `none`: already in the target format; the bytes are untouched.
+ * - `remuxed`: only the `moov` position was off; rewritten losslessly, same file.
+ * - `transcoded`: an MP4 whose video or audio was re-encoded, same file.
+ * - `conformed`: a different container (WebM, MKV, MOV, …) rewritten as a new `.mp4`.
+ * - `skipped`: nothing was done (no ffmpeg, a failed or timed-out run); the original serves.
+ */
+export type WebReadyAction = 'none' | 'remuxed' | 'transcoded' | 'conformed' | 'skipped';
 export type WebReadyResult = {
     action: WebReadyAction;
-    /** Human-readable explanation (what was detected, or why nothing was done). */
+    /** Human-readable explanation (what was detected and done, or why nothing was done). */
     reason: string;
 };
 export type WebReadyOptions = {
@@ -11,15 +55,34 @@ export type WebReadyOptions = {
     /** Path to the ffprobe binary. Default `"ffprobe"` (resolved via PATH). */
     ffprobePath?: string;
     /**
-     * Whether a non-web-safe codec triggers a full H.264 transcode. Default
-     * `true`. Set `false` to only ever do the lossless faststart remux —
-     * useful when transcode cost on the serving host is a concern.
+     * Whether an off-target stream is re-encoded. Default `true`. Set `false` to never re-encode:
+     * only lossless remuxes still run (a `moov` moved to the front, or another container whose
+     * streams already conform copied into an `.mp4`) — useful when transcode cost on the serving
+     * host is a concern.
      */
     transcode?: boolean;
+    /** Longest edge of the served video, in pixels; larger videos are scaled down. Default `1920`. */
+    maxEdge?: number;
     /** x264 CRF for the transcode path (lower = better/larger). Default `23`. */
     crf?: number;
     /** x264 preset for the transcode path. Default `"veryfast"`. */
     preset?: string;
+    /**
+     * Wall-clock limit for one ffmpeg run, in seconds; the run is killed and the original kept.
+     * A guard against a run that hangs, not a speed limit. Default `60 + 10 ×` the video's
+     * duration counted in 1080p30 seconds (a second of 4K at 120 fps counts 16), at most an hour,
+     * and an hour when the duration is unknown. The default comes from the upload's own metadata,
+     * so it's capped: a file can't claim its way to a days-long run. Set this for longer runs.
+     */
+    timeoutSeconds?: number;
+    /**
+     * `false`: leave every rewrite at a temporary `.mp4` path beside the input (the result's
+     * `outputPath`) instead of renaming it into place, so the caller can install it under its own
+     * lock and conditions. Default `true`.
+     */
+    install?: boolean;
+    /** Wall-clock limit for each ffprobe run over the upload, in seconds. Default `60`. */
+    probeTimeoutSeconds?: number;
     /** Optional logger; `error` fires when ffmpeg/ffprobe are missing or a rewrite fails. */
     logger?: PulseVaultLogger;
 };
@@ -32,23 +95,78 @@ export type MoovPosition = 'front' | 'end' | 'unknown';
  * costs microseconds regardless of file size.
  *
  * Returns `"unknown"` for non-MP4 bytes, truncated headers, or files missing
- * either box — callers should treat that as "leave the file alone".
+ * either box.
  */
 export declare function scanMoovPosition(filePath: string): Promise<MoovPosition>;
+/** What ffprobe says about a video: the streams the conform step maps, and its length. */
+export type VideoProbe = {
+    video: {
+        index: number;
+        codec: string;
+        pixelFormat: string;
+        width: number;
+        height: number;
+        /** The colour transfer (`bt709`, `arib-std-b67`, …), when tagged. */
+        transfer?: string;
+        /** `pc` for full range, `tv` for limited, when tagged. */
+        range?: string;
+        /**
+         * Display rotation in degrees from the stream's matrix: `0`, `90`, `-90` or `180`, or another
+         * angle in (-180, 180] when the matrix isn't within a degree of a quarter turn (not converted).
+         */
+        rotation: number;
+        /** Average frames per second, when ffprobe can tell. */
+        frameRate?: number;
+    };
+    /** The first audio stream, or `null` for a silent video. */
+    audio: {
+        index: number;
+        codec: string;
+    } | null;
+    /** Seconds, or `null` when neither the header nor the packets say. */
+    durationSeconds: number | null;
+};
+export type ProbeOptions = {
+    /** Path to the ffprobe binary. Default `"ffprobe"` (resolved via PATH). */
+    ffprobePath?: string;
+    /** Wall-clock limit for each ffprobe run, in seconds; past it the probe fails. Default `60`. */
+    timeoutSeconds?: number;
+};
+/** An ffprobe run past its `timeoutSeconds`: the file couldn't be read in time. */
+export declare class ProbeTimeoutError extends Error {
+}
+/**
+ * ffprobe a file: its first real video stream (not cover art), its first audio stream and its
+ * duration. `null` when it isn't a video: ffprobe can't read it, it has no video stream, or it
+ * is a picture (an image file, or a stream of one frame). Each ffprobe run is bounded by
+ * `timeoutSeconds`; past it, rejects with `ProbeTimeoutError`.
+ */
+export declare function probeVideo(filePath: string, options?: ProbeOptions): Promise<VideoProbe | null>;
+export declare function isBinaryAvailable(binPath: string): Promise<boolean>;
+/** Whether this host can conform videos: both `ffmpeg` and `ffprobe` run. */
+export declare function webReadyAvailable(options?: Pick<WebReadyOptions, 'ffmpegPath' | 'ffprobePath'>): Promise<boolean>;
+/** Fail at once on an option that can't work, for `ensureWebReady` and the core's `webReady`. */
+export declare function validateWebReadyOptions(options: WebReadyOptions): void;
 /**
- * Make the MP4 at `filePath` web-playable, in place:
+ * Bring the video at `filePath` to `CONFORM_TARGET`:
  *
- * - moov at the end + web-safe codec → lossless `-c copy -movflags +faststart`
- *   remux (sub-second, no quality change);
- * - non-web-safe codec (HEVC etc.) → one-time `libx264` transcode (audio
- *   stream-copied) with faststart;
- * - already faststart H.264, non-MP4 bytes, unprobeable files, or missing
- *   ffmpeg/ffprobe → untouched (`skipped`/`none`).
+ * - already conforming → `none`, bytes untouched;
+ * - an MP4 with conforming streams but the `moov` at the end → lossless faststart remux in
+ *   place (`remuxed`);
+ * - any other container with conforming streams → lossless remux into a new `.mp4` beside it
+ *   (`conformed`);
+ * - otherwise one ffmpeg run: the video re-encoded to H.264 when its codec, pixel format, bit
+ *   depth, size, rotation or dynamic range is off (scaled by the longest edge, rotation
+ *   applied, HDR tone-mapped), the audio re-encoded to AAC unless it already is — in place for
+ *   an MP4 (`transcoded`), into a new `.mp4` otherwise (`conformed`);
+ * - no ffmpeg/ffprobe, a file ffprobe can't read, a failed or timed-out run → `skipped` with
+ *   the reason; the original is untouched.
  *
- * The rewrite is atomic (tmp file + rename in the same directory), so a crash
- * mid-way never corrupts the served artifact. Never throws for pipeline
- * reasons — a failed ffmpeg run resolves to `skipped` with the reason, and the
- * original bytes keep serving.
+ * When the result carries `outputPath`, the conformed file was written there (`<name>.mp4`)
+ * and the original is left in place: the caller switches the artifact over, then removes it.
+ * With `install: false` nothing is renamed: every rewrite is left at a temporary path beside
+ * the input, returned as `outputPath`, for the caller to install (or remove).
+ * Never throws for pipeline reasons.
  *
  * NOTE: a rewrite changes the artifact's bytes, so any upload-time checksum
  * recorded for it (e.g. the local adapter's sidecar `checksum` from
@@ -56,5 +174,7 @@ export declare function scanMoovPosition(filePath: string): Promise<MoovPosition
  * Consumers verifying bytes against `getChecksum` must treat it as
  * upload-time provenance, not current-file integrity.
  */
-export declare function ensureWebReady(filePath: string, options?: WebReadyOptions): Promise<WebReadyResult>;
+export declare function ensureWebReady(filePath: string, options?: WebReadyOptions): Promise<WebReadyResult & {
+    outputPath?: string;
+}>;
 //# sourceMappingURL=web-ready.d.ts.map

package/dist/lib/web-ready.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-ready.d.ts","sourceRoot":"","sources":["../../src/lib/web-ready.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA4BrD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAE3E,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;AAEvD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA4C9E;AA4DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CA2DzB"}
+{"version":3,"file":"web-ready.d.ts","sourceRoot":"","sources":["../../src/lib/web-ready.ts"],"names":[],"mappings":"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"}