operations

operations indicates visual operations to be performed on Image and Video objects at insertion or at retrieval time, and on Frame and Clip objects at retrieval time.

operations is an array of operation objects. Each object has a type that names the operation and parameters specific to that operation.

An empty array is accepted and applies no transformations.

Operations are guaranteed to be performed in the specified order.

Each operation has its own required parameters. Supported operations differ between image commands (AddImage, FindImage, FindFrame) and video commands (AddVideo, FindVideo, FindClip); some operations apply to both groups.

Field contract

Fields not used by the selected operation are rejected. The command must also support that operation for its media type. An operation with missing required fields fails validation before processing media.

Field	Type / required	Behavior
`type`	string / required	Required operation name; the command determines which operations are supported.
`value`	integer / conditional	Required for threshold; inclusive range 0 through 255. Rejected for other operations.
`x`	nonnegative integer / conditional	Required crop coordinate; must fit a signed 32-bit integer. Rejected for other operations.
`y`	nonnegative integer / conditional	Required crop coordinate; must fit a signed 32-bit integer. Rejected for other operations.
`width`	positive integer / conditional	Required for crop; resize accepts width and/or height instead of scale. Must fit a signed 32-bit integer.
`height`	positive integer / conditional	Required for crop; resize accepts height and/or width instead of scale. Must fit a signed 32-bit integer.
`scale`	positive number / conditional	Resize only; cannot accompany width or height. Without scale, at least one dimension is required.
`mode`	string / conditional	Required for flip (horizontal, vertical, both) or transpose (clock, cclock, clock_flip, cclock_flip).
`angle`	number / conditional	Required for rotate; strictly greater than 0 and less than 360 degrees.
`resize`	boolean / conditional	Required for rotate; true expands the output canvas to fit. It has no implicit default.
`start`	nonnegative integer / conditional	Required for interval; must be less than stop.
`stop`	nonnegative integer / conditional	Required for interval; end bound for the selected frame interval.
`step`	positive integer / conditional	Interval only; default 1. Must not exceed stop - start.
`max_frame_count`	positive integer / conditional	Preview only; maximum frames. At least one preview limit is required.
`max_time_fraction`	number in (0, 1] / conditional	Preview only; maximum fraction of video duration. At least one preview limit is required.
`max_time_offset`	time-offset string / conditional	Preview only; seconds, minutes:seconds, or hours:minutes:seconds, optionally with up to six fractional digits. At least one preview limit is required.
`max_size_mb`	positive number / conditional	Preview only; maximum size in MiB (1024*1024 bytes), strictly less than 8796093022208. At least one preview limit is required.

Common Operations and Parameters

threshold:
- “type”: “threshold”
- “value”: [0,255]. Value of the threshold below which all pixel values are zeroed.
crop:
- “type”: “crop”
- “x”: specify the starting position x (row).
- “y”: specify the starting position y (column).
- “width”: specify the width of the crop.
- “height”: specify the height of the crop.
resize:
- “type”: “resize”
- “width”: set the new image width.
- “height”: set the new image height.
- “scale”: specify the scale for resizing the image along both dimensions.
- Either “scale” OR (“width” and/or “height”) can be specified.
- If only one dimension is specified (width or height), the other dimension will be scaled accordingly, keeping the image aspect ratio.
transpose:
- “type”: “transpose”
- “mode”: required string:
  - "clock": rotate 90 degrees clockwise.
  - "cclock": rotate 90 degrees counter-clockwise.
  - "clock_flip": rotate 90 degrees clockwise, then flip vertically.
  - "cclock_flip": rotate 90 degrees counter-clockwise, then flip vertically.
- Swaps width and height without interpolation or scaling. Unlike rotate, it does not accept angle or resize.
- If the output codec does not support the resulting dimensions, add an explicit resize operation afterward; transpose does not adjust them.
- Example: "operations": [{"type": "transpose", "mode": "clock"}].

Extra Operations for Image/Frame Objects

flip:
- “type”: “flip”
- “mode”: required string:
  - "horizontal": mirror left to right.
  - "vertical": mirror top to bottom.
  - "both": mirror along both axes.
- Example: "operations": [{"type": "flip", "mode": "horizontal"}].
rotate:
- “type”: “rotate”
- “angle”: rotation angle, specified in counter-clockwise degrees.
- “resize”: {true, false}. Specifies whether the image will be resized so that the rotated image fits (resize = true), or if the image will be kept the same size (resize = false).

Video and clip timeline operations

interval selects zero-based frame numbers from start through stop, including both endpoints. step is the distance between selected frame numbers and defaults to 1. For example, start 0, stop 6, and step 2 selects frames 0, 2, 4, and 6.

The selected frames form a shortened video. Each retained frame keeps its source duration. Audio from those same portions of the timeline is joined in the same order; skipped portions can cause audible discontinuities. Use with_audio:false on the video or clip command to omit audio.

preview keeps a prefix subject to one or more limits:

max_frame_count limits the number of output video frames.
max_time_fraction limits the fraction of the current video’s duration.
max_time_offset limits duration using a time-offset string.
max_size_mb limits the complete output size in MiB, including audio and container overhead.

When several limits are supplied, the result must satisfy all of them. A size limit may produce a shorter result than the time or frame limits allow. A limit that cannot hold a complete, playable video produces an error. Audio follows the retained prefix.

Operations use the result of the preceding operation. An interval followed by a preview limits the sampled video; a preview followed by an interval samples within that preview. For clips, frame numbers in operations refer to the selected clip, starting at zero.

Example

# resize and threshold.
"operations": [
    {
        "type": "resize",
        "height": 200,
        "width":  200
    },
    {
        "type": "threshold",
        "value": 155
    }
],

# resize along width dimension.
# this will scale height accordingly, keeping image aspect ratio.
# For example, if the original image is 1000x500 (hxw),
# the resulting image will be 200x100.
"operations": [
    {
        "type": "resize",
        "width": 100
    }
]

# rescale the image along both dimensions.
# For example, if the original image is 1000x500 (hxw),
# the resulting image will be 1500x750
"operations": [
    {
        "type": "resize",
        "scale": 1.5
    }
],

# crop and threshold.
"operations": [
    {
        "type": "crop",
        "x": 255,
        "y": 155,
        "height": 10,
        "width":  15
    },
    {
        "type": "threshold",
        "value": 155,
    }
],

# interval
"operations": [
    {
        "type": "flip",
        "mode": "horizontal"
    },
    {
      "type": "interval", # Interval Operation
      "start": 20,        # Start from the 20th frame
      "stop": 200,        # Stop at the 200th frame
      "step": 5           # Pick 1 every 5 frames.
    }
],


# resize and preview.
"operations": [
    {
        "type": "resize",
        "height": 640,
        "width":  480
    },
    {
        "type": "preview",                # Request an initial part of the
                                          # Video that is
        "max_time_offset": "00:00:30.000" # ... up to 30 seconds long,
        "max_size_mb": 10,                # ... up to 10 MB in size, and
        "max_frame_count": 1000           # ... up to 1,000 frames large.
    }
]

Field contract​

Common Operations and Parameters​

Extra Operations for Image/Frame Objects​

Video and clip timeline operations​

Example​

Field contract

Common Operations and Parameters

Extra Operations for Image/Frame Objects

Video and clip timeline operations

Example