@adonis-agora/media 0.8.2 → 0.9.0

package/dist/src/media_manager.js

@@ -1,5 +1,6 @@
 import { AttachmentManager } from './attachment.js';
-import { ResumableUploadsNotConfiguredError } from './errors.js';
+import { DirectUploadManager } from './direct_upload.js';
+import { DirectUploadsNotConfiguredError, ResumableUploadsNotConfiguredError } from './errors.js';
 import { MediaLibrary } from './media_library.js';
 import { ResumableUploadManager } from './resumable_upload.js';
 import { StorageManager } from './storage_manager.js';
@@ -28,6 +29,8 @@ export class MediaManager {
     uploads;
     /** Resumable (TUS) upload coordinator — present only when a session store is configured. */
     #resumable;
+    /** Session-backed direct upload coordinator — present only when a session store is configured. */
+    #direct;
     constructor(options) {
         this.store = options.store;
         this.storage = new StorageManager({ default: options.defaultDisk, resolve: options.resolve });
@@ -80,6 +83,25 @@ export class MediaManager {
                     : {}),
             });
         }
+        if (options.directUploadSessions !== undefined) {
+            this.#direct = new DirectUploadManager({
+                storage: this.storage,
+                sessions: options.directUploadSessions,
+                // The manager reads the whitelist from the same registry attach uses, so the initiate
+                // gate and the attach-time barrier cannot drift.
+                collections: this.library.collections,
+                ...(options.directPartSize !== undefined ? { partSize: options.directPartSize } : {}),
+                ...(options.directPresignTtlSeconds !== undefined
+                    ? { presignTtlSeconds: options.directPresignTtlSeconds }
+                    : {}),
+                ...(options.directSessionTtlSeconds !== undefined
+                    ? { sessionTtlSeconds: options.directSessionTtlSeconds }
+                    : {}),
+                ...(options.emitDiagnostics !== undefined
+                    ? { emitDiagnostics: options.emitDiagnostics }
+                    : {}),
+            });
+        }
     }
     /**
      * The resumable (TUS) upload coordinator. Throws {@link ResumableUploadsNotConfiguredError} unless
@@ -110,6 +132,37 @@ export class MediaManager {
         const { key, disk, size } = await this.resumable.complete(sessionId);
         return this.library.attachExisting({ ...input, key, disk, size });
     }
+    /**
+     * The session-backed direct upload coordinator. Throws {@link DirectUploadsNotConfiguredError}
+     * unless a session store was configured via `uploads.direct` in `config/media.ts`.
+     */
+    get direct() {
+        if (!this.#direct)
+            throw new DirectUploadsNotConfiguredError();
+        return this.#direct;
+    }
+    /** Whether session-backed direct uploads are configured (a session store is present). */
+    get hasDirect() {
+        return this.#direct !== undefined;
+    }
+    /**
+     * Finish a session-backed direct upload and register the assembled object as a media record, in
+     * one step — the direct-mode twin of {@link completeUploadToLibrary}, meeting the two layers at
+     * the manager the same way. `attachExisting` adopts the object zero-copy and re-validates the
+     * collection's whitelist against the REAL bytes (a short head read), so a client that lied about
+     * `contentType` at initiate is caught here, exactly like every other upload path.
+     *
+     * ```ts
+     * await media.completeDirectUploadToLibrary(sessionId, {
+     *   ownerType: 'Lesson', ownerId: lesson.id, collection: 'video',
+     *   fileName: 'original.mp4', mimeType: 'video/mp4',
+     * }, partsFromClient)
+     * ```
+     */
+    async completeDirectUploadToLibrary(sessionId, input, parts = []) {
+        const { key, disk, size } = await this.direct.complete(sessionId, parts);
+        return this.library.attachExisting({ ...input, key, disk, size });
+    }
     /**
      * The registered collection configs — the single source of truth for `acceptsMimeTypes`. Exposed
      * so the upload edge (`TusUploadHandler`) can enforce the very same whitelist the library will

package/dist/src/media_manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"media_manager.js","sourceRoot":"","sources":["../../src/media_manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,kCAAkC,EAAE,MAAM,aAAa,CAAC;AAGjE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIlD,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAML,aAAa,GACd,MAAM,qBAAqB,CAAC;AAkC7B;;;;;;;;;;GAUG;AACH,MAAM,OAAO,YAAY;IACd,OAAO,CAAiB;IACxB,OAAO,CAAe;IACtB,WAAW,CAAoB;IACxC;;;OAGG;IACM,KAAK,CAAa;IAC3B,qEAAqE;IAC5D,OAAO,CAAgB;IAChC,4FAA4F;IACnF,UAAU,CAAqC;IAExD,YAAY,OAA4B;QACtC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9F,IAAI,CAAC,OAAO,GAAG,IAAI,YAAY,CAAC;YAC9B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3F,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS;gBACvC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE;gBAC9C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrF,GAAG,CAAC,OAAO,CAAC,wBAAwB,KAAK,SAAS;gBAChD,CAAC,CAAC,EAAE,wBAAwB,EAAE,OAAO,CAAC,wBAAwB,EAAE;gBAChE,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,GAAG,IAAI,iBAAiB,CAAC;YACvC,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3F,GAAG,CAAC,OAAO,CAAC,mBAAmB,KAAK,SAAS;gBAC3C,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,mBAAmB,EAAE;gBAC5C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS;gBACvC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE;gBAC9C,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC;YAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzE,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrF,GAAG,CAAC,OAAO,CAAC,uBAAuB,KAAK,SAAS;gBAC/C,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,uBAAuB,EAAE;gBACxD,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS;gBACvC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE;gBAC9C,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;YACzC,IAAI,CAAC,UAAU,GAAG,IAAI,sBAAsB,CAAC;gBAC3C,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,QAAQ,EAAE,OAAO,CAAC,cAAc;gBAChC,GAAG,CAAC,OAAO,CAAC,kBAAkB,KAAK,SAAS;oBAC1C,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,kBAAkB,EAAE;oBAC3C,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,OAAO,CAAC,0BAA0B,KAAK,SAAS;oBAClD,CAAC,CAAC,EAAE,iBAAiB,EAAE,OAAO,CAAC,0BAA0B,EAAE;oBAC3D,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS;oBACvC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE;oBAC9C,CAAC,CAAC,EAAE,CAAC;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,IAAI,SAAS;QACX,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,MAAM,IAAI,kCAAkC,EAAE,CAAC;QACrE,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,uBAAuB,CAC3B,SAAiB,EACjB,KAAyD;QAEzD,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;;OAIG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IAClC,CAAC;IAED,mFAAmF;IACnF,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC;IACvC,CAAC;IAED,8EAA8E;IAC9E,IAAI,CAAC,IAAa;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,uFAAuF;IACvF,oBAAoB,CAAC,KAAgC;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,gEAAgE;IAChE,oBAAoB,CAAC,KAAgC;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,qDAAqD;IACrD,iBAAiB,CAAC,KAA6B;QAC7C,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,kFAAkF;IAClF,WAAW,CAAC,KAAuB;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;CACF"}
+{"version":3,"file":"media_manager.js","sourceRoot":"","sources":["../../src/media_manager.ts"],"names":[],"mappings":"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"}

package/dist/src/media_record.d.ts

@@ -1,6 +1,26 @@
+/**
+ * One generated derivative of a media record, keyed by conversion name in
+ * {@link MediaRecord.conversions}. Three shapes share this type:
+ *
+ * - an **image conversion** (a `ConversionPreset`): `{ path, disk }` — one file.
+ * - a **transformer output with artifacts** (e.g. the HLS package): `path` is the entry artifact
+ *   (the master playlist), `prefix` is the storage prefix holding every artifact, and `files`
+ *   lists them all relative to `prefix` — the authority for serving files out of the package and
+ *   for deleting it whole.
+ * - a **metadata-only transform** (a probe, a blurhash): no artifact at all — `path`/`disk` are
+ *   absent and only `meta` carries the result.
+ */
 export interface MediaConversion {
-    path: string;
-    disk: string;
+    /** Entry-point artifact key. Absent for metadata-only transforms. */
+    path?: string;
+    /** Disk holding the artifact(s). Absent when there are none. */
+    disk?: string;
+    /** Storage prefix (ends in `/`) holding every artifact of a multi-file conversion. */
+    prefix?: string;
+    /** Every artifact key relative to {@link prefix}, the entry included. */
+    files?: string[];
+    /** Transformer-reported metadata (duration, codecs, hashes, …), persisted verbatim. */
+    meta?: Record<string, unknown>;
 }
 /** A stored file associated with an owning entity (spatie media-library style). */
 export interface MediaRecord {

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

@@ -1 +1 @@
-{"version":3,"file":"media_record.d.ts","sourceRoot":"","sources":["../../src/media_record.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7C,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB"}
+{"version":3,"file":"media_record.d.ts","sourceRoot":"","sources":["../../src/media_record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC7C,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB"}

package/dist/src/testing/fake_transformer.d.ts

@@ -0,0 +1,32 @@
+import type { TransformResult, Transformer, TransformerContext } from '../transformer.js';
+export interface FakeTransformerOptions<Name extends string = string> {
+    /** Conversion name this fake produces. */
+    name: Name;
+    eager?: boolean;
+    /** Artifacts to write through `context.write`, keyed by prefix-relative path. */
+    artifacts?: Record<string, string>;
+    /**
+     * Entry declared in the result. Defaults to the first artifact key; pass `null` for a
+     * metadata-only result (with no artifacts).
+     */
+    entry?: string | null;
+    /** Metadata declared in the result. */
+    meta?: Record<string, unknown>;
+    /** Full behavior override — everything above but `name`/`eager` is ignored when set. */
+    behavior?: (context: TransformerContext) => Promise<TransformResult>;
+}
+/**
+ * Deterministic {@link Transformer} for tests — the transformer counterpart of
+ * `FakeImageProcessor`. It records every context it is called with and writes/declares exactly
+ * what it was configured to, so eager/deferred behaviour, artifact bookkeeping and rollback can be
+ * asserted without a media engine.
+ */
+export declare class FakeTransformer<Name extends string = string> implements Transformer {
+    readonly name: Name;
+    readonly eager: boolean;
+    readonly calls: TransformerContext[];
+    private readonly options;
+    constructor(options: FakeTransformerOptions<Name>);
+    transform(context: TransformerContext): Promise<TransformResult>;
+}
+//# sourceMappingURL=fake_transformer.d.ts.map

package/dist/src/testing/fake_transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake_transformer.d.ts","sourceRoot":"","sources":["../../../src/testing/fake_transformer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE1F,MAAM,WAAW,sBAAsB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IAClE,0CAA0C;IAC1C,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACtE;AAED;;;;;GAKG;AACH,qBAAa,eAAe,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,CAAE,YAAW,WAAW;IAC/E,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,EAAE,CAAM;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;gBAE3C,OAAO,EAAE,sBAAsB,CAAC,IAAI,CAAC;IAM3C,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;CAgBvE"}

package/dist/src/testing/fake_transformer.js

@@ -0,0 +1,32 @@
+/**
+ * Deterministic {@link Transformer} for tests — the transformer counterpart of
+ * `FakeImageProcessor`. It records every context it is called with and writes/declares exactly
+ * what it was configured to, so eager/deferred behaviour, artifact bookkeeping and rollback can be
+ * asserted without a media engine.
+ */
+export class FakeTransformer {
+    name;
+    eager;
+    calls = [];
+    options;
+    constructor(options) {
+        this.name = options.name;
+        this.eager = options.eager ?? false;
+        this.options = options;
+    }
+    async transform(context) {
+        this.calls.push(context);
+        if (this.options.behavior)
+            return this.options.behavior(context);
+        const artifacts = Object.entries(this.options.artifacts ?? {});
+        for (const [path, content] of artifacts) {
+            await context.write(path, Buffer.from(content, 'utf8'));
+        }
+        const entry = this.options.entry === null ? undefined : (this.options.entry ?? artifacts[0]?.[0]);
+        return {
+            ...(entry !== undefined ? { entry } : {}),
+            ...(this.options.meta !== undefined ? { meta: this.options.meta } : {}),
+        };
+    }
+}
+//# sourceMappingURL=fake_transformer.js.map

package/dist/src/testing/fake_transformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake_transformer.js","sourceRoot":"","sources":["../../../src/testing/fake_transformer.ts"],"names":[],"mappings":"AAmBA;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IACjB,IAAI,CAAO;IACX,KAAK,CAAU;IACf,KAAK,GAAyB,EAAE,CAAC;IACzB,OAAO,CAA+B;IAEvD,YAAY,OAAqC;QAC/C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,OAA2B;QACzC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEjE,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QAC/D,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,SAAS,EAAE,CAAC;YACxC,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,KAAK,GACT,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACtF,OAAO;YACL,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxE,CAAC;IACJ,CAAC;CACF"}

package/dist/src/testing/index.d.ts

@@ -3,4 +3,6 @@ export { InMemoryUploadSessionStore } from './in_memory_upload_session_store.js'
 export { InMemoryDisk, inMemoryDiskResolver } from './in_memory_disk.js';
 export type { DiskVisibility } from './in_memory_disk.js';
 export { FakeImageProcessor } from './fake_image_processor.js';
+export { FakeTransformer } from './fake_transformer.js';
+export type { FakeTransformerOptions } from './fake_transformer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/testing/index.js

@@ -2,4 +2,5 @@ export { InMemoryMediaStore } from './in_memory_media_store.js';
 export { InMemoryUploadSessionStore } from './in_memory_upload_session_store.js';
 export { InMemoryDisk, inMemoryDiskResolver } from './in_memory_disk.js';
 export { FakeImageProcessor } from './fake_image_processor.js';
+export { FakeTransformer } from './fake_transformer.js';
 //# sourceMappingURL=index.js.map

package/dist/src/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

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"}