@adonis-agora/media 0.8.1 → 0.9.0

package/dist/src/transformer.d.ts

@@ -0,0 +1,111 @@
+import type { Readable } from 'node:stream';
+import type { MediaRecord } from './media_record.js';
+import type { StorageManager } from './storage_manager.js';
+import type { Disk } from './types.js';
+/**
+ * Options for {@link TransformerContext.write}. `contentLength` matters when `contents` is a
+ * `Readable` on a disk that streams (S3 needs the length up front); it is ignored for byte payloads.
+ */
+export interface TransformerWriteOptions {
+    contentType?: string;
+    contentLength?: number;
+}
+/**
+ * Everything a {@link Transformer} gets to work with: the record being transformed, read access to
+ * its original bytes, and a sandboxed writer for the derived artifacts.
+ *
+ * The context — not the transformer — decides WHERE artifacts live: every {@link write} lands under
+ * {@link outputPrefix} (`<owner>/<id>/conversions/<name>/`), and the library tracks each written
+ * path so it can persist the artifact list on the record and delete every artifact when the media
+ * is deleted. A transformer never touches disk keys outside its prefix.
+ */
+export interface TransformerContext {
+    /** The media record whose content is being transformed. */
+    record: MediaRecord;
+    /** The disk holding the original object (and receiving the artifacts). */
+    disk: Disk;
+    /** Name of {@link disk}, as resolvable through the storage manager. */
+    diskName: string;
+    /**
+     * The storage façade, for reads OUTSIDE the record's own disk — auxiliary assets a transformer
+     * was configured with (a watermark logo on another disk, a font, a sidecar file). Artifact
+     * writes still go through {@link write}, never directly through a disk.
+     */
+    storage: StorageManager;
+    /** Buffer the original's bytes. Convenient for small originals; prefer {@link getStream} for video. */
+    getBytes(): Promise<Uint8Array>;
+    /** Stream the original without buffering it. */
+    getStream(): Promise<Readable>;
+    /**
+     * Storage prefix (ending in `/`) reserved for this transformation's artifacts:
+     * `<ownerType>/<ownerId>/<collection>/<mediaId>/conversions/<transformerName>/`.
+     */
+    outputPrefix: string;
+    /**
+     * Write one artifact at `outputPrefix + relativePath`. The path is validated (no `..`, no
+     * absolute paths) and recorded — the persisted conversion lists every written artifact, which is
+     * what makes multi-file outputs (an HLS package) deletable and servable file-by-file.
+     *
+     * A `Readable` with a known `contentLength` streams straight to the disk; anything else is
+     * buffered.
+     */
+    write(relativePath: string, contents: Uint8Array | Readable, options?: TransformerWriteOptions): Promise<void>;
+}
+/**
+ * What a {@link Transformer.transform} run reports back. The artifacts themselves were already
+ * written through {@link TransformerContext.write}; this names which of them is the entry point and
+ * attaches free-form metadata.
+ */
+export interface TransformResult {
+    /**
+     * The entry-point artifact, relative to {@link TransformerContext.outputPrefix} — what
+     * `url(id, name)` / `deliver(id, { conversion: name })` resolve for this conversion. Required
+     * when any artifact was written (and must be one of them); omit it for a metadata-only
+     * transform (a probe, a blurhash) that wrote nothing.
+     */
+    entry?: string;
+    /**
+     * Transformer-specific metadata persisted verbatim on the conversion entry
+     * (`record.conversions[name].meta`): duration, resolution, codecs, a blurhash string — whatever
+     * the transformer learned. Must be JSON-serializable (the Lucid store serializes it).
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * A pluggable content transformation: takes a stored media's content and produces derived
+ * artifacts on the disk and/or metadata on the record, persisted as a named conversion
+ * (`record.conversions[transformer.name]`).
+ *
+ * This is the seam the library's own {@link HlsTransformer} and {@link MetadataProbeTransformer}
+ * implement, and the one you implement for your own derivations — extract an audio track,
+ * stamp a watermark, generate a poster frame, request a transcription. The shapes it supports:
+ *
+ * - **many artifacts** — an HLS package (segments + playlists); `entry` names the master playlist.
+ * - **one artifact** — an optimized image, an extracted audio file; `entry` names it.
+ * - **no artifact** — a metadata probe or perceptual hash; return only `meta`.
+ * - **auxiliary inputs** — configure them on your transformer instance (bytes, a path, a media id)
+ *   and read foreign disks through {@link TransformerContext.storage}.
+ *
+ * Registered per collection (`collections: [{ name, transformers: [...] }]`). Set `eager: true`
+ * only for cheap transforms — they run synchronously inside `attach`/`attachExisting` (and so
+ * inside a TUS finalize), and a failure rolls the new media back. Heavy transforms (video!) stay
+ * deferred: the app triggers them from its own job via `media.library.transform(id, name)`,
+ * which is idempotent — already generated ⇒ skip.
+ *
+ * Import heavy engines lazily INSIDE `transform` (the built-ins import `mediabunny` there), so
+ * configuring a transformer never loads its optional peer at boot. A transformer that needs a
+ * runtime capability the host lacks (e.g. WebCodecs for re-encoding) should throw
+ * {@link TransformerRuntimeMissingError} with a clear hint rather than failing obscurely.
+ */
+export interface Transformer {
+    /** Unique conversion name this transformer produces (the key in `record.conversions`). */
+    readonly name: string;
+    /**
+     * Run synchronously on attach (like an eager image conversion) instead of waiting for an
+     * explicit `transform()` call. Default `false` — transformations are assumed heavy.
+     */
+    readonly eager?: boolean;
+    /** Produce the derived artifacts/metadata for one media record. */
+    transform(context: TransformerContext): Promise<TransformResult>;
+}
+//# sourceMappingURL=transformer.d.ts.map

package/dist/src/transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.d.ts","sourceRoot":"","sources":["../../src/transformer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,MAAM,EAAE,WAAW,CAAC;IACpB,0EAA0E;IAC1E,IAAI,EAAE,IAAI,CAAC;IACX,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,EAAE,cAAc,CAAC;IACxB,uGAAuG;IACvG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,gDAAgD;IAChD,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,CACH,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,UAAU,GAAG,QAAQ,EAC/B,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,WAAW;IAC1B,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAClE"}

package/dist/src/transformer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transformer.js.map

package/dist/src/transformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformer.js","sourceRoot":"","sources":["../../src/transformer.ts"],"names":[],"mappings":""}

package/dist/src/transformers/factory.d.ts

@@ -0,0 +1,30 @@
+import { HlsTransformer, type HlsTransformerOptions } from './hls.js';
+import { MetadataProbeTransformer, type MetadataProbeTransformerOptions } from './probe.js';
+/**
+ * The transformer factory namespace used in `config/media.ts` — the {@link Transformer}
+ * counterpart of `processors`/`disks`/`stores`:
+ *
+ * ```ts
+ * import { defineConfig, transformers } from '@adonis-agora/media'
+ *
+ * export default defineConfig({
+ *   collections: [
+ *     {
+ *       name: 'videos',
+ *       acceptsMimeTypes: ['video/mp4'],
+ *       transformers: [transformers.hls({ targetDuration: 4 }), transformers.probe()],
+ *     },
+ *   ],
+ * })
+ * ```
+ *
+ * Constructing a transformer here never loads its engine — the optional `mediabunny` peer is
+ * imported inside the first `transform()` call, so config stays side-effect-free.
+ */
+export declare const transformers: {
+    /** Video → HLS package (MPEG-TS segments + playlists) via mediabunny. Default name `'hls'`. */
+    hls<Name extends string = "hls">(options?: HlsTransformerOptions<Name>): HlsTransformer<Name>;
+    /** Metadata-only probe (duration/resolution/codecs) via mediabunny. Default name `'probe'`. */
+    probe<Name extends string = "probe">(options?: MetadataProbeTransformerOptions<Name>): MetadataProbeTransformer<Name>;
+};
+//# sourceMappingURL=factory.d.ts.map

package/dist/src/transformers/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/transformers/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAE,KAAK,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY;IACvB,+FAA+F;QAC3F,IAAI,SAAS,MAAM,oBAAmB,qBAAqB,CAAC,IAAI,CAAC;IAGrE,+FAA+F;UACzF,IAAI,SAAS,MAAM,sBAAqB,+BAA+B,CAAC,IAAI,CAAC;CAGpF,CAAC"}

package/dist/src/transformers/factory.js

@@ -0,0 +1,34 @@
+import { HlsTransformer } from './hls.js';
+import { MetadataProbeTransformer } from './probe.js';
+/**
+ * The transformer factory namespace used in `config/media.ts` — the {@link Transformer}
+ * counterpart of `processors`/`disks`/`stores`:
+ *
+ * ```ts
+ * import { defineConfig, transformers } from '@adonis-agora/media'
+ *
+ * export default defineConfig({
+ *   collections: [
+ *     {
+ *       name: 'videos',
+ *       acceptsMimeTypes: ['video/mp4'],
+ *       transformers: [transformers.hls({ targetDuration: 4 }), transformers.probe()],
+ *     },
+ *   ],
+ * })
+ * ```
+ *
+ * Constructing a transformer here never loads its engine — the optional `mediabunny` peer is
+ * imported inside the first `transform()` call, so config stays side-effect-free.
+ */
+export const transformers = {
+    /** Video → HLS package (MPEG-TS segments + playlists) via mediabunny. Default name `'hls'`. */
+    hls(options = {}) {
+        return new HlsTransformer(options);
+    },
+    /** Metadata-only probe (duration/resolution/codecs) via mediabunny. Default name `'probe'`. */
+    probe(options = {}) {
+        return new MetadataProbeTransformer(options);
+    },
+};
+//# sourceMappingURL=factory.js.map

package/dist/src/transformers/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/transformers/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA8B,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,wBAAwB,EAAwC,MAAM,YAAY,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,+FAA+F;IAC/F,GAAG,CAA8B,UAAuC,EAAE;QACxE,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,+FAA+F;IAC/F,KAAK,CAAgC,UAAiD,EAAE;QACtF,OAAO,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;CACF,CAAC"}

package/dist/src/transformers/hls.d.ts

@@ -0,0 +1,110 @@
+import type { TransformResult, Transformer, TransformerContext } from '../transformer.js';
+/**
+ * Lazily supplies a WebCodecs implementation (`{ VideoEncoder, VideoDecoder, AudioEncoder, … }`).
+ * Node has no built-in WebCodecs, which is exactly why the HLS transformer is remux-only by
+ * default — but NAPI-based implementations exist (e.g. `@napi-rs/webcodecs`), and injecting one
+ * unlocks the re-encode fallback for sources whose codecs cannot be stream-copied:
+ *
+ * ```ts
+ * transformers.hls({ webcodecs: () => import('@napi-rs/webcodecs') })
+ * ```
+ *
+ * The engine installs the provided classes onto `globalThis` (only the ones missing — a native
+ * implementation is never overwritten), because that is where the underlying media engine looks
+ * the API up.
+ */
+export type WebCodecsProvider = () => Promise<Record<string, unknown>>;
+/** How a runtime can satisfy the WebCodecs requirement. See {@link resolveWebCodecsSupport}. */
+export type WebCodecsSupport = 'native' | 'injected' | 'absent';
+/**
+ * Detect how (whether) WebCodecs is available: `'native'` when the runtime already exposes
+ * `VideoEncoder`, `'injected'` when a {@link WebCodecsProvider} supplies one, `'absent'` otherwise.
+ * `'absent'` means encoding is impossible — transforms stay stream-copy only, and a transformer
+ * that cannot proceed without an encoder should throw `TransformerRuntimeMissingError`.
+ */
+export declare function resolveWebCodecsSupport(provider?: WebCodecsProvider): Promise<WebCodecsSupport>;
+/** What {@link HlsRemuxEngine.remux} receives. */
+export interface HlsRemuxRequest {
+    /** Local path of the source file. */
+    sourcePath: string;
+    /** Local directory the engine writes the whole package into (entry playlist at its root). */
+    outputDir: string;
+    /** File name of the entry (master) playlist, e.g. `index.m3u8`. */
+    entryName: string;
+    /** Target (max) segment duration in seconds. */
+    targetDuration: number;
+    /** Optional WebCodecs implementation enabling the re-encode fallback. */
+    webcodecs?: WebCodecsProvider | undefined;
+}
+/** What the engine learned about the source while remuxing — persisted into the conversion `meta`. */
+export interface HlsRemuxSummary {
+    durationSeconds?: number;
+    width?: number;
+    height?: number;
+    videoCodec?: string | null;
+    audioCodec?: string | null;
+}
+/**
+ * The engine seam of {@link HlsTransformer}: local file in, HLS package (playlists + segments) in
+ * a local directory out. The default engine is mediabunny, loaded lazily on first transform; tests
+ * inject a fake that writes files, so every bit of orchestration around the engine is testable
+ * without the optional peer.
+ */
+export interface HlsRemuxEngine {
+    remux(request: HlsRemuxRequest): Promise<HlsRemuxSummary>;
+}
+export interface HlsTransformerOptions<Name extends string = 'hls'> {
+    /** Conversion name on the record. Default `'hls'`. */
+    name?: Name;
+    /**
+     * Run inside attach. Default `false`, and think twice: a remux takes real time, and an eager
+     * failure rolls the attach back. The intended flow is deferred —
+     * `media.library.transform(id, 'hls')` from a job.
+     */
+    eager?: boolean;
+    /** Target (max) segment duration in seconds. Default 4. */
+    targetDuration?: number;
+    /** WebCodecs implementation for the re-encode fallback (see {@link WebCodecsProvider}). */
+    webcodecs?: WebCodecsProvider;
+    /** Replace the mediabunny engine (mainly for tests). */
+    engine?: HlsRemuxEngine;
+}
+/** File name of the entry (master) playlist an {@link HlsTransformer} produces. */
+export declare const HLS_ENTRY_PLAYLIST = "index.m3u8";
+/**
+ * The built-in video {@link Transformer}: converts a stored video into an HLS package — MPEG-TS
+ * segments plus media playlists behind one master playlist — written under the conversion prefix
+ * and persisted as `record.conversions['hls']` with duration/resolution/codec metadata.
+ *
+ * **Remux-only by default.** The engine (mediabunny, pure JS — no ffmpeg binary) stream-copies
+ * the source's h264/aac tracks into segments without re-encoding, because encoding needs
+ * WebCodecs, which Node does not provide. Two consequences, both deliberate:
+ *
+ * - a source whose codecs MPEG-TS cannot carry (vp9, av1…) fails with a clear, definitive
+ *   `HlsSourceUnsupportedError` — unless a {@link WebCodecsProvider} is configured, which enables
+ *   the engine's re-encode fallback;
+ * - the package has a single variant at the original resolution. Multi-quality renditions are the
+ *   documented evolution once an encoder is present (mediabunny supports fan-out video options),
+ *   not something this transformer fakes today.
+ *
+ * The engine also carries the subtle bit the naive implementation gets wrong: AAC audio with
+ * priming (an mp4 edit list) starts at a **negative** timestamp, and a conversion trimmed at t=0
+ * would kick that track off the stream-copy fast path — impossible without an encoder. The
+ * conversion is therefore trimmed at the source's real first timestamp, shifting all tracks
+ * equally (sync is unchanged) and keeping every track copyable.
+ *
+ * Serving the result is the other half: playlists are stored with storage-relative references and
+ * must be rewritten per request — see {@link HlsDeliveryHandler}.
+ */
+export declare class HlsTransformer<Name extends string = 'hls'> implements Transformer {
+    readonly name: Name;
+    readonly eager: boolean;
+    private readonly targetDuration;
+    private readonly webcodecs;
+    private readonly engine;
+    constructor(options?: HlsTransformerOptions<Name>);
+    transform(context: TransformerContext): Promise<TransformResult>;
+}
+/** Drop `undefined` values so the persisted meta round-trips identically through JSON stores. */
+export declare function compactMeta(meta: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=hls.d.ts.map

package/dist/src/transformers/hls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hls.d.ts","sourceRoot":"","sources":["../../../src/transformers/hls.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAI1F;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEvE,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEhE;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAI3B;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,SAAS,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC3C;AAED,sGAAsG;AACtG,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,qBAAqB,CAAC,IAAI,SAAS,MAAM,GAAG,KAAK;IAChE,sDAAsD;IACtD,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,wDAAwD;IACxD,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAc,CAAC,IAAI,SAAS,MAAM,GAAG,KAAK,CAAE,YAAW,WAAW;IAC7E,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;gBAExC,OAAO,GAAE,qBAAqB,CAAC,IAAI,CAAM;IAQ/C,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;CA8CvE;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAElF"}

package/dist/src/transformers/hls.js

@@ -0,0 +1,111 @@
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hlsArtifactContentType } from '../hls/playlist.js';
+import { loadMediabunny } from './mediabunny_loader.js';
+import { withSourceFile } from './source_file.js';
+/**
+ * Detect how (whether) WebCodecs is available: `'native'` when the runtime already exposes
+ * `VideoEncoder`, `'injected'` when a {@link WebCodecsProvider} supplies one, `'absent'` otherwise.
+ * `'absent'` means encoding is impossible — transforms stay stream-copy only, and a transformer
+ * that cannot proceed without an encoder should throw `TransformerRuntimeMissingError`.
+ */
+export async function resolveWebCodecsSupport(provider) {
+    if (globalThis.VideoEncoder !== undefined)
+        return 'native';
+    if (provider && (await provider()).VideoEncoder !== undefined)
+        return 'injected';
+    return 'absent';
+}
+/** File name of the entry (master) playlist an {@link HlsTransformer} produces. */
+export const HLS_ENTRY_PLAYLIST = 'index.m3u8';
+/**
+ * The built-in video {@link Transformer}: converts a stored video into an HLS package — MPEG-TS
+ * segments plus media playlists behind one master playlist — written under the conversion prefix
+ * and persisted as `record.conversions['hls']` with duration/resolution/codec metadata.
+ *
+ * **Remux-only by default.** The engine (mediabunny, pure JS — no ffmpeg binary) stream-copies
+ * the source's h264/aac tracks into segments without re-encoding, because encoding needs
+ * WebCodecs, which Node does not provide. Two consequences, both deliberate:
+ *
+ * - a source whose codecs MPEG-TS cannot carry (vp9, av1…) fails with a clear, definitive
+ *   `HlsSourceUnsupportedError` — unless a {@link WebCodecsProvider} is configured, which enables
+ *   the engine's re-encode fallback;
+ * - the package has a single variant at the original resolution. Multi-quality renditions are the
+ *   documented evolution once an encoder is present (mediabunny supports fan-out video options),
+ *   not something this transformer fakes today.
+ *
+ * The engine also carries the subtle bit the naive implementation gets wrong: AAC audio with
+ * priming (an mp4 edit list) starts at a **negative** timestamp, and a conversion trimmed at t=0
+ * would kick that track off the stream-copy fast path — impossible without an encoder. The
+ * conversion is therefore trimmed at the source's real first timestamp, shifting all tracks
+ * equally (sync is unchanged) and keeping every track copyable.
+ *
+ * Serving the result is the other half: playlists are stored with storage-relative references and
+ * must be rewritten per request — see {@link HlsDeliveryHandler}.
+ */
+export class HlsTransformer {
+    name;
+    eager;
+    targetDuration;
+    webcodecs;
+    engine;
+    constructor(options = {}) {
+        this.name = options.name ?? 'hls';
+        this.eager = options.eager ?? false;
+        this.targetDuration = options.targetDuration ?? 4;
+        this.webcodecs = options.webcodecs;
+        this.engine = options.engine;
+    }
+    async transform(context) {
+        const engine = this.engine ?? (await loadMediabunny(this.name)).createHlsEngine();
+        return withSourceFile(context, async ({ sourcePath, tempDir }) => {
+            const outputDir = join(tempDir, 'hls');
+            await mkdir(outputDir, { recursive: true });
+            const summary = await engine.remux({
+                sourcePath,
+                outputDir,
+                entryName: HLS_ENTRY_PLAYLIST,
+                targetDuration: this.targetDuration,
+                webcodecs: this.webcodecs,
+            });
+            // Upload the whole package the engine wrote — playlists and segments alike — streaming each
+            // file (a segment never has to fit in memory). Sorted for deterministic order in
+            // `conversions[name].files`.
+            const files = (await readdir(outputDir, { recursive: true })).sort();
+            let segmentCount = 0;
+            let playlistCount = 0;
+            for (const file of files) {
+                const relative = file.split('\\').join('/');
+                const local = join(outputDir, file);
+                const info = await stat(local);
+                if (!info.isFile())
+                    continue;
+                if (relative.toLowerCase().endsWith('.m3u8'))
+                    playlistCount += 1;
+                else
+                    segmentCount += 1;
+                const contentType = hlsArtifactContentType(relative);
+                await context.write(relative, createReadStream(local), {
+                    contentLength: info.size,
+                    ...(contentType !== undefined ? { contentType } : {}),
+                });
+            }
+            return {
+                entry: HLS_ENTRY_PLAYLIST,
+                meta: compactMeta({
+                    ...summary,
+                    segmentCount,
+                    playlistCount,
+                    targetDuration: this.targetDuration,
+                }),
+            };
+        });
+    }
+}
+/** Drop `undefined` values so the persisted meta round-trips identically through JSON stores. */
+export function compactMeta(meta) {
+    return Object.fromEntries(Object.entries(meta).filter(([, value]) => value !== undefined));
+}
+//# sourceMappingURL=hls.js.map

package/dist/src/transformers/hls.js.map

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

package/dist/src/transformers/mediabunny.d.ts

@@ -0,0 +1,5 @@
+import type { HlsRemuxEngine } from './hls.js';
+import type { MediaProbeEngine } from './probe.js';
+export declare function createHlsEngine(): HlsRemuxEngine;
+export declare function createProbeEngine(): MediaProbeEngine;
+//# sourceMappingURL=mediabunny.d.ts.map

package/dist/src/transformers/mediabunny.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediabunny.d.ts","sourceRoot":"","sources":["../../../src/transformers/mediabunny.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAuD,MAAM,UAAU,CAAC;AACpG,OAAO,KAAK,EAAE,gBAAgB,EAAqB,MAAM,YAAY,CAAC;AA+DtE,wBAAgB,eAAe,IAAI,cAAc,CA8DhD;AAED,wBAAgB,iBAAiB,IAAI,gBAAgB,CAiCpD"}

package/dist/src/transformers/mediabunny.js

@@ -0,0 +1,150 @@
+import { join } from 'node:path';
+import { ALL_FORMATS, Conversion, FilePathSource, FilePathTarget, HlsOutputFormat, Input, MpegTsOutputFormat, Output, PathedTarget, } from 'mediabunny';
+import { HlsSourceUnsupportedError } from '../errors.js';
+/**
+ * The mediabunny-backed engines — the ONLY module in the package that imports the optional
+ * `mediabunny` peer, reached lazily through `mediabunny_loader.ts` at first transform.
+ *
+ * Why mediabunny: pure TypeScript, no ffmpeg binary — a production container without system
+ * ffmpeg (the usual case) remuxes fine. The trade-off is that *encoding* rides on WebCodecs,
+ * which Node lacks, hence the remux-only default and the {@link WebCodecsProvider} injection
+ * seam documented on `HlsTransformer`.
+ */
+/** The WebCodecs API surface mediabunny reads from `globalThis`. */
+const WEBCODECS_GLOBALS = [
+    'VideoEncoder',
+    'VideoDecoder',
+    'AudioEncoder',
+    'AudioDecoder',
+    'VideoFrame',
+    'AudioData',
+    'EncodedVideoChunk',
+    'EncodedAudioChunk',
+];
+/**
+ * Install an injected WebCodecs implementation onto `globalThis` — only the classes that are
+ * missing; a native implementation is never overwritten. Global mutation is deliberate and
+ * additive: `globalThis` is where the WebCodecs spec (and therefore mediabunny) looks the API up,
+ * so "injecting an implementation" and "installing it globally" are the same thing. Installing
+ * per-conversion and uninstalling after would race concurrent transforms for zero benefit.
+ */
+async function installWebCodecs(provider) {
+    if (!provider)
+        return;
+    const implementation = await provider();
+    const globals = globalThis;
+    for (const name of WEBCODECS_GLOBALS) {
+        if (globals[name] === undefined && implementation[name] !== undefined) {
+            globals[name] = implementation[name];
+        }
+    }
+}
+/** Best-effort technical summary of an input — never fails the transform over metadata. */
+async function summarize(input) {
+    const summary = {};
+    try {
+        summary.durationSeconds = await input.computeDuration();
+        const video = await input.getPrimaryVideoTrack();
+        if (video) {
+            summary.width = await video.getDisplayWidth();
+            summary.height = await video.getDisplayHeight();
+            summary.videoCodec = await video.getCodec();
+        }
+        const audio = await input.getPrimaryAudioTrack();
+        if (audio) {
+            summary.audioCodec = await audio.getCodec();
+        }
+    }
+    catch {
+        // metadata is a bonus; the artifacts are the product
+    }
+    return summary;
+}
+export function createHlsEngine() {
+    return {
+        async remux(request) {
+            await installWebCodecs(request.webcodecs);
+            const input = new Input({
+                source: new FilePathSource(request.sourcePath),
+                formats: ALL_FORMATS,
+            });
+            try {
+                const output = new Output({
+                    format: new HlsOutputFormat({
+                        segmentFormat: new MpegTsOutputFormat(),
+                        targetDuration: request.targetDuration,
+                    }),
+                    // The HLS output is many files; each one lands in the local output directory.
+                    target: new PathedTarget(join(request.outputDir, request.entryName), (target) => new FilePathTarget(target.path)),
+                });
+                // THE gotcha: AAC audio with priming (an mp4 edit list) starts at a NEGATIVE timestamp.
+                // Mediabunny's default trims the conversion at t=0, which would throw that audio track off
+                // the packet-copy fast path — and re-encoding it needs an encoder we may not have.
+                // Trimming at the source's real first timestamp keeps every track a pure stream copy; all
+                // tracks shift equally, so A/V sync is untouched.
+                const firstTimestamp = await input.getFirstTimestamp();
+                const conversion = await Conversion.init({
+                    input,
+                    output,
+                    trim: { start: firstTimestamp },
+                });
+                // With no video/audio options, mediabunny copies compatible tracks and re-encodes the
+                // rest — but re-encoding needs an encoder, so without WebCodecs an incompatible track is
+                // DISCARDED instead. Silently shipping a video without its audio (or vice versa) is not a
+                // conversion, it is data loss: fail loudly, with the codec and the reason per track.
+                if (conversion.discardedTracks.length > 0) {
+                    const reasons = await Promise.all(conversion.discardedTracks.map(async (discarded) => {
+                        const codec = await discarded.track.getCodec().catch(() => null);
+                        return `${discarded.track.type}/${codec ?? 'unknown'}: ${discarded.reason}`;
+                    }));
+                    throw new HlsSourceUnsupportedError(reasons.join('; '));
+                }
+                if (!conversion.isValid) {
+                    throw new HlsSourceUnsupportedError('the file contains no usable track');
+                }
+                const summary = await summarize(input);
+                await conversion.execute();
+                return summary;
+            }
+            finally {
+                input.dispose();
+            }
+        },
+    };
+}
+export function createProbeEngine() {
+    return {
+        async probe(sourcePath) {
+            const input = new Input({ source: new FilePathSource(sourcePath), formats: ALL_FORMATS });
+            try {
+                const format = await input.getFormat();
+                const summary = {
+                    format: format.name,
+                    mimeType: await input.getMimeType(),
+                    durationSeconds: await input.computeDuration(),
+                    hasVideo: false,
+                    hasAudio: false,
+                };
+                const video = await input.getPrimaryVideoTrack();
+                if (video) {
+                    summary.hasVideo = true;
+                    summary.width = await video.getDisplayWidth();
+                    summary.height = await video.getDisplayHeight();
+                    summary.videoCodec = await video.getCodec();
+                }
+                const audio = await input.getPrimaryAudioTrack();
+                if (audio) {
+                    summary.hasAudio = true;
+                    summary.audioCodec = await audio.getCodec();
+                    summary.audioSampleRate = await audio.getSampleRate();
+                    summary.audioChannels = await audio.getNumberOfChannels();
+                }
+                return summary;
+            }
+            finally {
+                input.dispose();
+            }
+        },
+    };
+}
+//# sourceMappingURL=mediabunny.js.map

package/dist/src/transformers/mediabunny.js.map

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

package/dist/src/transformers/mediabunny_loader.d.ts

@@ -0,0 +1,15 @@
+import type { HlsRemuxEngine } from './hls.js';
+import type { MediaProbeEngine } from './probe.js';
+/** The engine factories `./mediabunny.js` exports (the only module that imports the peer). */
+export interface MediabunnyEngineModule {
+    createHlsEngine(): HlsRemuxEngine;
+    createProbeEngine(): MediaProbeEngine;
+}
+/**
+ * Load the mediabunny-backed engine module, translating a missing optional peer into the typed
+ * {@link TransformerRuntimeMissingError} instead of a raw `ERR_MODULE_NOT_FOUND` five imports deep.
+ * Import happens here — at first transform — never at boot: configuring a transformer must not
+ * load its engine (the same laziness `processors.sharp()` and `disks.s3()` follow).
+ */
+export declare function loadMediabunny(transformerName: string): Promise<MediabunnyEngineModule>;
+//# sourceMappingURL=mediabunny_loader.d.ts.map

package/dist/src/transformers/mediabunny_loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediabunny_loader.d.ts","sourceRoot":"","sources":["../../../src/transformers/mediabunny_loader.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,8FAA8F;AAC9F,MAAM,WAAW,sBAAsB;IACrC,eAAe,IAAI,cAAc,CAAC;IAClC,iBAAiB,IAAI,gBAAgB,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAiB7F"}

package/dist/src/transformers/mediabunny_loader.js

@@ -0,0 +1,21 @@
+import { TransformerRuntimeMissingError } from '../errors.js';
+/**
+ * Load the mediabunny-backed engine module, translating a missing optional peer into the typed
+ * {@link TransformerRuntimeMissingError} instead of a raw `ERR_MODULE_NOT_FOUND` five imports deep.
+ * Import happens here — at first transform — never at boot: configuring a transformer must not
+ * load its engine (the same laziness `processors.sharp()` and `disks.s3()` follow).
+ */
+export async function loadMediabunny(transformerName) {
+    try {
+        return await import('./mediabunny.js');
+    }
+    catch (error) {
+        if (error.code === 'ERR_MODULE_NOT_FOUND' &&
+            error instanceof Error &&
+            error.message.includes('mediabunny')) {
+            throw new TransformerRuntimeMissingError(transformerName, "the optional peer dependency 'mediabunny'", 'Install it (`pnpm add mediabunny`) or inject a custom `engine`.');
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=mediabunny_loader.js.map