transloadit 6.0.2 → 6.0.3

package/src/alphalib/types/robots/_ocr-output.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+
+/** An OCR polygon vertex in pixel coordinates. Provider omissions belong at the property site. */
+export const ocrBoundingVertexSchema = z.object({ x: z.number(), y: z.number() })
+
+/** Complete OCR text and pixel coordinates shared by image/document result projections. */
+export const ocrTextWithPolygonSchema = z.object({
+  text: z.string(),
+  boundingPolygon: z.array(ocrBoundingVertexSchema),
+})
+
+/** Full-granularity OCR JSON projection requiring complete polygons. */
+export const ocrFullOutputSchema = z.array(ocrTextWithPolygonSchema)
+
+/** The list-granularity OCR result used by both AWS and GCP. */
+export const ocrTextListSchema = z.array(z.string())
+
+/** A list-granularity metadata projection with recognized text required. */
+export const ocrTextListMetaSchema = z.object({ recognized_text: ocrTextListSchema })

package/src/alphalib/types/robots/audio-encode.ts

@@ -45,7 +45,14 @@ export const robotAudioEncodeInstructionsSchema = robotBase
       .boolean()
       .optional()
       .describe('Whether the results of this Step should be present in the Assembly Status JSON'),
-    robot: z.literal('/audio/encode'),
+    // The page renders the purpose sentence separately; add only the spatial-audio section here.
+    robot: z.literal('/audio/encode').describe(`
+## iPhone spatial audio
+
+Videos recorded with iPhone spatial audio can contain a stereo AAC track alongside an Apple Positional Audio Codec (APAC) track. When unsupported audio is present, this <dfn>Robot</dfn> keeps one supported audio track by default. Spatial audio is not preserved or converted.
+
+Files containing only unsupported audio still fail. Individual audio track selections and stream-copy requests keep the tracks you select; the output format must support copied tracks.
+`),
     bitrate: bitrateSchema.optional().describe(robotParameterDocs.audio_bitrate.description),
     sample_rate: sampleRateSchema
       .optional()

package/src/alphalib/types/robots/audio-split.ts

@@ -65,6 +65,8 @@ export const robotAudioSplitInstructionsSchema = robotBase
       .describe('Whether the results of this Step should be present in the Assembly Status JSON'),
     robot: z.literal('/audio/split').describe(`
 Splits an audio file into multiple segments based on an array of from/to durations. Each segment produces a separate output file. This is useful for cutting an audio file into parts, for example to insert ads later via [🤖/audio/concat](/docs/robots/audio-concat/).
+
+For iPhone videos with spatial audio, see [iPhone spatial audio in 🤖/audio/encode](/docs/robots/audio-encode/#iphone-spatial-audio).
 `),
     segments: z
       .array(segmentSchema)

package/src/alphalib/types/robots/digitalocean-store.ts

@@ -42,7 +42,7 @@ export const robotDigitaloceanStoreInstructionsSchema = robotBase
       .describe(`
 The URL prefix used for the returned URL, such as \`"https://my.cdn.com/some/path"\`.
 `),
-    acl: storageAcl,
+    acl: storageAcl.default('private'),
     headers: z
       .record(z.string())
       .default({ 'Content-Type': '${file.mime}' })

package/src/alphalib/types/robots/document-convert.ts

@@ -6,6 +6,7 @@ import type {
 
 import { z } from 'zod'
 
+import { zodCaseInsensitiveEnum } from '../../lib/zodInputSemantics.ts'
 import {
   createProcessingExample,
   defineRobot,
@@ -14,6 +15,11 @@ import {
   robotUse,
 } from './_instructions-primitives.ts'
 
+/** Accepts Playwright's paper-format case variants while publishing canonical spellings. */
+export const documentConvertPdfFormatSchema = zodCaseInsensitiveEnum(
+  z.enum(['A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'Ledger', 'Legal', 'Letter', 'Tabloid']),
+)
+
 export const meta: RobotMetaInput = {
   ...robotDocumentProcessingMeta,
   example_code: createProcessingExample('converted', '/document/convert', {
@@ -209,11 +215,8 @@ Print PDF background graphics.
 
 Currently this parameter is only supported when converting from \`html\`.
 `),
-    pdf_format: z
-      .enum(['A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'Ledger', 'Legal', 'Letter', 'Tabloid'])
-      .default('Letter')
-      .describe(`
-PDF paper format.
+    pdf_format: documentConvertPdfFormatSchema.default('Letter').describe(`
+PDF paper format. Values are case-insensitive.
 
 Currently this parameter is only supported when converting from \`html\`.
 `),

package/src/alphalib/types/robots/google-store.ts

@@ -1,5 +1,5 @@
 import type {
-  RobotDefinition,
+  RobotDefinitionWithHiddenFields,
   RobotMetaInput,
   RobotSchemaVariantTypes,
 } from './_instructions-primitives.ts'
@@ -8,7 +8,7 @@ import { z } from 'zod'
 
 import {
   createStorageStoreExample,
-  defineRobot,
+  defineRobotWithHiddenFields,
   getGoogleCredentialsDescription,
   googleBase,
   robotBase,
@@ -87,8 +87,19 @@ The SSL URL of the file in the result JSON. The following [Assembly variables](/
   })
   .strict()
 
-export const robotDefinition: RobotDefinition<typeof robotGoogleStoreInstructionsSchema.shape> =
-  defineRobot(meta, robotGoogleStoreInstructionsSchema)
+// Credential alternatives stay optional while Templates and Assembly overrides are merged.
+// GoogleStoreRobot validates the resolved values after credential injection.
+const hiddenFields = {
+  bucket: z.string().optional(),
+  credentials: robotGoogleStoreInstructionsSchema.shape.credentials.optional(),
+  key_file_contents: z.string().optional(),
+  project_id: z.string().optional(),
+}
+
+export const robotDefinition: RobotDefinitionWithHiddenFields<
+  typeof robotGoogleStoreInstructionsSchema.shape,
+  typeof hiddenFields
+> = defineRobotWithHiddenFields(meta, robotGoogleStoreInstructionsSchema, hiddenFields)
 
 export const {
   withHiddenFields: robotGoogleStoreInstructionsWithHiddenFieldsSchema,

package/src/alphalib/types/robots/image-describe.ts

@@ -17,6 +17,13 @@ import {
   robotUse,
 } from './_instructions-primitives.ts'
 
+export {
+  imageDescribeFullMetaSchema,
+  imageDescribeFullOutputSchema,
+  imageDescribeLabelSchema,
+  imageDescribeListMetaSchema,
+} from './_image-describe-output.ts'
+
 export const meta: RobotMetaInput = {
   ...robotArtificialIntelligenceMeta,
   example_code: createProcessingExample('described', '/image/describe', {
@@ -50,7 +57,7 @@ You can use the labels that we return in your application to automatically class
 Whether to return a full response (\`"full"\`) including confidence percentages for each found label, or just a flat list of labels (\`"list"\`).
 `),
     format: z
-      .enum(['json', 'meta', 'text'])
+      .enum(['json', 'meta'])
       .default('json')
       .describe(`
 In what format to return the descriptions.

package/src/alphalib/types/robots/image-facedetect.ts

@@ -25,19 +25,10 @@ export const imageFacedetectFaceSelectionModes = [
 
 export const imageFacedetectFaceSelectionModeSchema = z.enum(imageFacedetectFaceSelectionModes)
 
-export const imageFacedetectFaceCoordinatesSchema = z
-  .object({
-    confidence: z.number().optional(),
-    height: z.number(),
-    width: z.number(),
-    x1: z.number(),
-    x2: z.number().optional(),
-    y1: z.number(),
-    y2: z.number().optional(),
-  })
-  .passthrough()
-
-export type ImageFacedetectFaceCoordinates = z.infer<typeof imageFacedetectFaceCoordinatesSchema>
+export {
+  type ImageFacedetectFaceCoordinates,
+  imageFacedetectFaceCoordinatesSchema,
+} from './_image-facedetect-output.ts'
 
 export const meta: RobotMetaInput = {
   ...robotArtificialIntelligenceMeta,

package/src/alphalib/types/robots/image-generate.ts

@@ -97,7 +97,7 @@ Best practice:
         'Prompt describing the desired image. For inpainting, describe what should appear in the masked/transparent region and that the rest should stay unchanged.',
       ),
     format: z
-      .enum(['jpeg', 'jpg', 'png', 'gif', 'webp', 'svg'])
+      .enum(['jpeg', 'jpg', 'png', 'webp', 'svg'])
       .optional()
       .describe(
         'Output format. Defaults depend on model: png for Google and OpenAI models, svg for recraft-v3, jpeg for others. Google models currently return PNG only.',

package/src/alphalib/types/robots/image-upscale.ts

@@ -6,6 +6,7 @@ import type {
 
 import { z } from 'zod'
 
+import { formatEnglishInteger } from '../../englishInteger.ts'
 import { imageUpscaleDefaultModelIdentifier, imageUpscaleModelIdentifiers } from './_ai-models.ts'
 import {
   autoProviderDescription,
@@ -29,7 +30,13 @@ export const meta: RobotMetaInput = {
   purpose_words: 'Upscale images',
   title: 'Upscale images',
   name: 'ImageUpscaleRobot',
+  // Preserve the runtime fallback; positive provider costs replace it during usage accounting.
   minimumChargeUsd: 0.06,
+  providerCostPricing: {
+    provider: 'replicate',
+    model: imageUpscaleDefaultModelIdentifier,
+    models: [...imageUpscaleModelIdentifiers],
+  },
   stage: 'beta',
 }
 
@@ -39,6 +46,12 @@ const upscaleModelSchema = z
 const upscaleScaleSchema = z.union([z.literal(2), z.literal(4)]).default(2)
 const upscaleFaceEnhanceSchema = z.boolean().default(false)
 
+/**
+ * Maximum input area accepted by the pinned Real-ESRGAN Replicate predictor.
+ * @see https://github.com/replicate/cog-real-esrgan/blob/6cbd5e6ce8bd0fa90db54af899a8a9a85eb3db41/predict.py#L19
+ */
+export const realEsrganMaxInputPixels = 1448 * 1448
+
 export const robotImageUpscaleInstructionsSchema = robotBase
   .merge(robotUse)
   .extend({
@@ -47,11 +60,13 @@ export const robotImageUpscaleInstructionsSchema = robotBase
     model: upscaleModelSchema
       .optional()
       .describe(
-        `The AI model to use for image upscaling. Defaults to ${upscaleModelSchema.parse(undefined)}.`,
+        `The AI model to use for image upscaling. Defaults to ${upscaleModelSchema.parse(undefined)}. Real-ESRGAN inputs exceeding ${formatEnglishInteger(realEsrganMaxInputPixels)} pixels are resized proportionally before upscaling.`,
       ),
     scale: upscaleScaleSchema
       .optional()
-      .describe(`Upscale factor. Defaults to ${upscaleScaleSchema.parse(undefined)}.`),
+      .describe(
+        `Upscale factor, applied after any input resizing. Defaults to ${upscaleScaleSchema.parse(undefined)}. GFPGAN results are resized after restoration to match this factor.`,
+      ),
     face_enhance: upscaleFaceEnhanceSchema
       .optional()
       .describe(

package/src/alphalib/types/robots/mega-store.ts

@@ -39,7 +39,7 @@ export const robotMegaStoreInstructionsSchema = robotBase
 The URL to the result file will be returned in the <dfn>Assembly Status JSON</dfn>.
 `),
     path: storeFilePath,
-    acl: storageAcl,
+    acl: storageAcl.default('private'),
     headers: z
       .record(z.string())
       .default({ 'Content-Type': '${file.mime}' })

package/src/alphalib/types/robots/s3-store.ts

@@ -17,7 +17,19 @@ import {
 } from './_instructions-primitives.ts'
 
 const s3StoreAclSchema = z
-  .enum(['bucket-default', 'private', 'public', 'public-read'])
+  // AWS object canned ACLs, plus the existing omission sentinel and legacy `public` value.
+  // `log-delivery-write` is bucket-only: https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl
+  .enum([
+    'authenticated-read',
+    'aws-exec-read',
+    'bucket-default',
+    'bucket-owner-full-control',
+    'bucket-owner-read',
+    'private',
+    'public',
+    'public-read',
+    'public-read-write',
+  ])
   .default('public-read')
 
 export const meta: RobotMetaInput = {
@@ -95,7 +107,7 @@ Short-lived AWS credentials are a matching set of \`key\`, \`secret\` and \`sess
 The URL prefix used for the returned URL, such as \`"http://my.cdn.com/some/path/"\`.
 `),
     acl: s3StoreAclSchema.describe(`
-The ACL used for this file. The default remains \`"${s3StoreAclSchema.parse(undefined)}"\`, which can conflict with S3 Block Public Access and disabled ACLs. For modern private buckets, explicitly set \`"bucket-default"\` to omit the generated ACL header, and do not supply ACL/grant headers in \`headers\`. \`"private"\` still sends an ACL.
+The ACL used for this file. Supports AWS’s [canned ACLs for objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl). Other S3-compatible providers may support different ACLs. The default remains \`"${s3StoreAclSchema.parse(undefined)}"\`, which can conflict with S3 Block Public Access and disabled ACLs. For modern private buckets, explicitly set \`"bucket-default"\` to omit the generated ACL header, and do not supply ACL/grant headers in \`headers\`. \`"private"\` still sends an ACL.
 `),
     check_integrity: z
       .boolean()

package/src/alphalib/types/robots/video-adaptive.ts

@@ -71,6 +71,16 @@ This <dfn>Robot</dfn> accepts all types of video files and audio files. Do not f
 
 This <dfn>Robot</dfn> is normally used in combination with [🤖/video/encode](/docs/robots/video-encode/). We have implemented video and audio encoding presets specifically for MPEG-Dash and HTTP Live Streaming support. These presets are prefixed with \`"dash/"\` and \`"hls/"\`. [View a HTTP Live Streaming demo here](/demos/video-encoding/implement-http-live-streaming/).
 
+### CMAF aspect ratios
+
+CMAF aligns near-equal rendition aspect ratios, within 1% of the largest rendition, without re-encoding or changing pixel dimensions. This lets presets such as \`"hls/480p"\` and \`"hls/720p"\` support bitrate switching together.
+
+Renditions with substantially different ratios, such as 4:3 and 16:9, keep their geometry in separate video groups. The Assembly warns because DASH players cannot switch bitrate between these groups. HLS still lists every variant. Use matching rendition ratios when custom FFmpeg options change video geometry or layout.
+
+### Segment alignment
+
+HLS and CMAF video segments split at existing keyframes, so their actual duration can exceed \`segment_duration\`. To align renditions to four-second segments, set \`"ffmpeg": { "force_key_frames": "expr:gte(t,n_forced*4)" }\` in each preceding [🤖/video/encode](/docs/robots/video-encode/) Step. Replace \`4\` with your chosen segment duration and use the same value for every rendition. Set keyframe intervals during encoding; packaging cannot add keyframes to copied streams.
+
 ### Required CORS settings for MPEG-Dash and HTTP Live Streaming
 
 Playing back MPEG-Dash Manifest or HLS playlist files requires a proper CORS setup on the server-side. The file-serving server should be configured to add the following header fields to responses:
@@ -106,6 +116,26 @@ To set up CORS for your S3 bucket:
 The <dfn>Robot</dfn> gives its result files (segments, initialization segments, MPD manifest files and M3U8 playlist files) the right metadata property \`relative_path\`, so that you can store them easily using one of our storage <dfn>Robots</dfn>.
 
 In the \`path\` parameter of the storage <dfn>Robot</dfn> of your choice, use the <dfn>Assembly Variable</dfn> \`\${file.meta.relative_path}\` to store files in the proper paths to make the playlist files work.
+`),
+    ffmpeg: robotFFmpegVideo.shape.ffmpeg.describe(`
+Custom FFmpeg options are supported for the \`"hls"\` and \`"cmaf"\` techniques. Non-empty custom options are rejected for \`"dash"\`, the default technique.
+
+These options apply to the packaging command, which copies the input streams by default. Set encoding options, such as keyframe intervals, in the preceding [🤖/video/encode](/docs/robots/video-encode/) Step.
+`),
+    ffmpeg_stack: robotFFmpegVideo.shape.ffmpeg_stack
+      .removeDefault()
+      .default('v7.0.0')
+      .describe(`
+Selects the FFmpeg stack for packaging. Defaults to \`"v7.0.0"\`. This Robot always uses at least \`"v7.0.0"\`; older stack selections are upgraded automatically.
+`),
+    preset: robotFFmpegVideo.shape.preset.describe(`
+This parameter has no effect on this Robot. Set the encoding preset in the preceding [🤖/video/encode](/docs/robots/video-encode/) Step.
+`),
+    width: robotFFmpegVideo.shape.width.describe(`
+This parameter has no effect on this Robot. Set the rendition width in the preceding [🤖/video/encode](/docs/robots/video-encode/) Step.
+`),
+    height: robotFFmpegVideo.shape.height.describe(`
+This parameter has no effect on this Robot. Set the rendition height in the preceding [🤖/video/encode](/docs/robots/video-encode/) Step.
 `),
     technique: z
       .enum(['dash', 'hls', 'cmaf'])
@@ -129,9 +159,9 @@ Only used when \`technique\` is \`"cmaf"\`. Defines the filename for the generat
     segment_duration: z
       .number()
       .int()
-      .default(10)
+      .optional()
       .describe(`
-The duration for each segment in seconds.
+The duration for each segment in seconds. When omitted, defaults to 4 seconds for MPEG-Dash and CMAF, and 10 seconds for HLS.
 `),
     closed_captions: z
       .boolean()
@@ -147,7 +177,11 @@ When set to \`true\` and using the \`"hls"\` technique, audio-only input files a
 
 When enabled, video inputs only include their video stream in the output segments (any muxed audio is excluded). Provide audio separately as audio-only input files.
 
-This option is only supported for the \`"hls"\` technique and has no effect when using \`"dash"\`.
+Each rendition’s \`LANGUAGE\` comes from the first audio stream’s \`language\` tag in its audio-only input file, or \`"und"\` when the tag is missing. Set the tag on [🤖/audio/encode](/docs/robots/audio-encode/) with \`"ffmpeg": {"metadata:s:a:0": "language=deu"}\`, for example.
+
+The first audio-only input in \`use.steps\` order becomes \`DEFAULT=YES\`; the other renditions have \`DEFAULT=NO\`. All audio renditions have \`AUTOSELECT=YES\`. Their \`NAME\` uses the audio stream’s \`title\` tag when present, otherwise its language’s English name (for example, \`"eng"\` becomes “English” and \`"deu"\` becomes “German”). Untagged audio is named “Unknown”; unrecognized language codes are used as the name. Duplicate names receive a numeric suffix.
+
+This option only enables alternate audio renditions with the \`"hls"\` technique and does not change packaging with \`"dash"\` or \`"cmaf"\`. CMAF puts all audio in one adaptation set labeled with the first audio language. Setting \`audio_group: true\` with CMAF, or providing CMAF inputs with more than one known audio language (including tracks muxed in a single video), adds an Assembly warning; packaging continues with the existing CMAF output. For multi-language audio, use \`technique: "hls"\` with \`audio_group: true\`.
 `),
   })
   .strict()

package/src/alphalib/types/robots/video-concat.ts

@@ -89,9 +89,11 @@ Please note this parameter is independent of adding video fades between sections
       .boolean()
       .default(false)
       .describe(`
-When set to \`true\`, the concatenated video will contain chapter markers at the positions where the input videos are joined. Each chapter will be titled with the basename of the corresponding input video file.
+When set to \`true\`, the concatenated video will contain a chapter marker where each input video starts in the output. Each chapter will be titled with the basename of the corresponding input video file. When a \`transition\` is enabled, the incoming clip’s chapter starts at the beginning of its transition, accounting for the overlap between clips.
 
 This is useful for navigation in video players that support chapter-based seeking.
+
+In MP4 output, chapter markers add a \`bin_data\` track containing the chapter information. This is normal and does not affect video or audio playback.
 `),
     sort_by: inputSortBySchema,
     transition: z
@@ -104,7 +106,7 @@ Specifies the transition effect to apply between concatenated video clips.
 - \`"crossfade"\`: Applies a crossfade transition where the end of one clip gradually blends into the beginning of the next clip. Both video and audio are crossfaded.
 - \`"fade_to_black"\`: Applies a fade-to-black transition where each clip fades out to black before the next clip fades in from black.
 
-When using \`"crossfade"\` or \`"fade_to_black"\`, the \`transition_duration\` parameter controls how long the transition lasts. Note that crossfade transitions will reduce the total output duration since clips overlap during the transition.
+When using \`"crossfade"\` or \`"fade_to_black"\`, the \`transition_duration\` parameter controls how long the transition lasts. Both effects overlap adjacent clips and reduce the total output duration by the applied transition duration at each join. The applied duration is capped at half of the shorter clip in each pair.
 `),
     transition_duration: z
       .number()
@@ -114,7 +116,9 @@ The duration of the transition effect in seconds. Only applies when \`transition
 
 For example, a value of \`1.0\` creates a 1-second transition between clips. The value can be a float for sub-second precision (e.g., \`0.5\` for 500 milliseconds) and must be greater than \`0\` whenever transitions are enabled.
 
-For crossfade transitions, this is the overlap duration where both clips are visible. For fade_to_black transitions, this is the total time for the fade out and fade in (half for each). The applied transition is capped at half of the shorter clip in each transition pair.
+For crossfade transitions, this is the overlap duration where both clips are visible. For \`"fade_to_black"\`, the video fades out over approximately the first 20% of the transition and fades in over the remaining 80% (about 0.2 seconds out and 0.8 seconds in for a 1-second transition). Audio is crossfaded throughout the transition for both effects.
+
+The applied transition is capped at half of the shorter clip in each transition pair. Both effects shorten the output by this applied duration at each join.
 `),
   })
   .strict()

package/src/alphalib/types/robots/video-encode.ts

@@ -39,6 +39,12 @@ export const robotVideoEncodeInstructionsSchema = robotBase
     robot: z.literal('/video/encode').describe(`
 The /video/encode Robot is a versatile tool for video processing that handles transcoding, resizing, and watermarking. It supports various formats including modern standards like HEVC (H.265), and provides features such as presets for common devices, custom FFmpeg parameters for powerusers, watermark positioning, and more.
 
+## iPhone spatial audio
+
+Videos recorded with iPhone spatial audio can contain a stereo AAC track alongside an Apple Positional Audio Codec (APAC) track. When unsupported audio is present, this <dfn>Robot</dfn> keeps one supported audio track by default. Spatial audio is not preserved or converted.
+
+Files containing only unsupported audio still fail. Individual audio track selections and stream-copy requests keep the tracks you select; the output format must support copied tracks.
+
 ## Adding text overlays with FFmpeg
 
 You can add text overlays to videos using FFmpeg's \`drawtext\` filter through this <dfn>Robot</dfn>'s \`ffmpeg\` parameter. Here are two examples — one with the default font and one with a custom font family name:

package/src/alphalib/types/robots/video-generate.ts

@@ -49,7 +49,7 @@ export const robotVideoGenerateInstructionsSchema = robotBase
         `The AI model to use for video generation. Defaults to ${videoGenerateDefaultModelIdentifier}.`,
       ),
     prompt: z.string().describe('The prompt describing the desired video content.'),
-    format: z.enum(['mp4', 'gif']).optional().describe('Format of the generated video.'),
+    format: z.enum(['mp4']).optional().describe('Format of the generated video.'),
     seed: z.number().optional().describe(robotParameterDocs.seed.description),
     aspect_ratio: z.string().optional().describe('Aspect ratio of the generated video.'),
     height: z.number().optional().describe('Height of the generated video.'),

package/src/alphalib/types/robots/video-merge.ts

@@ -24,6 +24,8 @@ export const meta: RobotMetaInput = {
     steps: {
       merged: {
         robot: '/video/merge',
+        preset: 'empty',
+        ffmpeg: { f: 'mp4' },
         use: [
           { name: ':original', as: 'image' },
           { name: ':original', as: 'audio' },
@@ -51,7 +53,12 @@ export const robotVideoMergeInstructionsSchema = robotBase
   .merge(robotUse)
   .merge(robotFFmpegVideo)
   .extend({
-    robot: z.literal('/video/merge'),
+    // The robot literal's description supplies the Robot page introduction.
+    robot: z.literal('/video/merge').describe(`
+When concatenating videos end-to-end, all inputs must have the same width and height, with or without a \`transition\`. For joining clips, use [🤖/video/concat](/docs/robots/video-concat/), which pre-transcodes inputs to matching specifications when needed.
+
+When both \`preset\` and \`ffmpeg\` are omitted, this Robot uses the legacy \`"flash"\` preset and outputs FLV. Choose an output preset or set \`ffmpeg.f\` explicitly to select another format, such as \`"mp4"\`.
+`),
     resize_strategy: resize_strategy.describe(`
 If the given width/height parameters are bigger than the input image's dimensions, then the \`resize_strategy\` determines how the image will be resized to match the provided width/height. See the [available resize strategies](/docs/topics/resize-strategies/).
 `),
@@ -107,6 +114,7 @@ Stacks the input media vertically. All streams need to have the same pixel forma
 The URL of an image to be merged with the audio or video. When this parameter is provided, the robot will download the image from the URL and merge it with the other media.
 `),
     sort_by: inputSortBySchema,
+    // Include join constraints in parameter help as well as the Robot introduction.
     transition: z
       .enum(['none', 'crossfade', 'fade_to_black'])
       .default('none')
@@ -116,12 +124,18 @@ The type of transition effect to apply between concatenated video clips. Only ap
 - \`"none"\` — No transition effect. Videos are joined end-to-end.
 - \`"crossfade"\` — A gradual blend from one clip to the next (both video and audio).
 - \`"fade_to_black"\` — The current clip fades out to black, then the next clip fades in from black.
+
+Both \`"crossfade"\` and \`"fade_to_black"\` overlap adjacent clips and shorten the output by the applied \`transition_duration\` at each join. The applied duration is capped at half of the shorter clip in each pair.
+
+All concatenated videos must have the same width and height, even when \`transition\` is \`"none"\`. For joining clips with different dimensions, use [🤖/video/concat](/docs/robots/video-concat/).
 `),
     transition_duration: z
       .number()
       .default(1)
       .describe(`
 The duration of the transition effect in seconds. Only applies when \`transition\` is not \`"none"\`. Supports float values (e.g., \`0.5\` for a 500ms transition) and must be greater than \`0\` whenever transitions are enabled. The applied transition is automatically capped at half of the shorter clip in each transition pair to prevent overlapping transitions.
+
+For \`"crossfade"\`, this is the overlap duration where both clips are visible. For \`"fade_to_black"\`, the video fades out over approximately the first 20% of the transition and fades in over the remaining 80% (about 0.2 seconds out and 0.8 seconds in for a 1-second transition). Audio is crossfaded throughout the transition for both effects. Both effects shorten the output by the applied duration at each join.
 `),
   })
   .strict()

package/src/alphalib/types/robots/video-split.ts

@@ -57,6 +57,8 @@ export const robotVideoSplitInstructionsSchema = robotBase
   .extend({
     robot: z.literal('/video/split').describe(`
 Splits a video into multiple segments based on an array of from/to durations. Each segment produces a separate output file. This is useful for cutting a video into parts, for example to insert ads later via [🤖/video/concat](/docs/robots/video-concat/).
+
+For iPhone videos with spatial audio, see [iPhone spatial audio in 🤖/video/encode](/docs/robots/video-encode/#iphone-spatial-audio).
 `),
     segments: z
       .array(segmentSchema)