@giveitsmaller/contracts 0.4.0 → 0.5.0

package/operations/schemas/video_text_watermark.yaml

@@ -0,0 +1,174 @@
+schema_version: "2.0.0"
+
+operation:
+  type: video_text_watermark
+  availability: planned
+  description: |
+    Render a text overlay onto a base video using bundled Liberation
+    Sans (SIL OFL) via FFmpeg's `drawtext` filter. Single-input — the
+    text and its styling come from options, not from a file input.
+    Per ADR-0013.
+
+    **Dedicated operation, not an extension of `text_watermark`.**
+    `text_watermark` renders onto images (single-pass Rust path);
+    `video_text_watermark` renders per-frame via FFmpeg drawtext +
+    re-encode (overlay = pixel modification, no stream-copy escape).
+    Different runtime, different deploy unit.
+
+    **Audio passthrough.** The base video's audio stream is preserved
+    unchanged via FFmpeg stream-copy — the watermark applies to the
+    visual track only.
+
+    Two rendering modes (mirrors `text_watermark`):
+    - `single`: one label rendered at the anchor + margin position.
+    - `tiled`: text tiled across the source frames at the rotation
+      angle.
+
+    `availability: planned` until the cross-repo Lambda support ships;
+    dispatch returns `feature_not_available` (422) until then. Per
+    ADR-0013 + lambdas pre-launch epic Wave A (ticket
+    [`4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+  default: false
+  input_model: single
+
+  mime_groups:
+    video:
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        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:                            # baseline = Pro
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
+      options:
+        text:
+          type: string
+          required: true
+          description: |
+            Watermark text. Must be non-empty. Rendered with bundled
+            Liberation Sans (SIL OFL).
+
+        font_size:
+          type: float
+          min: 8.0
+          max: 512.0
+          default: 48.0
+          description: Font size in pixels. Clamped to range.
+
+        color:
+          type: string
+          default: "#FFFFFF80"
+          pattern: '^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$'
+          description: |
+            Text colour as hex RGB (#RRGGBB) or RGBA (#RRGGBBAA).
+            Default is white with 50% alpha. Same vocabulary as
+            `text_watermark.image.color`.
+
+        font_family:
+          type: enum
+          values:
+            - liberation_sans
+          default: liberation_sans
+          description: |
+            Font family. V2.0 ships with bundled Liberation Sans only;
+            user-uploaded fonts are a future extension (separate
+            ticket).
+
+        rotation:
+          type: float
+          min: -360.0
+          max: 360.0
+          default: -45.0
+          description: |
+            Rotation angle in degrees. Default -45° suits tiled mode
+            (angled diagonal pattern). Clamped to range.
+
+        watermark_mode:
+          type: enum
+          values: [single, tiled]
+          default: single
+          description: |
+            Rendering mode:
+            - `single`: one label placed at the anchor + margin offset
+              on each frame.
+            - `tiled`: repeated tiles across the entire frame at the
+              rotation angle.
+
+        tile_spacing:
+          type: integer
+          min: 0
+          max: 1000
+          depends_on: { watermark_mode: tiled }
+          description: |
+            Spacing between tiled labels in pixels. Defaults to
+            font_size when omitted. Only applies when watermark_mode
+            is tiled.
+
+        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. For `watermark_mode: single`, the
+            text label is placed at this anchor + margin_x/margin_y
+            offset on each frame. For `watermark_mode: tiled`, anchor
+            is ignored (tiles fill the frame).
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor as pixels (e.g. "40px")
+            or percentage of video frame width (e.g. "5%").
+            Anchor-relative. Ignored when `watermark_mode: tiled`.
+
+            **`anchor: center` exception** (watermark_mode: single
+            only). Non-zero `margin_x` combined 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 as pixels or percentage of
+            video frame height. Ignored when `watermark_mode: tiled`.
+
+            **`anchor: center` exception** (watermark_mode: single
+            only). Same rejection rule as `margin_x`.
+
+        opacity:
+          type: float
+          min: 0.0
+          max: 1.0
+          default: 1.0
+          description: |
+            Text overlay opacity. Default 1.0 — the alpha channel of
+            `color` already encodes transparency, so opacity is
+            usually left at 1.0 and transparency is set via the color
+            hex.

package/operations/schemas/video_watermark.yaml

@@ -0,0 +1,136 @@
+schema_version: "2.0.0"
+
+operation:
+  type: video_watermark
+  availability: planned
+  description: |
+    Apply an image overlay (file or external source) onto a base video
+    asset using FFmpeg's `overlay` filter. Multi-input role-based:
+    exactly one input with `role: base` (the source video) + exactly
+    one with `role: overlay` (the watermark image). The overlay can be
+    an upload, an external_import handle, or a vault connection per
+    `WorkflowSource`.
+
+    **Dedicated operation, not an extension of `image_watermark`.**
+    `image_watermark` is pure-Rust/no-FFmpeg and handles
+    image-on-image overlay only. `video_watermark` requires FFmpeg's
+    overlay filter + re-encode + a different deploy unit (no
+    stream-copy escape — overlay = pixel modification). Per ADR-0013.
+
+    **Audio passthrough.** The base video's audio stream is preserved
+    unchanged via FFmpeg stream-copy — the watermark applies to the
+    visual track only.
+
+    `availability: planned` until the cross-repo Lambda support ships;
+    dispatch returns `feature_not_available` (422) until then. Per
+    ADR-0013 + lambdas pre-launch epic Wave A (ticket
+    [`SlluxMBN`'s sibling `4NrRPCgh`](https://trello.com/c/4NrRPCgh)).
+  default: false
+  input_model: multi
+  min_inputs: 2
+  max_inputs: 2
+
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    overlay:
+      min: 1
+      max: 1
+
+  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. Mirrors the same-named feature on
+        `image_watermark`.
+
+  mime_groups:
+    video:
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        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:                            # baseline = Pro
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
+      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 vocabulary
+            as `image_watermark.image` and `text_watermark.image`.
+
+        margin_x:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Horizontal offset from the anchor as pixels (e.g. "40px")
+            or percentage of video frame width (e.g. "5%"). Direction
+            is anchor-relative — positive moves toward the frame
+            centre.
+
+            **`anchor: center` exception.** When the anchor is `center`
+            the centre is the centre — there is no anchor-relative
+            direction. Non-zero `margin_x` combined with
+            `anchor: center` is rejected by the API at workflow-create
+            time as `invalid_options` (HTTP 422). Same rule as the
+            other watermark operations.
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor as pixels or percentage of
+            video frame height. Anchor-relative; positive moves toward
+            the frame centre.
+
+            **`anchor: center` exception.** Same rejection rule as
+            `margin_x`.
+
+        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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -28,14 +28,18 @@
     "./availability/availability.json": "./availability/availability.json",
     "./operations/schemas/archive.yaml": "./operations/schemas/archive.yaml",
     "./operations/schemas/audio_overlay.yaml": "./operations/schemas/audio_overlay.yaml",
+    "./operations/schemas/audio_to_video.yaml": "./operations/schemas/audio_to_video.yaml",
     "./operations/schemas/audio_watermark.yaml": "./operations/schemas/audio_watermark.yaml",
     "./operations/schemas/compress.yaml": "./operations/schemas/compress.yaml",
     "./operations/schemas/convert.yaml": "./operations/schemas/convert.yaml",
     "./operations/schemas/custom_luma.yaml": "./operations/schemas/custom_luma.yaml",
     "./operations/schemas/image_watermark.yaml": "./operations/schemas/image_watermark.yaml",
     "./operations/schemas/merge.yaml": "./operations/schemas/merge.yaml",
+    "./operations/schemas/split.yaml": "./operations/schemas/split.yaml",
     "./operations/schemas/text_watermark.yaml": "./operations/schemas/text_watermark.yaml",
-    "./operations/schemas/thumbnail.yaml": "./operations/schemas/thumbnail.yaml"
+    "./operations/schemas/thumbnail.yaml": "./operations/schemas/thumbnail.yaml",
+    "./operations/schemas/video_text_watermark.yaml": "./operations/schemas/video_text_watermark.yaml",
+    "./operations/schemas/video_watermark.yaml": "./operations/schemas/video_watermark.yaml"
   },
   "files": [
     "dist/",
@@ -45,7 +49,8 @@
     "availability/availability.json"
   ],
   "scripts": {
-    "build": "tsc",
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build": "npm run clean && tsc",
     "prepack": "npm run build"
   },
   "devDependencies": {