ugcinc 4.20.0 → 4.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -321,3 +321,44 @@ of original upload quality or watermark removal is made.
321
321
  Both operations require an organization and `content:analyze` for scoped keys.
322
322
  Errors may include `errorCode` and `retryable`. Existing scraper credit/rate safeguards
323
323
  apply. Storage/provider errors do not imply that a post or profile was deleted.
324
+
325
+ ## Video inspection
326
+
327
+ ```ts
328
+ const frames = await client.media.extractFrames({url: videoUrl, timestampsMs: [0, 1500, 3000]});
329
+ const scenes = await client.media.detectScenes({url: videoUrl});
330
+ // Recover a pending job without submitting another analysis:
331
+ const status = await client.media.getMediaAnalysis({jobId});
332
+ ```
333
+
334
+ These methods use authenticated `POST /media/analysis/extract-frames`,
335
+ `POST /media/analysis/detect-scenes` and `POST /media/analysis/status`.
336
+ They require an organization and `content:analyze`. Agent tools are `extract_frames`,
337
+ `detect_scenes` and the supporting `get_media_analysis` status operation.
338
+
339
+ Extraction accepts either `timestampsMs` (1–48 values, including timestamps from other
340
+ analysis results) or `range: {startMs,endMs,intervalMs}` (end exclusive, maximum 48
341
+ samples). `selection` is `nearest` (default; ties choose the earlier frame), `before`
342
+ or `after`. Times are milliseconds from the first displayed video frame. Out-of-range
343
+ requests fail; `after` fails if no later frame exists. Returned frames include requested
344
+ and actual times, original integer PTS as a string, decoded frame index, dimensions
345
+ and owned PNG URL. Rotation and sample aspect ratio are applied; outputs fit within
346
+ 1280 pixels on each axis without upscaling. `contactSheet` defaults to true and returns
347
+ a labeled sheet with cell boxes linked to the individual images. Duplicate requests
348
+ retain their order and may reference the same decoded frame.
349
+
350
+ Scene detection reuses the existing adaptive and brightness/pHash detector and returns
351
+ source-time ranges, frame indices and detector settings. It does not export split MP4s.
352
+ Ranges end exclusively. The last scene ends at video duration; its endPts is null when
353
+ there is no following frame. Boundaries are detector estimates, especially for fades,
354
+ not a guarantee of semantic scenes or an exact creative edit point.
355
+
356
+ Both operations run as bounded worker jobs. SDK/tool calls make up to 180 status polls, spaced two seconds apart;
357
+ check `data.status`: pending/processing includes `jobId` for subsequent status calls,
358
+ completed includes `result`, and failed includes an explicit error. A successful HTTP
359
+ response does not imply job completion. Status handles belong to their organization
360
+ and expire after seven days. Each submission analyzes the current source bytes rather
361
+ than caching by URL. Results include source SHA-256, encoded/display dimensions,
362
+ rotation, time base, source starting PTS, decoded frame count and an owned manifest.
363
+ Video URLs must be public HTTPS sources. Limits: 100 MB, 30 minutes, 4096 pixels per
364
+ encoded dimension, 120,000 decoded frames. Unsupported/malformed media fails explicitly.
@@ -333,6 +333,8 @@ export declare const nodeDefinitions: {
333
333
  __TOutputs: import("./screenshot-animation").ScreenshotAnimationNodeOutputs;
334
334
  };
335
335
  readonly 'remotion-composition': NodeDefinition<"remotion-composition", "generator", {
336
+ width: number;
337
+ height: number;
336
338
  source: string;
337
339
  outputMode: "per-input" | "single";
338
340
  selectionMode: null;
@@ -343,8 +345,6 @@ export declare const nodeDefinitions: {
343
345
  isArray: boolean;
344
346
  required: boolean;
345
347
  }[];
346
- width: number;
347
- height: number;
348
348
  fps: number;
349
349
  durationInFrames: number;
350
350
  inputProps: Record<string, unknown>;
@@ -4,6 +4,8 @@ type Outputs = {
4
4
  output: VideoValue;
5
5
  };
6
6
  declare const defaults: {
7
+ width: number;
8
+ height: number;
7
9
  source: string;
8
10
  outputMode: "per-input" | "single";
9
11
  selectionMode: null;
@@ -14,13 +16,13 @@ declare const defaults: {
14
16
  isArray: boolean;
15
17
  required: boolean;
16
18
  }[];
17
- width: number;
18
- height: number;
19
19
  fps: number;
20
20
  durationInFrames: number;
21
21
  inputProps: Record<string, unknown>;
22
22
  };
23
23
  declare const _default: import("./types").NodeDefinition<"remotion-composition", "generator", {
24
+ width: number;
25
+ height: number;
24
26
  source: string;
25
27
  outputMode: "per-input" | "single";
26
28
  selectionMode: null;
@@ -31,8 +33,6 @@ declare const _default: import("./types").NodeDefinition<"remotion-composition",
31
33
  isArray: boolean;
32
34
  required: boolean;
33
35
  }[];
34
- width: number;
35
- height: number;
36
36
  fps: number;
37
37
  durationInFrames: number;
38
38
  inputProps: Record<string, unknown>;
package/dist/index.d.ts CHANGED
@@ -86,3 +86,5 @@ export type { SuccessResponse, ErrorResponse, ApiResponse, } from './types';
86
86
  export type { CropBoundary, CropAxisConfig, DynamicCropConfig, BorderRadiusConfig, VerticalAnchor, HorizontalAnchor, HorizontalSelfAnchor, VerticalSelfAnchor, RelativePositionConfigX, RelativePositionConfigY, } from './render/types';
87
87
  export type { PublicPostFailureCode, PublicPostRecovery, PublicPostNextAction, PublicPostFailure } from './post-failure';
88
88
  export type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult, SocialReferencePost, SocialReferenceAsset } from './social-acquisition';
89
+ export type { ExtractFramesParams, DetectScenesParams, FramesResult, ScenesResult, MediaAnalysisResult, MediaAnalysisJob } from "./media-analysis";
90
+ export { extractFramesSchema, detectScenesSchema, mediaAnalysisStatusSchema, mediaAnalysisResultSchema } from "./media-analysis";
package/dist/index.js CHANGED
@@ -7,7 +7,7 @@
7
7
  Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.hasMissingTriggerError = exports.getPortErrorsForNode = exports.getErrorNodeIds = exports.validateWorkflow = exports.getCapturedNodes = exports.getNodesDownstreamOfSet = exports.getDownstreamNodes = exports.checkCrossContextViolation = exports.getForEachContext = exports.getConnectedSource = exports.cleanupStaleConnections = exports.removeNodeConnections = exports.removeConnection = exports.addConnection = exports.deriveConnections = exports.createNode = exports.getOutputSchema = exports.getNodeByType = exports.getAllNodes = exports.getInputPreviewValue = exports.computeAllNodePortsWithPreviews = exports.computeAllNodePorts = exports.computePortsWithPreviews = exports.computePortsForNode = exports.areTypesCompatible = exports.parseRemotionPropsJson = exports.REMOTION_COMPOSITION_IMPORTS = exports.remotionCompositionPortSchema = exports.remotionCompositionNodeSchema = exports.remotionCompositionSchema = exports.submitIMessageDmRenderJob = exports.submitInstagramDmRenderJob = exports.submitAutoCaptionRenderJob = exports.submitRemotionCompositionRenderJob = exports.submitScreenshotAnimationRenderJob = exports.submitSceneSplitJob = exports.submitDeduplicationJob = exports.getRenderJobStatus = exports.submitVideoRenderJob = exports.submitImageRenderJob = exports.BillingClient = exports.CommentsClient = exports.MediaClient = exports.AutomationsClient = exports.OrganizationClient = exports.StatsClient = exports.PostsClient = exports.TasksClient = exports.AccountsClient = exports.UGCClient = void 0;
9
9
  exports.parseOpenAPIOutputPath = exports.parseOpenAPIInputs = exports.mapOpenAPIType = exports.nodeConfigToCaptionStyle = exports.HttpMethods = exports.prepareImageComposerInput = exports.substituteVariables = exports.processTemplate = exports.extractTemplateVariables = exports.PortIdSchema = exports.normalizeToPortId = exports.portIdToTitle = exports.isValidPortId = exports.portId = exports.selectFromPool = exports.getModelDurations = exports.getModelAspectRatios = exports.ALL_VIDEO_MODELS = exports.getAvailableInputModes = exports.hasReferenceVariant = exports.getReferenceModelId = exports.hasFirstLastFrameVariant = exports.getFirstLastFrameModelId = exports.hasImageToVideoVariant = exports.getImageToVideoModelId = exports.isImageToVideoModel = exports.IMAGE_ASPECT_RATIOS = exports.ALL_IMAGE_MODELS = exports.getEditModelId = exports.isEditModel = exports.getCapturedSourceNodeTypes = exports.getFlowControlNodeTypes = exports.getAllNodeDefinitions = exports.getNodeDefinition = exports.isPortType = exports.formatPortType = exports.isAsyncExecutor = exports.internalNodeTypes = exports.nodeDefinitions = exports.extractWorkflowConfig = exports.generateNodeName = exports.shuffleNodePreview = exports.getPreviewValue = exports.removePreviewForConnection = exports.updatePreviewMapForConnection = exports.computePreviewMap = exports.computeAllNodePreviews = exports.resolveNodePreview = exports.getWorkflowOutputSchema = exports.hasMissingTerminalError = void 0;
10
- exports.prepareVideoComposerInput = exports.formatDateTag = exports.outputFieldsToZod = exports.outputFieldToZod = exports.LLMProviders = exports.applyLogicOperator = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToString = exports.indexExpressionToIndexes = exports.resolveUnknownPath = exports.getOutputTypeFromCategory = void 0;
10
+ exports.mediaAnalysisResultSchema = exports.mediaAnalysisStatusSchema = exports.detectScenesSchema = exports.extractFramesSchema = exports.prepareVideoComposerInput = exports.formatDateTag = exports.outputFieldsToZod = exports.outputFieldToZod = exports.LLMProviders = exports.applyLogicOperator = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToString = exports.indexExpressionToIndexes = exports.resolveUnknownPath = exports.getOutputTypeFromCategory = void 0;
11
11
  // =============================================================================
12
12
  // Client Exports
13
13
  // =============================================================================
@@ -174,3 +174,8 @@ var save_to_media_1 = require("./automations/nodes/save-to-media");
174
174
  Object.defineProperty(exports, "formatDateTag", { enumerable: true, get: function () { return save_to_media_1.formatDateTag; } });
175
175
  var video_composer_1 = require("./automations/nodes/video-composer");
176
176
  Object.defineProperty(exports, "prepareVideoComposerInput", { enumerable: true, get: function () { return video_composer_1.prepareVideoComposerInput; } });
177
+ var media_analysis_1 = require("./media-analysis");
178
+ Object.defineProperty(exports, "extractFramesSchema", { enumerable: true, get: function () { return media_analysis_1.extractFramesSchema; } });
179
+ Object.defineProperty(exports, "detectScenesSchema", { enumerable: true, get: function () { return media_analysis_1.detectScenesSchema; } });
180
+ Object.defineProperty(exports, "mediaAnalysisStatusSchema", { enumerable: true, get: function () { return media_analysis_1.mediaAnalysisStatusSchema; } });
181
+ Object.defineProperty(exports, "mediaAnalysisResultSchema", { enumerable: true, get: function () { return media_analysis_1.mediaAnalysisResultSchema; } });
@@ -0,0 +1,942 @@
1
+ import { z } from 'zod';
2
+ export declare const detectScenesSchema: z.ZodObject<{
3
+ url: z.ZodEffects<z.ZodString, string, string>;
4
+ }, "strict", z.ZodTypeAny, {
5
+ url: string;
6
+ }, {
7
+ url: string;
8
+ }>;
9
+ export declare const extractFramesSchema: z.ZodEffects<z.ZodObject<{
10
+ url: z.ZodEffects<z.ZodString, string, string>;
11
+ timestampsMs: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
12
+ range: z.ZodOptional<z.ZodObject<{
13
+ startMs: z.ZodNumber;
14
+ endMs: z.ZodNumber;
15
+ intervalMs: z.ZodNumber;
16
+ }, "strict", z.ZodTypeAny, {
17
+ startMs: number;
18
+ endMs: number;
19
+ intervalMs: number;
20
+ }, {
21
+ startMs: number;
22
+ endMs: number;
23
+ intervalMs: number;
24
+ }>>;
25
+ selection: z.ZodDefault<z.ZodEnum<["nearest", "before", "after"]>>;
26
+ contactSheet: z.ZodDefault<z.ZodBoolean>;
27
+ }, "strict", z.ZodTypeAny, {
28
+ url: string;
29
+ selection: "nearest" | "before" | "after";
30
+ contactSheet: boolean;
31
+ timestampsMs?: number[] | undefined;
32
+ range?: {
33
+ startMs: number;
34
+ endMs: number;
35
+ intervalMs: number;
36
+ } | undefined;
37
+ }, {
38
+ url: string;
39
+ timestampsMs?: number[] | undefined;
40
+ range?: {
41
+ startMs: number;
42
+ endMs: number;
43
+ intervalMs: number;
44
+ } | undefined;
45
+ selection?: "nearest" | "before" | "after" | undefined;
46
+ contactSheet?: boolean | undefined;
47
+ }>, {
48
+ url: string;
49
+ selection: "nearest" | "before" | "after";
50
+ contactSheet: boolean;
51
+ timestampsMs?: number[] | undefined;
52
+ range?: {
53
+ startMs: number;
54
+ endMs: number;
55
+ intervalMs: number;
56
+ } | undefined;
57
+ }, {
58
+ url: string;
59
+ timestampsMs?: number[] | undefined;
60
+ range?: {
61
+ startMs: number;
62
+ endMs: number;
63
+ intervalMs: number;
64
+ } | undefined;
65
+ selection?: "nearest" | "before" | "after" | undefined;
66
+ contactSheet?: boolean | undefined;
67
+ }>;
68
+ export declare const mediaAnalysisStatusSchema: z.ZodObject<{
69
+ jobId: z.ZodString;
70
+ }, "strict", z.ZodTypeAny, {
71
+ jobId: string;
72
+ }, {
73
+ jobId: string;
74
+ }>;
75
+ export type ExtractFramesParams = z.input<typeof extractFramesSchema>;
76
+ export type DetectScenesParams = z.input<typeof detectScenesSchema>;
77
+ export declare const analysisSourceSchema: z.ZodObject<{
78
+ encodedWidth: z.ZodNumber;
79
+ encodedHeight: z.ZodNumber;
80
+ displayWidth: z.ZodNumber;
81
+ displayHeight: z.ZodNumber;
82
+ rotationDegrees: z.ZodNumber;
83
+ sampleAspectRatio: z.ZodString;
84
+ durationMs: z.ZodNumber;
85
+ timeBase: z.ZodString;
86
+ startPts: z.ZodString;
87
+ startTimeMs: z.ZodNumber;
88
+ frameCount: z.ZodNumber;
89
+ variableFrameRate: z.ZodBoolean;
90
+ sha256: z.ZodString;
91
+ bytes: z.ZodNumber;
92
+ }, "strip", z.ZodTypeAny, {
93
+ encodedWidth: number;
94
+ encodedHeight: number;
95
+ displayWidth: number;
96
+ displayHeight: number;
97
+ rotationDegrees: number;
98
+ sampleAspectRatio: string;
99
+ durationMs: number;
100
+ timeBase: string;
101
+ startPts: string;
102
+ startTimeMs: number;
103
+ frameCount: number;
104
+ variableFrameRate: boolean;
105
+ sha256: string;
106
+ bytes: number;
107
+ }, {
108
+ encodedWidth: number;
109
+ encodedHeight: number;
110
+ displayWidth: number;
111
+ displayHeight: number;
112
+ rotationDegrees: number;
113
+ sampleAspectRatio: string;
114
+ durationMs: number;
115
+ timeBase: string;
116
+ startPts: string;
117
+ startTimeMs: number;
118
+ frameCount: number;
119
+ variableFrameRate: boolean;
120
+ sha256: string;
121
+ bytes: number;
122
+ }>;
123
+ export declare const framesResultSchema: z.ZodObject<{
124
+ version: z.ZodLiteral<1>;
125
+ operation: z.ZodLiteral<"extract_frames">;
126
+ source: z.ZodObject<{
127
+ encodedWidth: z.ZodNumber;
128
+ encodedHeight: z.ZodNumber;
129
+ displayWidth: z.ZodNumber;
130
+ displayHeight: z.ZodNumber;
131
+ rotationDegrees: z.ZodNumber;
132
+ sampleAspectRatio: z.ZodString;
133
+ durationMs: z.ZodNumber;
134
+ timeBase: z.ZodString;
135
+ startPts: z.ZodString;
136
+ startTimeMs: z.ZodNumber;
137
+ frameCount: z.ZodNumber;
138
+ variableFrameRate: z.ZodBoolean;
139
+ sha256: z.ZodString;
140
+ bytes: z.ZodNumber;
141
+ }, "strip", z.ZodTypeAny, {
142
+ encodedWidth: number;
143
+ encodedHeight: number;
144
+ displayWidth: number;
145
+ displayHeight: number;
146
+ rotationDegrees: number;
147
+ sampleAspectRatio: string;
148
+ durationMs: number;
149
+ timeBase: string;
150
+ startPts: string;
151
+ startTimeMs: number;
152
+ frameCount: number;
153
+ variableFrameRate: boolean;
154
+ sha256: string;
155
+ bytes: number;
156
+ }, {
157
+ encodedWidth: number;
158
+ encodedHeight: number;
159
+ displayWidth: number;
160
+ displayHeight: number;
161
+ rotationDegrees: number;
162
+ sampleAspectRatio: string;
163
+ durationMs: number;
164
+ timeBase: string;
165
+ startPts: string;
166
+ startTimeMs: number;
167
+ frameCount: number;
168
+ variableFrameRate: boolean;
169
+ sha256: string;
170
+ bytes: number;
171
+ }>;
172
+ selection: z.ZodEnum<["nearest", "before", "after"]>;
173
+ frames: z.ZodArray<z.ZodObject<{
174
+ index: z.ZodNumber;
175
+ requestedTimeMs: z.ZodNumber;
176
+ timeMs: z.ZodNumber;
177
+ sourcePts: z.ZodString;
178
+ frameIndex: z.ZodNumber;
179
+ width: z.ZodNumber;
180
+ height: z.ZodNumber;
181
+ url: z.ZodString;
182
+ }, "strip", z.ZodTypeAny, {
183
+ url: string;
184
+ index: number;
185
+ requestedTimeMs: number;
186
+ timeMs: number;
187
+ sourcePts: string;
188
+ frameIndex: number;
189
+ width: number;
190
+ height: number;
191
+ }, {
192
+ url: string;
193
+ index: number;
194
+ requestedTimeMs: number;
195
+ timeMs: number;
196
+ sourcePts: string;
197
+ frameIndex: number;
198
+ width: number;
199
+ height: number;
200
+ }>, "many">;
201
+ contactSheet: z.ZodNullable<z.ZodObject<{
202
+ url: z.ZodString;
203
+ width: z.ZodNumber;
204
+ height: z.ZodNumber;
205
+ cells: z.ZodArray<z.ZodObject<{
206
+ frameIndex: z.ZodNumber;
207
+ box: z.ZodObject<{
208
+ x: z.ZodNumber;
209
+ y: z.ZodNumber;
210
+ width: z.ZodNumber;
211
+ height: z.ZodNumber;
212
+ }, "strip", z.ZodTypeAny, {
213
+ width: number;
214
+ height: number;
215
+ x: number;
216
+ y: number;
217
+ }, {
218
+ width: number;
219
+ height: number;
220
+ x: number;
221
+ y: number;
222
+ }>;
223
+ frameUrl: z.ZodString;
224
+ }, "strip", z.ZodTypeAny, {
225
+ frameIndex: number;
226
+ box: {
227
+ width: number;
228
+ height: number;
229
+ x: number;
230
+ y: number;
231
+ };
232
+ frameUrl: string;
233
+ }, {
234
+ frameIndex: number;
235
+ box: {
236
+ width: number;
237
+ height: number;
238
+ x: number;
239
+ y: number;
240
+ };
241
+ frameUrl: string;
242
+ }>, "many">;
243
+ }, "strip", z.ZodTypeAny, {
244
+ url: string;
245
+ width: number;
246
+ height: number;
247
+ cells: {
248
+ frameIndex: number;
249
+ box: {
250
+ width: number;
251
+ height: number;
252
+ x: number;
253
+ y: number;
254
+ };
255
+ frameUrl: string;
256
+ }[];
257
+ }, {
258
+ url: string;
259
+ width: number;
260
+ height: number;
261
+ cells: {
262
+ frameIndex: number;
263
+ box: {
264
+ width: number;
265
+ height: number;
266
+ x: number;
267
+ y: number;
268
+ };
269
+ frameUrl: string;
270
+ }[];
271
+ }>>;
272
+ manifestUrl: z.ZodString;
273
+ }, "strip", z.ZodTypeAny, {
274
+ selection: "nearest" | "before" | "after";
275
+ contactSheet: {
276
+ url: string;
277
+ width: number;
278
+ height: number;
279
+ cells: {
280
+ frameIndex: number;
281
+ box: {
282
+ width: number;
283
+ height: number;
284
+ x: number;
285
+ y: number;
286
+ };
287
+ frameUrl: string;
288
+ }[];
289
+ } | null;
290
+ version: 1;
291
+ operation: "extract_frames";
292
+ source: {
293
+ encodedWidth: number;
294
+ encodedHeight: number;
295
+ displayWidth: number;
296
+ displayHeight: number;
297
+ rotationDegrees: number;
298
+ sampleAspectRatio: string;
299
+ durationMs: number;
300
+ timeBase: string;
301
+ startPts: string;
302
+ startTimeMs: number;
303
+ frameCount: number;
304
+ variableFrameRate: boolean;
305
+ sha256: string;
306
+ bytes: number;
307
+ };
308
+ frames: {
309
+ url: string;
310
+ index: number;
311
+ requestedTimeMs: number;
312
+ timeMs: number;
313
+ sourcePts: string;
314
+ frameIndex: number;
315
+ width: number;
316
+ height: number;
317
+ }[];
318
+ manifestUrl: string;
319
+ }, {
320
+ selection: "nearest" | "before" | "after";
321
+ contactSheet: {
322
+ url: string;
323
+ width: number;
324
+ height: number;
325
+ cells: {
326
+ frameIndex: number;
327
+ box: {
328
+ width: number;
329
+ height: number;
330
+ x: number;
331
+ y: number;
332
+ };
333
+ frameUrl: string;
334
+ }[];
335
+ } | null;
336
+ version: 1;
337
+ operation: "extract_frames";
338
+ source: {
339
+ encodedWidth: number;
340
+ encodedHeight: number;
341
+ displayWidth: number;
342
+ displayHeight: number;
343
+ rotationDegrees: number;
344
+ sampleAspectRatio: string;
345
+ durationMs: number;
346
+ timeBase: string;
347
+ startPts: string;
348
+ startTimeMs: number;
349
+ frameCount: number;
350
+ variableFrameRate: boolean;
351
+ sha256: string;
352
+ bytes: number;
353
+ };
354
+ frames: {
355
+ url: string;
356
+ index: number;
357
+ requestedTimeMs: number;
358
+ timeMs: number;
359
+ sourcePts: string;
360
+ frameIndex: number;
361
+ width: number;
362
+ height: number;
363
+ }[];
364
+ manifestUrl: string;
365
+ }>;
366
+ export declare const scenesResultSchema: z.ZodObject<{
367
+ version: z.ZodLiteral<1>;
368
+ operation: z.ZodLiteral<"detect_scenes">;
369
+ source: z.ZodObject<{
370
+ encodedWidth: z.ZodNumber;
371
+ encodedHeight: z.ZodNumber;
372
+ displayWidth: z.ZodNumber;
373
+ displayHeight: z.ZodNumber;
374
+ rotationDegrees: z.ZodNumber;
375
+ sampleAspectRatio: z.ZodString;
376
+ durationMs: z.ZodNumber;
377
+ timeBase: z.ZodString;
378
+ startPts: z.ZodString;
379
+ startTimeMs: z.ZodNumber;
380
+ frameCount: z.ZodNumber;
381
+ variableFrameRate: z.ZodBoolean;
382
+ sha256: z.ZodString;
383
+ bytes: z.ZodNumber;
384
+ }, "strip", z.ZodTypeAny, {
385
+ encodedWidth: number;
386
+ encodedHeight: number;
387
+ displayWidth: number;
388
+ displayHeight: number;
389
+ rotationDegrees: number;
390
+ sampleAspectRatio: string;
391
+ durationMs: number;
392
+ timeBase: string;
393
+ startPts: string;
394
+ startTimeMs: number;
395
+ frameCount: number;
396
+ variableFrameRate: boolean;
397
+ sha256: string;
398
+ bytes: number;
399
+ }, {
400
+ encodedWidth: number;
401
+ encodedHeight: number;
402
+ displayWidth: number;
403
+ displayHeight: number;
404
+ rotationDegrees: number;
405
+ sampleAspectRatio: string;
406
+ durationMs: number;
407
+ timeBase: string;
408
+ startPts: string;
409
+ startTimeMs: number;
410
+ frameCount: number;
411
+ variableFrameRate: boolean;
412
+ sha256: string;
413
+ bytes: number;
414
+ }>;
415
+ scenes: z.ZodArray<z.ZodObject<{
416
+ index: z.ZodNumber;
417
+ startFrameIndex: z.ZodNumber;
418
+ endFrameIndexExclusive: z.ZodNumber;
419
+ startMs: z.ZodNumber;
420
+ endMs: z.ZodNumber;
421
+ startPts: z.ZodString;
422
+ endPts: z.ZodNullable<z.ZodString>;
423
+ }, "strip", z.ZodTypeAny, {
424
+ startMs: number;
425
+ endMs: number;
426
+ startPts: string;
427
+ index: number;
428
+ startFrameIndex: number;
429
+ endFrameIndexExclusive: number;
430
+ endPts: string | null;
431
+ }, {
432
+ startMs: number;
433
+ endMs: number;
434
+ startPts: string;
435
+ index: number;
436
+ startFrameIndex: number;
437
+ endFrameIndexExclusive: number;
438
+ endPts: string | null;
439
+ }>, "many">;
440
+ detector: z.ZodObject<{
441
+ name: z.ZodString;
442
+ version: z.ZodString;
443
+ settings: z.ZodRecord<z.ZodString, z.ZodNumber>;
444
+ }, "strip", z.ZodTypeAny, {
445
+ version: string;
446
+ name: string;
447
+ settings: Record<string, number>;
448
+ }, {
449
+ version: string;
450
+ name: string;
451
+ settings: Record<string, number>;
452
+ }>;
453
+ warnings: z.ZodArray<z.ZodString, "many">;
454
+ manifestUrl: z.ZodString;
455
+ }, "strip", z.ZodTypeAny, {
456
+ version: 1;
457
+ operation: "detect_scenes";
458
+ source: {
459
+ encodedWidth: number;
460
+ encodedHeight: number;
461
+ displayWidth: number;
462
+ displayHeight: number;
463
+ rotationDegrees: number;
464
+ sampleAspectRatio: string;
465
+ durationMs: number;
466
+ timeBase: string;
467
+ startPts: string;
468
+ startTimeMs: number;
469
+ frameCount: number;
470
+ variableFrameRate: boolean;
471
+ sha256: string;
472
+ bytes: number;
473
+ };
474
+ manifestUrl: string;
475
+ scenes: {
476
+ startMs: number;
477
+ endMs: number;
478
+ startPts: string;
479
+ index: number;
480
+ startFrameIndex: number;
481
+ endFrameIndexExclusive: number;
482
+ endPts: string | null;
483
+ }[];
484
+ detector: {
485
+ version: string;
486
+ name: string;
487
+ settings: Record<string, number>;
488
+ };
489
+ warnings: string[];
490
+ }, {
491
+ version: 1;
492
+ operation: "detect_scenes";
493
+ source: {
494
+ encodedWidth: number;
495
+ encodedHeight: number;
496
+ displayWidth: number;
497
+ displayHeight: number;
498
+ rotationDegrees: number;
499
+ sampleAspectRatio: string;
500
+ durationMs: number;
501
+ timeBase: string;
502
+ startPts: string;
503
+ startTimeMs: number;
504
+ frameCount: number;
505
+ variableFrameRate: boolean;
506
+ sha256: string;
507
+ bytes: number;
508
+ };
509
+ manifestUrl: string;
510
+ scenes: {
511
+ startMs: number;
512
+ endMs: number;
513
+ startPts: string;
514
+ index: number;
515
+ startFrameIndex: number;
516
+ endFrameIndexExclusive: number;
517
+ endPts: string | null;
518
+ }[];
519
+ detector: {
520
+ version: string;
521
+ name: string;
522
+ settings: Record<string, number>;
523
+ };
524
+ warnings: string[];
525
+ }>;
526
+ export declare const mediaAnalysisResultSchema: z.ZodDiscriminatedUnion<"operation", [z.ZodObject<{
527
+ version: z.ZodLiteral<1>;
528
+ operation: z.ZodLiteral<"extract_frames">;
529
+ source: z.ZodObject<{
530
+ encodedWidth: z.ZodNumber;
531
+ encodedHeight: z.ZodNumber;
532
+ displayWidth: z.ZodNumber;
533
+ displayHeight: z.ZodNumber;
534
+ rotationDegrees: z.ZodNumber;
535
+ sampleAspectRatio: z.ZodString;
536
+ durationMs: z.ZodNumber;
537
+ timeBase: z.ZodString;
538
+ startPts: z.ZodString;
539
+ startTimeMs: z.ZodNumber;
540
+ frameCount: z.ZodNumber;
541
+ variableFrameRate: z.ZodBoolean;
542
+ sha256: z.ZodString;
543
+ bytes: z.ZodNumber;
544
+ }, "strip", z.ZodTypeAny, {
545
+ encodedWidth: number;
546
+ encodedHeight: number;
547
+ displayWidth: number;
548
+ displayHeight: number;
549
+ rotationDegrees: number;
550
+ sampleAspectRatio: string;
551
+ durationMs: number;
552
+ timeBase: string;
553
+ startPts: string;
554
+ startTimeMs: number;
555
+ frameCount: number;
556
+ variableFrameRate: boolean;
557
+ sha256: string;
558
+ bytes: number;
559
+ }, {
560
+ encodedWidth: number;
561
+ encodedHeight: number;
562
+ displayWidth: number;
563
+ displayHeight: number;
564
+ rotationDegrees: number;
565
+ sampleAspectRatio: string;
566
+ durationMs: number;
567
+ timeBase: string;
568
+ startPts: string;
569
+ startTimeMs: number;
570
+ frameCount: number;
571
+ variableFrameRate: boolean;
572
+ sha256: string;
573
+ bytes: number;
574
+ }>;
575
+ selection: z.ZodEnum<["nearest", "before", "after"]>;
576
+ frames: z.ZodArray<z.ZodObject<{
577
+ index: z.ZodNumber;
578
+ requestedTimeMs: z.ZodNumber;
579
+ timeMs: z.ZodNumber;
580
+ sourcePts: z.ZodString;
581
+ frameIndex: z.ZodNumber;
582
+ width: z.ZodNumber;
583
+ height: z.ZodNumber;
584
+ url: z.ZodString;
585
+ }, "strip", z.ZodTypeAny, {
586
+ url: string;
587
+ index: number;
588
+ requestedTimeMs: number;
589
+ timeMs: number;
590
+ sourcePts: string;
591
+ frameIndex: number;
592
+ width: number;
593
+ height: number;
594
+ }, {
595
+ url: string;
596
+ index: number;
597
+ requestedTimeMs: number;
598
+ timeMs: number;
599
+ sourcePts: string;
600
+ frameIndex: number;
601
+ width: number;
602
+ height: number;
603
+ }>, "many">;
604
+ contactSheet: z.ZodNullable<z.ZodObject<{
605
+ url: z.ZodString;
606
+ width: z.ZodNumber;
607
+ height: z.ZodNumber;
608
+ cells: z.ZodArray<z.ZodObject<{
609
+ frameIndex: z.ZodNumber;
610
+ box: z.ZodObject<{
611
+ x: z.ZodNumber;
612
+ y: z.ZodNumber;
613
+ width: z.ZodNumber;
614
+ height: z.ZodNumber;
615
+ }, "strip", z.ZodTypeAny, {
616
+ width: number;
617
+ height: number;
618
+ x: number;
619
+ y: number;
620
+ }, {
621
+ width: number;
622
+ height: number;
623
+ x: number;
624
+ y: number;
625
+ }>;
626
+ frameUrl: z.ZodString;
627
+ }, "strip", z.ZodTypeAny, {
628
+ frameIndex: number;
629
+ box: {
630
+ width: number;
631
+ height: number;
632
+ x: number;
633
+ y: number;
634
+ };
635
+ frameUrl: string;
636
+ }, {
637
+ frameIndex: number;
638
+ box: {
639
+ width: number;
640
+ height: number;
641
+ x: number;
642
+ y: number;
643
+ };
644
+ frameUrl: string;
645
+ }>, "many">;
646
+ }, "strip", z.ZodTypeAny, {
647
+ url: string;
648
+ width: number;
649
+ height: number;
650
+ cells: {
651
+ frameIndex: number;
652
+ box: {
653
+ width: number;
654
+ height: number;
655
+ x: number;
656
+ y: number;
657
+ };
658
+ frameUrl: string;
659
+ }[];
660
+ }, {
661
+ url: string;
662
+ width: number;
663
+ height: number;
664
+ cells: {
665
+ frameIndex: number;
666
+ box: {
667
+ width: number;
668
+ height: number;
669
+ x: number;
670
+ y: number;
671
+ };
672
+ frameUrl: string;
673
+ }[];
674
+ }>>;
675
+ manifestUrl: z.ZodString;
676
+ }, "strip", z.ZodTypeAny, {
677
+ selection: "nearest" | "before" | "after";
678
+ contactSheet: {
679
+ url: string;
680
+ width: number;
681
+ height: number;
682
+ cells: {
683
+ frameIndex: number;
684
+ box: {
685
+ width: number;
686
+ height: number;
687
+ x: number;
688
+ y: number;
689
+ };
690
+ frameUrl: string;
691
+ }[];
692
+ } | null;
693
+ version: 1;
694
+ operation: "extract_frames";
695
+ source: {
696
+ encodedWidth: number;
697
+ encodedHeight: number;
698
+ displayWidth: number;
699
+ displayHeight: number;
700
+ rotationDegrees: number;
701
+ sampleAspectRatio: string;
702
+ durationMs: number;
703
+ timeBase: string;
704
+ startPts: string;
705
+ startTimeMs: number;
706
+ frameCount: number;
707
+ variableFrameRate: boolean;
708
+ sha256: string;
709
+ bytes: number;
710
+ };
711
+ frames: {
712
+ url: string;
713
+ index: number;
714
+ requestedTimeMs: number;
715
+ timeMs: number;
716
+ sourcePts: string;
717
+ frameIndex: number;
718
+ width: number;
719
+ height: number;
720
+ }[];
721
+ manifestUrl: string;
722
+ }, {
723
+ selection: "nearest" | "before" | "after";
724
+ contactSheet: {
725
+ url: string;
726
+ width: number;
727
+ height: number;
728
+ cells: {
729
+ frameIndex: number;
730
+ box: {
731
+ width: number;
732
+ height: number;
733
+ x: number;
734
+ y: number;
735
+ };
736
+ frameUrl: string;
737
+ }[];
738
+ } | null;
739
+ version: 1;
740
+ operation: "extract_frames";
741
+ source: {
742
+ encodedWidth: number;
743
+ encodedHeight: number;
744
+ displayWidth: number;
745
+ displayHeight: number;
746
+ rotationDegrees: number;
747
+ sampleAspectRatio: string;
748
+ durationMs: number;
749
+ timeBase: string;
750
+ startPts: string;
751
+ startTimeMs: number;
752
+ frameCount: number;
753
+ variableFrameRate: boolean;
754
+ sha256: string;
755
+ bytes: number;
756
+ };
757
+ frames: {
758
+ url: string;
759
+ index: number;
760
+ requestedTimeMs: number;
761
+ timeMs: number;
762
+ sourcePts: string;
763
+ frameIndex: number;
764
+ width: number;
765
+ height: number;
766
+ }[];
767
+ manifestUrl: string;
768
+ }>, z.ZodObject<{
769
+ version: z.ZodLiteral<1>;
770
+ operation: z.ZodLiteral<"detect_scenes">;
771
+ source: z.ZodObject<{
772
+ encodedWidth: z.ZodNumber;
773
+ encodedHeight: z.ZodNumber;
774
+ displayWidth: z.ZodNumber;
775
+ displayHeight: z.ZodNumber;
776
+ rotationDegrees: z.ZodNumber;
777
+ sampleAspectRatio: z.ZodString;
778
+ durationMs: z.ZodNumber;
779
+ timeBase: z.ZodString;
780
+ startPts: z.ZodString;
781
+ startTimeMs: z.ZodNumber;
782
+ frameCount: z.ZodNumber;
783
+ variableFrameRate: z.ZodBoolean;
784
+ sha256: z.ZodString;
785
+ bytes: z.ZodNumber;
786
+ }, "strip", z.ZodTypeAny, {
787
+ encodedWidth: number;
788
+ encodedHeight: number;
789
+ displayWidth: number;
790
+ displayHeight: number;
791
+ rotationDegrees: number;
792
+ sampleAspectRatio: string;
793
+ durationMs: number;
794
+ timeBase: string;
795
+ startPts: string;
796
+ startTimeMs: number;
797
+ frameCount: number;
798
+ variableFrameRate: boolean;
799
+ sha256: string;
800
+ bytes: number;
801
+ }, {
802
+ encodedWidth: number;
803
+ encodedHeight: number;
804
+ displayWidth: number;
805
+ displayHeight: number;
806
+ rotationDegrees: number;
807
+ sampleAspectRatio: string;
808
+ durationMs: number;
809
+ timeBase: string;
810
+ startPts: string;
811
+ startTimeMs: number;
812
+ frameCount: number;
813
+ variableFrameRate: boolean;
814
+ sha256: string;
815
+ bytes: number;
816
+ }>;
817
+ scenes: z.ZodArray<z.ZodObject<{
818
+ index: z.ZodNumber;
819
+ startFrameIndex: z.ZodNumber;
820
+ endFrameIndexExclusive: z.ZodNumber;
821
+ startMs: z.ZodNumber;
822
+ endMs: z.ZodNumber;
823
+ startPts: z.ZodString;
824
+ endPts: z.ZodNullable<z.ZodString>;
825
+ }, "strip", z.ZodTypeAny, {
826
+ startMs: number;
827
+ endMs: number;
828
+ startPts: string;
829
+ index: number;
830
+ startFrameIndex: number;
831
+ endFrameIndexExclusive: number;
832
+ endPts: string | null;
833
+ }, {
834
+ startMs: number;
835
+ endMs: number;
836
+ startPts: string;
837
+ index: number;
838
+ startFrameIndex: number;
839
+ endFrameIndexExclusive: number;
840
+ endPts: string | null;
841
+ }>, "many">;
842
+ detector: z.ZodObject<{
843
+ name: z.ZodString;
844
+ version: z.ZodString;
845
+ settings: z.ZodRecord<z.ZodString, z.ZodNumber>;
846
+ }, "strip", z.ZodTypeAny, {
847
+ version: string;
848
+ name: string;
849
+ settings: Record<string, number>;
850
+ }, {
851
+ version: string;
852
+ name: string;
853
+ settings: Record<string, number>;
854
+ }>;
855
+ warnings: z.ZodArray<z.ZodString, "many">;
856
+ manifestUrl: z.ZodString;
857
+ }, "strip", z.ZodTypeAny, {
858
+ version: 1;
859
+ operation: "detect_scenes";
860
+ source: {
861
+ encodedWidth: number;
862
+ encodedHeight: number;
863
+ displayWidth: number;
864
+ displayHeight: number;
865
+ rotationDegrees: number;
866
+ sampleAspectRatio: string;
867
+ durationMs: number;
868
+ timeBase: string;
869
+ startPts: string;
870
+ startTimeMs: number;
871
+ frameCount: number;
872
+ variableFrameRate: boolean;
873
+ sha256: string;
874
+ bytes: number;
875
+ };
876
+ manifestUrl: string;
877
+ scenes: {
878
+ startMs: number;
879
+ endMs: number;
880
+ startPts: string;
881
+ index: number;
882
+ startFrameIndex: number;
883
+ endFrameIndexExclusive: number;
884
+ endPts: string | null;
885
+ }[];
886
+ detector: {
887
+ version: string;
888
+ name: string;
889
+ settings: Record<string, number>;
890
+ };
891
+ warnings: string[];
892
+ }, {
893
+ version: 1;
894
+ operation: "detect_scenes";
895
+ source: {
896
+ encodedWidth: number;
897
+ encodedHeight: number;
898
+ displayWidth: number;
899
+ displayHeight: number;
900
+ rotationDegrees: number;
901
+ sampleAspectRatio: string;
902
+ durationMs: number;
903
+ timeBase: string;
904
+ startPts: string;
905
+ startTimeMs: number;
906
+ frameCount: number;
907
+ variableFrameRate: boolean;
908
+ sha256: string;
909
+ bytes: number;
910
+ };
911
+ manifestUrl: string;
912
+ scenes: {
913
+ startMs: number;
914
+ endMs: number;
915
+ startPts: string;
916
+ index: number;
917
+ startFrameIndex: number;
918
+ endFrameIndexExclusive: number;
919
+ endPts: string | null;
920
+ }[];
921
+ detector: {
922
+ version: string;
923
+ name: string;
924
+ settings: Record<string, number>;
925
+ };
926
+ warnings: string[];
927
+ }>]>;
928
+ export type FramesResult = z.infer<typeof framesResultSchema>;
929
+ export type ScenesResult = z.infer<typeof scenesResultSchema>;
930
+ export type MediaAnalysisResult = z.infer<typeof mediaAnalysisResultSchema>;
931
+ export interface MediaAnalysisJob {
932
+ jobId: string;
933
+ operation: 'extract_frames' | 'detect_scenes';
934
+ status: 'pending' | 'processing' | 'completed' | 'failed';
935
+ progress: number;
936
+ result?: MediaAnalysisResult;
937
+ error?: {
938
+ code: string;
939
+ message: string;
940
+ retryable: boolean;
941
+ };
942
+ }
@@ -0,0 +1,36 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.mediaAnalysisResultSchema = exports.scenesResultSchema = exports.framesResultSchema = exports.analysisSourceSchema = exports.mediaAnalysisStatusSchema = exports.extractFramesSchema = exports.detectScenesSchema = void 0;
4
+ const zod_1 = require("zod");
5
+ const videoUrl = zod_1.z.string().url().max(8192).refine(value => {
6
+ const url = new URL(value);
7
+ return url.protocol === 'https:' && !url.username && !url.password && !url.hash;
8
+ }, 'Expected an HTTPS video URL without credentials or fragment');
9
+ const time = zod_1.z.number().finite().nonnegative();
10
+ exports.detectScenesSchema = zod_1.z.object({ url: videoUrl }).strict();
11
+ exports.extractFramesSchema = zod_1.z.object({
12
+ url: videoUrl,
13
+ timestampsMs: zod_1.z.array(time).min(1).max(48).optional(),
14
+ range: zod_1.z.object({ startMs: time, endMs: time, intervalMs: zod_1.z.number().finite().positive() }).strict().optional(),
15
+ selection: zod_1.z.enum(['nearest', 'before', 'after']).default('nearest'),
16
+ contactSheet: zod_1.z.boolean().default(true),
17
+ }).strict().superRefine((value, ctx) => {
18
+ if (Boolean(value.timestampsMs) === Boolean(value.range))
19
+ ctx.addIssue({ code: 'custom', message: 'Provide timestampsMs or range, exclusively' });
20
+ const r = value.range;
21
+ if (r && (r.endMs <= r.startMs || Math.ceil((r.endMs - r.startMs) / r.intervalMs) > 48))
22
+ ctx.addIssue({ code: 'custom', message: 'Range must contain 1 to 48 samples with an exclusive end' });
23
+ });
24
+ exports.mediaAnalysisStatusSchema = zod_1.z.object({ jobId: zod_1.z.string().uuid() }).strict();
25
+ exports.analysisSourceSchema = zod_1.z.object({
26
+ 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(),
27
+ 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(),
28
+ });
29
+ 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() });
30
+ 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() });
31
+ 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),
32
+ 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() });
33
+ exports.scenesResultSchema = zod_1.z.object({ version: zod_1.z.literal(1), operation: zod_1.z.literal('detect_scenes'), source: exports.analysisSourceSchema,
34
+ 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() })),
35
+ 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() });
36
+ exports.mediaAnalysisResultSchema = zod_1.z.discriminatedUnion('operation', [exports.framesResultSchema, exports.scenesResultSchema]);
package/dist/media.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { BaseClient } from './base';
2
+ import type { ExtractFramesParams, DetectScenesParams, MediaAnalysisJob } from './media-analysis';
2
3
  import type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult } from './social-acquisition';
3
4
  import type { ApiResponse } from './types';
4
5
  export interface UserMedia {
@@ -199,6 +200,14 @@ export interface OwnedUploadResponse {
199
200
  * Client for managing media files
200
201
  */
201
202
  export declare class MediaClient extends BaseClient {
203
+ /** Extract decoded frames and optionally a contact sheet. Follows up to 180 status polls; pending jobs can be polled by ID. */
204
+ extractFrames(params: ExtractFramesParams): Promise<ApiResponse<MediaAnalysisJob>>;
205
+ /** Detect scene ranges without exporting video clips. */
206
+ detectScenes(params: DetectScenesParams): Promise<ApiResponse<MediaAnalysisJob>>;
207
+ getMediaAnalysis(params: {
208
+ jobId: string;
209
+ }): Promise<ApiResponse<MediaAnalysisJob>>;
210
+ private waitForAnalysis;
202
211
  /** List a bounded page of TikTok/Instagram references; does not download media. */
203
212
  listProfilePosts(params: ListProfilePostsParams): Promise<ApiResponse<ListProfilePostsResult>>;
204
213
  /** Import actual post assets to owned media. Continuations are checkpointed server-side. */
package/dist/media.js CHANGED
@@ -6,6 +6,29 @@ const base_1 = require("./base");
6
6
  * Client for managing media files
7
7
  */
8
8
  class MediaClient extends base_1.BaseClient {
9
+ /** Extract decoded frames and optionally a contact sheet. Follows up to 180 status polls; pending jobs can be polled by ID. */
10
+ async extractFrames(params) {
11
+ return this.waitForAnalysis(await this.post('/media/analysis/extract-frames', params));
12
+ }
13
+ /** Detect scene ranges without exporting video clips. */
14
+ async detectScenes(params) {
15
+ return this.waitForAnalysis(await this.post('/media/analysis/detect-scenes', params));
16
+ }
17
+ async getMediaAnalysis(params) {
18
+ return this.post('/media/analysis/status', params);
19
+ }
20
+ async waitForAnalysis(initial) {
21
+ let response = initial;
22
+ for (let attempt = 0; attempt < 180 && response.ok && ['pending', 'processing'].includes(response.data.status); attempt++) {
23
+ await new Promise(resolve => setTimeout(resolve, 2000));
24
+ const next = await this.getMediaAnalysis({ jobId: response.data.jobId });
25
+ // Preserve the job handle if a transient polling failure interrupts the wait.
26
+ if (!next.ok)
27
+ return response;
28
+ response = next;
29
+ }
30
+ return response;
31
+ }
9
32
  /** List a bounded page of TikTok/Instagram references; does not download media. */
10
33
  async listProfilePosts(params) {
11
34
  return this.post('/media/social/list-profile-posts', params);
@@ -399,6 +399,8 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
399
399
  dynamicCrop: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
400
400
  cropVerticalCenter: z.ZodOptional<z.ZodBoolean>;
401
401
  }, "strip", z.ZodTypeAny, {
402
+ width?: number | undefined;
403
+ height?: number | undefined;
402
404
  time?: string | undefined;
403
405
  backgroundColor?: string | undefined;
404
406
  lightMode?: boolean | undefined;
@@ -412,8 +414,6 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
412
414
  groupWithPrevious?: boolean | undefined;
413
415
  }[] | undefined;
414
416
  dynamicCrop?: Record<string, any> | undefined;
415
- width?: number | undefined;
416
- height?: number | undefined;
417
417
  fps?: number | undefined;
418
418
  durationInFrames?: number | undefined;
419
419
  showDebugOverlay?: boolean | undefined;
@@ -582,6 +582,8 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
582
582
  readReceiptLeft?: number | undefined;
583
583
  readReceiptRight?: number | undefined;
584
584
  }, {
585
+ width?: number | undefined;
586
+ height?: number | undefined;
585
587
  time?: string | undefined;
586
588
  backgroundColor?: string | undefined;
587
589
  lightMode?: boolean | undefined;
@@ -595,8 +597,6 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
595
597
  groupWithPrevious?: boolean | undefined;
596
598
  }[] | undefined;
597
599
  dynamicCrop?: Record<string, any> | undefined;
598
- width?: number | undefined;
599
- height?: number | undefined;
600
600
  fps?: number | undefined;
601
601
  durationInFrames?: number | undefined;
602
602
  showDebugOverlay?: boolean | undefined;
@@ -8,16 +8,16 @@ export declare const remotionCompositionSchema: z.ZodObject<{
8
8
  durationInFrames: z.ZodNumber;
9
9
  inputProps: z.ZodRecord<z.ZodString, z.ZodUnknown>;
10
10
  }, "strict", z.ZodTypeAny, {
11
- source: string;
12
11
  width: number;
13
12
  height: number;
13
+ source: string;
14
14
  fps: number;
15
15
  durationInFrames: number;
16
16
  inputProps: Record<string, unknown>;
17
17
  }, {
18
- source: string;
19
18
  width: number;
20
19
  height: number;
20
+ source: string;
21
21
  fps: number;
22
22
  durationInFrames: number;
23
23
  inputProps: Record<string, unknown>;
@@ -77,6 +77,8 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
77
77
  outputMode: z.ZodEnum<["single", "per-input"]>;
78
78
  selectionMode: z.ZodNull;
79
79
  }, "strict", z.ZodTypeAny, {
80
+ width: number;
81
+ height: number;
80
82
  source: string;
81
83
  outputMode: "per-input" | "single";
82
84
  selectionMode: null;
@@ -87,12 +89,12 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
87
89
  isArray: boolean;
88
90
  required: boolean;
89
91
  }[];
90
- width: number;
91
- height: number;
92
92
  fps: number;
93
93
  durationInFrames: number;
94
94
  inputProps: Record<string, unknown>;
95
95
  }, {
96
+ width: number;
97
+ height: number;
96
98
  source: string;
97
99
  outputMode: "per-input" | "single";
98
100
  selectionMode: null;
@@ -102,8 +104,6 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
102
104
  isArray: boolean;
103
105
  required: boolean;
104
106
  }[];
105
- width: number;
106
- height: number;
107
107
  fps: number;
108
108
  durationInFrames: number;
109
109
  inputProps: Record<string, unknown>;
@@ -1,8 +1,12 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.mediaTools = void 0;
4
+ const media_analysis_1 = require("../media-analysis");
4
5
  const zod_1 = require("zod");
5
6
  exports.mediaTools = [
7
+ { 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) },
8
+ { 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) },
9
+ { 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) },
6
10
  {
7
11
  name: 'list_profile_posts',
8
12
  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 CHANGED
@@ -20,3 +20,4 @@ export interface ErrorResponse {
20
20
  export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
21
21
  export type { PublicPostFailureCode, PublicPostRecovery, PublicPostNextAction, PublicPostFailure } from './post-failure';
22
22
  export type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult, SocialReferencePost, SocialReferenceAsset } from './social-acquisition';
23
+ export type { ExtractFramesParams, DetectScenesParams, FramesResult, ScenesResult, MediaAnalysisResult, MediaAnalysisJob } from "./media-analysis";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ugcinc",
3
- "version": "4.20.0",
3
+ "version": "4.21.0",
4
4
  "description": "TypeScript/JavaScript client for the UGC Inc API",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",