@clipform/mcp-server 2.12.0 → 2.13.0

package/dist/{chunk-UVRL2EXF.js → chunk-66KZWBI7.js}

@@ -18535,6 +18535,7 @@ var MediaAssetItemSchema = external_exports.object({
       ).min(1).describe("Per-word timestamps within the segment. Required - copy the full array from clipform_generate_tts verbatim.")
     })
   ).optional().describe("Word-level captions from clipform_generate_tts. `words` is a required field on each caption (schema-enforced) - pass the full objects returned by clipform_generate_tts unmodified."),
+  caption_ref: external_exports.string().optional().describe("caption_ref from clipform_generate_tts - an opaque handle that attaches that TTS run's word-level captions to this asset, resolved server-side. Preferred over captions."),
   ai_generated: external_exports.boolean().optional().describe("Whether this media was AI-generated. Drives the viewer's disclosure chip - set true for AI-rendered/synthesized media.")
 });
 function registerUploadMediaAssetTool(server) {
@@ -18544,7 +18545,7 @@ function registerUploadMediaAssetTool(server) {
       title: "Upload Media Asset",
       description: `Put one or more media files into your workspace media library (max 10, uploaded sequentially). This is step one of attaching media to a node - follow up with clipform_attach_node_media to place the returned media_asset_id on a node.
 
-When a public URL is provided, the media is fetched and stored automatically. For video: ingested via Mux. For image: stored in Supabase. Captions from clipform_generate_tts enable per-word highlighting in the viewer once attached.`,
+When a public URL is provided, the media is fetched and stored automatically. For video: ingested via Mux. For image: stored in Supabase. Word-level captions from clipform_generate_tts enable per-word highlighting in the viewer once attached - pass the caption_ref it returned instead of hand-copying the captions array.`,
       inputSchema: {
         items: external_exports.array(MediaAssetItemSchema).min(1).max(10).describe("One or more media items to create as workspace library assets")
       },
@@ -18592,6 +18593,7 @@ When a public URL is provided, the media is fetched and stored automatically. Fo
         };
         if (item.url) createBody.url = item.url;
         if (item.captions) createBody.captions = item.captions;
+        if (item.caption_ref) createBody.caption_ref = item.caption_ref;
         if (item.ai_generated !== void 0) createBody.ai_generated = item.ai_generated;
         const created = await callApi(`/workspaces/${workspaceId}/media`, { method: "POST", body: createBody });
         if (!created.ok) {
@@ -18629,7 +18631,9 @@ When a public URL is provided, the media is fetched and stored automatically. Fo
         } else {
           resultLines.push(`Media stored in the workspace library.`);
         }
-        if (item.captions) {
+        if (item.caption_ref) {
+          resultLines.push(`Captions resolved from caption_ref.`);
+        } else if (item.captions) {
           resultLines.push(`Captions: ${item.captions.length} segments saved`);
         }
         lines.push(resultLines.join("\n"));
@@ -19082,7 +19086,7 @@ Available voices: ryan (British male, clear), sonia (British female, warm), andr
 
 Use the tone parameter to direct HOW the voice speaks. Always set a tone that matches the form's mood - e.g. quizzes: "Energetic and playful, like a quiz show host teasing the audience", surveys: "Professional but warm, encouraging honest answers", personality quizzes: "Curious and reflective". This dramatically improves the narration quality.
 
-Pass one item or many (max 10) - multiple items run in parallel. Returns audio URL and word-level captions per item.`,
+Pass one item or many (max 10) - multiple items run in parallel. Returns audio_url and caption_ref per item - pass caption_ref downstream to clipform_render_composition / clipform_render_video_template / clipform_upload_media_asset to attach this run's word-level captions instead of hand-copying the captions array.`,
       inputSchema: {
         items: external_exports.array(TtsItemSchema).min(1).max(10).describe("One or more TTS items to generate")
       },
@@ -19091,7 +19095,8 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
           external_exports.object({
             ok: external_exports.boolean(),
             audio_url: external_exports.string().optional(),
-            captions: external_exports.array(CaptionSchema2).optional().describe("Pass as the captions param to upload_media_asset"),
+            caption_ref: external_exports.string().optional().describe("Pass this as the caption_ref param on clipform_render_composition / clipform_render_video_template / clipform_upload_media_asset to attach this run's word-level captions - never hand-copy the captions array."),
+            captions: external_exports.array(CaptionSchema2).optional().describe("Word-level captions, for reference only - prefer passing caption_ref downstream instead of copying this array."),
             error: external_exports.string().optional()
           })
         ).describe("One result per item, in order")
@@ -19118,6 +19123,9 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
           successCount++;
           const data = r.value.data;
           lines.push(`Audio URL: ${data.audioUrl}`);
+          if (data.captionRef) {
+            lines.push(`Caption ref: ${data.captionRef} (pass as caption_ref to clipform_render_composition / clipform_render_video_template / clipform_upload_media_asset)`);
+          }
           const rawCaptions = Array.isArray(data.captions) ? data.captions : [];
           const captions = rawCaptions.map((c) => ({
             start: c.start,
@@ -19129,6 +19137,7 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
           structured.push({
             ok: true,
             ...data.audioUrl ? { audio_url: String(data.audioUrl) } : {},
+            ...data.captionRef ? { caption_ref: String(data.captionRef) } : {},
             captions
           });
         } else {
@@ -19144,7 +19153,7 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
         lines.unshift(`TTS: ${successCount}/${items.length} succeeded
 `);
       }
-      lines.push(`Pass the complete Captions JSON as the "captions" parameter when uploading.`);
+      lines.push(`Pass caption_ref downstream (to clipform_render_composition / clipform_render_video_template / clipform_upload_media_asset) instead of hand-copying the captions array.`);
       if (successCount === 0) return errorResult(lines.join("\n"));
       return structuredResult(lines.join("\n"), { results: structured });
     }
@@ -19401,6 +19410,7 @@ async function completeViaPlaceholder(placeholder, input) {
   try {
     const body = { url: input.publicUrl };
     if (input.captions?.length) body.captions = input.captions;
+    if (input.captionRef) body.caption_ref = input.captionRef;
     const completed = await callApi(`/workspaces/${placeholder.workspaceId}/media/${placeholder.assetId}/complete`, {
       method: "POST",
       body
@@ -19429,6 +19439,7 @@ async function legacyAutoAttach(input) {
       url: input.publicUrl
     };
     if (input.captions?.length) createBody.captions = input.captions;
+    if (input.captionRef) createBody.caption_ref = input.captionRef;
     const created = await callApi(`/workspaces/${workspaceId}/media`, { method: "POST", body: createBody });
     if (!created.ok) return { attached: false, error: `Failed to create media asset: ${created.error}` };
     const mediaAssetId = created.data?.media_asset_id;
@@ -19474,7 +19485,8 @@ var RenderItemSchema = external_exports.object({
   outputFormat: external_exports.enum(["mp4", "png"]).default("mp4").describe("Output format (default: mp4)"),
   inputProps: external_exports.record(external_exports.unknown()).optional().describe("Props matching the composition's schema - validated strictly"),
   node_id: external_exports.string().optional().describe("Form node to attach this item's render to automatically once it completes. Requires the batch's top-level form_id."),
-  captions: external_exports.array(CaptionSchema).optional().describe("Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set.")
+  captions: external_exports.array(CaptionSchema).optional().describe("Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set."),
+  caption_ref: external_exports.string().optional().describe("caption_ref from clipform_generate_tts - an opaque handle that attaches that TTS run's word-level captions to the media asset, resolved server-side. Preferred over captions. Only used when node_id is set.")
 });
 function fireRender(item, formId) {
   const job = createJob("clipform_render_composition");
@@ -19506,6 +19518,7 @@ function fireRender(item, formId) {
           publicUrl,
           mediaType,
           captions: item.captions,
+          captionRef: item.caption_ref,
           placeholder
         });
       } else {
@@ -19544,7 +19557,8 @@ ${RENDER_ATTACH_RULE} In batch mode, set node_id per item (see items) and form_i
         items: external_exports.array(RenderItemSchema).min(1).max(10).optional().describe("Batch mode: multiple renders in one call. All fire in parallel; returns one job ID per item - collect with clipform_check_render (job_ids). Use this whenever rendering more than one clip."),
         node_id: external_exports.string().optional().describe("Single render only: form node to attach this render to automatically once it completes. Requires form_id. For batch mode, set node_id per item instead."),
         form_id: external_exports.string().uuid().optional().describe("The form UUID - required when node_id is set (single render) or any item sets node_id (batch)."),
-        captions: external_exports.array(CaptionSchema).optional().describe("Single render only: word-level captions from clipform_generate_tts, carried onto the attached media asset. Only used when node_id is set. For batch mode, set captions per item instead.")
+        captions: external_exports.array(CaptionSchema).optional().describe("Single render only: word-level captions from clipform_generate_tts, carried onto the attached media asset. Only used when node_id is set. For batch mode, set captions per item instead."),
+        caption_ref: external_exports.string().optional().describe("Single render only: caption_ref from clipform_generate_tts - an opaque handle that attaches that TTS run's word-level captions to the media asset, resolved server-side. Preferred over captions. Only used when node_id is set. For batch mode, set caption_ref per item instead.")
       },
       outputSchema: {
         jobs: external_exports.array(
@@ -19567,7 +19581,7 @@ ${RENDER_ATTACH_RULE} In batch mode, set node_id per item (see items) and form_i
       // node_id too (destructive/openWorld apply "even in only select modes").
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
     },
-    async ({ compositionId, outputFormat, inputProps, wait, items, node_id, form_id, captions }) => {
+    async ({ compositionId, outputFormat, inputProps, wait, items, node_id, form_id, captions, caption_ref }) => {
       if (items?.length && compositionId) {
         return errorResult("Pass EITHER items (batch) OR compositionId (single render), not both.");
       }
@@ -19604,7 +19618,7 @@ ${RENDER_ATTACH_RULE} In batch mode, set node_id per item (see items) and form_i
         );
       }
       if (wait === false) {
-        const job = fireRender({ compositionId, outputFormat, inputProps, node_id, captions }, form_id);
+        const job = fireRender({ compositionId, outputFormat, inputProps, node_id, captions, caption_ref }, form_id);
         return structuredResult(
           [
             `Render started (${compositionId}).`,
@@ -19638,6 +19652,7 @@ ${RENDER_ATTACH_RULE} In batch mode, set node_id per item (see items) and form_i
             publicUrl: data.public_url,
             mediaType: mediaTypeSingle,
             captions,
+            captionRef: caption_ref,
             placeholder
           });
         } else if (placeholder) {
@@ -19893,7 +19908,8 @@ ${RENDER_ATTACH_RULE}`,
         wait: external_exports.boolean().optional().default(true).describe("true (default) blocks until the render is ready and returns its URL; false returns a job ID for clipform_check_render."),
         node_id: external_exports.string().optional().describe("Form node to attach this render to automatically once it completes - skips the manual clipform_upload_media_asset + clipform_attach_node_media steps and republishes the form if it's currently live. Requires form_id."),
         form_id: external_exports.string().uuid().optional().describe("The form UUID (required when node_id is set)."),
-        captions: external_exports.array(CaptionSchema).optional().describe("Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set.")
+        captions: external_exports.array(CaptionSchema).optional().describe("Word-level captions from clipform_generate_tts - carried onto the attached media asset. Only used when node_id is set."),
+        caption_ref: external_exports.string().optional().describe("caption_ref from clipform_generate_tts - an opaque handle that attaches that TTS run's word-level captions to the media asset, resolved server-side. Preferred over captions. Only used when node_id is set.")
       },
       outputSchema: {
         status: external_exports.enum(["rendering", "complete"]),
@@ -19912,7 +19928,7 @@ ${RENDER_ATTACH_RULE}`,
       // node_id too (destructive/openWorld apply "even in only select modes").
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
     },
-    async ({ template, controls, outputFormat, wait, node_id, form_id, captions }) => {
+    async ({ template, controls, outputFormat, wait, node_id, form_id, captions, caption_ref }) => {
       if (node_id && !form_id) {
         return errorResult("form_id is required when node_id is set.");
       }
@@ -19936,7 +19952,7 @@ ${RENDER_ATTACH_RULE}`,
             const publicUrl = r.data.public_url;
             const placeholder = await placeholderPromise2;
             if (publicUrl) {
-              attach2 = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl, mediaType, captions, placeholder });
+              attach2 = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl, mediaType, captions, captionRef: caption_ref, placeholder });
             } else {
               const message = "Render completed without a public_url; nothing to attach.";
               attach2 = { attached: false, error: message };
@@ -19974,7 +19990,7 @@ ${RENDER_ATTACH_RULE}`,
       if (node_id && form_id) {
         const placeholder = await placeholderPromise;
         if (data.public_url) {
-          attach = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl: data.public_url, mediaType, captions, placeholder });
+          attach = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl: data.public_url, mediaType, captions, captionRef: caption_ref, placeholder });
         } else if (placeholder) {
           await failPlaceholder(placeholder, "Render completed without a public_url; nothing to attach.");
         }
@@ -20165,7 +20181,7 @@ ${RENDER_ATTACH_RULE}`,
             const publicUrl = r.data.public_url;
             const placeholder = await placeholderPromise2;
             if (publicUrl) {
-              attach2 = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl, mediaType: "video", captions, placeholder });
+              attach2 = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl, mediaType: "video", captions, captionRef: audio_url, placeholder });
             } else {
               const message = "Render completed without a public_url; nothing to attach.";
               attach2 = { attached: false, error: message };
@@ -20200,7 +20216,7 @@ ${RENDER_ATTACH_RULE}`,
       if (node_id && form_id) {
         const placeholder = await placeholderPromise;
         if (data.public_url) {
-          attach = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl: data.public_url, mediaType: "video", captions, placeholder });
+          attach = await autoAttachRender({ formId: form_id, nodeId: node_id, publicUrl: data.public_url, mediaType: "video", captions, captionRef: audio_url, placeholder });
         } else if (placeholder) {
           await failPlaceholder(placeholder, "Render completed without a public_url; nothing to attach.");
         }
@@ -20704,4 +20720,4 @@ export {
   buildInstructions,
   createServer
 };
-//# sourceMappingURL=chunk-UVRL2EXF.js.map
+//# sourceMappingURL=chunk-66KZWBI7.js.map