ugcinc 4.20.0 → 4.22.0

package/dist/media-analysis.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaAnalysisResultSchema = exports.videoTextResultSchema = exports.imageTextResultSchema = exports.textLineSchema = exports.textRegionSchema = exports.readVideoTextSchema = exports.readImageTextSchema = exports.scenesResultSchema = exports.framesResultSchema = exports.analysisSourceSchema = exports.mediaAnalysisStatusSchema = exports.extractFramesSchema = exports.detectScenesSchema = void 0;
+const zod_1 = require("zod");
+const videoUrl = zod_1.z.string().url().max(8192).refine(value => {
+    const url = new URL(value);
+    return url.protocol === 'https:' && !url.username && !url.password && !url.hash;
+}, 'Expected an HTTPS video URL without credentials or fragment');
+const time = zod_1.z.number().finite().nonnegative();
+exports.detectScenesSchema = zod_1.z.object({ url: videoUrl }).strict();
+exports.extractFramesSchema = zod_1.z.object({
+    url: videoUrl,
+    timestampsMs: zod_1.z.array(time).min(1).max(48).optional(),
+    range: zod_1.z.object({ startMs: time, endMs: time, intervalMs: zod_1.z.number().finite().positive() }).strict().optional(),
+    selection: zod_1.z.enum(['nearest', 'before', 'after']).default('nearest'),
+    contactSheet: zod_1.z.boolean().default(true),
+}).strict().superRefine((value, ctx) => {
+    if (Boolean(value.timestampsMs) === Boolean(value.range))
+        ctx.addIssue({ code: 'custom', message: 'Provide timestampsMs or range, exclusively' });
+    const r = value.range;
+    if (r && (r.endMs <= r.startMs || Math.ceil((r.endMs - r.startMs) / r.intervalMs) > 48))
+        ctx.addIssue({ code: 'custom', message: 'Range must contain 1 to 48 samples with an exclusive end' });
+});
+exports.mediaAnalysisStatusSchema = zod_1.z.object({ jobId: zod_1.z.string().uuid() }).strict();
+exports.analysisSourceSchema = zod_1.z.object({
+    encodedWidth: zod_1.z.number(), encodedHeight: zod_1.z.number(), displayWidth: zod_1.z.number(), displayHeight: zod_1.z.number(), rotationDegrees: zod_1.z.number(),
+    sampleAspectRatio: zod_1.z.string(), durationMs: zod_1.z.number(), timeBase: zod_1.z.string(), startPts: zod_1.z.string(), startTimeMs: zod_1.z.number(), frameCount: zod_1.z.number(), variableFrameRate: zod_1.z.boolean(), sha256: zod_1.z.string(), bytes: zod_1.z.number(),
+});
+const frameSchema = zod_1.z.object({ index: zod_1.z.number(), requestedTimeMs: zod_1.z.number(), timeMs: zod_1.z.number(), sourcePts: zod_1.z.string(), frameIndex: zod_1.z.number(), width: zod_1.z.number(), height: zod_1.z.number(), url: zod_1.z.string().url() });
+const boxSchema = zod_1.z.object({ x: zod_1.z.number(), y: zod_1.z.number(), width: zod_1.z.number(), height: zod_1.z.number() });
+exports.framesResultSchema = zod_1.z.object({ version: zod_1.z.literal(1), operation: zod_1.z.literal('extract_frames'), source: exports.analysisSourceSchema, selection: zod_1.z.enum(['nearest', 'before', 'after']), frames: zod_1.z.array(frameSchema),
+    contactSheet: zod_1.z.object({ url: zod_1.z.string().url(), width: zod_1.z.number(), height: zod_1.z.number(), cells: zod_1.z.array(zod_1.z.object({ frameIndex: zod_1.z.number(), box: boxSchema, frameUrl: zod_1.z.string().url() })) }).nullable(), manifestUrl: zod_1.z.string().url() });
+exports.scenesResultSchema = zod_1.z.object({ version: zod_1.z.literal(1), operation: zod_1.z.literal('detect_scenes'), source: exports.analysisSourceSchema,
+    scenes: zod_1.z.array(zod_1.z.object({ index: zod_1.z.number(), startFrameIndex: zod_1.z.number(), endFrameIndexExclusive: zod_1.z.number(), startMs: zod_1.z.number(), endMs: zod_1.z.number(), startPts: zod_1.z.string(), endPts: zod_1.z.string().nullable() })),
+    detector: zod_1.z.object({ name: zod_1.z.string(), version: zod_1.z.string(), settings: zod_1.z.record(zod_1.z.number()) }), warnings: zod_1.z.array(zod_1.z.string()), manifestUrl: zod_1.z.string().url() });
+exports.readImageTextSchema = zod_1.z.object({ url: videoUrl }).strict();
+exports.readVideoTextSchema = zod_1.z.object({
+    url: videoUrl, mode: zod_1.z.enum(['fast', 'frame_scan']).default('fast'),
+    range: zod_1.z.object({ startMs: time, endMs: time }).strict().optional(),
+    intervalMs: zod_1.z.number().finite().min(100).max(120000).optional(),
+}).strict().superRefine((v, ctx) => {
+    if (v.mode === 'frame_scan' && v.intervalMs !== undefined)
+        ctx.addIssue({ code: 'custom', message: 'intervalMs applies only to fast mode' });
+    if (v.range && (v.range.endMs <= v.range.startMs || v.range.endMs - v.range.startMs > 120000))
+        ctx.addIssue({ code: 'custom', message: 'OCR range must be positive and at most 120 seconds' });
+});
+const pointSchema = zod_1.z.object({ x: zod_1.z.number().finite(), y: zod_1.z.number().finite() });
+const textFields = { text: zod_1.z.string().nullable(), rawText: zod_1.z.string(), confidence: zod_1.z.number().min(0).max(1), status: zod_1.z.enum(['readable', 'unreadable']) };
+exports.textRegionSchema = zod_1.z.object({ id: zod_1.z.string(), polygon: zod_1.z.array(pointSchema).length(4), box: boxSchema, ...textFields });
+exports.textLineSchema = zod_1.z.object({ id: zod_1.z.string(), readingOrder: zod_1.z.number().int().nonnegative(), regionIds: zod_1.z.array(zod_1.z.string()), box: boxSchema, ...textFields });
+const ocrModelSchema = zod_1.z.object({ name: zod_1.z.string(), runtime: zod_1.z.string(), device: zod_1.z.literal('cpu'), modelHashes: zod_1.z.record(zod_1.z.string()), orientationClassifier: zod_1.z.string(), recognitionThreshold: zod_1.z.number(), coordinates: zod_1.z.literal('display-oriented-source-pixels') });
+const textContent = { regions: zod_1.z.array(exports.textRegionSchema), lines: zod_1.z.array(exports.textLineSchema) };
+exports.imageTextResultSchema = zod_1.z.object({ version: zod_1.z.literal(1), operation: zod_1.z.literal('read_image_text'),
+    source: zod_1.z.object({ encodedWidth: zod_1.z.number(), encodedHeight: zod_1.z.number(), displayWidth: zod_1.z.number(), displayHeight: zod_1.z.number(), exifOrientation: zod_1.z.number(), alphaBackground: zod_1.z.literal('white'), sha256: zod_1.z.string(), bytes: zod_1.z.number() }),
+    ...textContent, model: ocrModelSchema, warnings: zod_1.z.array(zod_1.z.string()), previewUrl: zod_1.z.string().url(), manifestUrl: zod_1.z.string().url() });
+const intervalSchema = zod_1.z.object({ startMs: time, endMs: time });
+exports.videoTextResultSchema = zod_1.z.object({ version: zod_1.z.literal(1), operation: zod_1.z.literal('read_video_text'), source: exports.analysisSourceSchema,
+    model: ocrModelSchema, warnings: zod_1.z.array(zod_1.z.string()), manifestUrl: zod_1.z.string().url(),
+    frames: zod_1.z.array(zod_1.z.object({ frameIndex: zod_1.z.number().int(), sourcePts: zod_1.z.string(), timeMs: time, endMs: time, ...textContent, sceneChange: zod_1.z.boolean(), previewUrl: zod_1.z.string().url().optional() })),
+    tracks: zod_1.z.array(zod_1.z.object({ id: zod_1.z.string(), text: zod_1.z.string().nullable(), rawText: zod_1.z.string(), firstObservedMs: time, lastObservedEndMs: time,
+        observations: zod_1.z.array(zod_1.z.object({ sampleIndex: zod_1.z.number().int(), frameIndex: zod_1.z.number().int(), sourcePts: zod_1.z.string(), timeMs: time, endMs: time, lineId: zod_1.z.string(), box: boxSchema, confidence: zod_1.z.number() })) })),
+    coverage: zod_1.z.object({ mode: zod_1.z.enum(['fast', 'frame_scan']), range: intervalSchema, complete: zod_1.z.boolean(), uninspected: zod_1.z.array(intervalSchema),
+        inspected: zod_1.z.array(intervalSchema.extend({ frameIndex: zod_1.z.number().int(), sourcePts: zod_1.z.string() })) }),
+});
+exports.mediaAnalysisResultSchema = zod_1.z.discriminatedUnion('operation', [exports.framesResultSchema, exports.scenesResultSchema, exports.imageTextResultSchema, exports.videoTextResultSchema]);

package/dist/media.d.ts

@@ -1,4 +1,5 @@
 import { BaseClient } from './base';
+import type { ExtractFramesParams, DetectScenesParams, ReadImageTextParams, ReadVideoTextParams, MediaAnalysisJob } from './media-analysis';
 import type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult } from './social-acquisition';
 import type { ApiResponse } from './types';
 export interface UserMedia {
@@ -199,6 +200,16 @@ export interface OwnedUploadResponse {
  * Client for managing media files
  */
 export declare class MediaClient extends BaseClient {
+    /** Read English text with source-coordinate polygons and an annotated preview. */
+    readImageText(params: ReadImageTextParams): Promise<ApiResponse<MediaAnalysisJob>>;
+    readVideoText(params: ReadVideoTextParams): Promise<ApiResponse<MediaAnalysisJob>>;
+    extractFrames(params: ExtractFramesParams): Promise<ApiResponse<MediaAnalysisJob>>;
+    /** Detect scene ranges without exporting video clips. */
+    detectScenes(params: DetectScenesParams): Promise<ApiResponse<MediaAnalysisJob>>;
+    getMediaAnalysis(params: {
+        jobId: string;
+    }): Promise<ApiResponse<MediaAnalysisJob>>;
+    private waitForAnalysis;
     /** List a bounded page of TikTok/Instagram references; does not download media. */
     listProfilePosts(params: ListProfilePostsParams): Promise<ApiResponse<ListProfilePostsResult>>;
     /** Import actual post assets to owned media. Continuations are checkpointed server-side. */

package/dist/media.js

@@ -6,6 +6,35 @@ const base_1 = require("./base");
  * Client for managing media files
  */
 class MediaClient extends base_1.BaseClient {
+    /** Read English text with source-coordinate polygons and an annotated preview. */
+    async readImageText(params) {
+        return this.waitForAnalysis(await this.post('/media/analysis/read-image-text', params));
+    }
+    async readVideoText(params) {
+        return this.waitForAnalysis(await this.post('/media/analysis/read-video-text', params));
+    }
+    async extractFrames(params) {
+        return this.waitForAnalysis(await this.post('/media/analysis/extract-frames', params));
+    }
+    /** Detect scene ranges without exporting video clips. */
+    async detectScenes(params) {
+        return this.waitForAnalysis(await this.post('/media/analysis/detect-scenes', params));
+    }
+    async getMediaAnalysis(params) {
+        return this.post('/media/analysis/status', params);
+    }
+    async waitForAnalysis(initial) {
+        let response = initial;
+        for (let attempt = 0; attempt < 180 && response.ok && ['pending', 'processing'].includes(response.data.status); attempt++) {
+            await new Promise(resolve => setTimeout(resolve, 2000));
+            const next = await this.getMediaAnalysis({ jobId: response.data.jobId });
+            // Preserve the job handle if a transient polling failure interrupts the wait.
+            if (!next.ok)
+                return response;
+            response = next;
+        }
+        return response;
+    }
     /** List a bounded page of TikTok/Instagram references; does not download media. */
     async listProfilePosts(params) {
         return this.post('/media/social/list-profile-posts', params);

package/dist/render/compositions/IMessageDmComposition/types.d.ts

@@ -384,14 +384,14 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
         imageUrl: z.ZodOptional<z.ZodString>;
         groupWithPrevious: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        text: string;
         id: string;
+        text: string;
         sender: "user" | "recipient";
         imageUrl?: string | undefined;
         groupWithPrevious?: boolean | undefined;
     }, {
-        text: string;
         id: string;
+        text: string;
         sender: "user" | "recipient";
         imageUrl?: string | undefined;
         groupWithPrevious?: boolean | undefined;
@@ -399,21 +399,21 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
     dynamicCrop: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     cropVerticalCenter: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
+    width?: number | undefined;
+    height?: number | undefined;
     time?: string | undefined;
     backgroundColor?: string | undefined;
     lightMode?: boolean | undefined;
     username?: string | undefined;
     profilePicUrl?: string | undefined;
     messages?: {
-        text: string;
         id: string;
+        text: string;
         sender: "user" | "recipient";
         imageUrl?: string | undefined;
         groupWithPrevious?: boolean | undefined;
     }[] | undefined;
     dynamicCrop?: Record<string, any> | undefined;
-    width?: number | undefined;
-    height?: number | undefined;
     fps?: number | undefined;
     durationInFrames?: number | undefined;
     showDebugOverlay?: boolean | undefined;
@@ -582,21 +582,21 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
     readReceiptLeft?: number | undefined;
     readReceiptRight?: number | undefined;
 }, {
+    width?: number | undefined;
+    height?: number | undefined;
     time?: string | undefined;
     backgroundColor?: string | undefined;
     lightMode?: boolean | undefined;
     username?: string | undefined;
     profilePicUrl?: string | undefined;
     messages?: {
-        text: string;
         id: string;
+        text: string;
         sender: "user" | "recipient";
         imageUrl?: string | undefined;
         groupWithPrevious?: boolean | undefined;
     }[] | undefined;
     dynamicCrop?: Record<string, any> | undefined;
-    width?: number | undefined;
-    height?: number | undefined;
     fps?: number | undefined;
     durationInFrames?: number | undefined;
     showDebugOverlay?: boolean | undefined;

package/dist/render/types/remotion-composition.d.ts

@@ -8,16 +8,16 @@ export declare const remotionCompositionSchema: z.ZodObject<{
     durationInFrames: z.ZodNumber;
     inputProps: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, "strict", z.ZodTypeAny, {
-    source: string;
     width: number;
     height: number;
+    source: string;
     fps: number;
     durationInFrames: number;
     inputProps: Record<string, unknown>;
 }, {
-    source: string;
     width: number;
     height: number;
+    source: string;
     fps: number;
     durationInFrames: number;
     inputProps: Record<string, unknown>;
@@ -29,12 +29,12 @@ export declare const remotionCompositionPortSchema: z.ZodObject<{
     isArray: z.ZodBoolean;
     required: z.ZodBoolean;
 }, "strict", z.ZodTypeAny, {
-    type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+    type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
     id: string;
     isArray: boolean;
     required: boolean;
 }, {
-    type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+    type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
     id: string;
     isArray: boolean;
     required: boolean;
@@ -54,22 +54,22 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
         isArray: z.ZodBoolean;
         required: z.ZodBoolean;
     }, "strict", z.ZodTypeAny, {
-        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }, {
-        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }>, "many">, {
-        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[], {
-        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
@@ -77,33 +77,33 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
     outputMode: z.ZodEnum<["single", "per-input"]>;
     selectionMode: z.ZodNull;
 }, "strict", z.ZodTypeAny, {
+    width: number;
+    height: number;
     source: string;
     outputMode: "per-input" | "single";
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    width: number;
-    height: number;
     fps: number;
     durationInFrames: number;
     inputProps: Record<string, unknown>;
 }, {
+    width: number;
+    height: number;
     source: string;
     outputMode: "per-input" | "single";
     selectionMode: null;
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    width: number;
-    height: number;
     fps: number;
     durationInFrames: number;
     inputProps: Record<string, unknown>;

package/dist/tools/media.js

@@ -1,8 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mediaTools = void 0;
+const media_analysis_1 = require("../media-analysis");
 const zod_1 = require("zod");
 exports.mediaTools = [
+    { name: 'read_image_text', description: 'Read English image text with raw recognition, polygons in display-oriented source pixels, inferred lines/order and confidence. Includes annotated preview. Empty output does not prove no text. If pending, use get_media_analysis.', schema: media_analysis_1.readImageTextSchema, execute: async (client, params) => client.media.readImageText(params) },
+    { name: 'read_video_text', description: 'Read English video text and positional changes. fast samples frames (default 1000ms); frame_scan inspects every decoded frame in range. Returns source PTS, observed text tracks and explicit uninspected gaps. At most 240 inspected frames and 120 seconds per request. Sampling cannot guarantee exact appearance/disappearance. If pending, use get_media_analysis.', schema: media_analysis_1.readVideoTextSchema, execute: async (client, params) => client.media.readVideoText(params) },
+    { name: 'extract_frames', description: 'Extract video frames at timestampsMs or a range {startMs,endMs,intervalMs}; milliseconds relative to the first displayed frame. Returns actual decoded times and optional contact sheet. At most 48 samples. If pending, use get_media_analysis with jobId.', schema: media_analysis_1.extractFramesSchema, execute: async (client, params) => client.media.extractFrames(params) },
+    { name: 'detect_scenes', description: 'Detect scene ranges in a video using the existing adaptive/fade detector, without exporting clips. Times are source-relative milliseconds. If pending, use get_media_analysis with jobId.', schema: media_analysis_1.detectScenesSchema, execute: async (client, params) => client.media.detectScenes(params) },
+    { name: 'get_media_analysis', description: 'Read the status/result of a frame extraction or scene detection job in the current organization.', schema: media_analysis_1.mediaAnalysisStatusSchema, execute: async (client, params) => client.media.getMediaAnalysis(params) },
     {
         name: 'list_profile_posts',
         description: 'List a page of TikTok or Instagram profile posts, with metadata and an opaque continuation cursor. Does not download files; provider-visible history may be incomplete.',

package/dist/types.d.ts

@@ -20,3 +20,4 @@ export interface ErrorResponse {
 export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
 export type { PublicPostFailureCode, PublicPostRecovery, PublicPostNextAction, PublicPostFailure } from './post-failure';
 export type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult, SocialReferencePost, SocialReferenceAsset } from './social-acquisition';
+export type { ReadImageTextParams, ReadVideoTextParams, ImageTextResult, VideoTextResult, ExtractFramesParams, DetectScenesParams, FramesResult, ScenesResult, MediaAnalysisResult, MediaAnalysisJob } from "./media-analysis";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugcinc",
-  "version": "4.20.0",
+  "version": "4.22.0",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",