@giveitsmaller/contracts 0.4.0 → 0.5.0

package/operations/schemas/audio_to_video.yaml

@@ -0,0 +1,122 @@
+schema_version: "2.0.0"
+
+operation:
+  type: audio_to_video
+  availability: planned
+  description: |
+    Produce a video from an audio input plus an OPTIONAL still image
+    overlay. Use cases: podcast → YouTube uploads, audio-only tracks
+    that need a video container for platforms requiring it, branded
+    audio releases with a static cover image.
+
+    **Role asymmetry.** First role-based operation on the contract
+    with an OPTIONAL role — REQUIRED `base` (audio source) +
+    OPTIONAL `overlay` (still image, 0..1). When `overlay` is
+    omitted, the video uses a solid `background_color`. The
+    machine-readable cardinality lives in `per_role_cardinality`
+    on this schema (per ADR-0015). API consumption site:
+    `OperationInputRoleValidator` (rule table) consumed by
+    `SchemaValidationService.php` in `compression_api`.
+
+    **Input vs output asymmetry.** The single `mime_groups.audio`
+    block keys the INPUT MIME family (the `base` role input is
+    audio). The OUTPUT is always video — `output_format` controls
+    the container; `mime_groups` is NOT the output type. Mirrors
+    the `audio_overlay.video` group pattern (input-keyed).
+
+    Re-encode required (audio → video composition always re-encodes).
+    Lower framerate + FFmpeg `-tune stillimage` keeps file size
+    tiny when the overlay is a still image (the common case).
+
+    Per ticket [`SlluxMBN`](https://trello.com/c/SlluxMBN) +
+    ADR-0015. `availability: planned` until the cross-repo Lambda
+    support ships; the API rejects workflow-create with
+    `feature_not_available` (422) until then.
+
+  default: false
+  input_model: multi
+  min_inputs: 1
+  max_inputs: 2
+
+  # Per-role input-count constraints — first role-based op with
+  # an OPTIONAL role. See ADR-0015 for the vocab primitive.
+  # Arithmetic-consistency rule (CI-checked):
+  # - sum(role.min) == min_inputs  (1 + 0 = 1)
+  # - sum(role.max) == max_inputs  (1 + 1 = 2)
+  per_role_cardinality:
+    base:
+      min: 1
+      max: 1
+    overlay:
+      min: 0
+      max: 1
+
+  mime_groups:
+    audio:
+      # INPUT MIME family for the `base` role. Output is video via
+      # `output_format` — NOT determined by this mime_group key.
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/wav
+        - audio/x-wav
+        - audio/flac
+        - audio/ogg
+        - audio/opus
+        - audio/x-m4a
+      options:
+        output_resolution:
+          type: enum
+          values: [hd_720p, fhd_1080p, sd_480p]
+          default: hd_720p
+          description: |
+            Output video resolution. `hd_720p` = 1280×720 (default),
+            `fhd_1080p` = 1920×1080, `sd_480p` = 854×480. Choose
+            lower for small file size; higher when the overlay image
+            quality warrants it.
+        background_color:
+          type: string
+          default: "#000000"
+          description: |
+            Hex `#RRGGBB` solid background colour. Used only when
+            `overlay` is omitted (no image input). When an `overlay`
+            image is provided, the background colour is invisible
+            behind the image (subject to `image_fit`).
+        image_fit:
+          type: enum
+          values: [contain, cover, stretch]
+          default: contain
+          description: |
+            How to fit the overlay image into the output frame.
+            `contain` = letterbox (preserve aspect ratio, may show
+            background); `cover` = crop (fill the frame, may crop
+            the image); `stretch` = distort to fit (preserves no
+            aspect ratio). Default `contain` preserves the image
+            aesthetic.
+        framerate:
+          type: integer
+          min: 1
+          max: 60
+          default: 2
+          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
+            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).
+        output_format:
+          type: enum
+          values: [mp4]
+          default: mp4
+          description: |
+            Output container format. V1 supports `mp4` only. Future
+            additions (webm, mov) await Lambda follow-up.
+
+  # NOTE: role-MIME constraint (base MUST be audio, overlay MUST be
+  # image) is documented in prose only for V1. ADR-0015 records this
+  # as future-work — a `per_role_mime_compat` vocab primitive can be
+  # added when a second role-based op needs the asymmetry (today
+  # only audio_to_video has it). The API edge validator enforces
+  # the role→MIME constraint at workflow-create time per the prose
+  # contract.

package/operations/schemas/image_watermark.yaml

@@ -10,11 +10,15 @@ operation:
     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.
+    image/webp); animated GIF bases are advertised as `planned` via
+    the parallel `image_gif` mime_group — schema is contract-defined,
+    dispatch returns `feature_not_available` (422) until Lambda
+    support ships. Per Tension 1 (ADR-0001) + plan v5 §F4 round 6.
+
+    **Video bases are NOT supported by `image_watermark`.** Use the
+    dedicated `video_watermark` operation
+    (`schemas/operations/video_watermark.yaml`) which routes through
+    FFmpeg overlay + re-encode. Per ADR-0013.
 
     **Audio is explicitly NOT supported.** For audio overlay (DJ tags,
     podcast intros, jingles), use the `audio_overlay` operation
@@ -22,7 +26,7 @@ operation:
     `availability: planned`).
 
     Source capped at 25 megapixels for image bases (V1 watermark
-    precedent retained); per-frame caps for GIF / video bases will be
+    precedent retained); per-frame caps for animated GIF bases will be
     defined when the corresponding Lambda support ships.
     Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
   default: false
@@ -188,100 +192,8 @@ operation:
             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:
-          # 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).
-          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 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.
+    # Video base mime_group REMOVED per ADR-0013 — video watermarking
+    # is now owned by the dedicated `video_watermark` operation
+    # (`schemas/operations/video_watermark.yaml`). The previous
+    # `availability: planned` advertising had no consumers; the
+    # dedicated operation is the canonical landing site.

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

@@ -117,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