ugcinc 4.7.0 → 4.8.0

package/README.md

@@ -93,6 +93,22 @@ do {
 } while (cursor);
 ```
 
+## Caption Overlays
+
+Video posts can carry text overlays to display on the video. Pass `captionOverlays` to
+`posts.createVideo()`; each `CaptionOverlay` is `{ text, x, y, fontSize }`, where `x`/`y` are the
+overlay center as a fraction (0-1) of the video width/height and `fontSize` is a fraction (0-1) of
+the video height. Overlays are returned on the `Post` as `caption_overlays`.
+
+```typescript
+await client.posts.createVideo({
+  accountId: "acc_123",
+  videoUrl: "https://example.com/video.mp4",
+  caption: "Post description",
+  captionOverlays: [{ text: "Wait for it...", x: 0.5, y: 0.2, fontSize: 0.04 }],
+});
+```
+
 ## Useful Exports
 
 - `UGCClient` for API access

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { InputType } from './automations/nodes/types';
 export type { ClientConfig } from './base';
 export type { Account, AccountStat, AccountTask, EditProfileInfo, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, AccountInfoUpdate, UpdateAccountInfoParams, AccountInfoUpdateResult, UpdateAccountInfoResponse, AccountSocialUpdate, UpdateAccountSocialParams, AccountSocialUpdateResult, UpdateAccountSocialResponse, DeleteAccountPostsParams, DeleteAccountPostsResponse, ResetWarmupParams, ResetWarmupResponse, NicheSwitchUpdate, NicheSwitchParams, NicheSwitchResult, NicheSwitchResponse, CreateAccountInput, CreateAccountsParams, CreateAccountResult, CreateAccountsResponse, TroubleshootFailReason, TroubleshootAccount, TroubleshootParams, } from './accounts';
 export type { TaskType, Task, GetTasksParams } from './tasks';
-export type { PostType, PostStatus, Post, PostStat, GetPostsParams, CreateDraftParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, UpdatePostParams, DeletePostsParams, DeletePostsResponse, RetryPostsParams, SetPostStatusParams, SetPostStatusResponse, PreviewScheduleEntry, PreviewScheduleParams, PreviewScheduleResult, } from './posts';
+export type { PostType, PostStatus, Post, PostStat, CaptionOverlay, GetPostsParams, CreateDraftParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, UpdatePostParams, DeletePostsParams, DeletePostsResponse, RetryPostsParams, SetPostStatusParams, SetPostStatusResponse, PreviewScheduleEntry, PreviewScheduleParams, PreviewScheduleResult, } from './posts';
 export type { RefreshStatsParams, RefreshStatsError, RefreshStatsResponse, RefreshStatsProgressResponse, RefreshStartEvent, RefreshProgressEvent, RefreshDoneEvent, RefreshStreamEvent, DailyAggregatedStat, GetDailyAggregatedStatsParams, DailyAccountStat, GetDailyAccountStatsParams, DailyPostStat, GetDailyPostStatsParams, DashboardDailyStat, GetDashboardDailyStatsParams, TopAccount, GetTopAccountsParams, TopPost, GetTopPostsParams, } from './stats';
 export type { Org, ApiKey, DeleteApiKeyParams, EditApiKeyParams, IntegrationKey, IntegrationProvider, UpsertIntegrationKeyParams, DeleteIntegrationKeyParams } from './org';
 export type { UserMedia, MediaUse, SocialAudio, Media, GetMediaParams, GetSocialAudioParams, UploadMediaParams, UploadMediaResponse, MediaTagUpdate, UpdateMediaTagsParams, MediaTagUpdateResult, UpdateMediaTagsResponse, UpdateMediaTagParams, UpdateMediaNameParams, DeleteMediaParams, DeleteMediaResponse, CreateSocialAudioParams, ImportTextParams, ImportTextResponse, CreateMediaFromUrlParams, GetMediaUseParams, GetMediaUseResponse, FilterMediaParams, FilterMediaResponse, GetUploadTokenParams, UploadTokenResponse, } from './media';

package/dist/posts.d.ts

@@ -2,6 +2,17 @@ import { BaseClient } from './base';
 import type { ApiResponse } from './types';
 export type PostType = 'video' | 'slideshow';
 export type PostStatus = 'draft' | 'scheduled' | 'pending' | 'complete' | 'failed' | 'retrying' | 'deleting' | 'deleted' | 'hidden' | 'require-approval';
+/**
+ * A text overlay to display on top of a video post.
+ * x/y are the overlay center as a fraction (0-1) of the video width/height;
+ * fontSize is a fraction (0-1) of the video height.
+ */
+export interface CaptionOverlay {
+    text: string;
+    x: number;
+    y: number;
+    fontSize: number;
+}
 export interface Post {
     id: string;
     account_id: string | null;
@@ -9,6 +20,7 @@ export interface Post {
     status: PostStatus;
     social_id: string | null;
     caption: string | null;
+    caption_overlays: CaptionOverlay[] | null;
     title: string | null;
     media_urls: string[] | null;
     thumbnail_url: string | null;
@@ -62,6 +74,7 @@ export interface GetPostStatusParams {
 export interface CreateVideoParams {
     accountId: string | null;
     caption?: string;
+    captionOverlays?: CaptionOverlay[];
     socialAudioId?: string;
     postTime?: string;
     videoUrl: string;

package/dist/render/components/VideoElement.js

@@ -12,6 +12,14 @@ const react_1 = require("react");
 const remotion_1 = require("remotion");
 const defaults_1 = require("../utils/defaults");
 const text_1 = require("../utils/text");
+/**
+ * Preview sync threshold: remotion hard-seeks the media tag when it drifts
+ * further than this from the timeline (default ~0.65s). Fractional playback
+ * speeds accumulate drift, so the default produces large visible "rubberband"
+ * jumps; a tight threshold keeps corrections to a few frames. Preview-only —
+ * ignored during server rendering.
+ */
+const ACCEPTABLE_TIME_SHIFT_SECONDS = 0.2;
 /**
  * Map FitMode to CSS object-fit
  */
@@ -102,7 +110,7 @@ function VideoElement({ segment, src, startFrame, durationInFrames, scale = 1 })
         const effectiveDurationMs = loopSourceDurationMs / speed;
         return Math.max(1, Math.round((effectiveDurationMs / 1000) * fps));
     }, [loop, loopSourceDurationMs, speed, fps]);
-    const videoElement = ((0, jsx_runtime_1.jsx)(remotion_1.OffthreadVideo, { src: src, style: videoStyle, startFrom: startFromFrames, playbackRate: speed, volume: volume }));
+    const videoElement = ((0, jsx_runtime_1.jsx)(remotion_1.OffthreadVideo, { src: src, style: videoStyle, startFrom: startFromFrames, playbackRate: speed, volume: volume, acceptableTimeShiftInSeconds: ACCEPTABLE_TIME_SHIFT_SECONDS }));
     return ((0, jsx_runtime_1.jsx)("div", { style: containerStyle, children: loop && loopDurationInFrames ? ((0, jsx_runtime_1.jsx)(remotion_1.Loop, { durationInFrames: loopDurationInFrames, children: videoElement })) : (videoElement) }));
 }
 exports.default = VideoElement;

package/dist/render/compositions/VideoEditorComposition.js

@@ -134,27 +134,28 @@ function calculateSegmentTimings(config, fps) {
  * ```
  */
 function VideoEditorComposition({ config, sources = {}, textContent = {}, }) {
-    const frame = (0, remotion_1.useCurrentFrame)();
-    const { fps, durationInFrames } = (0, remotion_1.useVideoConfig)();
+    const { fps } = (0, remotion_1.useVideoConfig)();
     // Calculate segment timings
     const segmentTimings = (0, react_1.useMemo)(() => calculateSegmentTimings(config, fps), [config, fps]);
-    // Get active visual segments at current frame, sorted by zIndex
-    const activeVisualSegments = (0, react_1.useMemo)(() => {
+    // All visual segments, statically sorted by zIndex (stable sort keeps the
+    // original channel order for ties). Every segment is always rendered inside
+    // a <Sequence> window, which handles per-frame visibility — mounting is no
+    // longer gated on the current frame, so upcoming media can premount.
+    const visualTimings = (0, react_1.useMemo)(() => {
         return segmentTimings
-            .filter(({ segment, startFrame, endFrame }) => {
-            // Only visual segments (including sequences)
-            if (segment.type !== 'video' && segment.type !== 'image' && segment.type !== 'text' && segment.type !== 'image-sequence' && segment.type !== 'video-sequence') {
-                return false;
-            }
-            // Check if active at current frame
-            return frame >= startFrame && frame < endFrame;
+            .filter(({ segment }) => {
+            return segment.type === 'video' || segment.type === 'image' || segment.type === 'text' || segment.type === 'image-sequence' || segment.type === 'video-sequence';
         })
             .sort((a, b) => {
             const aZ = a.segment.zIndex ?? 0;
             const bZ = b.segment.zIndex ?? 0;
             return aZ - bZ;
         });
-    }, [segmentTimings, frame]);
+    }, [segmentTimings]);
+    // Premount window for video sequences: in the Player, upcoming videos
+    // mount invisibly this many frames early so they buffer and pre-seek
+    // before becoming visible. No effect on server rendering.
+    const premountFrames = Math.round(fps * 2);
     // Get source URL for a segment
     const getSource = (segment) => {
         if (segment.source) {
@@ -170,25 +171,25 @@ function VideoEditorComposition({ config, sources = {}, textContent = {}, }) {
     const audioTimings = (0, react_1.useMemo)(() => {
         return segmentTimings.filter(({ segment }) => segment.type === 'audio');
     }, [segmentTimings]);
-    return ((0, jsx_runtime_1.jsxs)(remotion_1.AbsoluteFill, { style: { backgroundColor: '#000000' }, children: [activeVisualSegments.map(({ segment, startFrame, durationInFrames }) => {
+    return ((0, jsx_runtime_1.jsxs)(remotion_1.AbsoluteFill, { style: { backgroundColor: '#000000' }, children: [visualTimings.map(({ segment, startFrame, durationInFrames }) => {
                 if (segment.type === 'text') {
                     const textSegment = segment;
                     const text = getTextContent(textSegment);
-                    return ((0, jsx_runtime_1.jsx)(TextElement_1.TextElement, { segment: { ...textSegment, text }, scale: 1 }, segment.id));
+                    return ((0, jsx_runtime_1.jsx)(remotion_1.Sequence, { from: startFrame, durationInFrames: durationInFrames, children: (0, jsx_runtime_1.jsx)(TextElement_1.TextElement, { segment: { ...textSegment, text }, scale: 1 }) }, segment.id));
                 }
                 if (segment.type === 'image') {
                     const src = getSource(segment);
                     if (!src) {
                         return null;
                     }
-                    return ((0, jsx_runtime_1.jsx)(ImageElement_1.ImageElement, { segment: segment, src: src, startFrame: startFrame, scale: 1 }, segment.id));
+                    return ((0, jsx_runtime_1.jsx)(remotion_1.Sequence, { from: startFrame, durationInFrames: durationInFrames, children: (0, jsx_runtime_1.jsx)(ImageElement_1.ImageElement, { segment: segment, src: src, startFrame: 0, scale: 1 }) }, segment.id));
                 }
                 if (segment.type === 'video') {
                     const src = getSource(segment);
                     if (!src) {
                         return null;
                     }
-                    return ((0, jsx_runtime_1.jsx)(remotion_1.Sequence, { from: startFrame, durationInFrames: durationInFrames, children: (0, jsx_runtime_1.jsx)(VideoElement_1.VideoElement, { segment: segment, src: src, startFrame: 0, durationInFrames: durationInFrames, scale: 1 }) }, segment.id));
+                    return ((0, jsx_runtime_1.jsx)(remotion_1.Sequence, { from: startFrame, durationInFrames: durationInFrames, premountFor: premountFrames, children: (0, jsx_runtime_1.jsx)(VideoElement_1.VideoElement, { segment: segment, src: src, startFrame: 0, durationInFrames: durationInFrames, scale: 1 }) }, segment.id));
                 }
                 if (segment.type === 'image-sequence') {
                     const sequenceSegment = segment;
@@ -196,32 +197,29 @@ function VideoEditorComposition({ config, sources = {}, textContent = {}, }) {
                     if (items.length === 0) {
                         return null;
                     }
-                    // Calculate which item should be shown at current frame
-                    const frameIntoSegment = frame - startFrame;
-                    const itemDurationFrames = Math.round((sequenceSegment.defaultDuration / 1000) * fps);
-                    const currentItemIndex = Math.floor(frameIntoSegment / itemDurationFrames);
-                    const currentItemUrl = items[currentItemIndex];
-                    if (currentItemIndex >= items.length || !currentItemUrl) {
-                        return null;
-                    }
-                    const itemStartFrame = startFrame + currentItemIndex * itemDurationFrames;
-                    const syntheticImageSegment = {
-                        id: `${segment.id}-item-${currentItemIndex}`,
-                        type: 'image',
-                        source: currentItemUrl,
-                        order: segment.order,
-                        offset: { type: 'absolute', value: 0 },
-                        xOffset: sequenceSegment.xOffset,
-                        yOffset: sequenceSegment.yOffset,
-                        width: sequenceSegment.width,
-                        height: sequenceSegment.height,
-                        fit: sequenceSegment.fit,
-                        rotation: sequenceSegment.rotation,
-                        opacity: sequenceSegment.opacity,
-                        zIndex: sequenceSegment.zIndex,
-                        fadeIn: sequenceSegment.fadeIn,
-                    };
-                    return ((0, jsx_runtime_1.jsx)(ImageElement_1.ImageElement, { segment: syntheticImageSegment, src: currentItemUrl, startFrame: itemStartFrame, scale: 1 }, `${segment.id}-${currentItemUrl}`));
+                    const itemDurationFrames = Math.max(1, Math.round((sequenceSegment.defaultDuration / 1000) * fps));
+                    return items.map((itemUrl, itemIndex) => {
+                        if (!itemUrl) {
+                            return null;
+                        }
+                        const syntheticImageSegment = {
+                            id: `${segment.id}-item-${itemIndex}`,
+                            type: 'image',
+                            source: itemUrl,
+                            order: segment.order,
+                            offset: { type: 'absolute', value: 0 },
+                            xOffset: sequenceSegment.xOffset,
+                            yOffset: sequenceSegment.yOffset,
+                            width: sequenceSegment.width,
+                            height: sequenceSegment.height,
+                            fit: sequenceSegment.fit,
+                            rotation: sequenceSegment.rotation,
+                            opacity: sequenceSegment.opacity,
+                            zIndex: sequenceSegment.zIndex,
+                            fadeIn: sequenceSegment.fadeIn,
+                        };
+                        return ((0, jsx_runtime_1.jsx)(remotion_1.Sequence, { from: startFrame + itemIndex * itemDurationFrames, durationInFrames: itemDurationFrames, children: (0, jsx_runtime_1.jsx)(ImageElement_1.ImageElement, { segment: syntheticImageSegment, src: itemUrl, startFrame: 0, scale: 1 }) }, `${segment.id}-item-${itemIndex}`));
+                    });
                 }
                 if (segment.type === 'video-sequence') {
                     const sequenceSegment = segment;
@@ -230,44 +228,33 @@ function VideoEditorComposition({ config, sources = {}, textContent = {}, }) {
                     if (items.length === 0) {
                         return null;
                     }
-                    // Calculate which item should be shown at current frame
-                    const frameIntoSegment = frame - startFrame;
                     let accumulatedFrames = 0;
-                    let currentItemIndex = -1;
-                    let itemStartFrame = startFrame;
-                    for (let i = 0; i < items.length; i++) {
-                        const itemDurationMs = durations[i] ?? 5000;
-                        const itemDurationFrames = Math.round((itemDurationMs / 1000) * fps);
-                        if (frameIntoSegment < accumulatedFrames + itemDurationFrames) {
-                            currentItemIndex = i;
-                            itemStartFrame = startFrame + accumulatedFrames;
-                            break;
-                        }
+                    return items.map((itemUrl, itemIndex) => {
+                        const itemDurationMs = durations[itemIndex] ?? 5000;
+                        const itemDurationFrames = Math.max(1, Math.round((itemDurationMs / 1000) * fps));
+                        const itemStartFrame = startFrame + accumulatedFrames;
                         accumulatedFrames += itemDurationFrames;
-                    }
-                    const currentItemUrl = items[currentItemIndex];
-                    if (currentItemIndex < 0 || currentItemIndex >= items.length || !currentItemUrl) {
-                        return null;
-                    }
-                    const itemDurationMs = durations[currentItemIndex] ?? 5000;
-                    const itemDurationFrames = Math.round((itemDurationMs / 1000) * fps);
-                    const syntheticVideoSegment = {
-                        id: `${segment.id}-item-${currentItemIndex}`,
-                        type: 'video',
-                        source: currentItemUrl,
-                        order: segment.order,
-                        offset: { type: 'absolute', value: 0 },
-                        xOffset: sequenceSegment.xOffset,
-                        yOffset: sequenceSegment.yOffset,
-                        width: sequenceSegment.width,
-                        height: sequenceSegment.height,
-                        fit: sequenceSegment.fit,
-                        rotation: sequenceSegment.rotation,
-                        opacity: sequenceSegment.opacity,
-                        zIndex: sequenceSegment.zIndex,
-                        fadeIn: sequenceSegment.fadeIn,
-                    };
-                    return ((0, jsx_runtime_1.jsx)(remotion_1.Sequence, { from: itemStartFrame, durationInFrames: itemDurationFrames, children: (0, jsx_runtime_1.jsx)(VideoElement_1.VideoElement, { segment: syntheticVideoSegment, src: currentItemUrl, startFrame: 0, durationInFrames: itemDurationFrames, scale: 1 }) }, `${segment.id}-${currentItemUrl}`));
+                        if (!itemUrl) {
+                            return null;
+                        }
+                        const syntheticVideoSegment = {
+                            id: `${segment.id}-item-${itemIndex}`,
+                            type: 'video',
+                            source: itemUrl,
+                            order: segment.order,
+                            offset: { type: 'absolute', value: 0 },
+                            xOffset: sequenceSegment.xOffset,
+                            yOffset: sequenceSegment.yOffset,
+                            width: sequenceSegment.width,
+                            height: sequenceSegment.height,
+                            fit: sequenceSegment.fit,
+                            rotation: sequenceSegment.rotation,
+                            opacity: sequenceSegment.opacity,
+                            zIndex: sequenceSegment.zIndex,
+                            fadeIn: sequenceSegment.fadeIn,
+                        };
+                        return ((0, jsx_runtime_1.jsx)(remotion_1.Sequence, { from: itemStartFrame, durationInFrames: itemDurationFrames, premountFor: premountFrames, children: (0, jsx_runtime_1.jsx)(VideoElement_1.VideoElement, { segment: syntheticVideoSegment, src: itemUrl, startFrame: 0, durationInFrames: itemDurationFrames, scale: 1 }) }, `${segment.id}-item-${itemIndex}`));
+                    });
                 }
                 return null;
             }), audioTimings.map(({ segment, startFrame, durationInFrames }) => {

package/package.json

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