@de-otio/trellis 0.11.0 → 0.12.1

package/dist/lib/media/classify-worker-error.js

@@ -0,0 +1,319 @@
+/**
+ * classify-worker-error.ts — pure functional core, no I/O, no AWS SDK.
+ *
+ * Classifies any error thrown by a media-processing worker into one of two
+ * treatment buckets:
+ *
+ *   "poison"    — the media itself (or the job payload) is bad. A retry cannot
+ *                 help: the same bytes will fail the same way. The caller must
+ *                 ACK the message and move the object to moderationStatus=REVIEW
+ *                 for human triage, avoiding an infinite DLQ loop.
+ *
+ *   "retryable" — a transient infrastructure fault: throttling, timeout, 5xx
+ *                 upstream, network blip, eventual-consistency AccessDenied.
+ *                 The caller lets SQS retry naturally; the 3-strike DLQ + alert
+ *                 acts as the upper bound.
+ *
+ * DEFAULT RULE (documented here — the only operative "fallback threshold"):
+ *   When the error is unknown or cannot be classified with confidence, the
+ *   function returns "retryable". Rationale: an unrecognised error is more
+ *   likely to be a transient infra fault than a permanent media defect, and the
+ *   DLQ + 3-strike alert provides a bounded safety net. Silently sending
+ *   ambiguous errors to REVIEW would suppress alerts and hide systemic infra
+ *   problems. This default is deliberately fail-OPEN for retry but
+ *   fail-CLOSED for approval — REVIEW is never returned from this module; the
+ *   caller owns the status mapping.
+ *
+ * PURITY GUARANTEE: this module has no I/O, no AWS SDK dependency, no
+ * Date.now/Math.random. node:crypto is NOT used. All inputs produce
+ * deterministic outputs.
+ */
+// ---------------------------------------------------------------------------
+// Known poison error names / codes
+// ---------------------------------------------------------------------------
+/**
+ * Error `.name` values that indicate a permanent media/payload defect.
+ * All matching is case-insensitive to absorb capitalisation variance.
+ */
+const POISON_ERROR_NAMES = new Set([
+    // Standard decode/parse failures
+    "decodeerror",
+    "parseerror",
+    "formaterror",
+    "syntaxerror",
+    // Validation failures (payload, schema, duration)
+    "validationerror",
+    "schemaerror",
+    "constrainterror",
+    "durationerror",
+    "durationcapexceeded",
+    // Unsupported / corrupt media
+    "unsupportedformaterror",
+    "unsupportedmediaerror",
+    "unsupportedtypeerror",
+    "corrupterror",
+    "corruptmediaerror",
+    "corruptfileerror",
+    "invalidimageerror",
+    "invalidmediaerror",
+    "invalidpayloaderror",
+    "invalidinputerror",
+    // AWS Rekognition / media-specific permanent errors
+    "invalidimageexception",
+    "imagetoolargeexception",
+    "invalidparameter",
+    "invalidparameterexception",
+    "invalids3objectexception",
+]);
+/**
+ * Error `.name` substrings (lowercased) that indicate a poison condition.
+ * Used when the name doesn't match exactly but carries an indicative fragment.
+ */
+const POISON_NAME_FRAGMENTS = [
+    "decode",
+    "parse",
+    "corrupt",
+    "invalid",
+    "unsupported",
+    "format",
+    "duration",
+    "validation",
+    "schema",
+    "constraint",
+    "payload",
+];
+/**
+ * Error message substrings (lowercased) that indicate a permanent media fault
+ * even when the error name itself is generic (e.g. plain `Error`).
+ */
+const POISON_MESSAGE_FRAGMENTS = [
+    "decode",
+    "corrupt",
+    "unsupported format",
+    "unsupported media",
+    "unsupported type",
+    "invalid format",
+    "invalid image",
+    "invalid media",
+    "invalid payload",
+    "invalid input",
+    "duration cap",
+    "duration exceeded",
+    "duration limit",
+    "too large",
+    "cannot parse",
+    "failed to parse",
+    "failed to decode",
+    "not a valid",
+    "malformed",
+];
+// ---------------------------------------------------------------------------
+// Known retryable error names / codes
+// ---------------------------------------------------------------------------
+/**
+ * HTTP status codes (from AWS SDK `$metadata.httpStatusCode` or elsewhere) that
+ * indicate a transient upstream fault. 4xx codes are explicitly enumerated —
+ * only the "transient 4xx" set (429 + 503/504 aliases sometimes arrive as 4xx
+ * depending on SDK version) are retryable; all other 4xx are poison (client
+ * error, not fixable by retry).
+ */
+const RETRYABLE_HTTP_STATUS = new Set([
+    429, // Too Many Requests / throttle
+    500, // Internal Server Error
+    502, // Bad Gateway
+    503, // Service Unavailable
+    504, // Gateway Timeout
+]);
+/**
+ * AWS SDK error `.name` values (and common equivalents) that map to transient
+ * infrastructure faults. Matched case-insensitively.
+ */
+const RETRYABLE_ERROR_NAMES = new Set([
+    // AWS throttle / quota
+    "throttlingexception",
+    "requestlimitexceeded",
+    "provisionedthroughputexceededexception",
+    "limitsexceededexception",
+    "servicequotaexceededexception",
+    "toomanyrequestsexception",
+    // AWS transient service errors
+    "serviceexception",
+    "internalfailure",
+    "internalservererror",
+    "serviceunavailableexception",
+    "serviceunavailable",
+    "requesttimeoutexception",
+    "requestexpired",
+    "requesttimeout",
+    // AWS eventual-consistency access issues (retryable — policy propagation lag)
+    "accessdeniedexception",
+    // Network / socket
+    "networkerror",
+    "networktimeout",
+    "connectionerror",
+    "connectionreset",
+    "connectiontimeout",
+    "sockettimeout",
+    "econnreset",
+    "econnrefused",
+    "enotfound",
+    "etimedout",
+    "ehostunreach",
+    // Generic timeout
+    "timeouterror",
+    "aborterror",
+    "fetcherror",
+]);
+/**
+ * Error message substrings (lowercased) that indicate a transient fault even
+ * when the error name is generic.
+ */
+const RETRYABLE_MESSAGE_FRAGMENTS = [
+    "throttl",
+    "rate limit",
+    "rate exceeded",
+    "quota exceeded",
+    "too many requests",
+    "timeout",
+    "timed out",
+    "connection reset",
+    "network error",
+    "socket hang up",
+    "econnreset",
+    "econnrefused",
+    "service unavailable",
+    "temporarily unavailable",
+    "try again",
+    "please retry",
+    "internal server error",
+    "502",
+    "503",
+    "504",
+];
+// ---------------------------------------------------------------------------
+// Main classifier
+// ---------------------------------------------------------------------------
+/**
+ * Classifies `err` as `"poison"` or `"retryable"`.
+ *
+ * - TOTAL: never throws for any input (including null, undefined, non-Error objects).
+ * - FAIL-CLOSED on unknown: returns `"retryable"` when the error cannot be
+ *   classified with confidence (DLQ + alert is the bounded backstop).
+ * - Poison wins over retryable when signals conflict (conservative for serving
+ *   safety: a bad payload that also triggers throttle is still bad).
+ */
+export function classifyWorkerError(err) {
+    // --- 1. Pull every signal we can out of the value, safely. ---
+    const name = safeString(extractName(err));
+    const message = safeString(extractMessage(err));
+    const httpStatus = extractHttpStatus(err);
+    const code = safeString(extractCode(err));
+    // --- 2. Poison checks (take priority). ---
+    if (isPoisonByName(name))
+        return "poison";
+    if (isPoisonByMessage(message))
+        return "poison";
+    // String errors that look like decode/parse failures
+    if (typeof err === "string" && isPoisonByMessage(err.toLowerCase())) {
+        return "poison";
+    }
+    // --- 3. Retryable checks. ---
+    if (httpStatus !== undefined && RETRYABLE_HTTP_STATUS.has(httpStatus)) {
+        return "retryable";
+    }
+    if (isRetryableByName(name))
+        return "retryable";
+    if (isRetryableByName(code))
+        return "retryable";
+    if (isRetryableByMessage(message))
+        return "retryable";
+    if (typeof err === "string" && isRetryableByMessage(err.toLowerCase())) {
+        return "retryable";
+    }
+    // --- 4. Unknown — default to retryable (see module-level docstring). ---
+    return "retryable";
+}
+// ---------------------------------------------------------------------------
+// Predicate helpers
+// ---------------------------------------------------------------------------
+function isPoisonByName(name) {
+    if (!name)
+        return false;
+    if (POISON_ERROR_NAMES.has(name))
+        return true;
+    // Fragment scan: e.g. "UnsupportedFormatException" contains "format"
+    return POISON_NAME_FRAGMENTS.some((f) => name.includes(f));
+}
+function isPoisonByMessage(msg) {
+    if (!msg)
+        return false;
+    return POISON_MESSAGE_FRAGMENTS.some((f) => msg.includes(f));
+}
+function isRetryableByName(name) {
+    if (!name)
+        return false;
+    return RETRYABLE_ERROR_NAMES.has(name);
+}
+function isRetryableByMessage(msg) {
+    if (!msg)
+        return false;
+    return RETRYABLE_MESSAGE_FRAGMENTS.some((f) => msg.includes(f));
+}
+// ---------------------------------------------------------------------------
+// Safe extraction helpers — never throw
+// ---------------------------------------------------------------------------
+function extractName(err) {
+    if (err === null || err === undefined)
+        return undefined;
+    if (typeof err === "object") {
+        return err.name;
+    }
+    return undefined;
+}
+function extractMessage(err) {
+    if (err === null || err === undefined)
+        return undefined;
+    if (typeof err === "object") {
+        return err.message;
+    }
+    return undefined;
+}
+function extractCode(err) {
+    if (err === null || err === undefined)
+        return undefined;
+    if (typeof err === "object") {
+        const o = err;
+        // AWS SDK v3 uses .code or .__type; normalise both
+        return o.code ?? o.__type;
+    }
+    return undefined;
+}
+function extractHttpStatus(err) {
+    if (err === null || err === undefined)
+        return undefined;
+    if (typeof err !== "object")
+        return undefined;
+    const o = err;
+    // AWS SDK v3: err.$metadata.httpStatusCode
+    const meta = o.$metadata;
+    if (meta !== null && meta !== undefined && typeof meta === "object") {
+        const status = meta.httpStatusCode;
+        if (typeof status === "number")
+            return status;
+    }
+    // Generic: err.statusCode or err.status
+    const statusCode = o.statusCode ?? o.status;
+    if (typeof statusCode === "number")
+        return statusCode;
+    return undefined;
+}
+/**
+ * Coerce an extracted value to a lowercase string for matching.
+ * Returns `""` for anything that cannot be cleanly turned into a string.
+ */
+function safeString(value) {
+    if (typeof value === "string")
+        return value.toLowerCase();
+    return "";
+}
+//# sourceMappingURL=classify-worker-error.js.map

package/dist/lib/media/classify-worker-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-worker-error.js","sourceRoot":"","sources":["../../../src/lib/media/classify-worker-error.ts"],"names":[],"mappings":"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"}

package/dist/lib/media/dedupe-key.d.ts

@@ -0,0 +1,29 @@
+import type { DedupeKeyInput } from "./processing-types.js";
+export type { DedupeKeyInput };
+/**
+ * Derive a stable, collision-resistant dedupe key for one (contentHash, jobId,
+ * track) tuple.
+ *
+ * Implementation: encode the three fields as a length-prefixed canonical form,
+ * then SHA-256 hash it. Length-prefix encoding ensures that distinct tuples
+ * cannot be made to collide by crafting delimiter-containing field values
+ * (e.g. a jobId that itself contains a colon, slash, or any other separator).
+ *
+ * Format fed to SHA-256:
+ *   `<len(contentHash)>:<contentHash>|<len(jobId)>:<jobId>|<len(track)>:<track>`
+ *
+ * The hash output is lowercased hex — 64 characters, safe as a map key, a
+ * DynamoDB attribute value, or a Redis key.
+ *
+ * Properties (all property-tested):
+ *   - Deterministic (idempotent): same tuple → same key on every call.
+ *   - Injective: distinct tuples → distinct keys, even when jobId contains
+ *     delimiters (`|`, `:`), Unicode, NUL bytes, or embedded length-prefix
+ *     strings that would fool a naive join.
+ *   - Total: never throws, returns a non-empty string for any input.
+ *
+ * @param input - The (contentHash, jobId, track) triple.
+ * @returns A 64-character lowercase hex SHA-256 digest.
+ */
+export declare function deriveDedupeKey(input: DedupeKeyInput): string;
+//# sourceMappingURL=dedupe-key.d.ts.map

package/dist/lib/media/dedupe-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe-key.d.ts","sourceRoot":"","sources":["../../../src/lib/media/dedupe-key.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAW7D"}

package/dist/lib/media/dedupe-key.js

@@ -0,0 +1,49 @@
+// Pure functional-core unit. No I/O, no clock, no random.
+//
+// Derives a collision-resistant, injection-safe dedupe key for a (contentHash,
+// jobId, track) tuple. Used by the processing worker to idempotently fan-out /
+// fan-in async per-track moderation jobs without double-processing.
+//
+// COLLISION RESISTANCE: a naive delimiter join ("a:b:c") is vulnerable when
+// jobId is provider-controlled and may contain the delimiter. This module hashes
+// the canonical tuple with SHA-256 so that distinct tuples always yield distinct
+// keys regardless of delimiter characters in any field.
+//
+// Ships in the PUBLIC npm tarball: NO thresholds, secrets, or real-category
+// vocabulary here. node:crypto createHash is allowed (deterministic, CPU-only).
+import { createHash } from "node:crypto";
+/**
+ * Derive a stable, collision-resistant dedupe key for one (contentHash, jobId,
+ * track) tuple.
+ *
+ * Implementation: encode the three fields as a length-prefixed canonical form,
+ * then SHA-256 hash it. Length-prefix encoding ensures that distinct tuples
+ * cannot be made to collide by crafting delimiter-containing field values
+ * (e.g. a jobId that itself contains a colon, slash, or any other separator).
+ *
+ * Format fed to SHA-256:
+ *   `<len(contentHash)>:<contentHash>|<len(jobId)>:<jobId>|<len(track)>:<track>`
+ *
+ * The hash output is lowercased hex — 64 characters, safe as a map key, a
+ * DynamoDB attribute value, or a Redis key.
+ *
+ * Properties (all property-tested):
+ *   - Deterministic (idempotent): same tuple → same key on every call.
+ *   - Injective: distinct tuples → distinct keys, even when jobId contains
+ *     delimiters (`|`, `:`), Unicode, NUL bytes, or embedded length-prefix
+ *     strings that would fool a naive join.
+ *   - Total: never throws, returns a non-empty string for any input.
+ *
+ * @param input - The (contentHash, jobId, track) triple.
+ * @returns A 64-character lowercase hex SHA-256 digest.
+ */
+export function deriveDedupeKey(input) {
+    const { contentHash, jobId, track } = input;
+    // Length-prefixed encoding prevents injection: a field value that contains
+    // the separator cannot silently absorb a neighbouring field's value.
+    const canonical = `${contentHash.length}:${contentHash}` +
+        `|${jobId.length}:${jobId}` +
+        `|${track.length}:${track}`;
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+//# sourceMappingURL=dedupe-key.js.map

package/dist/lib/media/dedupe-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe-key.js","sourceRoot":"","sources":["../../../src/lib/media/dedupe-key.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,oEAAoE;AACpE,EAAE;AACF,4EAA4E;AAC5E,iFAAiF;AACjF,iFAAiF;AACjF,wDAAwD;AACxD,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAEhF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAOzC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAqB;IACnD,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAE5C,2EAA2E;IAC3E,qEAAqE;IACrE,MAAM,SAAS,GACb,GAAG,WAAW,CAAC,MAAM,IAAI,WAAW,EAAE;QACtC,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,EAAE;QAC3B,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;IAE9B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC"}

package/dist/lib/media/duration-cap.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Duration cap gate — pure functional core unit.
+ *
+ * Determines whether a probed media duration exceeds the configured cap.
+ * Fail-closed: any input that cannot be verified as a finite non-negative
+ * number is treated as "too long" (rejected), so uncertainty never yields a
+ * decision to process.
+ *
+ * Ships in the PUBLIC npm tarball: NO hard-coded operational thresholds here.
+ * The cap arrives as a function argument sourced from Env.media.maxDurationSeconds.
+ *
+ * Pure functional core: no I/O, no clock, no network, no fs. Total over all inputs.
+ */
+/**
+ * Returns `true` when `probedSeconds` exceeds the configured `capSeconds`,
+ * meaning the media object is too long to process.
+ *
+ * Fail-closed boundary conditions:
+ * - `probedSeconds` is NaN            => true  (cannot verify length; reject)
+ * - `probedSeconds` is ±Infinity      => true  (cannot verify length; reject)
+ * - `probedSeconds` is negative       => true  (invalid probe; reject)
+ * - `probedSeconds === capSeconds`    => false (exactly at cap is allowed)
+ * - `probedSeconds > capSeconds`      => true
+ *
+ * @param probedSeconds  The duration reported by the media probe (e.g. ffprobe).
+ * @param capSeconds     The maximum allowed duration, sourced from Env.media.maxDurationSeconds.
+ *                       Never a literal in this file.
+ */
+export declare function exceedsDurationCap(probedSeconds: number, capSeconds: number): boolean;
+//# sourceMappingURL=duration-cap.d.ts.map

package/dist/lib/media/duration-cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration-cap.d.ts","sourceRoot":"","sources":["../../../src/lib/media/duration-cap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAQT"}

package/dist/lib/media/duration-cap.js

@@ -0,0 +1,37 @@
+/**
+ * Duration cap gate — pure functional core unit.
+ *
+ * Determines whether a probed media duration exceeds the configured cap.
+ * Fail-closed: any input that cannot be verified as a finite non-negative
+ * number is treated as "too long" (rejected), so uncertainty never yields a
+ * decision to process.
+ *
+ * Ships in the PUBLIC npm tarball: NO hard-coded operational thresholds here.
+ * The cap arrives as a function argument sourced from Env.media.maxDurationSeconds.
+ *
+ * Pure functional core: no I/O, no clock, no network, no fs. Total over all inputs.
+ */
+/**
+ * Returns `true` when `probedSeconds` exceeds the configured `capSeconds`,
+ * meaning the media object is too long to process.
+ *
+ * Fail-closed boundary conditions:
+ * - `probedSeconds` is NaN            => true  (cannot verify length; reject)
+ * - `probedSeconds` is ±Infinity      => true  (cannot verify length; reject)
+ * - `probedSeconds` is negative       => true  (invalid probe; reject)
+ * - `probedSeconds === capSeconds`    => false (exactly at cap is allowed)
+ * - `probedSeconds > capSeconds`      => true
+ *
+ * @param probedSeconds  The duration reported by the media probe (e.g. ffprobe).
+ * @param capSeconds     The maximum allowed duration, sourced from Env.media.maxDurationSeconds.
+ *                       Never a literal in this file.
+ */
+export function exceedsDurationCap(probedSeconds, capSeconds) {
+    // Fail closed on any un-verifiable probe value.
+    if (!Number.isFinite(probedSeconds) || probedSeconds < 0) {
+        return true;
+    }
+    // Exactly at cap is permitted; strictly over cap is rejected.
+    return probedSeconds > capSeconds;
+}
+//# sourceMappingURL=duration-cap.js.map

package/dist/lib/media/duration-cap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration-cap.js","sourceRoot":"","sources":["../../../src/lib/media/duration-cap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAChC,aAAqB,EACrB,UAAkB;IAElB,gDAAgD;IAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8DAA8D;IAC9D,OAAO,aAAa,GAAG,UAAU,CAAC;AACpC,CAAC"}

package/dist/lib/media/ffmpeg-args.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pure functional-core builder for ffmpeg argument arrays.
+ *
+ * Produces an argv ARRAY passed directly to the ffmpeg process — NEVER a shell
+ * string. No interpolation into a shell context means no command injection risk
+ * regardless of what inputPath / outputPath / posterPath contain.
+ *
+ * Hardening applied unconditionally on every invocation:
+ *   - "-protocol_whitelist","file,pipe"   blocks SSRF (no http/https/rtmp/etc.)
+ *   - "-t", String(maxDurationSeconds)    bounds processing time (from spec; never a literal)
+ *   - "-dn"                               drop data tracks
+ *   - "-sn"                               drop subtitle tracks
+ *
+ * Video additionally gets:
+ *   - "-c:v","libx264","-c:a","aac"       re-encode to safe codecs
+ *   - "-movflags","+faststart"            progressive streaming
+ *
+ * Audio-only gets:
+ *   - "-c:a","aac"                        re-encode to safe codec
+ *
+ * Poster frame extraction is a SEPARATE argv (buildPosterArgs). Splitting the
+ * two operations keeps the main transcode deterministic and lets the poster be
+ * produced in a separate process without retranscoding. The poster job uses
+ * "-frames:v","1" to extract exactly one frame and inherits all hardening args.
+ *
+ * PURITY: no I/O, no AWS SDK, no fs, no Date.now, no Math.random. All
+ * operational parameters (maxDurationSeconds) arrive as function arguments
+ * sourced from Env.media — never as literals in this file. Ships in the PUBLIC
+ * npm tarball: no hard-coded operational numbers here.
+ */
+/**
+ * Specification for a single ffmpeg transcode job.
+ *
+ * - `kind`               — "video" or "audio"; controls codec flags
+ * - `inputPath`          — absolute path to the source file (read-only)
+ * - `outputPath`         — absolute path for the transcoded output
+ * - `posterPath`         — if set, {@link buildPosterArgs} targets this path
+ * - `maxDurationSeconds` — duration cap sourced from Env.media; passed to -t
+ */
+export interface FfmpegJobSpec {
+    readonly kind: "video" | "audio";
+    readonly inputPath: string;
+    readonly outputPath: string;
+    readonly posterPath?: string;
+    readonly maxDurationSeconds: number;
+}
+/**
+ * Build the argv for transcoding a media object.
+ *
+ * The returned array is passed to the child-process launcher directly — never
+ * joined into a shell string. The caller is responsible for prepending the
+ * ffmpeg binary path or using `execFile`/`spawn` with `shell: false`.
+ *
+ * The protocol whitelist, duration cap, and track-drop flags are always present
+ * in the output regardless of kind. The caller should verify these are present
+ * before launching (the test suite does so exhaustively).
+ */
+export declare function buildFfmpegArgs(spec: FfmpegJobSpec): string[];
+/**
+ * Build the argv for extracting a poster frame from a video.
+ *
+ * This is a SEPARATE invocation from {@link buildFfmpegArgs}: splitting the two
+ * means the transcode and the poster extraction run independently, the poster
+ * can be regenerated without retranscoding, and the transcode argv stays clean.
+ *
+ * The poster job inherits all hardening (protocol whitelist, duration cap,
+ * track drops) and adds:
+ *   - "-frames:v","1"   — extract exactly one video frame
+ *   - "-an"             — no audio output (image output only)
+ *
+ * Callers should only invoke this when `spec.posterPath` is defined. The
+ * function documents this contract via its signature: if posterPath is absent,
+ * the output path would be undefined and the caller must guard before spawning.
+ * The implementation always uses spec.posterPath so TypeScript callers can call
+ * with a spec that has posterPath set and get a well-formed array.
+ *
+ * @param spec - must have `posterPath` set; calling without it is a caller
+ *               contract violation (outputPath would be undefined).
+ */
+export declare function buildPosterArgs(spec: FfmpegJobSpec & {
+    readonly posterPath: string;
+}): string[];
+//# sourceMappingURL=ffmpeg-args.d.ts.map

package/dist/lib/media/ffmpeg-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg-args.d.ts","sourceRoot":"","sources":["../../../src/lib/media/ffmpeg-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAyC7D;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACpD,MAAM,EAAE,CAwBV"}