@giveitsmaller/contracts 0.2.0 → 0.3.0

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.