@adonis-agora/media 0.8.2 → 0.10.0

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":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,WAAW,EACX,UAAU,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,KAAK,EACL,kBAAkB,EAClB,MAAM,EACN,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAIzD;;;;;;;;GAQG;AAEH,oEAAoE;AACpE,MAAM,iBAAiB,GAAG;IACxB,cAAc;IACd,cAAc;IACd,cAAc;IACd,cAAc;IACd,YAAY;IACZ,WAAW;IACX,mBAAmB;IACnB,mBAAmB;CACX,CAAC;AAEX;;;;;;GAMG;AACH,KAAK,UAAU,gBAAgB,CAAC,QAAuC;IACrE,IAAI,CAAC,QAAQ;QAAE,OAAO;IACtB,MAAM,cAAc,GAAG,MAAM,QAAQ,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,UAAqC,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,iBAAiB,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACtE,OAAO,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,KAAK,UAAU,SAAS,CAAC,KAAY;IACnC,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,CAAC,eAAe,GAAG,MAAM,KAAK,CAAC,eAAe,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,oBAAoB,EAAE,CAAC;QACjD,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,GAAG,MAAM,KAAK,CAAC,eAAe,EAAE,CAAC;YAC9C,OAAO,CAAC,MAAM,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAC;YAChD,OAAO,CAAC,UAAU,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC9C,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,oBAAoB,EAAE,CAAC;QACjD,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,UAAU,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qDAAqD;IACvD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAwB;YAClC,MAAM,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAE1C,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC;gBACtB,MAAM,EAAE,IAAI,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC;gBAC9C,OAAO,EAAE,WAAW;aACrB,CAAC,CAAC;YAEH,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;oBACxB,MAAM,EAAE,IAAI,eAAe,CAAC;wBAC1B,aAAa,EAAE,IAAI,kBAAkB,EAAE;wBACvC,cAAc,EAAE,OAAO,CAAC,cAAc;qBACvC,CAAC;oBACF,8EAA8E;oBAC9E,MAAM,EAAE,IAAI,YAAY,CACtB,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,EAC1C,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAC5C;iBACF,CAAC,CAAC;gBAEH,wFAAwF;gBACxF,2FAA2F;gBAC3F,mFAAmF;gBACnF,0FAA0F;gBAC1F,kDAAkD;gBAClD,MAAM,cAAc,GAAG,MAAM,KAAK,CAAC,iBAAiB,EAAE,CAAC;gBAEvD,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC;oBACvC,KAAK;oBACL,MAAM;oBACN,IAAI,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE;iBAChC,CAAC,CAAC;gBAEH,sFAAsF;gBACtF,yFAAyF;gBACzF,0FAA0F;gBAC1F,qFAAqF;gBACrF,IAAI,UAAU,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC1C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,UAAU,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;wBACjD,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;wBACjE,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,IAAI,SAAS,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;oBAC9E,CAAC,CAAC,CACH,CAAC;oBACF,MAAM,IAAI,yBAAyB,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC1D,CAAC;gBAED,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;oBACxB,MAAM,IAAI,yBAAyB,CAAC,mCAAmC,CAAC,CAAC;gBAC3E,CAAC;gBAED,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;gBACvC,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC;gBAC3B,OAAO,OAAO,CAAC;YACjB,CAAC;oBAAS,CAAC;gBACT,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,UAAkB;YAC5B,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,cAAc,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;YAC1F,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,SAAS,EAAE,CAAC;gBACvC,MAAM,OAAO,GAAsB;oBACjC,MAAM,EAAE,MAAM,CAAC,IAAI;oBACnB,QAAQ,EAAE,MAAM,KAAK,CAAC,WAAW,EAAE;oBACnC,eAAe,EAAE,MAAM,KAAK,CAAC,eAAe,EAAE;oBAC9C,QAAQ,EAAE,KAAK;oBACf,QAAQ,EAAE,KAAK;iBAChB,CAAC;gBACF,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,oBAAoB,EAAE,CAAC;gBACjD,IAAI,KAAK,EAAE,CAAC;oBACV,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;oBACxB,OAAO,CAAC,KAAK,GAAG,MAAM,KAAK,CAAC,eAAe,EAAE,CAAC;oBAC9C,OAAO,CAAC,MAAM,GAAG,MAAM,KAAK,CAAC,gBAAgB,EAAE,CAAC;oBAChD,OAAO,CAAC,UAAU,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAC9C,CAAC;gBACD,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,oBAAoB,EAAE,CAAC;gBACjD,IAAI,KAAK,EAAE,CAAC;oBACV,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;oBACxB,OAAO,CAAC,UAAU,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC;oBAC5C,OAAO,CAAC,eAAe,GAAG,MAAM,KAAK,CAAC,aAAa,EAAE,CAAC;oBACtD,OAAO,CAAC,aAAa,GAAG,MAAM,KAAK,CAAC,mBAAmB,EAAE,CAAC;gBAC5D,CAAC;gBACD,OAAO,OAAO,CAAC;YACjB,CAAC;oBAAS,CAAC;gBACT,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"mediabunny_loader.js","sourceRoot":"","sources":["../../../src/transformers/mediabunny_loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAU9D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,eAAuB;IAC1D,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACG,KAA2B,CAAC,IAAI,KAAK,sBAAsB;YAC5D,KAAK,YAAY,KAAK;YACtB,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EACpC,CAAC;YACD,MAAM,IAAI,8BAA8B,CACtC,eAAe,EACf,2CAA2C,EAC3C,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,56 @@
+import type { TransformResult, Transformer, TransformerContext } from '../transformer.js';
+/** What probing a media file yields — persisted verbatim as the conversion's `meta`. */
+export interface MediaProbeSummary {
+    /** Container format name (e.g. `MP4`), when the engine can tell. */
+    format?: string;
+    /** Full MIME type including codecs parameter, when the engine can tell. */
+    mimeType?: string;
+    durationSeconds?: number;
+    width?: number;
+    height?: number;
+    videoCodec?: string | null;
+    audioCodec?: string | null;
+    audioSampleRate?: number;
+    audioChannels?: number;
+    hasVideo: boolean;
+    hasAudio: boolean;
+}
+/**
+ * The engine seam of {@link MetadataProbeTransformer}: local file in, metadata out. Default engine
+ * is mediabunny (lazy); tests inject a fake.
+ */
+export interface MediaProbeEngine {
+    probe(sourcePath: string): Promise<MediaProbeSummary>;
+}
+export interface MetadataProbeTransformerOptions<Name extends string = 'probe'> {
+    /** Conversion name on the record. Default `'probe'`. */
+    name?: Name;
+    /**
+     * Run inside attach. Default `false`: probing is CPU-cheap but reads the original, and on a
+     * remote disk that read is a download. Opt in for collections of small files.
+     */
+    eager?: boolean;
+    /** Replace the mediabunny engine (mainly for tests). */
+    engine?: MediaProbeEngine;
+}
+/**
+ * The built-in **metadata-only** {@link Transformer}: reads a media file's technical metadata —
+ * duration, resolution, codecs, channel layout — and persists it as
+ * `record.conversions['probe'].meta`, writing **no artifact at all**. The reference implementation
+ * of the "derive metadata, not files" transformer shape; the model for a blurhash/thumbhash
+ * placeholder transformer.
+ *
+ * ```ts
+ * await media.library.transform(id, 'probe')
+ * const record = await media.library.find(id)
+ * record.conversions.probe?.meta // { durationSeconds: 41.6, width: 1920, ... }
+ * ```
+ */
+export declare class MetadataProbeTransformer<Name extends string = 'probe'> implements Transformer {
+    readonly name: Name;
+    readonly eager: boolean;
+    private readonly engine;
+    constructor(options?: MetadataProbeTransformerOptions<Name>);
+    transform(context: TransformerContext): Promise<TransformResult>;
+}
+//# sourceMappingURL=probe.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../../src/transformers/probe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAK1F,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,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;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,+BAA+B,CAAC,IAAI,SAAS,MAAM,GAAG,OAAO;IAC5E,wDAAwD;IACxD,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAwB,CAAC,IAAI,SAAS,MAAM,GAAG,OAAO,CAAE,YAAW,WAAW;IACzF,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAE1C,OAAO,GAAE,+BAA+B,CAAC,IAAI,CAAM;IAMzD,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;CAKvE"}

package/dist/src/transformers/probe.js

@@ -0,0 +1,32 @@
+import { compactMeta } from './hls.js';
+import { loadMediabunny } from './mediabunny_loader.js';
+import { withSourceFile } from './source_file.js';
+/**
+ * The built-in **metadata-only** {@link Transformer}: reads a media file's technical metadata —
+ * duration, resolution, codecs, channel layout — and persists it as
+ * `record.conversions['probe'].meta`, writing **no artifact at all**. The reference implementation
+ * of the "derive metadata, not files" transformer shape; the model for a blurhash/thumbhash
+ * placeholder transformer.
+ *
+ * ```ts
+ * await media.library.transform(id, 'probe')
+ * const record = await media.library.find(id)
+ * record.conversions.probe?.meta // { durationSeconds: 41.6, width: 1920, ... }
+ * ```
+ */
+export class MetadataProbeTransformer {
+    name;
+    eager;
+    engine;
+    constructor(options = {}) {
+        this.name = options.name ?? 'probe';
+        this.eager = options.eager ?? false;
+        this.engine = options.engine;
+    }
+    async transform(context) {
+        const engine = this.engine ?? (await loadMediabunny(this.name)).createProbeEngine();
+        const summary = await withSourceFile(context, ({ sourcePath }) => engine.probe(sourcePath));
+        return { meta: compactMeta({ ...summary }) };
+    }
+}
+//# sourceMappingURL=probe.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../../src/transformers/probe.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAuClD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,wBAAwB;IAC1B,IAAI,CAAO;IACX,KAAK,CAAU;IACP,MAAM,CAA+B;IAEtD,YAAY,UAAiD,EAAE;QAC7D,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAK,OAAgB,CAAC;QAC9C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAA2B;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC;QACpF,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;QAC5F,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,EAAE,CAAC;IAC/C,CAAC;CACF"}

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

@@ -0,0 +1,20 @@
+import type { TransformerContext } from '../transformer.js';
+/** What {@link withSourceFile} hands its callback. */
+export interface MaterializedSource {
+    /** Local path of the original's bytes. */
+    sourcePath: string;
+    /** The temp directory the source lives in — free scratch space, removed when the callback ends. */
+    tempDir: string;
+}
+/**
+ * Materialize a media original into a local temp file for the duration of `fn`, then remove the
+ * whole temp directory — success or failure.
+ *
+ * File-based media engines (mediabunny, and most others) want random access to a local path, while
+ * a disk object only offers bytes/stream — so file-shaped transformers all start with this same
+ * dance. The bytes are **streamed** to disk, never buffered whole: the typical subject is a video.
+ * The file keeps the original's extension purely as a debugging nicety; engines detect the real
+ * format from content.
+ */
+export declare function withSourceFile<T>(context: TransformerContext, fn: (source: MaterializedSource) => Promise<T>): Promise<T>;
+//# sourceMappingURL=source_file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source_file.d.ts","sourceRoot":"","sources":["../../../src/transformers/source_file.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,kBAAkB,EAC3B,EAAE,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,CAAC,CAYZ"}

package/dist/src/transformers/source_file.js

@@ -0,0 +1,30 @@
+import { createWriteStream } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { extname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+/**
+ * Materialize a media original into a local temp file for the duration of `fn`, then remove the
+ * whole temp directory — success or failure.
+ *
+ * File-based media engines (mediabunny, and most others) want random access to a local path, while
+ * a disk object only offers bytes/stream — so file-shaped transformers all start with this same
+ * dance. The bytes are **streamed** to disk, never buffered whole: the typical subject is a video.
+ * The file keeps the original's extension purely as a debugging nicety; engines detect the real
+ * format from content.
+ */
+export async function withSourceFile(context, fn) {
+    const tempDir = await mkdtemp(join(tmpdir(), 'agora-media-transform-'));
+    try {
+        const extension = extname(context.record.fileName);
+        const sourcePath = join(tempDir, `source${extension || '.bin'}`);
+        await pipeline(await context.getStream(), createWriteStream(sourcePath));
+        return await fn({ sourcePath, tempDir });
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => {
+            // best-effort: temp cleanup must never mask the transform's own outcome
+        });
+    }
+}
+//# sourceMappingURL=source_file.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source_file.js","sourceRoot":"","sources":["../../../src/transformers/source_file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAWhD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAA2B,EAC3B,EAA8C;IAE9C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,wBAAwB,CAAC,CAAC,CAAC;IACxE,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACnD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,SAAS,IAAI,MAAM,EAAE,CAAC,CAAC;QACjE,MAAM,QAAQ,CAAC,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC;QACzE,OAAO,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC7D,wEAAwE;QAC1E,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/src/types.d.ts

@@ -1,4 +1,8 @@
 import type { Readable } from 'node:stream';
+import type { DirectUploadCreatedSession } from './direct_upload.js';
+import type { DirectUploadResponse } from './direct_upload_handler.js';
+import type { AttachExistingInput } from './media_library.js';
+import type { MediaRecord } from './media_record.js';
 /**
  * The minimal disk surface `@adonis-agora/media` needs — a structural subset of an
  * `@adonisjs/drive` (flydrive) Disk, so a real Drive disk satisfies it directly. The library
@@ -173,4 +177,80 @@ export interface MultipartUploadDisk {
  * Omitting the name yields the configured default disk.
  */
 export type DiskResolver = (name?: string) => Disk;
+/**
+ * The app's decision for ONE direct upload, returned by {@link DirectUploadPolicy.onInitiate}. The
+ * library owns the invariant mechanics (open the multipart upload, presign, persist the session,
+ * confirm parts, assemble, adopt); the policy supplies the variant — above all the final object
+ * {@link key}, resolved server-side per user/tenant (the client sends a `fileName`, never a key).
+ *
+ * `response` is merged onto the `201` body the client receives (after the session fields), so a
+ * policy can hand the client extra data — e.g. the app-side `directUploadSessionId` it just
+ * persisted. `rollback` runs if anything after `onInitiate` throws (MIME gate, S3 open), letting the
+ * policy undo app-side state it already created.
+ */
+export type InitiateDecision<C> = {
+    key: string;
+    collection?: string;
+    disk?: string;
+    visibility?: 'public' | 'private';
+    partSize?: number;
+    metadata?: Record<string, string>;
+    response?: Record<string, unknown>;
+    context?: C;
+    rollback?: () => void | Promise<void>;
+};
+/**
+ * How a completed upload maps onto the media library, returned by
+ * {@link DirectUploadPolicy.resolveComplete}. `target` is everything `attachExisting` needs to adopt
+ * the already-uploaded object (minus `key`/`disk`/`size`, which the session already fixes).
+ */
+export type CompleteResolution<C> = {
+    sessionId: string;
+    target: Omit<AttachExistingInput, 'key' | 'disk' | 'size'>;
+    context?: C;
+};
+/** Which policy phase failed, with the decision/resolution in flight — handed to {@link DirectUploadPolicy.mapError}. */
+export type PolicyErrorInfo<C> = {
+    phase: 'initiate';
+    decision?: InitiateDecision<C> | undefined;
+} | {
+    phase: 'complete';
+    resolution?: CompleteResolution<C> | undefined;
+} | {
+    phase: 'abort';
+};
+/**
+ * The app-injected strategy that turns the framework-neutral {@link DirectUploadHandler} into a
+ * complete upload feature. The handler stays dumb and authorization-free; the policy answers the
+ * app-specific questions — where the object lives (`onInitiate`), what it becomes on completion
+ * (`resolveComplete`/`onComplete`), and how failures read as HTTP (`mapError`).
+ *
+ * Methods (not arrow properties) on purpose: TypeScript checks method parameters bivariantly, so an
+ * app's `DirectUploadPolicy<HttpContext, FileUpload>` is assignable to the handler's
+ * `DirectUploadPolicy<unknown, unknown>` without a cast.
+ */
+export interface DirectUploadPolicy<Ctx, C> {
+    onInitiate(ctx: Ctx, input: {
+        fileName: string;
+        size: number;
+        contentType?: string | undefined;
+        metadata?: Record<string, string> | undefined;
+    }): Promise<InitiateDecision<C>> | InitiateDecision<C>;
+    onInitiated?(ctx: Ctx, info: {
+        decision: InitiateDecision<C>;
+        session: DirectUploadCreatedSession;
+    }): Promise<void> | void;
+    resolveComplete(ctx: Ctx, input: {
+        id: string;
+        parts?: MultipartPart[] | undefined;
+    }): Promise<CompleteResolution<C>> | CompleteResolution<C>;
+    onComplete(ctx: Ctx, info: {
+        record: MediaRecord;
+        resolution: CompleteResolution<C>;
+    }): Promise<unknown>;
+    onAbort?(ctx: Ctx, input: {
+        id: string;
+    }): Promise<void> | void;
+    mapError?(ctx: Ctx, error: unknown, info: PolicyErrorInfo<C>): Promise<DirectUploadResponse | undefined> | DirectUploadResponse | undefined;
+}
 //# sourceMappingURL=types.d.ts.map

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

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

package/dist/stubs/config/media.stub

@@ -55,5 +55,17 @@ export default defineConfig({
   //     sessionTtlSeconds: 24 * 60 * 60,
   //     routes: { enabled: true, prefix: '/media/uploads/tus' },
   //   },
+  //
+  //   // Session-backed direct uploads — the browser PUTs multipart parts straight to S3 through
+  //   // presigned URLs (bytes never pass through the app), and the session (uploadId, part size,
+  //   // confirmed ETags) persists server-side so an interrupted upload resumes after a page
+  //   // reload. Needs a multipart-capable disk (disks.s3()); shares the session tables above.
+  //   direct: {
+  //     store: 'lucid',
+  //     stores: { lucid: uploadSessions.lucid() },
+  //     partSize: 20 * 1024 * 1024,
+  //     sessionTtlSeconds: 24 * 60 * 60,
+  //     routes: { enabled: true, prefix: '/media/uploads/direct/sessions', collection: 'videos' },
+  //   },
   // },
 })