transloadit 3.0.2 → 4.0.0-2

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

@@ -0,0 +1,77 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: true,
+  bytescount: 10,
+  discount_factor: 0.1,
+  discount_pct: 90,
+  docs_redirect_from: ['/docs/export-to-your-own-tus-server/'],
+  example_code: {
+    steps: {
+      exported: {
+        robot: '/tus/store',
+        use: ':original',
+        endpoint: 'https://tusd.tusdemo.net/files/',
+      },
+    },
+  },
+  example_code_description: 'Export uploaded files to the Tus live demo server:',
+  minimum_charge: 0,
+  output_factor: 1,
+  override_lvl1: 'File Exporting',
+  purpose_sentence: 'exports encoding results to any Tus-compatible server',
+  purpose_verb: 'export',
+  purpose_word: 'Tus servers',
+  purpose_words: 'Export files to Tus-compatible servers',
+  service_slug: 'file-exporting',
+  slot_count: 10,
+  title: 'Export files to Tus-compatible servers',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotTusStoreInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/tus/store').describe(`
+**Note:** This <dfn>Robot</dfn> only accepts videos. [{.alert .alert-note}]
+
+**Warning:** Vimeo's API limits the number of concurrent uploads per minute based on your Vimeo account plan. To see how many videos can be uploaded at once based on your plan, click the following [link](https://developer.vimeo.com/guidelines/rate-limiting#table-1). [{.alert .alert-warning}]
+
+## Installation
+
+Since Vimeo works with OAuth, you will need to generate [Template Credentials](https://transloadit.com/c/template-credentials/) to use this <dfn>Robot</dfn>.
+
+To change the \`title\` or \`description\` per video, we recommend to [inject variables into your Template](/docs/topics/templates/).
+`),
+    endpoint: z.string().url().describe('The URL of the destination Tus server').describe(`
+The URL of the Tus-compatible server, which you're uploading files to.
+`),
+    credentials: z.string().optional().describe(`
+Create <dfn>Template Credentials</dfn> for this <dfn>Robot</dfn> in your [Transloadit account]({{site.base_url}}/c/template-credentials/) and use the name of the <dfn>Template Credentials</dfn> as this parameter's value. For this <dfn>Robot</dfn>, use the HTTP template, which allows request headers to be passed along to the destination server.
+`),
+    headers: z.record(z.string()).default({}).describe('Headers to pass along to destination')
+      .describe(`
+Optional extra headers outside of the <dfn>Template Credentials</dfn> can be passed along within this parameter.
+
+Although, we recommend to exclusively use <dfn>Template Credentials</dfn>, this may be necessary if you're looking to use dynamic credentials, which isn't a feature supported by <dfn>Template Credentials</dfn>.
+`),
+    metadata: z
+      .record(z.string())
+      .default({ filename: 'example.png', basename: 'example', extension: 'png' }).describe(`
+Metadata to pass along to destination. Includes some file info by default.
+`),
+    url_template: z.string().optional().describe(`
+The URL of the file in the <dfn>Assembly Status JSON</dfn>. The following [Assembly Variables](/docs/topics/assembly-instructions/#assembly-variables) are supported. If this is not specified, the upload URL specified by the destination server will be used instead.
+`),
+    ssl_url_template: z.string().optional().describe(`
+The SSL URL of the file in the <dfn>Assembly Status JSON</dfn>. The following [Assembly Variables](/docs/topics/assembly-instructions/#assembly-variables) are supported. If this is not specified, the upload URL specified by the destination server will be used instead, as long as it starts with \`https\`.
+`),
+  })
+  .strict()
+
+export type RobotTusStoreInstructions = z.infer<typeof robotTusStoreInstructionsSchema>
+export type RobotTusStoreInstructionsInput = z.input<typeof robotTusStoreInstructionsSchema>

package/src/alphalib/types/robots/upload-handle.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: false,
+  bytescount: 10,
+  discount_factor: 0.1,
+  discount_pct: 90,
+  example_code: {
+    steps: {
+      ':original': {
+        robot: '/upload/handle',
+      },
+      exported: {
+        robot: '/s3/store',
+        use: ':original',
+        credentials: 'YOUR_S3_CREDENTIALS',
+      },
+    },
+  },
+  example_code_description: 'Handle uploads and export the uploaded files to S3:',
+  minimum_charge: 0,
+  output_factor: 1,
+  override_lvl1: 'Handling Uploads',
+  purpose_sentence:
+    'receives uploads that your users throw at you from browser or apps, or that you throw at us programmatically',
+  purpose_verb: 'handle',
+  purpose_word: 'handle uploads',
+  purpose_words: 'Handle uploads',
+  redirect_from: ['/robots/upload-receive/', '/services/handling-uploads/upload-receive/'],
+  service_slug: 'handling-uploads',
+  slot_count: 0,
+  title: 'Handle uploads',
+  typical_file_size_mb: 1.2,
+  typical_file_type: 'file',
+}
+
+export const robotUploadHandleInstructionsSchema = robotBase
+  .merge(robotUse)
+  .extend({
+    robot: z.literal('/upload/handle').describe(`
+Transloadit handles file uploads by default, so specifying this <dfn>Robot</dfn> is optional.
+
+It can still be a good idea to define this <dfn>Robot</dfn>, though. It makes your <dfn>Assembly Instructions</dfn> explicit, and allows you to configure exactly how uploads should be handled. For example, you can extract specific metadata from the uploaded files.
+
+There are **3 important constraints** when using this <dfn>Robot</dfn>:
+
+1. Don’t define a \`use\` parameter, unlike with other <dfn>Robots</dfn>.
+2. Use it only once in a single set of <dfn>Assembly Instructions</dfn>.
+3. Name the Step as \`:original\`.
+`),
+  })
+  .strict()
+
+export type RobotUploadHandleInstructions = z.infer<typeof robotUploadHandleInstructionsSchema>
+export type RobotUploadHandleInstructionsInput = z.input<typeof robotUploadHandleInstructionsSchema>

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

@@ -0,0 +1,123 @@
+import { z } from 'zod'
+
+import { robotBase, robotUse, robotFFmpegVideo } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+import { stackVersions } from '../stackVersions.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: false,
+  bytescount: Infinity,
+  discount_factor: 1,
+  discount_pct: 0,
+  example_code: {
+    steps: {
+      ':original': {
+        robot: '/upload/handle',
+      },
+      encoded_480p: {
+        robot: '/video/encode',
+        use: ':original',
+        preset: 'hls/480p',
+        ffmpeg_stack: stackVersions.ffmpeg.recommendedVersion,
+      },
+      encoded_720p: {
+        robot: '/video/encode',
+        use: ':original',
+        preset: 'hls/720p',
+        ffmpeg_stack: stackVersions.ffmpeg.recommendedVersion,
+      },
+      encoded_1080p: {
+        robot: '/video/encode',
+        use: ':original',
+        preset: 'hls/1080p',
+        ffmpeg_stack: stackVersions.ffmpeg.recommendedVersion,
+      },
+      hls_bundled: {
+        robot: '/video/adaptive',
+        use: {
+          steps: ['encoded_480p', 'encoded_720p', 'encoded_1080p'],
+          bundle_steps: true,
+        },
+        technique: 'hls',
+        playlist_name: 'my_playlist.m3u8',
+      },
+    },
+  },
+  example_code_description:
+    'Implementing HTTP Live Streaming: encode the uploaded video into three versions, then cut them into several segments and generate playlist files containing all the segments:',
+  minimum_charge: 0,
+  output_factor: 1.2,
+  override_lvl1: 'Video Encoding',
+  purpose_sentence:
+    'encodes videos into HTTP Live Streaming (HLS) and MPEG-Dash supported formats and generates the necessary manifest and playlist files',
+  purpose_verb: 'convert',
+  purpose_word: 'make adaptive',
+  purpose_words: 'Convert videos to HLS and MPEG-Dash',
+  service_slug: 'video-encoding',
+  slot_count: 60,
+  title: 'Convert videos to HLS and MPEG-Dash',
+  typical_file_size_mb: 80,
+  typical_file_type: 'video',
+}
+
+export const robotVideoAdaptiveInstructionsSchema = robotBase
+  .merge(robotUse)
+  .merge(robotFFmpegVideo)
+  .extend({
+    robot: z.literal('/video/adaptive').describe(`
+This <dfn>Robot</dfn> accepts all types of video files and audio files. Do not forget to use <dfn>Step</dfn> bundling in your \`use\` parameter to make the <dfn>Robot</dfn> work on several input files at once.
+
+This <dfn>Robot</dfn> is normally used in combination with [🤖/video/encode](/docs/transcoding/video-encoding/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/).
+
+### 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:
+
+\`\`\`
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET
+Access-Control-Allow-Headers: *
+\`\`\`
+
+If the files are stored in an Amazon S3 Bucket, you can use the following [CORS definition](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) to ensure the CORS header fields are set correctly:
+
+\`\`\`json
+[
+  {
+    "AllowedHeaders": ["*"],
+    "AllowedMethods": ["GET"],
+    "AllowedOrigins": ["*"],
+    "ExposeHeaders": []
+  }
+]
+\`\`\`
+
+To set up CORS for your S3 bucket:
+
+1. Visit <https://s3.console.aws.amazon.com/s3/buckets/>
+1. Click on your bucket
+1. Click "Permissions"
+1. Edit "Cross-origin resource sharing (CORS)"
+
+### Storing Segments and Playlist files
+
+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.
+`),
+    technique: z.enum(['dash', 'hls']).default('dash').describe(`
+Determines which streaming technique should be used. Currently supports \`"dash"\` for MPEG-Dash and \`"hls"\` for HTTP Live Streaming.
+`),
+    playlist_name: z.string().optional().describe(`
+The filename for the generated manifest/playlist file. The default is \`"playlist.mpd"\` if your \`technique\` is \`"dash"\`, and \`"playlist.m3u8"\` if your \`technique\` is \`"hls"\`.
+`),
+    segment_duration: z.number().int().default(10).describe(`
+The duration for each segment in seconds.
+`),
+    closed_captions: z.boolean().default(true).describe(`
+Determines whether you want closed caption support when using the \`"hls"\` technique.
+`),
+  })
+  .strict()
+
+export type RobotVideoAdaptiveInstructions = z.infer<typeof robotVideoAdaptiveInstructionsSchema>

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

@@ -0,0 +1,68 @@
+import { z } from 'zod'
+
+import { robotFFmpegVideo, robotBase, robotUse } from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: false,
+  bytescount: 4,
+  discount_factor: 0.25,
+  discount_pct: 75,
+  example_code: {
+    steps: {
+      concatenated: {
+        robot: '/video/concat',
+        use: {
+          steps: [
+            { name: ':original', fields: 'first_video_file', as: 'video_1' },
+            { name: ':original', fields: 'second_video_file', as: 'video_2' },
+            { name: ':original', fields: 'third_video_file', as: 'video_3' },
+          ],
+        },
+      },
+    },
+  },
+  example_code_description:
+    'If you have a form with 3 file input fields and want to concatenate the uploaded videos in a specific order, instruct Transloadit using the `name` attribute of each input field. Use this attribute as the value for the `fields` key in the JSON, and set `as` to `video_[[index]]`. Transloadit will concatenate the files based on the ascending index order:',
+  minimum_charge: 0,
+  output_factor: 0.6,
+  override_lvl1: 'Video Encoding',
+  purpose_sentence: 'concatenates several videos together',
+  purpose_verb: 'concatenate',
+  purpose_word: 'concatenate',
+  purpose_words: 'Concatenate videos',
+  service_slug: 'video-encoding',
+  slot_count: 60,
+  title: 'Concatenate videos',
+  typical_file_size_mb: 80,
+  typical_file_type: 'video',
+  uses_tools: ['ffmpeg'],
+}
+
+export const robotVideoConcatInstructionsSchema = robotBase
+  .merge(robotUse)
+  .merge(robotFFmpegVideo)
+  .extend({
+    robot: z.literal('/video/concat').describe(`
+**Warning:** All videos you concatenate must have the same dimensions (width and height) and the same streams (audio and video streams), otherwise you will run into errors. If your videos donʼt have the desired dimensions when passing them to [🤖/video/concat](/docs/transcoding/video-encoding/video-concat/), encode them first with [🤖/video/encode](/docs/transcoding/video-encoding/video-encode/). [{.alert .alert-warning}]
+
+Itʼs possible to concatenate a virtually infinite number of video files using [🤖/video/concat](/docs/transcoding/video-encoding/video-concat/).
+`),
+    video_fade_seconds: z.number().default(1).describe(`
+When used this adds a video fade in and out effect between each section of your concatenated video. The float value is used so if you want a video delay effect of 500 milliseconds between each video section you would select \`0.5\`, however, integer values can also be represented.
+
+This parameter does not add a video fade effect at the beginning or end of your video. If you want to do so, create an additional [🤖/video/encode](/docs/transcoding/video-encoding/video-presets/) Step and use our \`ffmpeg\` parameter as shown in this [demo](/demos/video-encoding/concatenate-fade-effect/).
+
+Please note this parameter is independent of adding audio fades between sections.
+`),
+    audio_fade_seconds: z.number().default(1).describe(`
+When used this adds an audio fade in and out effect between each section of your concatenated video. The float value is used so if you want an audio delay effect of 500 milliseconds between each video section you would select \`0.5\`, however, integer values can also be represented.
+
+This parameter does not add an audio fade effect at the beginning or end of your video. If you want to do so, create an additional [🤖/video/encode](/docs/transcoding/video-encoding/video-presets/) Step and use our \`ffmpeg\` parameter as shown in this [demo](/demos/audio-encoding/ffmpeg-fade-in-and-out/).
+
+Please note this parameter is independent of adding video fades between sections.
+`),
+  })
+  .strict()
+
+export type RobotVideoConcatInstructions = z.infer<typeof robotVideoConcatInstructionsSchema>

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

@@ -0,0 +1,182 @@
+import { z } from 'zod'
+
+import {
+  color_with_alpha,
+  robotFFmpegVideo,
+  interpolationSchemaToYieldNumber,
+  interpolationSchemaToYieldString,
+  percentageSchema,
+  positionSchema,
+  resize_strategy,
+  robotBase,
+  robotUse,
+  unsafeCoordinatesSchema,
+} from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: false,
+  bytescount: 1,
+  discount_factor: 1,
+  discount_pct: 0,
+  example_code: {
+    steps: {
+      hevc_encoded: {
+        robot: '/video/encode',
+        use: ':original',
+        preset: 'hevc',
+      },
+    },
+  },
+  example_code_description:
+    'Transcode uploaded video to [HEVC](https://en.wikipedia.org/wiki/High_Efficiency_Video_Coding) (H.265):',
+  minimum_charge: 0,
+  output_factor: 0.6,
+  override_lvl1: 'Video Encoding',
+  purpose_sentence: 'encodes, resizes, applies watermarks to videos and animated GIFs',
+  purpose_verb: 'transcode',
+  purpose_word: 'transcode/resize/watermark',
+  purpose_words: 'Transcode, resize, or watermark videos',
+  service_slug: 'video-encoding',
+  slot_count: 60,
+  title: 'Transcode, resize, or watermark videos',
+  typical_file_size_mb: 80,
+  typical_file_type: 'video',
+  uses_tools: ['ffmpeg'],
+}
+
+export const robotVideoEncodeInstructionsInterpolatedSchema = robotBase
+  .merge(robotUse)
+  .merge(robotFFmpegVideo)
+  .extend({
+    robot: z.literal('/video/encode'),
+    resize_strategy: resize_strategy.describe(`
+See the [available resize strategies](/docs/transcoding/image-manipulation/image-resize/#resize-strategies).
+`),
+    zoom: z.boolean().default(true).describe(`
+If this is set to \`false\`, smaller videos will not be stretched to the desired width and height. For details about the impact of zooming for your preferred resize strategy, see the list of available [resize strategies](/docs/transcoding/image-manipulation/image-resize/#resize-strategies).
+`),
+    crop: unsafeCoordinatesSchema.optional().describe(`
+Specify an object containing coordinates for the top left and bottom right corners of the rectangle to be cropped from the original video(s). Values can be integers for absolute pixel values or strings for percentage based values.
+
+For example:
+
+\`\`\`json
+
+{
+  "x1": 80,
+  "y1": 100,
+  "x2": "60%",
+  "y2": "80%"
+}
+
+\`\`\`
+
+This will crop the area from \`(80, 100)\` to \`(600, 800)\` from a 1000×1000 pixels video, which is a square whose width is 520px and height is 700px. If \`crop\` is set, the width and height parameters are ignored, and the \`resize_strategy\` is set to \`crop\` automatically.
+
+You can also use a JSON string of such an object with coordinates in similar fashion: \`"{ "x1": <Integer>, "y1": <Integer>, "x2": <Integer>, "y2": <Integer> }"\`
+`),
+    background: color_with_alpha.default('#00000000').describe(`
+The background color of the resulting video the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is black.
+`),
+    rotate: z
+      // We can’t use enum.
+      // See https://github.com/colinhacks/zod/issues/2686
+      .union([
+        z.literal(0),
+        z.literal(90),
+        z.literal(180),
+        z.literal(270),
+        z.literal(360),
+        z.literal(false),
+      ])
+      .optional().describe(`
+Forces the video to be rotated by the specified degree integer. Currently, only multiples of \`90\` are supported. We automatically correct the orientation of many videos when the orientation is provided by the camera. This option is only useful for videos requiring rotation because it was not detected by the camera. If you set \`rotate\` to \`false\` no rotation is performed, even if the metadata contains such instructions.
+`),
+    hint: z.boolean().default(false).describe(`
+Enables hinting for mp4 files, for RTP/RTSP streaming.
+`),
+    turbo: z.boolean().default(false).describe(`
+Splits the video into multiple chunks so that each chunk can be encoded in parallel before all encoded chunks are stitched back together to form the result video. This comes at the expense of extra <dfn>Priority Job Slots</dfn> and may prove to be counter-productive for very small video files.
+`),
+    chunk_duration: z.number().int().min(1).optional().describe(`
+Allows you to specify the duration of each chunk when \`turbo\` is set to \`true\`. This means you can take advantage of that feature while using fewer <dfn>Priority Job Slots</dfn>. For instance, the longer each chunk is, the fewer <dfn>Encoding Jobs</dfn> will need to be used.
+`),
+    freeze_detect: z.boolean().default(false).describe(`
+Examines the transcoding result file for video freeze frames and re-transcodes the video a second time if they are found. This is useful when you are using \`turbo: true\` because freeze frames can sometimes happen there. The re-transcode would then happen without turbo mode.
+`),
+    watermark_url: z.string().default('').describe(`
+A URL indicating a PNG image to be overlaid above this image. You can also [supply the watermark via another Assembly Step](/docs/transcoding/video-encoding/video-encode/#watermark-parameters-video-encode).
+`),
+    watermark_position: z.union([positionSchema, z.array(positionSchema)]).default('center')
+      .describe(`
+The position at which the watermark is placed.
+
+An array of possible values can also be specified, in which case one value will be selected at random, such as \`[ "center", "left", "bottom-left", "bottom-right" ]\`.
+
+This setting puts the watermark in the specified corner. To use a specific pixel offset for the watermark, you will need to add the padding to the image itself.
+`),
+    watermark_x_offset: z.number().int().default(0).describe(`
+The x-offset in number of pixels at which the watermark will be placed in relation to the position it has due to \`watermark_position\`.
+
+Values can be both positive and negative and yield different results depending on the \`watermark_position\` parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point.
+`),
+    watermark_y_offset: z.number().int().default(0).describe(`
+The y-offset in number of pixels at which the watermark will be placed in relation to the position it has due to \`watermark_position\`.
+
+Values can be both positive and negative and yield different results depending on the \`watermark_position\` parameter. Positive values move the watermark closer to the image's center point, whereas negative values move the watermark further away from the image's center point.
+`),
+    watermark_size: percentageSchema.optional().describe(`
+The size of the watermark, as a percentage, such as \`"50%"\`. How the watermark is resized greatly depends on the \`watermark_resize_strategy\`.
+`),
+    watermark_resize_strategy: z.enum(['area', 'fit', 'stretch']).default('fit').describe(`
+To explain how the resize strategies work, let's assume our target video size is 800×800 pixels and our watermark image is 400×300 pixels. Let's also assume, the \`watermark_size\` parameter is set to \`"25%"\`.
+
+For the \`"fit"\` resize strategy, the watermark is scaled so that the longer side of the watermark takes up 25% of the corresponding video side. And the other side is scaled according to the aspect ratio of the watermark image. So with our watermark, the width is the longer side, and 25% of the video size would be 200px. Hence, the watermark would be resized to 200×150 pixels. If the \`watermark_size\` was set to \`"50%"\`", it would be resized to 400×300 pixels (so just left at its original size).
+
+For the \`"stretch"\` resize strategy, the watermark image is stretched (meaning, it is resized without keeping its aspect ratio in mind) so that both sides take up 25% of the corresponding video side. Since our video is 800×800 pixels, for a watermark size of 25% the watermark would be resized to 200×200 pixels. Its height would appear stretched, because keeping the aspect ratio in mind it would be resized to 200×150 pixels instead.
+
+For the \`"area"\` resize strategy, the watermark is resized (keeping its aspect ratio in check) so that it covers \`"xx%"\` of the video's surface area. The value from \`watermark_size\` is used for the percentage area size.
+`),
+    watermark_start_time: z.number().default(0).describe(`
+The delay in seconds from the start of the video for the watermark to appear. By default the watermark is immediately shown.
+`),
+    watermark_duration: z.number().default(-1).describe(`
+The duration in seconds for the watermark to be shown. Can be used together with \`watermark_start_time\` to create nice effects. The default value is \`-1.0\`, which means that the watermark is shown for the entire duration of the video.
+`),
+    watermark_opacity: z.number().min(0).max(1).default(1).describe(`
+The opacity of the watermark. Valid values are between \`0\` (invisible) and \`1.0\` (full visibility).
+`),
+    segment: z.boolean().default(false).describe(`
+Splits the file into multiple parts, to be used for Apple's [HTTP Live Streaming](https://developer.apple.com/resources/http-streaming/).
+`),
+    segment_duration: z.number().int().min(1).default(10).describe(`
+Specifies the length of each HTTP segment. This is optional, and the default value as recommended by Apple is \`10\`. Do not change this value unless you have a good reason.
+`),
+    segment_prefix: z.string().default('').describe(`
+The prefix used for the naming. For example, a prefix of \`"segment_"\` would produce files named \`"segment_0.ts"\`, \`"segment_1.ts"\` and so on. This is optional, and defaults to the base name of the input file. Also see the related \`segment_name\` parameter.
+`),
+    segment_name: z.string().default('').describe(`
+The name used for the final segment. Available variables are \`\${segment_prefix}\`, \`\${segment_number}\` and \`\${segment_id}\` (which is a UUIDv4 without dashes).
+`),
+  })
+  .strict()
+
+export const robotVideoEncodeInstructionsSchema =
+  robotVideoEncodeInstructionsInterpolatedSchema.extend({
+    width: robotVideoEncodeInstructionsInterpolatedSchema.shape.width.or(
+      interpolationSchemaToYieldNumber,
+    ),
+    height: robotVideoEncodeInstructionsInterpolatedSchema.shape.height.or(
+      interpolationSchemaToYieldNumber,
+    ),
+    background: robotVideoEncodeInstructionsInterpolatedSchema.shape.background.or(
+      interpolationSchemaToYieldString,
+    ),
+    resize_strategy: robotVideoEncodeInstructionsInterpolatedSchema.shape.resize_strategy.or(
+      interpolationSchemaToYieldString,
+    ),
+  })
+
+export type RobotVideoEncodeInstructions = z.infer<typeof robotVideoEncodeInstructionsSchema>
+export type RobotVideoEncodeInstructionsInput = z.input<typeof robotVideoEncodeInstructionsSchema>

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

@@ -0,0 +1,72 @@
+import { z } from 'zod'
+
+import {
+  color_with_alpha,
+  robotFFmpegVideo,
+  resize_strategy,
+  robotBase,
+  robotUse,
+} from './_instructions-primitives.ts'
+import type { RobotMeta } from './_instructions-primitives.ts'
+
+export const meta: RobotMeta = {
+  allowed_for_url_transform: false,
+  bytescount: 1,
+  discount_factor: 1,
+  discount_pct: 0,
+  minimum_charge: 0,
+  output_factor: 0.6,
+  override_lvl1: 'Video Encoding',
+  purpose_sentence:
+    'composes a new video by adding an audio track to existing still image(s) or video',
+  purpose_verb: 'merge',
+  purpose_word: 'merge',
+  purpose_words: 'Merge video, audio, images into one video',
+  service_slug: 'video-encoding',
+  slot_count: 60,
+  title: 'Merge video, audio, images into one video',
+  typical_file_size_mb: 80,
+  typical_file_type: 'video',
+  uses_tools: ['ffmpeg'],
+}
+
+export const robotVideoMergeInstructionsSchema = robotBase
+  .merge(robotUse)
+  .merge(robotFFmpegVideo)
+  .extend({
+    robot: z.literal('/video/merge'),
+    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/transcoding/image-manipulation/image-resize/#resize-strategies).
+`),
+    background: color_with_alpha.default('#00000000').describe(`
+The background color of the resulting video the \`"rrggbbaa"\` format (red, green, blue, alpha) when used with the \`"pad"\` resize strategy. The default color is black.
+`),
+    framerate: z
+      .union([z.number().int().min(1), z.string().regex(/^\d+(?:\/\d+)?$/)])
+      .default('1/5').describe(`
+When merging images to generate a video this is the input framerate. A value of "1/5" means each image is given 5 seconds before the next frame appears (the inverse of a framerate of "5"). Likewise for "1/10", "1/20", etc. A value of "5" means there are 5 frames per second.
+`),
+    image_durations: z.array(z.number()).default([]).describe(`
+When merging images to generate a video this allows you to define how long (in seconds) each image will be shown inside of the video. So if you pass 3 images and define \`[2.4, 5.6, 9]\` the first image will be shown for 2.4s, the second image for 5.6s and the last one for 9s. The \`duration\` parameter will automatically be set to the sum of the image_durations, so \`17\` in our example. It can still be overwritten, though, in which case the last image will be shown until the defined duration is reached.
+`),
+    duration: z.number().default(5).describe(`
+When merging images to generate a video or when merging audio and video this is the desired target duration in seconds. The float value can take one decimal digit. If you want all images to be displayed exactly once, then you can set the duration according to this formula: \`duration = numberOfImages / framerate\`. This also works for the inverse framerate values like \`1/5\`.
+
+If you set this value to \`null\` (default), then the duration of the input audio file will be used when merging images with an audio file.
+
+When merging audio files and video files, the duration of the longest video or audio file is used by default.
+`),
+    audio_delay: z.number().default(0).describe(`
+When merging a video and an audio file, and when merging images and an audio file to generate a video, this is the desired delay in seconds for the audio file to start playing. Imagine you merge a video file without sound and an audio file, but you wish the audio to start playing after 5 seconds and not immediately, then this is the parameter to use.
+`),
+    loop: z.boolean().default(false).describe(`
+  Determines whether the shorter media file should be looped to match the duration of the longer one. For example, if you merge a 1-minute video with a 3-minute audio file and enable this option, the video will play three times in a row to match the audio length.`),
+    replace_audio: z.boolean().default(false).describe(`
+Determines whether the audio of the video should be replaced with a provided audio file.
+`),
+    vstack: z.boolean().default(false).describe(`
+Stacks the input media vertically. All streams need to have the same pixel format and width - so consider using a [/video/encode](/docs/transcoding/video-encoding/video-encode/) <dfn>Step</dfn> before using this parameter to enforce this.
+`),
+  })
+  .strict()
+export type RobotVideoMergeInstructions = z.infer<typeof robotVideoMergeInstructionsSchema>