@giveitsmaller/contracts 0.2.3 → 0.3.0

package/operations/schemas/custom_luma.yaml

@@ -0,0 +1,109 @@
+schema_version: "2.0.0"
+
+operation:
+  type: custom_luma
+  availability: planned
+  required_tier: pro
+  description: |
+    Apply a caller-uploaded luma matte (transition-mask) over a base
+    video to produce a custom luma-matte transition effect. Inspired
+    by Cloudinary's deprecated luma-matte custom transitions and
+    intended as a paid-tier (`pro`+) creative feature.
+
+    **NOT** related to FFmpeg's `xfade=custom` filter (which is an
+    expression-mode parameter on the same `xfade` filter). The
+    `merge.transition.custom` value is tagged `planned` with
+    documentation_url pointing at this operation; once `custom_luma`
+    ships, the merge slot is repurposed to a "use the dedicated
+    `custom_luma` operation instead" advisory.
+
+    Multi-input: exactly one input with `role: base` (the source
+    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).
+
+    Per ADR-0001 §1.3 (Tension 1 — `planned` operations return
+    `feature_not_available` HTTP 422 until Lambda support ships).
+    Per ADR-0004 §"V2 JobDefinition" + plan v5 §F4 round 6
+    (codex-corrected — `xfade=custom` is an expression, not a
+    transition; this operation is the deliberate alternative).
+  default: false
+  input_model: multi
+  min_inputs: 2
+  max_inputs: 2
+
+  mime_groups:
+    video:
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form video tier (per ticket I15-CONS). custom_luma
+        # is itself `availability: planned` + `required_tier: pro`
+        # at the operation level; the per-class shape lands now to
+        # keep SDK/sidecar shape forward-compatible when the operation
+        # ships.
+        short_form:
+          availability: planned
+          required_tier: pro
+          constraints:
+            max_input_duration: "PT5M"
+            max_input_size_bytes: 524288000
+            max_output_size_bytes: 524288000
+        long_form:
+          availability: planned
+          required_tier: pro
+          constraints:
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 21474836480
+            max_output_size_bytes: 21474836480
+      options:
+        duration:
+          type: float
+          min: 0.1
+          max: 30.0
+          default: 1.0
+          description: |
+            Transition duration in seconds. The mask is time-stretched
+            or trimmed to this duration when applied.
+
+        start_offset:
+          type: float
+          min: 0.0
+          default: 0.0
+          description: |
+            Offset (seconds) from the base clip start at which the
+            transition begins. The transition runs for `duration`
+            seconds starting at `start_offset`.
+
+        mask_contrast:
+          type: float
+          min: 0.0
+          max: 4.0
+          default: 1.0
+          description: |
+            Contrast multiplier applied to the luma matte before
+            compositing. Sharpens (>1) or softens (<1) the
+            transition edge. Default 1.0 = no contrast adjustment.
+
+        mask_blur:
+          type: float
+          min: 0.0
+          max: 10.0
+          default: 0.0
+          description: |
+            Gaussian blur radius (pixels) applied to the luma matte
+            before compositing. Softens the transition edge. Default
+            0.0 = no blur. Larger values produce a more diffused
+            transition.
+
+        mask_invert:
+          type: boolean
+          default: false
+          description: |
+            When true, inverts the luma matte (bright ↔ dark). Lets
+            callers reuse a single mask asset for both reveal and
+            hide directions.

package/operations/schemas/image_watermark.yaml

@@ -0,0 +1,280 @@
+schema_version: "2.0.0"
+
+operation:
+  type: image_watermark
+  description: |
+    Apply an image overlay (file or external source) 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).
+
+    Stable today for static-image bases (image/jpeg, image/png,
+    image/webp); animated GIF and video bases are advertised as
+    `planned` via parallel mime_groups (`image_gif`, `video`) — schema
+    is contract-defined, dispatch returns `feature_not_available` (422)
+    until Lambda support ships. Per Tension 1 (ADR-0001) +
+    plan v5 §F4 round 6.
+
+    **Audio is explicitly NOT supported.** For audio overlay (DJ tags,
+    podcast intros, jingles), use the `audio_overlay` operation
+    (declared in schemas/operations/audio_overlay.yaml at
+    `availability: planned`).
+
+    Source capped at 25 megapixels for image bases (V1 watermark
+    precedent retained); per-frame caps for GIF / video bases will be
+    defined when the corresponding Lambda support ships.
+    Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
+  default: false
+  input_model: multi
+  min_inputs: 2
+  max_inputs: 2
+
+  features:
+    multi_overlay_stack:
+      availability: planned
+      description: |
+        Allow up to 8 overlay inputs per job (currently capped at 1
+        overlay). Per-overlay placement via JobInputV2.per_input_options.
+        Lambda-side support not yet confirmed; tagged planned per
+        ADR-0001 §1.4. Scope is image-base only at the time this feature
+        was specified; extension to GIF / video bases tracks alongside
+        the corresponding mime_group `planned` → `stable` flips.
+
+  mime_groups:
+    image:
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/webp
+      options:
+        anchor:
+          type: enum
+          values:
+            - top_left
+            - top_center
+            - top_right
+            - center_left
+            - center
+            - center_right
+            - bottom_left
+            - bottom_center
+            - 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.
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor as either pixels (e.g.
+            "40px") or percentage of base image width (e.g. "5%").
+            Direction is anchor-relative — positive moves toward image
+            centre.
+
+            **`anchor: center` exception.** When the anchor is `center`
+            the centre is the centre — there is no anchor-relative
+            direction. Non-zero `margin_x` (anything other than the
+            default `"0px"` or the equivalent `"0%"`) combined with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422). To nudge a
+            roughly-centred overlay, pick a peripheral anchor (e.g.
+            `top_left`) and use `margin_x` / `margin_y` to position it.
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor as either pixels (e.g.
+            "20px") or percentage of base image height (e.g. "3%").
+            Direction is anchor-relative — positive moves toward image
+            centre.
+
+            **`anchor: center` exception.** Same rejection rule as
+            `margin_x` — non-zero `margin_y` with `anchor: center` is
+            rejected by the API at workflow-create time as
+            `invalid_options` (HTTP 422).
+
+        opacity:
+          type: float
+          min: 0.0
+          max: 1.0
+          default: 0.5
+          description: |
+            Overlay opacity (0 = fully transparent, 1 = fully opaque).
+            Clamped to range.
+
+        overlay_width:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          description: |
+            Optional overlay width as either pixels (e.g. "200px") or
+            percentage of base image width (e.g. "30%"). Aspect ratio is
+            preserved. Omit to use the original overlay size.
+
+    # Animated GIF base — separate group because the rendering path is
+    # frame-preserving (each frame composited with the overlay), distinct
+    # from the static-image path. Tagged `planned` until Lambda confirms
+    # animated-GIF watermark support (cross-repo X5).
+    image_gif:
+      availability: planned
+      mimes:
+        - image/gif
+      options:
+        anchor:
+          type: enum
+          values:
+            - top_left
+            - top_center
+            - top_right
+            - center_left
+            - center
+            - center_right
+            - bottom_left
+            - bottom_center
+            - bottom_right
+          default: bottom_right
+          description: |
+            9-grid anchor position on the base GIF (applied uniformly
+            across frames). Same semantics as the `image` group.
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor in pixels or percentage of
+            base width. Anchor-relative; positive moves toward the
+            frame centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_x` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor in pixels or percentage of
+            base height. Anchor-relative; positive moves toward the
+            frame centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_y` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        opacity:
+          type: float
+          min: 0.0
+          max: 1.0
+          default: 0.5
+          description: |
+            Overlay opacity (0 = fully transparent, 1 = fully opaque).
+            Clamped to range.
+
+        overlay_width:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          description: |
+            Optional overlay width as pixels or percentage of base
+            width. Aspect ratio preserved. Omit to use the original
+            overlay size.
+
+    # Video base — single planned block covering common web video
+    # containers. Per-frame megapixel cap, codec acceptance and frame-
+    # rate constraints will be defined when the video-watermark Lambda
+    # ships (follow-up cross-repo ticket; tracked in plan v5 §F4
+    # round 6).
+    video:
+      availability: planned
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form tier (per ticket I15-CONS Decisions §2). Both
+        # classes `planned` because the video mime_group itself is
+        # `planned` at the group level. Forward-compatible with future
+        # Lambda activation.
+        short_form:
+          availability: planned
+          constraints:
+            max_input_duration: "PT5M"
+            max_input_size_bytes: 524288000
+            max_output_size_bytes: 524288000
+        long_form:
+          availability: planned
+          required_tier: pro
+          constraints:
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 21474836480
+            max_output_size_bytes: 21474836480
+      options:
+        anchor:
+          type: enum
+          values:
+            - top_left
+            - top_center
+            - top_right
+            - center_left
+            - center
+            - center_right
+            - bottom_left
+            - bottom_center
+            - bottom_right
+          default: bottom_right
+          description: |
+            9-grid anchor position on each video frame. Same semantics
+            as the `image` group.
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor in pixels or percentage of
+            video frame width. Anchor-relative; positive moves toward
+            the frame centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_x` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor in pixels or percentage of
+            video frame height. Anchor-relative; positive moves toward
+            the frame centre.
+
+            **`anchor: center` exception.** Same rejection rule as the
+            `image` mime_group — non-zero `margin_y` with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422).
+
+        opacity:
+          type: float
+          min: 0.0
+          max: 1.0
+          default: 0.5
+          description: |
+            Overlay opacity (0 = fully transparent, 1 = fully opaque).
+            Clamped to range.
+
+        overlay_width:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          description: |
+            Optional overlay width as pixels or percentage of video
+            frame width. Aspect ratio preserved. Omit to use the
+            original overlay size.