@getvitops/utils 2.0.0 → 2.1.0

package/dist/media/index.d.mts

@@ -0,0 +1,277 @@
+//#region src/media/types.d.ts
+/**
+ * The media module's own option surface.
+ *
+ * Everything here describes *how to encode*, never *what the site is* — which is
+ * why there is no `SiteConfig` block behind it. `legal`, `icons` and `indexing`
+ * are anchored to a site config because what they emit describes the site; an
+ * encoder setting describes a build step.
+ */
+/** What a source video is turned into. */
+type OutputKind = 'webm' | 'mp4' | 'poster';
+/** The default set: a modern codec, a universal fallback, and a poster frame. */
+declare const DEFAULT_OUTPUTS: OutputKind[];
+/** File extension per output kind. */
+declare const OUTPUT_EXT: Record<OutputKind, string>;
+/**
+ * Bumped when the ffmpeg arguments in `ffmpeg.ts` change in a way that alters the
+ * output bytes. It is part of the settings hash, so bumping it re-encodes every
+ * source on the next run.
+ *
+ * Bump it deliberately and rarely. Consumers commit their processed outputs (see
+ * the README), so every bump is a large binary diff in someone's repository —
+ * that cost is worth paying for a real encoder fix and not for a tidy-up.
+ */
+declare const ENCODER_VERSION = 1;
+/** How to encode. Every field here feeds the settings hash. */
+interface MediaConfig {
+  /**
+   * Cap the output width in pixels, preserving aspect ratio. Default 1920.
+   *
+   * A source larger than its display size is the usual reason a hero video is
+   * enormous, so this is on by default rather than opt-in. `0` disables scaling.
+   */
+  maxWidth?: number | undefined;
+  /**
+   * Constant-quality level, on **VP9's CRF scale (0–63, lower is better)**.
+   * Default 32, which is the range VP9's own guidance recommends for 1080p.
+   *
+   * H.264 uses a different scale (0–51), so the MP4 fallback is encoded at
+   * `round(crf * 0.72)` — 23 at the default, x264's own default. One knob, because
+   * two would drift apart and nobody would know which one mattered.
+   */
+  crf?: number | undefined;
+  /**
+   * Optional ceiling, e.g. `'2M'`. Absent by default: a bitrate cap makes the
+   * encode constrained-quality rather than constant-quality, which is right when
+   * you are protecting a data budget and wrong as a default, because the correct
+   * cap depends on the resolution you are capping.
+   */
+  maxBitrate?: string | undefined;
+  /**
+   * Keep the audio track. Default false — the common case is a muted autoplay
+   * loop, where the audio stream is bytes nobody will ever hear.
+   */
+  audio?: boolean | undefined;
+  /**
+   * Timestamp (seconds) the poster frame is taken from. Default 0.
+   *
+   * Frame 0 is often black on a clip that fades in, which is worth knowing before
+   * concluding the poster is broken.
+   */
+  posterTime?: number | undefined;
+  /** Which outputs to produce. Default `DEFAULT_OUTPUTS`. */
+  outputs?: OutputKind[] | undefined;
+}
+/** A discovered source video. */
+interface MediaSource {
+  /** Absolute path on disk. */
+  path: string;
+  /**
+   * Path relative to the raw directory, POSIX-separated — the manifest key.
+   * Relative so a manifest stays valid when the project moves or is cloned
+   * somewhere else, which is the whole point of committing it.
+   */
+  id: string;
+  /** sha256 of the file contents, truncated. */
+  hash: string;
+}
+/** One file an encode will write. */
+interface MediaOutput {
+  kind: OutputKind;
+  /** Path relative to the output directory, POSIX-separated. */
+  file: string;
+}
+/** One source and everything decided about it. */
+interface MediaJob {
+  source: MediaSource;
+  outputs: MediaOutput[];
+  /** Hash of the settings these outputs were produced under. */
+  settings: string;
+  /** Why this job needs no work. Present iff it is being skipped. */
+  skip?: string | undefined;
+}
+/** The complete account of a run, decided before any of it happens. */
+interface MediaPlan {
+  jobs: MediaJob[];
+  /** Things the operator needs to read. Printed by `--dry` and by a real run. */
+  notes: string[];
+}
+/** One manifest record: what these outputs were made from, and under what settings. */
+interface MediaManifestEntry {
+  /** `MediaSource.hash` at the time of encoding. */
+  source: string;
+  /** Settings hash at the time of encoding. */
+  settings: string;
+  /** Output paths relative to the output directory. */
+  outputs: string[];
+}
+/**
+ * The cache. A committed artifact, so it carries no timestamp and its keys are
+ * sorted — a rebuild of unchanged sources must produce a byte-identical file, or
+ * it shows up as noise in every diff.
+ */
+interface MediaManifest {
+  version: 1;
+  entries: Record<string, MediaManifestEntry>;
+}
+//#endregion
+//#region src/media/discover.d.ts
+/** Container formats worth accepting as input. */
+declare const VIDEO_EXT: ReadonlySet<string>;
+/** Directories that never hold hand-managed source assets. */
+declare const DISCOVER_SKIP: ReadonlySet<string>;
+/** sha256 of the file contents, streamed. Truncated — 16 hex chars is 64 bits. */
+declare function hashFile(path: string): Promise<string>;
+/**
+ * Every video under `dir`, with its content hash.
+ *
+ * Sorted by `id` so a plan — and therefore the manifest and the log — comes out in
+ * the same order on every machine, regardless of what the filesystem hands back.
+ */
+declare function discoverVideos(dir: string): Promise<MediaSource[]>;
+//#endregion
+//#region src/media/plan.d.ts
+/** Defaults, resolved once so the settings hash is computed over real values. */
+interface ResolvedMediaConfig {
+  maxWidth: number;
+  crf: number;
+  maxBitrate: string | undefined;
+  audio: boolean;
+  posterTime: number;
+  outputs: OutputKind[];
+}
+/**
+ * Injected existence probe — `plan.ts` touches no filesystem itself.
+ *
+ * Takes a path relative to the output directory. The same injection shape as
+ * `collectEntries(source, read)` in `indexing/sitemap.ts`.
+ */
+type OutputProbe = (relativePath: string) => boolean;
+interface MediaPlanInput {
+  sources: MediaSource[];
+  config?: MediaConfig | undefined;
+  /** The previous run's manifest, if there is a usable one. */
+  previous?: MediaManifest | undefined;
+  /** Whether an output file is already on disk. Defaults to "nothing exists". */
+  probe?: OutputProbe | undefined;
+  /** `--force`: re-encode regardless of the cache. */
+  force?: boolean | undefined;
+}
+/** Fill in defaults. Exported because the encoder and the hash must agree on them. */
+declare function resolveConfig(config?: MediaConfig): ResolvedMediaConfig;
+/**
+ * Hash the settings that decide the output bytes.
+ *
+ * Order-independent in the one place it could bite (`outputs` is sorted), so
+ * re-ordering the list in a config doesn't re-encode a whole library.
+ */
+declare function settingsHash(config: ResolvedMediaConfig): string;
+/**
+ * Decide what to encode.
+ *
+ * A job is skipped only when all three hold: the source contents hash the same as
+ * last time, the settings hash the same, and every declared output is still on
+ * disk. Anything else re-encodes — including an absent or unreadable manifest,
+ * which reads as "encode everything" and never as "everything is done".
+ *
+ * Throws on an output collision (`hero.mp4` and `hero.mov` in one directory both
+ * want `hero.webm`). That is a layout mistake rather than a runtime condition, and
+ * the failure it would otherwise cause — two sources overwriting each other every
+ * run, each invalidating the other's cache entry — is invisible from the outside.
+ */
+declare function planMedia(input: MediaPlanInput): MediaPlan;
+/** The jobs that will actually run. */
+declare const pendingJobs: (plan: MediaPlan) => MediaJob[];
+/** Human-readable account of a plan, for `--dry` and for the run summary. */
+declare function formatPlan(plan: MediaPlan): string;
+//#endregion
+//#region src/media/ffmpeg.d.ts
+/**
+ * Fail early and clearly when ffmpeg isn't installed.
+ *
+ * Deliberately not the `optimizePng` shape in `favicon.ts`, which swallows a
+ * missing `oxipng` and warns once. That is right for a best-effort lossless crush,
+ * where skipping costs a few kilobytes. It is wrong here: skipping produces no
+ * output at all, and a build that carries on would ship the page referencing a
+ * video that was never encoded.
+ */
+declare function requireFfmpeg(): Promise<void>;
+/**
+ * VP9/WebM, two passes.
+ *
+ * The pass log goes into a fresh temp directory rather than the working directory.
+ * ffmpeg's default (`ffmpeg2pass-0.log`, in cwd) makes cleanup cwd-dependent and
+ * makes two concurrent encodes silently share one log — the second encode's rate
+ * control then reads the first clip's statistics.
+ */
+declare function encodeWebm(input: string, output: string, config: ResolvedMediaConfig): Promise<void>;
+/**
+ * H.264/MP4 — the fallback that makes `<video>` work on older iOS and in the
+ * in-app webviews that still don't decode VP9.
+ *
+ * `+faststart` moves the moov atom to the front. Without it the browser has to
+ * download the whole file before it can show frame one, which on a hero video
+ * looks exactly like the optimisation didn't work.
+ */
+declare function encodeMp4(input: string, output: string, config: ResolvedMediaConfig): Promise<void>;
+/** The poster frame. `-ss` before `-i` so the seek is a fast one. */
+declare function extractPoster(input: string, output: string, config: ResolvedMediaConfig): Promise<void>;
+//#endregion
+//#region src/media/manifest.d.ts
+/** Default location, relative to the consumer's project root. */
+declare const MEDIA_MANIFEST_PATH = ".vitops/media-manifest.json";
+/**
+ * Read the manifest, or `undefined` when there isn't a usable one.
+ *
+ * A corrupt or wrong-version file reads as absent, which re-encodes everything.
+ * The opposite reading — treating it as an empty but valid manifest — is the same
+ * shape of bug `readSnapshot` avoids, except here it would be silent: nothing
+ * would encode, and the build would reference outputs that were never written.
+ */
+declare function readManifest(path: string): MediaManifest | undefined;
+/** Build a manifest with its keys and output lists in a stable order. */
+declare function toManifest(entries: Record<string, MediaManifestEntry>): MediaManifest;
+/**
+ * Write the manifest, creating its directory.
+ *
+ * Record a job only once its outputs are on disk. Writing eagerly would mark a
+ * source as encoded that isn't, and because the next run trusts this file, the
+ * result is a missing video that no rebuild ever fixes.
+ */
+declare function writeManifest(path: string, manifest: MediaManifest): void;
+//#endregion
+//#region src/media/index.d.ts
+interface ProcessMediaOptions {
+  /** Directory of unprocessed sources. Walked recursively. */
+  raw: string;
+  /** Where the encoded outputs go. Structure under `raw` is preserved. */
+  out: string;
+  config?: MediaConfig | undefined;
+  /** Cache location. Default `.vitops/media-manifest.json`. */
+  manifest?: string | undefined;
+  /** Re-encode regardless of the cache. */
+  force?: boolean | undefined;
+  /** Decide everything, run nothing. */
+  dry?: boolean | undefined;
+  /** Called before each source is encoded — these take minutes, so say so. */
+  onProgress?: ((message: string) => void) | undefined;
+}
+interface ProcessMediaResult {
+  plan: MediaPlan;
+  /** Outputs written this run, relative to `out`. */
+  written: string[];
+  /** Sources that needed no work. */
+  skipped: number;
+}
+/**
+ * Encode everything under `raw` that has changed since the last run.
+ *
+ * Callers get the cache for free because it lives here rather than in either of
+ * them: `vitops media` and the Astro integration are equally incremental, since
+ * they call this same function.
+ */
+declare function processMedia(options: ProcessMediaOptions): Promise<ProcessMediaResult>;
+//#endregion
+export { DEFAULT_OUTPUTS, DISCOVER_SKIP, ENCODER_VERSION, MEDIA_MANIFEST_PATH, type MediaConfig, type MediaJob, type MediaManifest, type MediaManifestEntry, type MediaOutput, type MediaPlan, type MediaPlanInput, type MediaSource, OUTPUT_EXT, type OutputKind, type OutputProbe, ProcessMediaOptions, ProcessMediaResult, type ResolvedMediaConfig, VIDEO_EXT, discoverVideos, encodeMp4, encodeWebm, extractPoster, formatPlan, hashFile, pendingJobs, planMedia, processMedia, readManifest, requireFfmpeg, resolveConfig, settingsHash, toManifest, writeManifest };
+//# sourceMappingURL=index.d.mts.map

package/dist/media/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/media/types.ts","../../src/media/discover.ts","../../src/media/plan.ts","../../src/media/ffmpeg.ts","../../src/media/manifest.ts","../../src/media/index.ts"],"mappings":"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"}