@giveitsmaller/contracts 0.9.0 → 0.16.0

package/operations/schemas/archive.yaml

@@ -19,4 +19,4 @@ operation:
       type: enum
       values: [flat, by_job]
       default: flat
-      description: "flat = all files in root, by_job = subfolder per source job"
+      description: "flat = all files together at the top level; by_job = a separate subfolder for each source"

package/operations/schemas/audio_overlay.yaml

@@ -20,9 +20,12 @@ operation:
     (`features.multi_overlay_stack`) but Lambda-side implementation
     deferred.
 
-    The overlay can be uploaded directly, imported externally, or
-    referenced from a vault connection per `WorkflowSource` (from
-    I10). The base is whatever single-asset source the workflow
+    Each input is a `MultiInputSource` — imported externally,
+    referenced from a vault connection, or an upstream `job_output`
+    (uploads are NOT referenced directly inside inputs[]). An uploaded
+    overlay or base enters via a `passthrough` source job referenced by
+    `{ type: job_output, from: <id> }` (per ticket 4som89Uh). The base
+    is whatever single-asset source the workflow
     upstream has — for `mime_groups.audio`, the base is the primary
     audio track; for `mime_groups.video`, the overlay is mixed into
     the video's audio track and the visual track passes through
@@ -36,6 +39,18 @@ operation:
   min_inputs: 2
   max_inputs: 2
 
+  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
+  # exactly one each. Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 1 = 2)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    overlay:
+      min: 1
+      max: 1
+
   features:
     multi_overlay_stack:
       availability: planned
@@ -132,11 +147,12 @@ operation:
           default: mix
           description: |
             How the overlay combines with the base audio:
-            - `mix`: simple sum (overlay + base; both audible).
-            - `duck`: side-chain compress the base under the overlay
-              (base attenuates while overlay plays — broadcast pattern).
+            - `mix`: both play together (overlay added on top; both audible).
+            - `duck`: the base audio dips while the overlay plays, then
+              returns — the broadcast voice-over pattern.
             - `replace`: mute the base for the overlay's duration
               (overlay only; useful for hard-cut station IDs).
+          # `duck` is implemented as a side-chain compressor in the worker.
           per_value_availability:
             duck: { availability: planned }
 
@@ -147,8 +163,8 @@ operation:
           default: -20.0
           depends_on: { mode: duck }
           description: |
-            Side-chain threshold (dB). Base audio is ducked when the
-            overlay exceeds this level. Only applies when `mode: duck`.
+            Level (dB) the overlay must reach before the base audio
+            ducks. Only applies when `mode: duck`.
 
         duck_ratio:
           type: float
@@ -157,8 +173,8 @@ operation:
           default: 4.0
           depends_on: { mode: duck }
           description: |
-            Side-chain compression ratio. Higher values produce more
-            aggressive ducking. Only applies when `mode: duck`.
+            How strongly the base ducks — higher values dip it more
+            aggressively. Only applies when `mode: duck`.
 
         duck_attack_ms:
           type: integer
@@ -304,7 +320,7 @@ operation:
           values: [mix, duck, replace]
           default: mix
           description: |
-            Same modes as the audio mime_group. `replace` mutes the
+            Same modes as for audio overlays. `replace` mutes the
             base video's audio for the overlay's duration.
           per_value_availability:
             duck: { availability: planned }
@@ -315,7 +331,7 @@ operation:
           max: 0.0
           default: -20.0
           depends_on: { mode: duck }
-          description: "Side-chain threshold (dB). Only applies when `mode: duck`."
+          description: "Level (dB) the overlay must reach before the base audio ducks. Only applies when `mode: duck`."
 
         duck_ratio:
           type: float
@@ -323,7 +339,7 @@ operation:
           max: 20.0
           default: 4.0
           depends_on: { mode: duck }
-          description: "Side-chain compression ratio. Only applies when `mode: duck`."
+          description: "How strongly the base ducks — higher values dip it more aggressively. Only applies when `mode: duck`."
 
         duck_attack_ms:
           type: integer

package/operations/schemas/audio_to_video.yaml

@@ -65,6 +65,7 @@ operation:
         - audio/flac
         - audio/ogg
         - audio/opus
+        - audio/mp4
         - audio/x-m4a
       options:
         output_resolution:
@@ -100,10 +101,10 @@ operation:
           min: 1
           max: 60
           default: 2
+          # Low framerate + the encoder's still-image tuning keeps size tiny.
           description: |
-            Output video framerate. Default `2` fps — combined with
-            FFmpeg `-tune stillimage`, keeps the file size tiny for
-            the common case of a single still overlay. Raise for
+            Output video framerate. Default `2` fps keeps the file size
+            tiny for the common case of a single still overlay. Raise for
             animated overlays (not supported in V1 — overlay must be
             a still image) or platform requirements (e.g. YouTube
             recommends 24+ fps; some platforms accept lower).
@@ -112,8 +113,8 @@ operation:
           values: [mp4]
           default: mp4
           description: |
-            Output container format. V1 supports `mp4` only. Future
-            additions (webm, mov) await Lambda follow-up.
+            Output container format. V1 supports `mp4` only; webm and mov
+            are planned additions.
 
   # NOTE: role-MIME constraint (base MUST be audio, overlay MUST be
   # image) is documented in prose only for V1. ADR-0015 records this

package/operations/schemas/audio_watermark.yaml

@@ -76,7 +76,7 @@ operation:
             Optional caller-supplied payload to embed (max 256
             characters). Use cases: ownership marker, distribution
             channel ID, license key. When omitted, the server
-            generates a UUID-v7 `watermark_id` and embeds that
+            generates an identifier automatically and embeds that
             instead; the generated ID is returned on
             `OperationResult` so the caller can subsequently call
             the decode endpoint to verify.
@@ -85,18 +85,20 @@ operation:
           type: enum
           values: [auto, psychoacoustic, neural]
           default: auto
+          # `psychoacoustic` follows Resemble's open-source PerTh
+          # library as the path-to-prod reference; `neural` is a
+          # deep-generative embedding.
           description: |
             Watermarking algorithm:
             - `auto`: server selects the best available method for the
               input (currently maps to `psychoacoustic`; will widen as
               `neural` ships).
-            - `psychoacoustic`: classical masking-curve embedding.
-              Resemble's open-source PerTh library provides the path-
-              to-prod reference implementation. Survives MP3/AAC at
-              moderate bitrates and broadcast chains.
-            - `neural`: ML-based embedding (deep generative). Higher
-              survival under aggressive transcoding + analog-hole
-              capture; longer encoding time + non-deterministic.
+            - `psychoacoustic`: hides the mark below what the ear can
+              hear, so it stays inaudible. Survives MP3/AAC at moderate
+              bitrates and broadcast chains.
+            - `neural`: machine-learning embedding. Higher survival
+              under aggressive re-encoding and microphone re-recording;
+              longer encoding time and non-deterministic.
           per_value_availability:
             # `auto` + `psychoacoustic` land first (PerTh path-to-prod);
             # `neural` lands later via Lambda follow-up.
@@ -114,9 +116,9 @@ operation:
             - `compression_resistant` (default): survives multiple
               MP3/AAC re-encodes at typical streaming bitrates.
             - `broadcast_grade`: survives broadcast compression
-              chains, EQ, dynamic-range compression, and analog-hole
-              capture (microphone re-recording). Higher embedding
-              time + slightly larger perceptual footprint.
+              chains, EQ, dynamic-range compression, and microphone
+              re-recording. Higher embedding time + slightly larger
+              perceptual footprint.
 
         density:
           type: enum
@@ -166,16 +168,16 @@ operation:
           required: false
           description: |
             Optional caller-supplied payload to embed (max 256
-            characters). When omitted, the server generates a UUID-v7
-            `watermark_id` and embeds that instead.
+            characters). When omitted, the server generates an
+            identifier automatically and embeds that instead.
 
         method:
           type: enum
           values: [auto, psychoacoustic, neural]
           default: auto
           description: |
-            Watermarking algorithm. Same semantics as the `audio`
-            mime_group; embedded into the video's audio track only.
+            Watermarking algorithm. Same as for an audio input;
+            embedded into the video's audio track only.
           per_value_availability:
             neural: { availability: planned }
 
@@ -183,7 +185,7 @@ operation:
           type: enum
           values: [light, compression_resistant, broadcast_grade]
           default: compression_resistant
-          description: "Survival profile. Same semantics as audio mime_group."
+          description: "Survival profile. Same as for an audio input."
 
         density:
           type: enum

package/operations/schemas/compress.yaml

@@ -29,22 +29,12 @@ operation:
           default: 80
           depends_on: { mode: lossy }
           description: "Compression quality (1 = smallest file, 100 = best quality). Only applies to lossy mode."
-        width:
-          type: integer
-          min: 1
-          max: 16384
-          description: "Maximum output width in pixels"
-        height:
-          type: integer
-          min: 1
-          max: 16384
-          description: "Maximum output height in pixels"
-        fit:
-          type: enum
-          values: [max, crop, scale]
-          default: max
-          depends_on: { width: set, height: set, logic: or }
-          description: "Resize mode. max = fit within bounds, crop = fill and trim, scale = force exact dimensions. Only applies when width or height is set."
+        # width / height / fit / auto_orient were REMOVED from compress.image
+        # per EsD1hs5u — the libcaesium image-compress worker recompresses
+        # ONLY and silently IGNORED them (accept-then-ignore). Image resize +
+        # EXIF auto-orient are served by the `thumbnail` op; format change by
+        # `convert`. The `video` mime_group KEEPS width/height/fit (ffmpeg
+        # honors them — do not remove there).
         metadata:
           type: enum
           values: [all, none, copyright, sensitive]
@@ -57,10 +47,6 @@ operation:
           values: [preserve, strip, srgb]
           default: preserve
           description: "ICC color profile handling. preserve = keep original, strip = remove, srgb = convert to sRGB"
-        auto_orient:
-          type: boolean
-          default: true
-          description: "Auto-rotate based on EXIF orientation"
         progressive:
           type: boolean
           default: true
@@ -105,17 +91,24 @@ operation:
         trim_start:
           type: float
           min: 0
-          description: "Trim from beginning in seconds"
+          availability: planned
+          description: >
+            Trim from beginning in seconds. Gated `planned` (qZI5EK9j):
+            no compression worker implements per-clip trim yet, so the
+            server returns `feature_not_available` rather than accepting
+            and silently ignoring it. Flips to `stable` when a worker
+            lands; to trim today, chain a `split` op.
         trim_end:
           type: float
           min: 0
-          description: "Trim from end in seconds"
+          availability: planned
+          description: "Trim from end in seconds. Gated `planned` (qZI5EK9j) — see `trim_start`."
 
     video:
       mimes:
         - video/mp4
         - video/webm
-        - video/ogg
+        - video/quicktime
       processing_class:
         # F8 long-form video tier (per ticket I15-CONS, Trello YZpBKzOM).
         # Public contract uses logical names only — backend selection is
@@ -149,7 +142,8 @@ operation:
           type: enum
           values: [crf, target_size]
           default: crf
-          description: "crf = constant quality (variable file size), target_size = constrained file size (two-pass)"
+          # target_size is implemented as a two-pass encode in the worker.
+          description: "crf = constant quality (variable file size), target_size = constrained file size"
         crf:
           type: integer
           min: 0
@@ -161,7 +155,8 @@ operation:
           type: integer
           min: 1048576
           depends_on: { encoding_mode: target_size }
-          description: "Target output file size in bytes (min 1MB). Two-pass encoding to meet this target."
+          # Met via a two-pass encode in the worker.
+          description: "Target output file size in bytes (min 1MB)."
         preset:
           type: enum
           values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
@@ -169,14 +164,14 @@ operation:
           description: "Encoding speed vs compression ratio trade-off"
         width:
           type: integer
-          min: 1
+          min: 2
           max: 7680
-          description: "Output width in pixels"
+          description: "Output width in pixels. Must be an EVEN integer >= 2 (yuv420p chroma-subsampling); odd values are rejected as invalid_options by the encoder."
         height:
           type: integer
-          min: 1
+          min: 2
           max: 4320
-          description: "Output height in pixels"
+          description: "Output height in pixels. Must be an EVEN integer >= 2 (yuv420p chroma-subsampling); odd values are rejected as invalid_options by the encoder."
         fit:
           type: enum
           values: [max, crop, scale, pad]
@@ -191,7 +186,7 @@ operation:
         faststart:
           type: boolean
           default: true
-          description: "Move MP4 moov atom to start for progressive web playback (MP4 only)"
+          description: "Move the MP4/MOV moov atom to start for progressive web playback. MP4/MOV only; an explicit faststart on a WebM output is rejected as invalid_options (no moov atom)."
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
@@ -206,11 +201,18 @@ operation:
         trim_start:
           type: float
           min: 0
-          description: "Trim from beginning in seconds"
+          availability: planned
+          description: >
+            Trim from beginning in seconds. Gated `planned` (qZI5EK9j):
+            no compression worker implements per-clip trim yet, so the
+            server returns `feature_not_available` rather than accepting
+            and silently ignoring it. Flips to `stable` when a worker
+            lands; to trim today, chain a `split` op.
         trim_end:
           type: float
           min: 0
-          description: "Trim from end in seconds"
+          availability: planned
+          description: "Trim from end in seconds. Gated `planned` (qZI5EK9j) — see `trim_start`."
 
     document_pdf:
       mimes:

package/operations/schemas/custom_luma.yaml

@@ -20,9 +20,12 @@ operation:
     video being transitioned) + exactly one input with
     `role: transition_mask` (the luma matte — a video whose pixel
     luminance drives the transition reveal — bright = revealed,
-    dark = held). The mask can be uploaded directly, imported
-    externally, or referenced from a vault connection per
-    `WorkflowSource` (from I10).
+    dark = held). Each input is a `MultiInputSource` — imported
+    externally, referenced from a vault connection, or an upstream
+    `job_output` (uploads are NOT referenced directly inside inputs[]).
+    An uploaded base or mask enters via a `passthrough` source job
+    referenced by `{ type: job_output, from: <id> }` (per ticket
+    4som89Uh).
 
     Per ADR-0001 §1.3 (Tension 1 — `planned` operations return
     `feature_not_available` HTTP 422 until Lambda support ships).
@@ -34,6 +37,18 @@ operation:
   min_inputs: 2
   max_inputs: 2
 
+  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
+  # exactly one each. Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 1 = 2)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    transition_mask:
+      min: 1
+      max: 1
+
   mime_groups:
     video:
       mimes:

package/operations/schemas/image_watermark.yaml

@@ -3,11 +3,14 @@ schema_version: "2.0.0"
 operation:
   type: image_watermark
   description: |
-    Apply an image overlay (file or external source) onto a base media
+    Apply an image overlay onto a base media
     asset. Multi-input: exactly one input with role: base (the source
-    asset) + exactly one with role: overlay (the watermark). The overlay
-    can be an upload, an external_import handle, or a vault connection
-    per WorkflowSource (ticket I10).
+    asset) + exactly one with role: overlay (the watermark). Each input
+    is a `MultiInputSource` — an external_import handle, a vault
+    connection, or an upstream `job_output` (uploads are NOT referenced
+    directly inside inputs[]). To use an uploaded base or overlay, feed
+    it through a `passthrough` source job and reference that job via
+    `{ type: job_output, from: <id> }` (per ticket 4som89Uh).
 
     Stable today for static-image bases (image/jpeg, image/png,
     image/webp); animated GIF bases are advertised as `planned` via
@@ -34,6 +37,18 @@ operation:
   min_inputs: 2
   max_inputs: 2
 
+  # Per-role input-count constraints (ADR-0015). Both roles REQUIRED,
+  # exactly one each. Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 1 = 2)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    overlay:
+      min: 1
+      max: 1
+
   features:
     multi_overlay_stack:
       availability: planned
@@ -66,9 +81,9 @@ operation:
             - bottom_right
           default: bottom_right
           description: |
-            9-grid anchor position on the base image. Mirrors
-            Mux/Cloudinary positioning. Combined with margin_x and
-            margin_y for fine-grained offset from the anchor point.
+            9-grid anchor position on the base image. Combined with
+            margin_x and margin_y for fine-grained offset from the
+            anchor point.
 
         margin_x:
           type: string

package/operations/schemas/merge.yaml

@@ -75,10 +75,8 @@ operation:
           depends_on: { output_type: video }
           description: |
             Transition effect between images in the slideshow output.
-            Catalog from FFmpeg 7.1.1 xfade filter (per ADR-0007). See
-            per_value_availability for per-value rollout state. The
-            `none` value is a sentinel ("no transition / hard cut"),
-            not an FFmpeg preset.
+            `none` means a hard cut with no transition. Some effects
+            are still rolling out — check their availability.
           per_value_availability:
             # Untagged values default to stable per ADR-0001 §1.4.
             smoothleft:   { availability: beta }
@@ -139,12 +137,27 @@ operation:
       mimes:
         - video/mp4
         - video/webm
+        - video/quicktime
       processing_class:
         # F8 long-form video tier (per ticket I15-CONS). Merge uses
-        # alias class names because its differentiator is concat-
-        # compatibility (I16-CONS re_encode_mode) rather than just
-        # size/duration — a small merge can still need long_form
-        # when inputs require re-encoding.
+        # alias class names (short_form_concat / long_form_re_encode),
+        # but ROUTING (which class) is DURATION/SIZE-driven at
+        # create-plan, NOT concat-compatibility: the API resolver
+        # assigns long_form when summed input duration exceeds the
+        # short_form cap (PT5M) OR summed size exceeds 1 GiB; it has no
+        # per-input codec/pixfmt at create-plan to decide re-encode-need
+        # (MAVh1blw; api d363a4ab). re_encode-vs-stream-copy is a WORKER
+        # SUB-MODE WITHIN EACH class, not a long-form differentiator:
+        # short-form (filter_complex) re-encodes heterogeneous inputs +
+        # crossfade fine; long_form_re_encode (FFmpeg concat-demuxer)
+        # REQUIRES UNIFORM inputs and re-encodes them (e.g. uniform VP9 ->
+        # mp4). So long_form_re_encode = LONG-duration/size + uniform-but-
+        # not-stream-copyable. HETEROGENEOUS long merges (per-input codec
+        # mismatch at long duration) are the deferred Phase-3 gap (NOT
+        # built; concat-demuxer uniformity-rejects them). The earlier
+        # "a small merge can need long_form when inputs require
+        # re-encoding" claim was an over-claim describing a future
+        # two-trigger state — corrected here.
         short_form_concat:
           availability: stable
           constraints:
@@ -183,9 +196,8 @@ operation:
                    custom, wipetl, wipetr, wipebl]
           default: none
           description: |
-            Default transition between clips. Catalog from FFmpeg 7.1.1
-            xfade filter (per ADR-0007). See per_value_availability for
-            per-value rollout state.
+            Default transition between clips. Some effects are still
+            rolling out — check their availability.
           per_value_availability:
             smoothleft:   { availability: beta }
             smoothright:  { availability: beta }
@@ -291,33 +303,37 @@ operation:
           depends_on: { re_encode_mode: [auto, always] }
           per_value_depends_on:
             target_size: { codec: [h264] }
+          # target_size is currently codec=h264 only — h265 / vp9 / av1
+          # each require a different encoder invocation and are tracked
+          # as separate per-codec Lambda follow-ups. The
+          # per_value_depends_on block above gates encoding_mode=target_size
+          # on codec ∈ [h264], so a request pairing target_size with
+          # {h265, vp9, av1} is rejected as invalid_options whether or not
+          # target_size_bytes is supplied — closing the gap left by the
+          # previous option-level depends_on (which only triggered when
+          # target_size_bytes was present). Per ticket bsV3FWM5.
           description: |
-            CRF (quality-targeted) vs target_size (two-pass to fixed file size).
-            `target_size` is currently `codec=h264` only — libx265 / libvpx-vp9 / libsvtav1 each
-            require a different two-pass invocation and are tracked as separate per-codec
-            Lambda follow-ups. The `per_value_depends_on` block above gates
-            `encoding_mode=target_size` itself on `codec ∈ [h264]`, so a request with
-            `encoding_mode=target_size + codec ∈ {h265, vp9, av1}` is rejected as
-            `invalid_options` regardless of whether `target_size_bytes` is supplied —
-            closing the gap left by the previous option-level `depends_on` (which only
-            triggered when `target_size_bytes` was present in the payload). Per ticket
-            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5).
+            CRF aims for a quality level and lets the file size vary;
+            target_size aims for a fixed output file size. `target_size`
+            currently works with `codec=h264` only — a request pairing it
+            with another codec is rejected as `invalid_options`.
 
         target_size_bytes:
           type: integer
           min: 1048576
           depends_on: { re_encode_mode: [auto, always], encoding_mode: target_size }
+          # h264-only — the codec gate lives on
+          # encoding_mode.per_value_depends_on.target_size.codec (per ticket
+          # bsV3FWM5); this option's own depends_on no longer duplicates it.
+          # The practical floor below is enforced by the h264 encoder.
           description: |
-            Two-pass target file size in bytes (minimum 1 MiB). Required when
-            `encoding_mode=target_size`. h264-only — the codec gate now lives on
-            `encoding_mode.per_value_depends_on.target_size.codec` (per ticket
-            [`bsV3FWM5`](https://trello.com/c/bsV3FWM5)); this option's own
-            `depends_on` no longer duplicates it.
+            Target file size in bytes (minimum 1 MiB). Required when
+            `encoding_mode=target_size`, which is h264-only.
 
-            Practical floor: a ~100 kbps post-AAC video bitrate (i.e. `target_size_bytes`
-            corresponding to less than ~100 kbps of video after subtracting the 160 kbps
-            AAC audio track over the merged duration) is silently floored by libx264 and
-            the resulting file will not honour the requested `target_size_bytes`.
+            Practical floor: if the target works out to less than
+            ~100 kbps of video (after subtracting the ~160 kbps AAC audio
+            track over the merged duration), the encoder floors it and the
+            resulting file will not honour the requested `target_size_bytes`.
             Publishers targeting very small outputs should size accordingly.
 
       per_input_options:
@@ -373,6 +389,24 @@ operation:
           max: 5.0
           depends_on: { transition: crossfade }
           description: "Override crossfade duration for this join point"
+        trim_start:
+          type: float
+          min: 0
+          description: |
+            Trim from beginning in seconds (per-input). Applied to this
+            input BEFORE any transition/crossfade. Matches the
+            `compress` trim semantic. No `max` — the upper bound is the
+            input's own duration, enforced by the worker, not statically
+            bounded here.
+        trim_end:
+          type: float
+          min: 0
+          description: |
+            Trim from end in seconds (per-input). Applied to this input
+            BEFORE any transition/crossfade. Matches the `compress` trim
+            semantic. No `max` — the upper bound is the input's own
+            duration, enforced by the worker, not statically bounded
+            here.
 
     audio:
       # Audio transition catalog is intentionally separate from the
@@ -404,12 +438,13 @@ operation:
           # xfade catalog on merge.image / merge.video.
           values: [none, crossfade]
           default: none
+          # Audio-only catalog (acrossfade-backed); see FORMAT.md §"Audio
+          # vs visual transition catalogs (merge)" for the additions
+          # policy. Future values are added with per_value_availability
+          # per ADR-0001 §1.4.
           description: |
-            Default transition between clips. Audio-only catalog
-            (acrossfade-backed); see FORMAT.md §"Audio vs visual
-            transition catalogs (merge)" for additions policy. Future
-            values (e.g. `fade_curve` variants) will be added with
-            `per_value_availability` per ADR-0001 §1.4.
+            Transition between audio clips. `none` joins them with a
+            hard cut; `crossfade` blends one into the next.
         crossfade_duration:
           type: float
           min: 0
@@ -448,3 +483,21 @@ operation:
           min: 0
           max: 10.0
           description: "Override gap duration for this join point"
+        trim_start:
+          type: float
+          min: 0
+          description: |
+            Trim from beginning in seconds (per-input). Applied to this
+            input BEFORE any transition/crossfade. Matches the
+            `compress` trim semantic. No `max` — the upper bound is the
+            input's own duration, enforced by the worker, not statically
+            bounded here.
+        trim_end:
+          type: float
+          min: 0
+          description: |
+            Trim from end in seconds (per-input). Applied to this input
+            BEFORE any transition/crossfade. Matches the `compress` trim
+            semantic. No `max` — the upper bound is the input's own
+            duration, enforced by the worker, not statically bounded
+            here.