@sync.so/mcp-server 0.1.4 → 0.2.0

package/dist/tools/timeline-lipsync.d.ts

@@ -0,0 +1,316 @@
+import { z } from 'zod';
+import { type ClientProfile } from '../client-profile.js';
+import type { HttpClient } from '../http-client.js';
+import type { ParsedOperation } from '../openapi/types.js';
+import type { McpToolDefinition } from './generator.js';
+declare const keptInput: z.ZodObject<{
+    projectCreationKey: z.ZodOptional<z.ZodUUID>;
+    videoAssetId: z.ZodUUID;
+    model: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodObject<{
+        sync_mode: z.ZodOptional<z.ZodEnum<{
+            bounce: "bounce";
+            cut_off: "cut_off";
+            loop: "loop";
+            remap: "remap";
+            silence: "silence";
+        }>>;
+        temperature: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        active_speaker_detection: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            auto_detect: z.ZodOptional<z.ZodBoolean>;
+            use_v2: z.ZodOptional<z.ZodBoolean>;
+            v3: z.ZodOptional<z.ZodBoolean>;
+            face_image: z.ZodOptional<z.ZodString>;
+            frame_number: z.ZodOptional<z.ZodNumber>;
+            coordinates: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, z.core.$strict>]>>;
+        occlusion_detection_enabled: z.ZodOptional<z.ZodBoolean>;
+        reasoning_enabled: z.ZodOptional<z.ZodBoolean>;
+        model_mode: z.ZodOptional<z.ZodEnum<{
+            face: "face";
+            head: "head";
+            lips: "lips";
+        }>>;
+    }, z.core.$strict>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+    projectName: z.ZodOptional<z.ZodString>;
+    clips: z.ZodArray<z.ZodObject<{
+        audioAssetId: z.ZodOptional<z.ZodUUID>;
+        audioUrl: z.ZodOptional<z.ZodURL>;
+        startTime: z.ZodOptional<z.ZodNumber>;
+        endTime: z.ZodOptional<z.ZodNumber>;
+        startFrame: z.ZodOptional<z.ZodNumber>;
+        endFrame: z.ZodOptional<z.ZodNumber>;
+        audioStartTime: z.ZodOptional<z.ZodNumber>;
+        audioEndTime: z.ZodOptional<z.ZodNumber>;
+        syncMode: z.ZodOptional<z.ZodEnum<{
+            bounce: "bounce";
+            cut_off: "cut_off";
+            loop: "loop";
+            remap: "remap";
+            silence: "silence";
+        }>>;
+        speaker: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            frameNumber: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            faceTrackUrl: z.ZodURL;
+        }, z.core.$strict>, z.ZodObject<{
+            detect: z.ZodLiteral<true>;
+        }, z.core.$strict>]>>;
+        lipsync: z.ZodOptional<z.ZodLiteral<false>>;
+    }, z.core.$strict>>;
+    outputAudio: z.ZodOptional<z.ZodObject<{
+        audioAssetId: z.ZodOptional<z.ZodUUID>;
+        audioUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type TimelineInput = z.infer<typeof keptInput>;
+/**
+ * Lipsyncs one video with several audio clips placed at given times, the shape
+ * of a Studio timeline. Each distinct audio asset becomes one input, and each
+ * clip a segment that reads its part of that audio.
+ */
+export declare function generationBody(args: TimelineInput, projectId: string): {
+    model: string;
+    options?: {
+        sync_mode?: "bounce" | "cut_off" | "loop" | "remap" | "silence" | undefined;
+        temperature?: number | null | undefined;
+        active_speaker_detection?: boolean | {
+            auto_detect?: boolean | undefined;
+            use_v2?: boolean | undefined;
+            v3?: boolean | undefined;
+            face_image?: string | undefined;
+            frame_number?: number | undefined;
+            coordinates?: [number, number] | undefined;
+        } | undefined;
+        occlusion_detection_enabled?: boolean | undefined;
+        reasoning_enabled?: boolean | undefined;
+        model_mode?: "face" | "head" | "lips" | undefined;
+    } | undefined;
+    input: ({
+        type: string;
+        assetId: string;
+    } | {
+        type: string;
+        assetId: string;
+        refId: string;
+        url?: undefined;
+    } | {
+        assetId?: undefined;
+        type: string;
+        url: string;
+        refId: string;
+    })[];
+    segments: ({
+        startTime: number | undefined;
+        endTime: number | undefined;
+        lipsync: boolean;
+    } | {
+        optionsOverride?: undefined;
+        startTime: number | undefined;
+        endTime: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    } | {
+        optionsOverride: {
+            sync_mode?: "bounce" | "cut_off" | "loop" | "remap" | "silence" | undefined;
+            active_speaker_detection?: {
+                auto_detect: boolean;
+                bounding_boxes_url?: undefined;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                auto_detect: boolean;
+                bounding_boxes_url: string;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                bounding_boxes_url?: undefined;
+                auto_detect: boolean;
+                frame_number: number;
+                coordinates: number[];
+            } | undefined;
+        };
+        startTime: number | undefined;
+        endTime: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    } | {
+        startFrame: number;
+        endFrame: number | undefined;
+        lipsync: boolean;
+    } | {
+        optionsOverride?: undefined;
+        startFrame: number;
+        endFrame: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    } | {
+        optionsOverride: {
+            sync_mode?: "bounce" | "cut_off" | "loop" | "remap" | "silence" | undefined;
+            active_speaker_detection?: {
+                auto_detect: boolean;
+                bounding_boxes_url?: undefined;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                auto_detect: boolean;
+                bounding_boxes_url: string;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                bounding_boxes_url?: undefined;
+                auto_detect: boolean;
+                frame_number: number;
+                coordinates: number[];
+            } | undefined;
+        };
+        startFrame: number;
+        endFrame: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    })[];
+    projectId: string;
+    outputAudio: {
+        refId: string;
+    };
+} | {
+    model: string;
+    options?: {
+        sync_mode?: "bounce" | "cut_off" | "loop" | "remap" | "silence" | undefined;
+        temperature?: number | null | undefined;
+        active_speaker_detection?: boolean | {
+            auto_detect?: boolean | undefined;
+            use_v2?: boolean | undefined;
+            v3?: boolean | undefined;
+            face_image?: string | undefined;
+            frame_number?: number | undefined;
+            coordinates?: [number, number] | undefined;
+        } | undefined;
+        occlusion_detection_enabled?: boolean | undefined;
+        reasoning_enabled?: boolean | undefined;
+        model_mode?: "face" | "head" | "lips" | undefined;
+    } | undefined;
+    input: ({
+        type: string;
+        assetId: string;
+    } | {
+        type: string;
+        assetId: string;
+        refId: string;
+        url?: undefined;
+    } | {
+        assetId?: undefined;
+        type: string;
+        url: string;
+        refId: string;
+    })[];
+    segments: ({
+        startTime: number | undefined;
+        endTime: number | undefined;
+        lipsync: boolean;
+    } | {
+        optionsOverride?: undefined;
+        startTime: number | undefined;
+        endTime: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    } | {
+        optionsOverride: {
+            sync_mode?: "bounce" | "cut_off" | "loop" | "remap" | "silence" | undefined;
+            active_speaker_detection?: {
+                auto_detect: boolean;
+                bounding_boxes_url?: undefined;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                auto_detect: boolean;
+                bounding_boxes_url: string;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                bounding_boxes_url?: undefined;
+                auto_detect: boolean;
+                frame_number: number;
+                coordinates: number[];
+            } | undefined;
+        };
+        startTime: number | undefined;
+        endTime: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    } | {
+        startFrame: number;
+        endFrame: number | undefined;
+        lipsync: boolean;
+    } | {
+        optionsOverride?: undefined;
+        startFrame: number;
+        endFrame: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    } | {
+        optionsOverride: {
+            sync_mode?: "bounce" | "cut_off" | "loop" | "remap" | "silence" | undefined;
+            active_speaker_detection?: {
+                auto_detect: boolean;
+                bounding_boxes_url?: undefined;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                auto_detect: boolean;
+                bounding_boxes_url: string;
+                frame_number?: undefined;
+                coordinates?: undefined;
+            } | {
+                bounding_boxes_url?: undefined;
+                auto_detect: boolean;
+                frame_number: number;
+                coordinates: number[];
+            } | undefined;
+        };
+        startFrame: number;
+        endFrame: number | undefined;
+        audioInput: {
+            refId: string;
+            startTime?: number | undefined;
+            endTime?: number | undefined;
+        };
+    })[];
+    projectId: string;
+    outputAudio?: undefined;
+};
+/** segments.maxItems on POST /v2/generate, when the API's spec publishes it. */
+export declare function timelineClipLimit(operations: ParsedOperation[]): number | undefined;
+/** Whether the API takes segments[].lipsync: false and a top-level outputAudio. */
+export declare function timelineKeepsClips(operations: ParsedOperation[]): boolean;
+export declare function createTimelineLipsyncTool(httpClient: HttpClient, getProfile?: () => ClientProfile, features?: {
+    maxClips?: number;
+    keptClips?: boolean;
+}): McpToolDefinition;
+export {};
+//# sourceMappingURL=timeline-lipsync.d.ts.map

package/dist/tools/timeline-lipsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-lipsync.d.ts","sourceRoot":"","sources":["../../src/tools/timeline-lipsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,sBAAsB,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AA2IxD,QAAA,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBASb,CAAC;AAGH,KAAK,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AA6F/C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAqCnB,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBtD;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,MAAM,GAAG,SAAS,CAOnF;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,OAAO,CAOzE;AAED,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,UAAU,GAAE,MAAM,aAA4C,EAE9D,QAAQ,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACxD,iBAAiB,CAsDnB"}

package/dist/tools/timeline-lipsync.js

@@ -0,0 +1,304 @@
+import { z } from 'zod';
+import { resolveClientProfile } from '../client-profile.js';
+import { schemaProperty } from '../openapi/parser.js';
+import { modelOptionsSchema, parseModelOptions } from './model-options.js';
+import { generationOutputSchema } from './output-schemas.js';
+import { assertProjectDestination, createProjectId, newProjectFields, } from './project-destination.js';
+const seconds = z.number().finite().nonnegative();
+const frame = z.number().int().nonnegative();
+// How Studio sets the face a clip lipsyncs: a point on it or a face track,
+// both counted from the clip's own first frame, or automatic detection.
+const speaker = z.union([
+    z
+        .object({
+        frameNumber: frame.describe('Frame of this clip, counted from its first frame, showing the face.'),
+        x: z
+            .number()
+            .finite()
+            .describe('Pixel x on the face in that frame of the video. A point off the face (even on the hair) rejects the whole generation, so aim at the face centre.'),
+        y: z.number().finite().describe('Pixel y on the face in that frame of the video.'),
+    })
+        .strict(),
+    z
+        .object({
+        faceTrackUrl: z
+            .url({ protocol: /^https$/ })
+            .describe('HTTPS URL of a JSON face track: one bounding box per frame of this clip.'),
+    })
+        .strict(),
+    z
+        .object({
+        detect: z.literal(true).describe('Detect the speaking face in this clip automatically.'),
+    })
+        .strict(),
+]);
+const clip = z
+    .object({
+    audioAssetId: z
+        .uuid()
+        .optional()
+        .describe('Sync asset id of the audio clip. Give audioAssetId or audioUrl.'),
+    audioUrl: z
+        .url({ protocol: /^https$/ })
+        .optional()
+        .describe('HTTPS URL of the audio instead of an asset, such as a completed translation preview’s outputMediaUrl.'),
+    startTime: seconds
+        .optional()
+        .describe('Second on the video where this clip starts. Give startTime and endTime, or startFrame and endFrame.'),
+    endTime: seconds.optional().describe('Second on the video where this clip ends.'),
+    startFrame: frame
+        .optional()
+        .describe('First frame of the video this clip covers, used when its speaker is picked.'),
+    endFrame: frame.optional().describe('Last frame of the video this clip covers, inclusive.'),
+    audioStartTime: seconds
+        .optional()
+        .describe('Second into the audio file this clip plays from. Omit to start at 0.'),
+    audioEndTime: seconds
+        .optional()
+        .describe('Second into the audio file this clip plays to. Omit to play on from the start.'),
+    syncMode: modelOptionsSchema.shape.sync_mode.describe('How this clip fits when its audio and video lengths differ. Omit to use options.sync_mode.'),
+    speaker: speaker
+        .optional()
+        .describe('The face this clip lipsyncs: a point on it in one of the clip’s frames, a face track, or automatic detection. Omit to use options.active_speaker_detection.'),
+})
+    .strict();
+const input = z
+    .object({
+    videoAssetId: z.uuid().describe('Sync asset id of the video.'),
+    clips: z
+        .array(clip)
+        .min(1)
+        .max(200)
+        .describe('Audio clips placed on the video, in any order, without overlapping. Parts of the video no clip covers keep their original picture and sound.'),
+    model: z.string().trim().min(1).optional().describe('Model to use. Defaults to sync-3.'),
+    options: modelOptionsSchema.optional(),
+    idempotencyKey: z
+        .string()
+        .regex(/^[A-Za-z0-9._~-]{1,128}$/)
+        .optional()
+        .describe('Unique key for this generation. Reuse it with identical arguments when retrying after a lost response. Passed as the Idempotency-Key header.'),
+    ...newProjectFields,
+    projectId: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe('Existing Sync project id, only for a project the user explicitly selected or one just created for this request.'),
+    projectName: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe('Name for a NEW project only. Never search or reuse a matching name. Cannot be combined with projectId.'),
+})
+    .strict();
+// Offered only when the API publishes segments[].lipsync and outputAudio.
+const keptClip = clip.extend({
+    lipsync: z
+        .literal(false)
+        .optional()
+        .describe('false keeps this part of the video exactly as it is: not lipsynced and not billed, while outputAudio still plays over it. Give no audio, syncMode or speaker. Use it for shots that should hear the dub without moving lips (listeners, people off camera or facing away).'),
+});
+const outputAudio = z
+    .object({
+    audioAssetId: z.uuid().optional().describe('Sync asset id of the audio.'),
+    audioUrl: z
+        .url({ protocol: /^https$/ })
+        .optional()
+        .describe('HTTPS URL of the audio.'),
+})
+    .strict()
+    .describe('One audio that plays over the whole finished output from its first second, replacing the sound of every part, such as the full dubbed track. Defaults, when a clip sets lipsync: false, to the only audio the clips use.');
+const keptInput = input.extend({
+    clips: z
+        .array(keptClip)
+        .min(1)
+        .max(200)
+        .describe('Clips placed on the video, in any order, without overlapping. Parts no clip covers keep their original picture and sound; clips with lipsync: false keep their picture but play outputAudio.'),
+    outputAudio: outputAudio.optional(),
+});
+/** A clip's stretch of the video, in seconds or in frames (end inclusive). */
+function spanOf({ startTime, endTime, startFrame, endFrame }, index) {
+    const given = [startTime, endTime, startFrame, endFrame].filter((v) => v !== undefined).length;
+    if (given === 2 && startTime !== undefined && endTime !== undefined)
+        return { unit: 'seconds', start: startTime, end: endTime, index };
+    if (given === 2 && startFrame !== undefined && endFrame !== undefined)
+        return { unit: 'frames', start: startFrame, end: endFrame + 1, index };
+    throw new Error(`clips[${index}]: give startTime and endTime, or startFrame and endFrame, not a mix.`);
+}
+function describeSpan(span) {
+    return span.unit === 'frames'
+        ? `frames ${span.start}-${span.end - 1}`
+        : `seconds ${span.start}-${span.end}`;
+}
+/** Clips must have a positive span and may not share any part of the video. */
+function assertPlaceable(clips, maxClips) {
+    if (maxClips !== undefined && clips.length > maxClips)
+        throw new Error(`A generation takes at most ${maxClips} clips; this request has ${clips.length}. Merge neighbouring clips of the same face, or split the video into parts.`);
+    const byUnit = { seconds: [], frames: [] };
+    if (clips.every((c) => c.lipsync === false))
+        throw new Error('Every clip sets lipsync: false, so there is nothing to lipsync.');
+    clips.forEach((c, index) => {
+        const kept = c.lipsync === false;
+        if (kept &&
+            [c.audioAssetId, c.audioUrl, c.audioStartTime, c.audioEndTime, c.syncMode, c.speaker].some((value) => value !== undefined))
+            throw new Error(`clips[${index}] sets lipsync: false, so it takes no audio, syncMode or speaker; outputAudio plays there.`);
+        if (!kept && (c.audioAssetId === undefined) === (c.audioUrl === undefined))
+            throw new Error(`clips[${index}]: give audioAssetId or audioUrl, exactly one.`);
+        const span = spanOf(c, index);
+        if (span.end <= span.start + (span.unit === 'frames' ? 1 : 0))
+            throw new Error(`clips[${index}] (${describeSpan(span)}) must end after it starts.`);
+        if (c.audioEndTime !== undefined && c.audioEndTime <= (c.audioStartTime ?? 0))
+            throw new Error(`clips[${index}]: audioEndTime must be after audioStartTime, which defaults to 0.`);
+        if (span.unit === 'frames' &&
+            c.speaker &&
+            'frameNumber' in c.speaker &&
+            c.speaker.frameNumber >= span.end - span.start)
+            throw new Error(`clips[${index}]: speaker.frameNumber ${c.speaker.frameNumber} is not one of its ${span.end - span.start} frames; it counts from the clip’s first frame (0), not the video’s.`);
+        byUnit[span.unit].push(span);
+    });
+    for (const spans of Object.values(byUnit)) {
+        const sorted = spans.sort((a, b) => a.start - b.start);
+        for (let i = 1; i < sorted.length; i++) {
+            const [previous, current] = [sorted[i - 1], sorted[i]];
+            if (current.start < previous.end)
+                throw new Error(`clips[${previous.index}] (${describeSpan(previous)}) and clips[${current.index}] (${describeSpan(current)}) overlap; each part of the video takes one clip, so end one before the other starts.`);
+        }
+    }
+}
+/** Per-clip settings, in the shape the API's segment override takes. */
+function clipOverride({ syncMode, speaker: face }) {
+    const detection = face === undefined
+        ? undefined
+        : 'detect' in face
+            ? { auto_detect: true }
+            : 'faceTrackUrl' in face
+                ? { auto_detect: false, bounding_boxes_url: face.faceTrackUrl }
+                : { auto_detect: false, frame_number: face.frameNumber, coordinates: [face.x, face.y] };
+    if (syncMode === undefined && detection === undefined)
+        return {};
+    return {
+        optionsOverride: {
+            ...(syncMode === undefined ? {} : { sync_mode: syncMode }),
+            ...(detection === undefined ? {} : { active_speaker_detection: detection }),
+        },
+    };
+}
+/**
+ * Lipsyncs one video with several audio clips placed at given times, the shape
+ * of a Studio timeline. Each distinct audio asset becomes one input, and each
+ * clip a segment that reads its part of that audio.
+ */
+export function generationBody(args, projectId) {
+    // One input per distinct audio, keyed by asset id or URL.
+    const audioKey = (c) => c.audioAssetId ? `asset:${c.audioAssetId}` : `url:${c.audioUrl}`;
+    const refs = new Map();
+    const audios = [
+        ...args.clips.filter((placed) => placed.lipsync !== false),
+        ...(args.outputAudio ? [args.outputAudio] : []),
+    ];
+    for (const audio of audios)
+        if (!refs.has(audioKey(audio)))
+            refs.set(audioKey(audio), `audio-${refs.size + 1}`);
+    const model = args.model ?? 'sync-3';
+    const options = parseModelOptions(args.options, { model });
+    return {
+        model,
+        ...(options === undefined ? {} : { options }),
+        input: [
+            { type: 'video', assetId: args.videoAssetId },
+            ...[...refs].map(([key, refId]) => key.startsWith('asset:')
+                ? { type: 'audio', assetId: key.slice('asset:'.length), refId }
+                : { type: 'audio', url: key.slice('url:'.length), refId }),
+        ],
+        segments: args.clips.map((c) => ({
+            ...(c.startFrame === undefined
+                ? { startTime: c.startTime, endTime: c.endTime }
+                : { startFrame: c.startFrame, endFrame: c.endFrame }),
+            ...(c.lipsync === false ? { lipsync: false } : audioPart(c)),
+        })),
+        ...outputAudioPart(),
+        projectId,
+    };
+    // Kept clips need one track over the whole output: outputAudio, or the only audio the clips
+    // use. Sent explicitly so the request says which track plays, not the API's default.
+    function outputAudioPart() {
+        if (args.outputAudio)
+            return { outputAudio: { refId: refs.get(audioKey(args.outputAudio)) } };
+        if (args.clips.some((placed) => placed.lipsync === false) && refs.size === 1)
+            return { outputAudio: { refId: [...refs.values()][0] } };
+        return {};
+    }
+    function audioPart(c) {
+        return {
+            audioInput: {
+                refId: refs.get(audioKey(c)),
+                ...(c.audioStartTime === undefined ? {} : { startTime: c.audioStartTime }),
+                ...(c.audioEndTime === undefined ? {} : { endTime: c.audioEndTime }),
+            },
+            ...clipOverride(c),
+        };
+    }
+}
+/** segments.maxItems on POST /v2/generate, when the API's spec publishes it. */
+export function timelineClipLimit(operations) {
+    const generate = operations.find((operation) => operation.method === 'post' && operation.path === '/v2/generate');
+    const segments = generate?.requestBody && schemaProperty(generate.requestBody.schema, 'segments');
+    const limit = segments?.maxItems;
+    return typeof limit === 'number' && Number.isInteger(limit) && limit > 0 ? limit : undefined;
+}
+/** Whether the API takes segments[].lipsync: false and a top-level outputAudio. */
+export function timelineKeepsClips(operations) {
+    const generate = operations.find((operation) => operation.method === 'post' && operation.path === '/v2/generate');
+    const body = generate?.requestBody?.schema;
+    const segment = schemaProperty(body, 'segments')?.items;
+    return !!schemaProperty(segment, 'lipsync') && !!schemaProperty(body, 'outputAudio');
+}
+export function createTimelineLipsyncTool(httpClient, getProfile = () => resolveClientProfile(), 
+// Read from the API's spec: its segment limit, and whether clips can be kept.
+features = {}) {
+    const schema = features.keptClips ? keptInput : input;
+    return {
+        name: 'lipsync_create-timeline',
+        title: 'Create timeline lipsync',
+        description: 'Lipsync one video with several audio clips placed at given times, like a Studio timeline. Each clip names a Sync audio asset or audio URL, the seconds (or frames) of the video it covers, and optionally the part of the audio file it plays, its sync mode and the face it lipsyncs. Parts of the video no clip covers keep their original picture and sound, so leave a gap wherever the user wants no lipsync. For one audio across the whole video, use lipsync_create. Defaults to sync-3 and, unless projectId names a project the user picked, a new project; a keyed request without projectId needs a fresh projectCreationKey. Estimate and confirm before creating; this starts an asynchronous generation and returns its id. Poll it with generations_get and wait: true. Clips are checked before anything is created, and errors name the clip index.' +
+            (features.keptClips
+                ? ' To dub a whole video while lipsyncing only some shots, pass the full dubbed track as outputAudio, lipsync the speaking shots with clips that play their part of it, and add clips with lipsync: false for the rest; the result plays the dub continuously with no cuts.'
+                : ''),
+        inputSchema: schema.shape,
+        outputSchema: generationOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        meta: {
+            'openai/toolInvocation/invoking': 'Creating your timeline lipsync…',
+            'openai/toolInvocation/invoked': 'Timeline lipsync started.',
+        },
+        handler: async (rawArgs, context) => {
+            const signal = context?.signal;
+            const args = schema.parse(rawArgs);
+            assertProjectDestination(args.projectId, args.projectName, args.projectCreationKey);
+            assertPlaceable(args.clips, features.maxClips);
+            if (args.outputAudio &&
+                (args.outputAudio.audioAssetId === undefined) === (args.outputAudio.audioUrl === undefined))
+                throw new Error('outputAudio: give audioAssetId or audioUrl, exactly one.');
+            // Like lipsync_create: a new project unless the user picked one.
+            const projectId = args.projectId ??
+                (await createProjectId(httpClient, {
+                    name: args.projectName ?? (context?.clientProfile ?? getProfile()).defaultProjectName,
+                    projectCreationKey: args.projectCreationKey,
+                    idempotencyKey: args.idempotencyKey,
+                    defaultWorkflow: 'lipsync',
+                }, signal));
+            signal?.throwIfAborted();
+            return httpClient.request('post', '/v2/generate', {
+                signal,
+                ...(args.idempotencyKey ? { headers: { 'Idempotency-Key': args.idempotencyKey } } : {}),
+                body: generationBody(args, projectId),
+            });
+        },
+    };
+}

package/dist/tools/translation-preview.d.ts

@@ -0,0 +1,8 @@
+import type { HttpClient } from '../http-client.js';
+import type { ParsedOperation } from '../openapi/types.js';
+import type { McpToolDefinition } from './generator.js';
+export declare function translationPreviewOperations(operations: ParsedOperation[]): ParsedOperation[];
+export declare function translationPreviewAvailable(operations: ParsedOperation[]): boolean;
+/** The existing translation API must advertise saved-source authorization and keyed recovery. */
+export declare function createTranslationPreviewTools(operations: ParsedOperation[], http: HttpClient): McpToolDefinition[];
+//# sourceMappingURL=translation-preview.d.ts.map

package/dist/tools/translation-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-preview.d.ts","sourceRoot":"","sources":["../../src/tools/translation-preview.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAUxD,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAM7F;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,OAAO,CAkClF;AA+BD,iGAAiG;AACjG,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,eAAe,EAAE,EAC7B,IAAI,EAAE,UAAU,GACf,iBAAiB,EAAE,CAwFrB"}