@giveitsmaller/contracts 0.3.0 → 0.5.0

package/operations/schemas/split.yaml

@@ -0,0 +1,309 @@
+schema_version: "2.0.0"
+
+operation:
+  type: split
+  availability: planned
+  description: |
+    Fan one input file into N outputs across GIF, PDF, audio, and
+    video MIME families. Single-input — one input file per job, fanned
+    into N outputs per the per-mime-group catalog. Mirrors the
+    `merge` / `convert` catalog-split-by-mime-group pattern.
+
+    **Three modes** (audio + video; the mode discriminator gates which
+    of the three options applies per the `depends_on` rules in this
+    schema):
+    - `interval`: split every N numeric-seconds.
+    - `count`: split into N equal-duration pieces (integer 2..=200).
+    - `cut_points`: explicit cut points in numeric-seconds (strictly
+      increasing, no duplicates, each > 0 and < probed duration).
+
+    **GIF + PDF use range-based selection** instead of three modes:
+    - GIF (`image_gif`): `frame_range` REQUIRED + `output_format`
+      enum {png,webp,jpg}.
+    - PDF (`document_pdf`): `page_range` OR `page_groups` (mutually
+      exclusive per `depends_on`).
+
+    **Wire format**: numeric seconds (floats allowed for sub-second
+    precision). NOT ISO 8601 duration strings. Matches FFmpeg /
+    Cloudinary / Shotstack / AWS MediaConvert conventions.
+
+    **200-output hard cap** per ADR-0009 §D5
+    (`OperationResult.outputs[].maxItems: 200`). Preflight rejects
+    requests exceeding this BEFORE work as `invalid_options` (422).
+    Cap math by mode:
+    - `interval`: `ceil(probed_duration / interval) <= 200`
+    - `count`: enforced by the option's `min: 2 max: 200` range
+    - `cut_points`: `cut_points.len() + 1 <= 200`
+    - PDF: resolved page count after expansion `<= 200`
+      (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))
+    - GIF: resolved frame count after expansion `<= 200`
+
+    **Output naming**: 3-digit zero-padded — `output-001` ..
+    `output-200`. Matches the convert PDF→N precedent.
+
+    **Output envelope binding** (per ADR-0014 + ADR-0009 §D2):
+    - `image_gif`: `PositionIndexed` (frame stream-position 0-based
+      ordinal)
+    - `document_pdf`: `PageIndexed` (1-based gapless page index)
+    - `audio`: `PositionIndexed` (cut stream-position ordinal)
+    - `video`: `PositionIndexed` (cut stream-position ordinal)
+
+    **`precision` flag** (audio + video only): `fast` (default) =
+    packet-boundary approximate cuts; `exact` = re-encode-aligned
+    precise cuts. Mime_group scoping is the gate — precision does
+    NOT apply to GIF or PDF (frame extraction is exact and PDF page
+    selection is exact by definition).
+
+    **Long-form video** routes to a separate `split-video-fargate`
+    Lambda (same `split` OperationType, different worker; routing
+    via `processing_class`). No schema-side discriminator beyond MIME
+    detection + `processing_class`.
+
+    `availability: planned` until the cross-repo Lambda support ships
+    ([`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + lambdas L1).
+    Dispatch returns `feature_not_available` (422) until then.
+
+    Per ADR-0014.
+  default: false
+  input_model: single
+
+  features:
+    silence_mode_audio:
+      availability: planned
+      description: |
+        Silence-detect cut mode for audio (`mode: silence` —
+        Cinavia/Resemble territory, server-side silence detection).
+        OUT of V1 (Lambda support not yet shipped); declared as a
+        future-work feature here so SDK consumers see the gate.
+        Picked up as a separate post-launch ticket.
+
+  mime_groups:
+    # Animated GIF base — parallel mime_group naming follows the
+    # `image_gif` precedent established by `image_watermark.image_gif`.
+    image_gif:
+      mimes:
+        - image/gif
+      options:
+        frame_range:
+          type: string
+          required: true
+          pattern: '^\d+-\d+$'
+          description: |
+            Frame range as `start-end` integer pair (e.g. "1-100").
+            REQUIRED in V1 — no silent default. Without explicit
+            range, a 30-second GIF at 24 fps = 720 frames would blow
+            the 200-output cap on every input. Both start and end are
+            1-based, inclusive. Resolved frame count MUST be <= 200
+            (`invalid_options` 422 if exceeded).
+
+        output_format:
+          type: enum
+          values: [png, webp, jpg]
+          default: png
+          description: |
+            Output image format for each extracted frame. Aspect ratio
+            and dimensions preserved from the source GIF.
+
+    # PDF base — page-split via qpdf or pdftk equivalent.
+    document_pdf:
+      mimes:
+        - application/pdf
+      options:
+        mode:
+          type: enum
+          values: [page_range, page_groups]
+          default: page_range
+          description: |
+            PDF split strategy:
+            - `page_range`: select pages via a range expression.
+            - `page_groups`: group N pages per output.
+
+        page_range:
+          type: string
+          pattern: '^\d+(-\d+)?(,\d+(-\d+)?)*$'
+          required: true
+          depends_on: { mode: page_range }
+          description: |
+            Page-range expression (e.g. "1-5", "1,3,5-7", "10-20").
+            1-based inclusive. Required when `mode: page_range`.
+            Resolved page count MUST be <= 200 (`invalid_options`
+            422 if exceeded — cross-ref
+            [`WgCqnMRa`](https://trello.com/c/WgCqnMRa)).
+
+        page_groups:
+          type: integer
+          min: 2
+          max: 200
+          required: true
+          depends_on: { mode: page_groups }
+          description: |
+            Group N pages per output (e.g. `page_groups: 5` on a
+            50-page PDF produces 10 outputs of 5 pages each).
+            Required when `mode: page_groups`. The page-count cap
+            applies to the resolved group count: `ceil(total_pages /
+            page_groups) <= 200`.
+
+    # Audio base — three modes + precision flag.
+    audio:
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/ogg
+        - audio/flac
+        - audio/wav
+        - audio/mp4
+      options:
+        mode:
+          type: enum
+          values: [interval, count, cut_points]
+          default: interval
+          description: |
+            Split strategy:
+            - `interval`: cut every `interval` seconds.
+            - `count`: cut into `count` equal-duration pieces.
+            - `cut_points`: cut at explicit timestamps.
+
+        interval:
+          type: float
+          min: 0.001
+          required: true
+          depends_on: { mode: interval }
+          description: |
+            Cut interval in numeric seconds (float, sub-second
+            allowed). `ceil(probed_duration / interval) <= 200`
+            preflight rule applies. Only valid when `mode: interval`.
+
+        count:
+          type: integer
+          min: 2
+          max: 200
+          required: true
+          depends_on: { mode: count }
+          description: |
+            Number of equal-duration output pieces. Range 2..=200
+            enforced declaratively (1 = no-op, rejected;
+            cap = 200-output ceiling). Only valid when `mode: count`.
+
+        cut_points:
+          type: array
+          items:
+            type: number
+            exclusiveMinimum: 0
+          minItems: 1
+          maxItems: 199
+          uniqueItems: true
+          required: true
+          depends_on: { mode: cut_points }
+          description: |
+            Cut points in numeric seconds (float, sub-second allowed).
+            Array entries; NOT a comma-separated string. MUST be
+            strictly increasing (preflight-validated against probe);
+            each entry > 0 and < probed duration. `uniqueItems: true`
+            catches accidental duplicates at the OpenAPI layer; strict
+            monotonicity and the < probed-duration bound are
+            preflight-checked at workflow-create. Output count =
+            `cut_points.length + 1`; `maxItems: 199` expresses the
+            200-output cap declaratively. Only valid when
+            `mode: cut_points`.
+
+        precision:
+          type: enum
+          values: [fast, exact]
+          default: fast
+          description: |
+            Cut precision. Under `fast`, audio cuts are
+            packet-boundary approximate (drift bounded by codec
+            packet size — typically <= 23ms for AAC, <= 26ms for
+            MP3). Under `exact`, the Lambda re-encodes to align cuts
+            precisely at the requested timestamps (slower, larger
+            output, but sample-accurate). Avoid "keyframe" language
+            — that's video-only; audio drift is packet-boundary.
+
+    # Video base — same three modes + precision + processing_class.
+    # Long-form routes to `split-video-fargate` (same OperationType,
+    # different worker per `processing_class`).
+    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:
+          # Routes to split-video-fargate worker per ADR-0014.
+          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
+              max_output_size_bytes: 120000000000
+      options:
+        mode:
+          type: enum
+          values: [interval, count, cut_points]
+          default: interval
+          description: |
+            Split strategy:
+            - `interval`: cut every `interval` seconds.
+            - `count`: cut into `count` equal-duration pieces.
+            - `cut_points`: cut at explicit timestamps.
+
+        interval:
+          type: float
+          min: 0.001
+          required: true
+          depends_on: { mode: interval }
+          description: |
+            Cut interval in numeric seconds. `ceil(probed_duration /
+            interval) <= 200`. Only valid when `mode: interval`.
+
+        count:
+          type: integer
+          min: 2
+          max: 200
+          required: true
+          depends_on: { mode: count }
+          description: |
+            Number of equal-duration output pieces. Range 2..=200.
+            Only valid when `mode: count`.
+
+        cut_points:
+          type: array
+          items:
+            type: number
+            exclusiveMinimum: 0
+          minItems: 1
+          maxItems: 199
+          uniqueItems: true
+          required: true
+          depends_on: { mode: cut_points }
+          description: |
+            Cut points in numeric seconds (float, sub-second allowed).
+            Array entries; NOT a comma-separated string. Strictly
+            increasing (preflight-validated against probe); each entry
+            > 0 and < probed duration. `uniqueItems: true` catches
+            accidental duplicates at the OpenAPI layer; strict
+            monotonicity and the < probed-duration bound are
+            preflight-checked at workflow-create. Output count =
+            `cut_points.length + 1`; `maxItems: 199` expresses the
+            200-output cap declaratively. Only valid when
+            `mode: cut_points`.
+
+        precision:
+          type: enum
+          values: [fast, exact]
+          default: fast
+          description: |
+            Cut precision. Under `fast`, video cuts are keyframe-
+            aligned (drift bounded by GOP size — typically up to 1-2
+            seconds depending on encoder). Under `exact`, the Lambda
+            re-encodes to align cuts precisely at the requested
+            timestamps (slower, larger output, but frame-accurate).

package/operations/schemas/thumbnail.yaml

@@ -56,11 +56,18 @@ operation:
             max_input_duration: "PT5M"
             max_input_size_bytes: 524288000
         long_form:
+          # Stays planned (CON-1 flips only compress.video.long_form +
+          # merge.video.long_form_re_encode). Per-tier caps per ADR-0011 —
+          # advertised shape; availability gates execution off (422).
+          # No max_output_size_bytes: thumbnail output is a single bounded image.
           availability: planned
           required_tier: pro
-          constraints:
+          constraints:                            # baseline = Pro
             max_input_duration: "PT12H"
-            max_input_size_bytes: 21474836480
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+          per_tier_constraints:
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
       options:
         timestamp:
           type: string
@@ -110,7 +117,13 @@ operation:
           min: 1
           default: 1
           depends_on: { source: page }
-          description: "Page/sheet/slide number to render"
+          description: >-
+            1-based index of the printed page to render, after print-layout
+            pagination is applied. For office formats this is the page in the
+            LibreOffice PDF export — NOT a 1:1 sheet/slide index: a spreadsheet
+            sheet may span multiple printed pages and multi-sheet workbooks
+            paginate their sheets in order. For PDF inputs it is the PDF page
+            number directly.
         width:
           type: integer
           min: 1

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.3.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": {