@maravilla-labs/platform 0.12.0 → 0.14.0

package/dist/{transforms-DwCPOVTn.d.ts → transforms-BHWez32E.d.ts}

@@ -32,6 +32,15 @@ interface TranscodeOpts {
     max_height?: number;
     audio_codec?: string;
     bitrate_kbps?: number;
+    /**
+     * Force a constant output frame rate (fps). Pass this for variable-frame-rate
+     * sources (e.g. MediaRecorder WebM) so the MP4 stays frame-accurately
+     * seekable for the frames pipeline — without it, a near-static VFR segment
+     * can collapse to a handful of frames that a fixed-rate renderer stalls on.
+     * When omitted, the worker auto-applies CFR only if it probes the source as
+     * VFR; a determinate-rate source is left untouched.
+     */
+    fps?: number;
 }
 /** Options for `transforms.thumbnail` — extract a single video frame. */
 interface ThumbnailOpts {
@@ -43,6 +52,80 @@ interface ThumbnailOpts {
     format?: ImageFormat;
     quality?: number;
 }
+/**
+ * Options for `transforms.extractFrames` — decode a video into a sequence of
+ * still images at a fixed fps. General capability (any MP4 → frames); the
+ * frames renderer consumes the result to swap `<video>`→`<img>` per frame, and
+ * it's reusable for thumbnails/scrubbing.
+ */
+interface ExtractFramesOpts {
+    /** Frames per second to sample the source at. */
+    fps: number;
+    /** Optional max width (height auto, aspect preserved, no upscaling). */
+    width?: number;
+    /** Output image format. Defaults to `"jpg"` server-side when omitted. */
+    format?: ImageFormat;
+    /** JPEG/WebP quality 1..=100 (higher = better). Ignored for PNG. */
+    quality?: number;
+    /** Start offset into the clip, ms (default 0). */
+    seek_ms?: number;
+    /** How much of the clip to extract from `seek_ms`, ms (default: to end). */
+    duration_ms?: number;
+    /**
+     * Also extract the source's audio track to `detach_audio.target` in the SAME
+     * job — one call yields both the frame set and a detachable audio asset
+     * (folds the upload-time "detach audio" step into frame extraction). The
+     * frame-set manifest is still the job's primary output; the audio is written
+     * to the caller-chosen `target` key.
+     */
+    detach_audio?: DetachAudioOpts;
+}
+/**
+ * Bundle a detached-audio side-output into an {@link ExtractFramesOpts} job.
+ * The worker runs one extra audio-extraction pass on the same source and writes
+ * the AAC/m4a result to `target` (a caller-chosen, tenant-scoped storage key).
+ */
+interface DetachAudioOpts {
+    /** Storage key to write the extracted audio (AAC/m4a) to. */
+    target: string;
+    /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+    bitrate_kbps?: number;
+    /** Start offset into the source, ms (default 0). */
+    seek_ms?: number;
+    /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+    duration_ms?: number;
+}
+/**
+ * Options for `transforms.extractAudio` — split a video's audio track off into
+ * a standalone AAC/m4a asset. Used to detach the mic/system audio recorded
+ * alongside a camera/screen clip so it can be placed + ducked independently on
+ * the frames timeline.
+ */
+interface ExtractAudioOpts {
+    /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+    bitrate_kbps?: number;
+    /** Start offset into the source, ms (default 0). */
+    seek_ms?: number;
+    /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+    duration_ms?: number;
+}
+/**
+ * Result of an `extractFrames` job: a JSON manifest stored at the job's
+ * `output_key` describing the frame set. Frame `i` (0-based) lives at
+ * `${prefix}/frame_${i padded to 6}.${ext}`.
+ */
+interface FramesetManifest {
+    /** Storage key prefix the frame images live under (no trailing slash). */
+    prefix: string;
+    /** Number of frames written. */
+    count: number;
+    /** Sampling fps the frames were extracted at. */
+    fps: number;
+    /** Frame image format. */
+    format: ImageFormat;
+    width?: number;
+    height?: number;
+}
 /** Options for `transforms.resize`. */
 interface ResizeOpts {
     width?: number;
@@ -174,6 +257,10 @@ type TransformSpec = ({
 } & TranscodeOpts) | ({
     kind: 'thumbnail';
 } & ThumbnailOpts) | ({
+    kind: 'extract_frames';
+} & ExtractFramesOpts) | ({
+    kind: 'extract_audio';
+} & ExtractAudioOpts) | ({
     kind: 'resize';
 } & ResizeOpts) | ({
     kind: 'ocr';
@@ -219,6 +306,17 @@ interface JobStatusResponse {
 interface TransformsService {
     transcode(srcKey: string, opts: TranscodeOpts): Promise<JobHandle>;
     thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle>;
+    /**
+     * Decode a video into a sequence of frame images at a fixed fps. Resolves to
+     * a `JobHandle` whose `output_key` holds a `FramesetManifest` (JSON) once
+     * complete; frames live under `${manifest.prefix}/frame_NNNNNN.<ext>`.
+     */
+    extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle>;
+    /**
+     * Extract a video's audio track to a standalone AAC/m4a asset. Resolves to a
+     * `JobHandle` whose `output_key` holds the audio file once complete.
+     */
+    extractAudio(srcKey: string, opts?: ExtractAudioOpts | null): Promise<JobHandle>;
     resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
     probe(srcKey: string): Promise<MediaInfo>;
     ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
@@ -298,4 +396,4 @@ interface TransformsPatternSpec {
  */
 type TransformsConfig = Record<string, TransformsPatternSpec>;
 
-export { type DocFormat as D, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type DocToPdfOpts as d, type DocThumbnailOpts as e, type DocConvertOpts as f, type DocToMarkdownOpts as g, type DocToHtmlOpts as h, type ImageRef as i, type DocReplaceImagesOpts as j, type DocInsertQrCodeOpts as k, type QrPayload as l, type DocTemplateMergeOpts as m, type TransformSpec as n, type JobHandle as o, type JobStatusResponse as p, type TransformsService as q, keyFor as r, transforms as t };
+export { type DetachAudioOpts as D, type ExtractFramesOpts as E, type FramesetManifest as F, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type ExtractAudioOpts as d, type DocFormat as e, type DocToPdfOpts as f, type DocThumbnailOpts as g, type DocConvertOpts as h, type DocToMarkdownOpts as i, type DocToHtmlOpts as j, type ImageRef as k, type DocReplaceImagesOpts as l, type DocInsertQrCodeOpts as m, type QrPayload as n, type DocTemplateMergeOpts as o, type TransformSpec as p, type JobHandle as q, type JobStatusResponse as r, type TransformsService as s, keyFor as t, transforms as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/remote-client.ts

@@ -1,5 +1,5 @@
 import type { KvNamespace, KvListResult, Database, DbDocument, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, CreateManagedUserOptions, UserListFilter, UserListResponse, UpdateUserOptions, Relation, AddRelationOptions, ListRelationsOptions, PolicyExplain, CanCheck, ConnectedClient, ApiKeyInfo, LoginSession, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord, BrowserClient, FramesClient, BrowserJobHandle, ScreenshotRequest, PdfRequest, FramesRenderRequest } from './types.js';
-import type { TransformsService, TranscodeOpts, ThumbnailOpts, ResizeOpts, OcrOpts, DocToPdfOpts, DocThumbnailOpts, DocConvertOpts, DocToMarkdownOpts, DocToHtmlOpts, DocReplaceImagesOpts, DocInsertQrCodeOpts, DocTemplateMergeOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
+import type { TransformsService, TranscodeOpts, ExtractFramesOpts, ExtractAudioOpts, ThumbnailOpts, ResizeOpts, OcrOpts, DocToPdfOpts, DocThumbnailOpts, DocConvertOpts, DocToMarkdownOpts, DocToHtmlOpts, DocReplaceImagesOpts, DocInsertQrCodeOpts, DocTemplateMergeOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
 import { RemoteMediaService } from './media.js';
 import { getRequestAuthHeader } from './request-scope.js';
 
@@ -1280,6 +1280,14 @@ class RemoteTransformsService implements TransformsService {
     return this.post<JobHandle>('/transcode', { srcKey, opts });
   }
 
+  extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle> {
+    return this.post<JobHandle>('/extract_frames', { srcKey, opts });
+  }
+
+  extractAudio(srcKey: string, opts?: ExtractAudioOpts | null): Promise<JobHandle> {
+    return this.post<JobHandle>('/extract_audio', { srcKey, opts: opts ?? {} });
+  }
+
   thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle> {
     return this.post<JobHandle>('/thumbnail', { srcKey, opts });
   }

package/src/transforms.ts

@@ -80,6 +80,15 @@ export interface TranscodeOpts {
   max_height?: number;
   audio_codec?: string;
   bitrate_kbps?: number;
+  /**
+   * Force a constant output frame rate (fps). Pass this for variable-frame-rate
+   * sources (e.g. MediaRecorder WebM) so the MP4 stays frame-accurately
+   * seekable for the frames pipeline — without it, a near-static VFR segment
+   * can collapse to a handful of frames that a fixed-rate renderer stalls on.
+   * When omitted, the worker auto-applies CFR only if it probes the source as
+   * VFR; a determinate-rate source is left untouched.
+   */
+  fps?: number;
 }
 
 /** Options for `transforms.thumbnail` — extract a single video frame. */
@@ -93,6 +102,84 @@ export interface ThumbnailOpts {
   quality?: number;
 }
 
+/**
+ * Options for `transforms.extractFrames` — decode a video into a sequence of
+ * still images at a fixed fps. General capability (any MP4 → frames); the
+ * frames renderer consumes the result to swap `<video>`→`<img>` per frame, and
+ * it's reusable for thumbnails/scrubbing.
+ */
+export interface ExtractFramesOpts {
+  /** Frames per second to sample the source at. */
+  fps: number;
+  /** Optional max width (height auto, aspect preserved, no upscaling). */
+  width?: number;
+  /** Output image format. Defaults to `"jpg"` server-side when omitted. */
+  format?: ImageFormat;
+  /** JPEG/WebP quality 1..=100 (higher = better). Ignored for PNG. */
+  quality?: number;
+  /** Start offset into the clip, ms (default 0). */
+  seek_ms?: number;
+  /** How much of the clip to extract from `seek_ms`, ms (default: to end). */
+  duration_ms?: number;
+  /**
+   * Also extract the source's audio track to `detach_audio.target` in the SAME
+   * job — one call yields both the frame set and a detachable audio asset
+   * (folds the upload-time "detach audio" step into frame extraction). The
+   * frame-set manifest is still the job's primary output; the audio is written
+   * to the caller-chosen `target` key.
+   */
+  detach_audio?: DetachAudioOpts;
+}
+
+/**
+ * Bundle a detached-audio side-output into an {@link ExtractFramesOpts} job.
+ * The worker runs one extra audio-extraction pass on the same source and writes
+ * the AAC/m4a result to `target` (a caller-chosen, tenant-scoped storage key).
+ */
+export interface DetachAudioOpts {
+  /** Storage key to write the extracted audio (AAC/m4a) to. */
+  target: string;
+  /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+  bitrate_kbps?: number;
+  /** Start offset into the source, ms (default 0). */
+  seek_ms?: number;
+  /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+  duration_ms?: number;
+}
+
+/**
+ * Options for `transforms.extractAudio` — split a video's audio track off into
+ * a standalone AAC/m4a asset. Used to detach the mic/system audio recorded
+ * alongside a camera/screen clip so it can be placed + ducked independently on
+ * the frames timeline.
+ */
+export interface ExtractAudioOpts {
+  /** Output bitrate, kbps. Server picks a sensible AAC bitrate when omitted. */
+  bitrate_kbps?: number;
+  /** Start offset into the source, ms (default 0). */
+  seek_ms?: number;
+  /** How much of the source to extract from `seek_ms`, ms (default: to end). */
+  duration_ms?: number;
+}
+
+/**
+ * Result of an `extractFrames` job: a JSON manifest stored at the job's
+ * `output_key` describing the frame set. Frame `i` (0-based) lives at
+ * `${prefix}/frame_${i padded to 6}.${ext}`.
+ */
+export interface FramesetManifest {
+  /** Storage key prefix the frame images live under (no trailing slash). */
+  prefix: string;
+  /** Number of frames written. */
+  count: number;
+  /** Sampling fps the frames were extracted at. */
+  fps: number;
+  /** Frame image format. */
+  format: ImageFormat;
+  width?: number;
+  height?: number;
+}
+
 /** Options for `transforms.resize`. */
 export interface ResizeOpts {
   width?: number;
@@ -236,6 +323,8 @@ export interface DocTemplateMergeOpts {
 export type TransformSpec =
   | ({ kind: 'transcode' } & TranscodeOpts)
   | ({ kind: 'thumbnail' } & ThumbnailOpts)
+  | ({ kind: 'extract_frames' } & ExtractFramesOpts)
+  | ({ kind: 'extract_audio' } & ExtractAudioOpts)
   | ({ kind: 'resize' } & ResizeOpts)
   | ({ kind: 'ocr' } & OcrOpts)
   | ({ kind: 'doc_to_pdf' } & DocToPdfOpts)
@@ -277,6 +366,17 @@ export interface JobStatusResponse {
 export interface TransformsService {
   transcode(srcKey: string, opts: TranscodeOpts): Promise<JobHandle>;
   thumbnail(srcKey: string, opts: ThumbnailOpts): Promise<JobHandle>;
+  /**
+   * Decode a video into a sequence of frame images at a fixed fps. Resolves to
+   * a `JobHandle` whose `output_key` holds a `FramesetManifest` (JSON) once
+   * complete; frames live under `${manifest.prefix}/frame_NNNNNN.<ext>`.
+   */
+  extractFrames(srcKey: string, opts: ExtractFramesOpts): Promise<JobHandle>;
+  /**
+   * Extract a video's audio track to a standalone AAC/m4a asset. Resolves to a
+   * `JobHandle` whose `output_key` holds the audio file once complete.
+   */
+  extractAudio(srcKey: string, opts?: ExtractAudioOpts | null): Promise<JobHandle>;
   resize(srcKey: string, opts: ResizeOpts): Promise<JobHandle>;
   probe(srcKey: string): Promise<MediaInfo>;
   ocr(srcKey: string, opts?: OcrOpts | null): Promise<JobHandle>;
@@ -340,6 +440,11 @@ function outputExtension(spec: TransformSpec): string {
   switch (spec.kind) {
     case 'transcode':
       return spec.format; // 'mp4' | 'webm'
+    case 'extract_frames':
+      // Output key is the JSON frameset manifest; frames live under its base.
+      return 'json';
+    case 'extract_audio':
+      return 'm4a';
     case 'thumbnail':
     case 'resize': {
       // thumbnail's `format` is optional in TS (defaults to jpg server-side);