ugcinc 4.26.0 → 4.27.0

package/dist/media.d.ts

@@ -2,6 +2,7 @@ import { BaseClient } from './base';
 import type { MatchTextStyleParams, SampleColorsParams, MeasureLayoutParams, TranscribeAudioParams, MeasureAudioLevelsParams, ExtractFramesParams, DetectScenesParams, ReadImageTextParams, ReadVideoTextParams, MediaAnalysisJob } from './media-analysis';
 import type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult } from './social-acquisition';
 import type { ApiResponse } from './types';
+import type { IMessageConversationInput, IMessageConversationJob } from './imessage-conversation';
 export interface UserMedia {
     id: string;
     org_id: string;
@@ -216,6 +217,16 @@ export declare class MediaClient extends BaseClient {
     getMediaAnalysis(params: {
         jobId: string;
     }): Promise<ApiResponse<MediaAnalysisJob>>;
+    /** Queue a native 60fps iMessage video or a lossless PNG snapshot of the same authored scene. */
+    renderIMessageConversation(params: IMessageConversationInput): Promise<ApiResponse<IMessageConversationJob>>;
+    /** Poll an iMessage render owned by this organization. */
+    getIMessageConversation(params: {
+        jobId: string;
+    }): Promise<ApiResponse<IMessageConversationJob>>;
+    /** Request cooperative cancellation; poll until cancelled or another terminal state. */
+    cancelIMessageConversation(params: {
+        jobId: string;
+    }): Promise<ApiResponse<IMessageConversationJob>>;
     private waitForAnalysis;
     /** List a bounded page of TikTok/Instagram references; does not download media. */
     listProfilePosts(params: ListProfilePostsParams): Promise<ApiResponse<ListProfilePostsResult>>;

package/dist/media.js

@@ -40,6 +40,18 @@ class MediaClient extends base_1.BaseClient {
     async getMediaAnalysis(params) {
         return this.post('/media/analysis/status', params);
     }
+    /** Queue a native 60fps iMessage video or a lossless PNG snapshot of the same authored scene. */
+    async renderIMessageConversation(params) {
+        return this.post('/media/render/imessage', params);
+    }
+    /** Poll an iMessage render owned by this organization. */
+    async getIMessageConversation(params) {
+        return this.post('/media/render/imessage/status', params);
+    }
+    /** Request cooperative cancellation; poll until cancelled or another terminal state. */
+    async cancelIMessageConversation(params) {
+        return this.post('/media/render/imessage/cancel', params);
+    }
     async waitForAnalysis(initial) {
         let response = initial;
         for (let attempt = 0; attempt < 180 && response.ok && ['pending', 'processing'].includes(response.data.status); attempt++) {

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

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

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

@@ -8,18 +8,18 @@ export declare const remotionCompositionSchema: z.ZodObject<{
     durationInFrames: z.ZodNumber;
     inputProps: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, "strict", z.ZodTypeAny, {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
 }, {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
 }>;
 export type RemotionCompositionInput = z.infer<typeof remotionCompositionSchema>;
@@ -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" | "text" | "audio";
+    type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
     id: string;
     isArray: boolean;
     required: boolean;
 }, {
-    type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+    type: "number" | "boolean" | "object" | "text" | "video" | "image" | "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" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }, {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }>, "many">, {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[], {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
@@ -77,6 +77,8 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
     outputMode: z.ZodEnum<["single", "per-input"]>;
     selectionMode: z.ZodNull;
 }, "strict", z.ZodTypeAny, {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
@@ -84,28 +86,26 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
 }, {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
     outputMode: "per-input" | "single";
     selectionMode: null;
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
     outputType?: "video" | "image" | undefined;
 }>;

package/dist/skills.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.skillFiles = void 0;
+const content_skills_1 = require("./content-skills");
 const run = 'npx ugcinc';
 exports.skillFiles = {
     'accounts/SKILL.md': `---
@@ -152,67 +153,6 @@ ${run} retry_posts '{"postIds":["id1"]}'
 - After creating a post, tell the user the post ID and scheduled time
 - For failed posts, check status first to understand the error before retrying
 - If $ARGUMENTS is provided, interpret it as a natural language request
-`,
-    'media/SKILL.md': `---
-name: media
-description: Manage UGC Inc media library - list, import, and organize videos, images, audio, and text. Use when the user wants to upload media, import audio, or manage their library.
-allowed-tools: Bash, Read
----
-
-You manage UGC Inc media through the CLI. Run tools with:
-\`\`\`bash
-${run} <tool_name> '<json_params>'
-\`\`\`
-
-Auth: \`npx ugcinc auth <api_key> [--admin]\`. Only needed once. Use \`--admin\` for admin keys.
-
-## Tools
-
-### list_media
-List all media (user media + social audio).
-\`\`\`bash
-${run} list_media
-${run} list_media '{"tag":"campaign-1"}'
-${run} list_media '{"ids":["id1","id2"]}'
-\`\`\`
-
-### list_social_audio
-List social audio only.
-\`\`\`bash
-${run} list_social_audio
-${run} list_social_audio '{"tag":"trending"}'
-\`\`\`
-
-### create_media_from_urls
-Import media from URLs (videos, images already hosted somewhere).
-\`\`\`bash
-${run} create_media_from_urls '{"urls":["https://example.com/video.mp4"],"tag":"imported"}'
-${run} create_media_from_urls '{"urls":["url1","url2"],"names":["Video 1","Video 2"]}'
-\`\`\`
-
-### import_text
-Import text content as media.
-\`\`\`bash
-${run} import_text '{"texts":[{"content":"Hello world","name":"greeting","tag":"captions"}]}'
-\`\`\`
-
-### create_social_audio
-Extract audio from a TikTok or Instagram URL.
-\`\`\`bash
-${run} create_social_audio '{"url":"https://www.tiktok.com/@user/video/123","tag":"trending"}'
-\`\`\`
-
-### delete_media
-Delete media items (also removes from storage).
-\`\`\`bash
-${run} delete_media '{"ids":["id1","id2"]}'
-\`\`\`
-
-## Workflow tips
-- Media types: video, image, audio, text, social_audio
-- When importing audio from TikTok/Instagram, use \`create_social_audio\` not \`create_media_from_urls\`
-- Tags help organize media - suggest tagging when importing
-- If $ARGUMENTS is provided, interpret it as a natural language request
 `,
     'automations/SKILL.md': `---
 name: automations
@@ -527,4 +467,5 @@ ${run} upsert_integration_key '{"provider":"openai","key":"sk-..."}'
 - Mention when stats were last refreshed and offer to refresh if stale
 - If $ARGUMENTS is provided, interpret it as a natural language request
 `,
+    ...content_skills_1.contentSkillFiles,
 };

package/dist/types.d.ts

@@ -18,6 +18,7 @@ export interface ErrorResponse {
     retryable?: boolean;
 }
 export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
+export type { IMessageConversationInput, IMessageConversationSettings, IMessageTiming, IMessageConversationPlan, IMessageConversationJob } from './imessage-conversation';
 export type { PublicPostFailureCode, PublicPostRecovery, PublicPostNextAction, PublicPostFailure } from './post-failure';
 export type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult, SocialReferencePost, SocialReferenceAsset } from './social-acquisition';
 export type { MatchTextStyleParams, MatchTextStyleResult, SampleColorsParams, MeasureLayoutParams, SampleColorsResult, MeasureLayoutResult, TranscribeAudioParams, MeasureAudioLevelsParams, AudioTranscriptResult, AudioLevelsResult, ReadImageTextParams, ReadVideoTextParams, ImageTextResult, VideoTextResult, ExtractFramesParams, DetectScenesParams, FramesResult, ScenesResult, MediaAnalysisResult, MediaAnalysisJob } from "./media-analysis";

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "ugcinc",
-  "version": "4.26.0",
+  "version": "4.27.0",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
+    "./imessage": {
+      "types": "./dist/imessage-conversation.d.ts",
+      "default": "./dist/imessage-conversation.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
@@ -23,7 +27,7 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/build-skills.cjs && tsc",
     "prepublishOnly": "npm run build",
     "test": "echo \"No tests specified\" && exit 0"
   },
@@ -65,6 +69,7 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ]
 }

package/skills/content-automation/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: content-automation
+description: Turn reference social posts or a rough content idea into a reusable UGC Inc workflow, with editable inputs and reviewed visual/audio output. Use for developing and validating content formats rather than scheduling existing finished posts.
+allowed-tools: Bash, Read
+---
+
+Build the format the user wants and collaborate at the level they requested.
+When they want to discuss, compare or review a specific artifact, do that before
+making additional format decisions. Keep questions concise and ask only when a
+missing answer prevents useful work. Do not impose a new per-video reference input
+when the user wants a fixed reusable visual format.
+
+Use the `media` skill for acquisition/inspection and the `automations` skill for
+current workflow tool calls. Read [references/build-review.md](references/build-review.md)
+when constructing or reviewing a workflow. Use only shipped tools/nodes discovered
+through `npx ugcinc --list`, `list_node_types` and `get_node_type`.
+
+## Understand and specify the format
+
+Acquire a bounded set of real references and inspect full frames and changes over
+time, including audio using available modalities. A contact sheet or transcript
+alone cannot establish all animation/pacing/music details. State uninspected
+parts instead of claiming playback. Distinguish reusable formats from variants;
+several posts may use the same structure with different assets, copy or timing.
+
+Write a compact spec: what the viewer sees first, the sequence/reveal, required
+inputs, reusable assets/components, changing copy, audio source/timing and final
+action/CTA if required by this format. Separate measured facts from inference
+and user choices. Share a verified HTTPS reference/preview when the user needs
+to identify the parts they want changed.
+
+Classify assets by replacement behavior. A recognizable Mii, Wojak or other exact
+meme image may need a static asset; an ordinary or newly generated face need not
+be static just because it looks meme-like. Preserve a headshot's identity across
+variants when requested, while making intended differences visibly meaningful.
+
+## Build reusable production behavior
+
+Separate layout, data/assets and motion. Expose the inputs a normal run needs:
+asset pools/overrides, text pools, contact/destination, duration/timing and seed
+where appropriate. Keep canonical outputs independent of an operator's laptop.
+Implement procedural animations as reusable components rendered on demand;
+do not substitute one pre-rendered clip when each run should vary. Randomness
+must respect the intended visual roles and remain replayable from saved inputs.
+
+Reuse existing nodes/compositions and actual public schemas. Analysis tools are
+available as CLI/SDK operations; do not assume every one is a workflow node.
+Validate the graph before executing. Prefer a reviewable output over publishing
+or enabling recurring runs unless the user authorized those actions.
+
+## Make the content work
+
+- Keep the hierarchy clear: readable hook, focal content, then the intended CTA.
+  Give characters/subjects enough visual weight; align visible content within
+  its section instead of trusting transparent image bounds alone.
+- Measure margins, spacing, text wrapping and overlap. Check at phone viewing
+  size, not only on a large canvas. Keep important text away from platform UI;
+  inspect the relevant target presentation rather than assuming universal margins.
+- Use sampled reference colors and real render previews. Judge font, stroke,
+  kerning, line height and emoji spacing together. Treat text-style fitting as a
+  measured candidate, not proof of an exact font or pixel-perfect output.
+- Match the reference post's actual audio excerpt, mix, start and duration when
+  requested. Preserve attribution separately. Empty transcription can mean music
+  or unrecognized speech, not silence. Keep visual reveals and audio timing coherent.
+- Keep required CTA/contact copy present and legible across every requested
+  variant. Use the user's actual destination/formatting, not a number copied from
+  an old example. Vary copy intentionally without altering the required action.
+- Test with real content and multiple asset/copy lengths. A composition that
+  works with one face or one short headline is not a validated reusable format.
+  Inspect early, changing and final states; a still cannot certify a full video.
+
+## Deliver and describe the boundary
+
+Provide the workflow, its normal inputs, replayable example parameters, verified
+HTTPS previews, and any observed visual/audio limits. For videos verify decoding,
+duration/dimensions/audio and byte-range playback; images need correct content
+type and decoding. Do not use local/localhost/private URLs as deliverables.
+
+SAM and automatic segmentation/overlay tracking are deferred. Use supplied
+assets, user-supplied boxes/masks or honest visual analysis; do not claim recovered
+source layers or automatic clean cutouts. If the runtime cannot inspect a media
+modality, record that limit and do not certify the uninspected property.

package/skills/content-automation/references/build-review.md

@@ -0,0 +1,66 @@
+# Construct and review a reusable workflow
+
+## Discover the real interface
+
+`npx ugcinc list_node_types '{}'` lists current node metadata.
+Use `get_node_type '{"nodeType":"..."}'` for the nodes you choose and read the
+bundled `automations` skill for current tool parameters. These tools still need
+a configured CLI key even when their own operation is local.
+
+Connections live on the target node, not a separate edges array:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "target",
+      "type": "node-type-from-discovery",
+      "config": {},
+      "inputs": {
+        "actual-input-port": {
+          "sourceNodeId": "source",
+          "sourceOutputId": "actual-output-port"
+        }
+      }
+    }
+  ]
+}
+```
+
+Use actual IDs/configuration returned by discovery, not these placeholders.
+Configure dynamic interfaces before wiring them. Re-check ports after config
+changes. Current validation requires a terminal outcome; inspect pass-through,
+save-to-media and posting nodes to choose the intended behavior. Publishing is
+not required just to make a reviewable workflow output.
+
+For reusable sub-workflows, configure their input/output contracts explicitly
+and inspect the Compose Workflow node's actual schema. For custom Remotion,
+inspect `remotion-composition`; use its supported composition/props/import
+contract. Do not invent an upload/register API or rely on arbitrary packages.
+
+Validate using `validate_workflow` with the shape described by the installed
+automation skill/tool. Execute only the intended single test scope, inspect its
+status/output, and retain resolved inputs and seed. Saving a template or receiving
+a run ID alone does not prove the output renders correctly.
+
+## Review a representative run
+
+Check the viewer's actual sequence: hook visibility, subject size, changing state,
+text wrapping/CTA, transitions and finish. Compare the full frame before zooming
+into details. Inspect multiple points around animation/text changes. Re-test a
+longer caption and a different asset where those vary in normal runs.
+
+Distinguish observed pixels/timestamps from estimates. Examples: sRGB sampling
+does not recover design colors from compression, transcript word timestamps are
+estimated, sampled OCR leaves gaps, and bounding boxes are not exact ink bounds.
+Manually supplied boxes are allowed; describe how they were determined.
+
+Preserve both soundtrack bytes and source attribution. Check whether music is
+embedded or only attributed, whether the output repeats/truncates it, and whether
+visual changes coincide with the intended moments. Do not invent beat detection,
+audio separation, universal media comparison or other unavailable tools.
+
+When revising content, name the concrete issue and inspect the changed output.
+Keep reusable parameters instead of baking a correction into one reference
+image. Report remaining defects plainly; avoid calling a draft production-ready
+based only on successful API execution.

package/skills/media/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: media
+description: Acquire TikTok and Instagram posts and inspect images, video and audio with UGC Inc tools. Use for reference analysis, OCR, frames, scenes, transcription, colors, layout, text-style fitting, or media-library management.
+allowed-tools: Bash, Read
+---
+
+Use the installed UGC Inc CLI:
+
+```bash
+npx ugcinc --list
+npx ugcinc <tool_name> '<json_params>'
+```
+
+Credentials come from `UGC_API_KEY` or existing UGC configuration. Use the user's
+organization and a key with `content:analyze` for acquisition/analysis. If using
+an admin key, pass the authorized `orgId` in the JSON parameters. Do not print
+credentials, copy an administrator key to another user's machine, or change
+organizations to bypass a denial. Confirm access with one small tool call.
+If credentials already live in an app env file, set `UGC_ENV_FILE` to that file's
+path so the CLI reads the existing key without duplicating its contents. Set
+`UGC_ORG_ID` in that file or the process environment to scope calls to the user's
+organization; an explicit JSON `orgId` takes priority.
+
+Read [references/tools.md](references/tools.md) for request shapes, result fields
+and limits. The CLI lists names/descriptions; the reference explains parameters.
+
+## Choose the input and tools
+
+- A profile URL: `list_profile_posts` discovers a bounded page; follow its cursor
+  only as needed. Listing does not download media or guarantee complete history.
+- A post URL: `download_social_post` ingests its ordered assets into owned media.
+  Use returned asset URLs for analysis; the TikTok/Instagram HTML URL is not a
+  video file. Check complete/partial/failed status and failed assets.
+- A direct media URL: use the corresponding inspection tool directly.
+- Video: `detect_scenes`, `extract_frames`, `read_video_text`; audio tools accept
+  video too. Inspect multiple moments, including changes near the beginning/end.
+- Image: `read_image_text`, `sample_colors`, `measure_layout` using supplied
+  boxes/masks, and `match_text_style` for a specified text crop.
+- Audio: `transcribe_audio` and `measure_audio_levels`.
+
+The SDK/CLI waits for processing automatically. Check both the outer response's
+`ok` and the returned job's `status`. Analysis is usable when
+`data.status === "completed"`; its content is `data.result`. If still pending or
+processing, keep its job ID and use `get_media_analysis` rather than resubmitting.
+Use bounded retries for retryable failures; report persistent errors/partial
+coverage. A zero process exit code alone does not establish API success.
+
+## Interpret evidence accurately
+
+- Coordinates are display-oriented source pixels; times are source-relative
+  milliseconds. Use returned decoded timestamps, dimensions and coverage.
+- OCR is English, may miss stylized text, and can be empty on unreadable input.
+  `fast` video OCR leaves uninspected intervals. `frame_scan` is bounded and
+  cannot inspect an arbitrarily long clip in one request.
+- Speech timestamps are estimates; speaker labels/forced alignment are absent.
+  A transcript does not establish music, emotion, delivery or sound effects.
+- Color sampling measures decoded sRGB pixels, not guaranteed design hex values.
+  Layout measurement does not detect objects or recover original layer files.
+- Text-style matching returns supported UGC settings and visual residuals. Font
+  identity is unverified; inspect the preview before calling a fit accurate.
+  It has a restricted ASCII/font/style surface; the native TikTok renderer is a
+  separate bounded rendering capability, not proof that matching is exact.
+- SAM/object segmentation, automatic overlay detection, element/mask tracking,
+  motion measurement, extraction, media comparison/alignment and semantic search
+  are not available through this tool set. Do not invent those calls or install
+  SAM. Existing OCR text tracks remain available.
+
+## Review and share media
+
+Open returned image/contact-sheet previews and review the relevant sequence.
+When the agent runtime can consume audio/video, use it. Otherwise use the
+available transcript, audio preview and level measurements and explicitly state
+what was not listened to or inspected. Do not claim to have watched/listened
+because an analysis request succeeded.
+
+Share only verified browser-accessible HTTPS artifacts. Fetch without auth and
+check status, content type and decoding; for video also check byte-range support.
+Use the returned owned-media URLs. Local paths, localhost/private addresses and
+expiring upstream CDN links are not deliverable previews. If an artifact needs
+uploading, use the supported owned storage path; do not claim a file is hosted
+because a media record was created for an arbitrary URL.
+
+For building a reusable content format, use the `content-automation` skill.

package/skills/media/references/tools.md

@@ -0,0 +1,64 @@
+# UGC media tool requests and results
+
+Run `npx ugcinc TOOL 'JSON'`. Shell quoting varies on Windows; if the shell
+changes the JSON, use a small Node script with `UGCClient` and its `media`
+methods instead of repeatedly sending malformed requests. For example:
+
+```js
+const { UGCClient } = require('ugcinc');
+const client = new UGCClient({
+  apiKey: process.env.UGC_API_KEY,
+  orgId: process.env.UGC_ORG_ID,
+});
+// Use admin:true only with an authorized administrator credential.
+```
+
+Request URLs must be HTTPS. Analysis source URLs must not contain credentials
+or fragments. Image operations support still PNG/JPEG/WebP, at most4096pixels
+per side; the shared download limit is100MiB. Geometry must fit the actual
+display-oriented source. Respect more restrictive operation limits below.
+
+## Acquisition
+
+| CLI tool / SDK method | Parameters | Result |
+| --- | --- | --- |
+| `list_profile_posts` / `media.listProfilePosts` | `{url, limit?, cursor?}`; TikTok/Instagram profile; limit1–50 | `data.posts`, profile metadata, continuation cursor. Follow the actual returned cursor, not a fabricated page number. |
+| `download_social_post` / `media.downloadSocialPost` | `{url}`; canonical TikTok/Instagram post URL | `data.status`, `assets[]` in order, `failedAssets[]`, `manifestUrl`, post/sound metadata. Each asset has `url`, `mediaId`, dimensions, type, duration, audio presence and hash. Repeat the same URL to resume retryable partial imports. |
+
+Embedded video audio remains attached. Photo assets have no embedded soundtrack;
+sound attribution does not mean audio bytes were downloaded. Preserve sound
+ID/link separately; never replace a post excerpt with the full sound-page track
+and call them identical. Partial imports are not a complete carousel.
+
+## Analysis
+
+These return `{ok, data:{jobId,status,operation,result?,error?}}`. Use the completed
+`data.result` fields listed below. Failure can occur after successful submission.
+
+| CLI tool / SDK method | Parameters | Result content |
+| --- | --- | --- |
+| `extract_frames` / `media.extractFrames` | `{url,timestampsMs:[0,1500,3000],selection:"nearest",contactSheet:true}` OR `{url,range:{startMs,endMs,intervalMs}}`; choose exactly one selector, at most48samples | `frames[]` with requested/decoded time, source PTS, dimensions and URL; optional `contactSheet` with individual frame links; source metadata. |
+| `detect_scenes` / `media.detectScenes` | `{url}` | `scenes[]` with start/end milliseconds, frame indexes, source PTS; no split MP4 exports. |
+| `read_image_text` / `media.readImageText` | `{url}` | `regions[]` with text/rawText, polygons/boxes/confidence; inferred `lines[]`/reading order; `previewUrl`. |
+| `read_video_text` / `media.readVideoText` | `{url,mode:"fast",intervalMs:1000,range?:{startMs,endMs}}` OR `{url,mode:"frame_scan",range?:{startMs,endMs}}` | `frames[]`, text `tracks[]` with observations/positions; explicit `coverage.inspected` and `uninspected`. Maximum240inspected frames and120seconds per request. `intervalMs` only applies to fast mode. |
+| `transcribe_audio` / `media.transcribeAudio` | `{url,range?:{startMs,endMs},language?:"auto",timing?:"word",channel?:0}` | `status`, `text`, timed `segments[]` and estimated words, warnings, `audioPreviewUrl`. Range at most120seconds; timing `word` or `segment`; optional channel0/1. Empty/no-audio/no-speech states are distinct. |
+| `measure_audio_levels` / `media.measureAudioLevels` | `{url,range?:{startMs,endMs},windowMs?:100,silenceThresholdDbfs?:-50}` | Native-channel RMS/sample peaks, loudness timeline/LUFS, silence, possible clipping, `previewUrl`. Windows20–5000ms, threshold−100to−10dBFS, range at most120seconds. |
+| `sample_colors` / `media.sampleColors` | `{url,maxColors?:8,point?:{x,y},box?:{x,y,width,height},mask?}`; choose at most one selection | Observed RGBA point or palette/proportions, omitted mass, declared color policy, `previewUrl`. Palette1–32colors. |
+| `measure_layout` / `media.measureLayout` | `{url,elements:[{id,box:{x,y,width,height}}]}`; each element may instead have `mask` | Margins, centers, spacing/alignment deltas, intersections/IoU and `previewUrl`.1–32unique IDs. Boxes are supplied, not automatically detected. |
+| `match_text_style` / `media.matchTextStyle` | `{url,box:{x,y,width,height},text?}`; integer crop16–1536wide,16–512high; optional supplied text | `status`, candidates with real image-editor `element`/`previewConfig`, `maskIoU`, `foregroundMae`, `quality`, previews/comparison and warnings. Up to160printable ASCII characters/four lines; supported fonts Arial/TikTok/Apple. Missing/unsupported styles may be unavailable or approximations. |
+| `get_media_analysis` / `media.getMediaAnalysis` | `{jobId}` | Current status/result in the current organization; use when automatic waiting returned pending/processing. |
+
+Boxes are half-open source-pixel rectangles. For masks used by colors/layout:
+`{width,height,counts}` uses row-major binary RLE, alternating background then
+foreground. Counts must sum to width×height. This is not COCO's column-major
+convention. Supply only masks you actually have; automatic segmentation is off.
+
+## Existing media library
+
+- `list_media({ids?,tag?})`, `list_social_audio({ids?,tag?})`.
+- `create_media_from_urls({urls,names?,tag?,sourceIds?,useName?})` registers URLs;
+  it does not turn an inaccessible local file into a public upload.
+- `import_text({texts:[{content,name?,tag?}]})`.
+- `create_social_audio({url,tag?})` imports social audio separately; do not use it
+  as proof of the exact soundtrack/mix/offset in a downloaded reference video.
+- `delete_media({ids})` removes media/storage; only use when deletion is requested.