@giveitsmaller/contracts 0.2.0 → 0.3.0

package/operations/schemas/merge.yaml

@@ -0,0 +1,440 @@
+schema_version: "2.1.0"
+
+operation:
+  type: merge
+  description: "Combine multiple files into one"
+  default: false
+  input_model: multi
+  min_inputs: 2
+  max_inputs: 10
+  # All merge operations route to the single `ops-merge` Lambda via
+  # `operation_type=merge` on the `operations` SNS topic. The
+  # `output_type` field below is read by the merge Lambda to decide
+  # the internal encoding path (animated GIF, video slideshow/concat,
+  # audio concat), not to influence SNS routing. The V1 Lambda does
+  # NOT support image collage/grid or PDF concatenation — those
+  # `output_type` values are absent from the allowlist. The API
+  # publisher additionally sets `media_group` as an informational SNS
+  # attribute on non-archive operations, but it is not used as a
+  # routing filter.
+
+  mime_groups:
+    image:
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/webp
+        - image/gif
+        - image/tiff
+        - image/bmp
+      options:
+        output_type:
+          type: enum
+          values: [gif, video]
+          required: true
+          description: "Result format: animated GIF or slideshow video. No default — caller must pick explicitly (image/collage and document/PDF concat are not supported by the V1 merge Lambda)."
+        # --- Options for output_type: gif ---
+        delay:
+          type: integer
+          min: 10
+          max: 5000
+          default: 500
+          depends_on: { output_type: gif }
+          description: "Milliseconds between frames"
+        loop_count:
+          type: integer
+          min: 0
+          max: 100
+          default: 0
+          depends_on: { output_type: gif }
+          description: "Number of loops (0 = infinite)"
+        # --- Options for output_type: video ---
+        duration_per_image:
+          type: float
+          min: 0.5
+          max: 30.0
+          default: 3.0
+          depends_on: { output_type: video }
+          description: "Seconds each image is displayed"
+        transition:
+          type: enum
+          # Catalog from FFmpeg 7.1.1 xfade filter (per ADR-0007). The
+          # `none` value is a sentinel meaning "no transition / hard
+          # cut" — Lambda short-circuits the xfade filter chain rather
+          # than passing it through. All other values map directly to
+          # FFmpeg `xfade` filter `transition=` parameter.
+          values: [none, fade, fadeblack, fadewhite, dissolve,
+                   wipeleft, wiperight, wipeup, wipedown, crossfade,
+                   smoothleft, smoothright, smoothup, smoothdown,
+                   circleopen, circleclose, circlecrop, rectcrop,
+                   slideleft, slideright, slideup, slidedown,
+                   radial, diagtl, diagtr, diagbl,
+                   pixelize, hlslice, vlslice, hblur, distance, squeezeh,
+                   custom, wipetl, wipetr, wipebl]
+          default: none
+          depends_on: { output_type: video }
+          description: |
+            Transition effect between images in the slideshow output.
+            Catalog from FFmpeg 7.1.1 xfade filter (per ADR-0007). See
+            per_value_availability for per-value rollout state. The
+            `none` value is a sentinel ("no transition / hard cut"),
+            not an FFmpeg preset.
+          per_value_availability:
+            # Untagged values default to stable per ADR-0001 §1.4.
+            smoothleft:   { availability: beta }
+            smoothright:  { availability: beta }
+            smoothup:     { availability: beta }
+            smoothdown:   { availability: beta }
+            circleopen:   { availability: beta }
+            circleclose:  { availability: beta }
+            circlecrop:   { availability: beta }
+            rectcrop:     { availability: beta }
+            slideleft:    { availability: beta }
+            slideright:   { availability: beta }
+            slideup:      { availability: beta }
+            slidedown:    { availability: beta }
+            radial:       { availability: beta }
+            diagtl:       { availability: beta }
+            diagtr:       { availability: beta }
+            diagbl:       { availability: beta }
+            pixelize:     { availability: experimental }
+            hlslice:      { availability: experimental }
+            vlslice:      { availability: experimental }
+            hblur:        { availability: experimental }
+            distance:     { availability: experimental }
+            squeezeh:     { availability: experimental }
+            # `custom` is `planned` indefinitely as an advisory — for
+            # caller-uploaded luma-matte transitions, use the dedicated
+            # `custom_luma` operation (multi-input with role: base +
+            # transition_mask) per ticket I29 (EPUE5Vs1). FFmpeg's
+            # xfade=custom is an expression-mode parameter, not the
+            # shape callers want; the dedicated operation is the
+            # supported path.
+            custom:       { availability: planned, documentation_url: "https://trello.com/c/EPUE5Vs1" }
+            wipetl:       { availability: planned, eta: "2026-Q3" }
+            wipetr:       { availability: planned, eta: "2026-Q3" }
+            wipebl:       { availability: planned, eta: "2026-Q3" }
+        transition_duration:
+          type: float
+          min: 0.1
+          max: 5.0
+          default: 0.5
+          depends_on: { output_type: video }
+          description: "Duration of transition effect in seconds"
+        fps:
+          type: integer
+          min: 1
+          max: 60
+          default: 30
+          depends_on: { output_type: video }
+          description: "Output frame rate"
+        video_format:
+          type: enum
+          values: [mp4, webm]
+          default: mp4
+          depends_on: { output_type: video }
+          description: "Output video container format"
+
+    video:
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form video tier (per ticket I15-CONS). Merge uses
+        # alias class names because its differentiator is concat-
+        # compatibility (I16-CONS re_encode_mode) rather than just
+        # size/duration — a small merge can still need long_form
+        # when inputs require re-encoding.
+        short_form_concat:
+          availability: stable
+          constraints:
+            max_total_duration: "PT5M"
+            max_total_input_size_bytes: 1073741824   # 1 GiB combined
+        long_form_re_encode:
+          availability: planned
+          required_tier: pro
+          constraints:
+            max_total_duration: "PT12H"
+            max_total_input_size_bytes: 21474836480
+      options:
+        output_type:
+          type: enum
+          values: [video]
+          required: false
+          description: "Output format for video merge (concatenation). Currently fixed at 'video'. Optional — API injects this default post-validation so callers may omit it."
+        transition:
+          type: enum
+          # Same catalog + per_value_availability as merge.image.transition.
+          # Catalog from FFmpeg 7.1.1 xfade filter (per ADR-0007). The
+          # `none` value is a sentinel ("no transition / hard cut").
+          values: [none, fade, fadeblack, fadewhite, dissolve,
+                   wipeleft, wiperight, wipeup, wipedown, crossfade,
+                   smoothleft, smoothright, smoothup, smoothdown,
+                   circleopen, circleclose, circlecrop, rectcrop,
+                   slideleft, slideright, slideup, slidedown,
+                   radial, diagtl, diagtr, diagbl,
+                   pixelize, hlslice, vlslice, hblur, distance, squeezeh,
+                   custom, wipetl, wipetr, wipebl]
+          default: none
+          description: |
+            Default transition between clips. Catalog from FFmpeg 7.1.1
+            xfade filter (per ADR-0007). See per_value_availability for
+            per-value rollout state.
+          per_value_availability:
+            smoothleft:   { availability: beta }
+            smoothright:  { availability: beta }
+            smoothup:     { availability: beta }
+            smoothdown:   { availability: beta }
+            circleopen:   { availability: beta }
+            circleclose:  { availability: beta }
+            circlecrop:   { availability: beta }
+            rectcrop:     { availability: beta }
+            slideleft:    { availability: beta }
+            slideright:   { availability: beta }
+            slideup:      { availability: beta }
+            slidedown:    { availability: beta }
+            radial:       { availability: beta }
+            diagtl:       { availability: beta }
+            diagtr:       { availability: beta }
+            diagbl:       { availability: beta }
+            pixelize:     { availability: experimental }
+            hlslice:      { availability: experimental }
+            vlslice:      { availability: experimental }
+            hblur:        { availability: experimental }
+            distance:     { availability: experimental }
+            squeezeh:     { availability: experimental }
+            # `custom` is `planned` indefinitely as an advisory — for
+            # caller-uploaded luma-matte transitions, use the dedicated
+            # `custom_luma` operation (multi-input with role: base +
+            # transition_mask) per ticket I29 (EPUE5Vs1). FFmpeg's
+            # xfade=custom is an expression-mode parameter, not the
+            # shape callers want; the dedicated operation is the
+            # supported path.
+            custom:       { availability: planned, documentation_url: "https://trello.com/c/EPUE5Vs1" }
+            wipetl:       { availability: planned, eta: "2026-Q3" }
+            wipetr:       { availability: planned, eta: "2026-Q3" }
+            wipebl:       { availability: planned, eta: "2026-Q3" }
+        crossfade_duration:
+          type: float
+          min: 0.1
+          max: 5.0
+          default: 1.0
+          depends_on: { transition: crossfade }
+          description: "Crossfade duration in seconds"
+        normalize_audio:
+          type: boolean
+          default: true
+          description: "Normalize audio levels across all clips"
+
+        re_encode_mode:
+          type: enum
+          values: [auto, always, never]
+          default: auto
+          description: |
+            Re-encode policy for video concat.
+            - `auto`: probe inputs and choose stream-copy concat (when
+              codec/container/timebase/framerate/resolution/pixel-format
+              match) or full re-encode.
+            - `always`: force re-encode (use when caller wants
+              normalised output options).
+            - `never`: return 422 `REQUIRES_REENCODE` if inputs are not
+              concat-compatible.
+            Compatibility algorithm is server-side and deliberately
+            opaque (per plan v5 §F8.2). The actual path taken is
+            reported on `OperationMetrics.re_encode_decision`.
+
+        codec:
+          type: enum
+          values: [h264, h265, vp9, av1]
+          default: h264
+          depends_on: { re_encode_mode: [auto, always] }
+          description: |
+            Output codec when merge re-encodes. Inert when stream-copy
+            concat is selected (re_encode_mode=auto + compatible inputs).
+          per_value_availability:
+            # AV1 encoder presence in mwader/static-ffmpeg:7.1.1 needs
+            # anti-drift confirmation per ADR-0006; tagged beta until
+            # I32 strict mode confirms.
+            av1: { availability: beta }
+
+        crf:
+          type: integer
+          min: 0
+          max: 51
+          default: 23
+          depends_on: { re_encode_mode: [auto, always], encoding_mode: crf }
+          description: "Constant Rate Factor when encoding_mode=crf. Lower = higher quality / larger file."
+
+        preset:
+          type: enum
+          values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
+          default: medium
+          depends_on: { re_encode_mode: [auto, always] }
+          description: "Encoder speed/compression trade-off when re-encoding."
+
+        target_resolution:
+          type: string
+          pattern: '^\d+x\d+$'
+          depends_on: { re_encode_mode: [auto, always] }
+          description: "Output dimensions WxH (e.g. \"1920x1080\"). Omit to inherit from inputs."
+
+        encoding_mode:
+          type: enum
+          values: [crf, target_size]
+          default: crf
+          depends_on: { re_encode_mode: [auto, always] }
+          description: |
+            CRF (quality-targeted) vs target_size (two-pass to fixed file size).
+            `target_size` is currently `codec=h264` only — libx265 / libvpx-vp9 / libsvtav1 each
+            require a different two-pass invocation and are tracked as separate per-codec
+            Lambda follow-ups. The contract narrows `target_size_bytes.depends_on` with
+            `codec: [h264]`, which rejects `encoding_mode=target_size + codec ∈ {h265, vp9, av1}`
+            as `invalid_options` **when `target_size_bytes` is present in the request**. Fully
+            gating `encoding_mode=target_size` itself on codec (so that omitting
+            `target_size_bytes` is also rejected) awaits a `per_value_depends_on` schema
+            vocab extension (ticket bsV3FWM5); Lambda continues to catch the residual
+            `target_size + non-h264 + no target_size_bytes` case in the meantime.
+
+        target_size_bytes:
+          type: integer
+          min: 1048576
+          depends_on: { re_encode_mode: [auto, always], encoding_mode: target_size, codec: [h264] }
+          description: |
+            Two-pass target file size in bytes (minimum 1 MiB). Required when
+            `encoding_mode=target_size`. h264-only today; see `encoding_mode` description
+            for per-codec rollout status.
+
+            Practical floor: a ~100 kbps post-AAC video bitrate (i.e. `target_size_bytes`
+            corresponding to less than ~100 kbps of video after subtracting the 160 kbps
+            AAC audio track over the merged duration) is silently floored by libx264 and
+            the resulting file will not honour the requested `target_size_bytes`.
+            Publishers targeting very small outputs should size accordingly.
+
+      per_input_options:
+        transition:
+          type: enum
+          # Same catalog as global transition; mirrors per_value_availability.
+          values: [none, fade, fadeblack, fadewhite, dissolve,
+                   wipeleft, wiperight, wipeup, wipedown, crossfade,
+                   smoothleft, smoothright, smoothup, smoothdown,
+                   circleopen, circleclose, circlecrop, rectcrop,
+                   slideleft, slideright, slideup, slidedown,
+                   radial, diagtl, diagtr, diagbl,
+                   pixelize, hlslice, vlslice, hblur, distance, squeezeh,
+                   custom, wipetl, wipetr, wipebl]
+          description: "Override transition for the join point preceding this input."
+          per_value_availability:
+            smoothleft:   { availability: beta }
+            smoothright:  { availability: beta }
+            smoothup:     { availability: beta }
+            smoothdown:   { availability: beta }
+            circleopen:   { availability: beta }
+            circleclose:  { availability: beta }
+            circlecrop:   { availability: beta }
+            rectcrop:     { availability: beta }
+            slideleft:    { availability: beta }
+            slideright:   { availability: beta }
+            slideup:      { availability: beta }
+            slidedown:    { availability: beta }
+            radial:       { availability: beta }
+            diagtl:       { availability: beta }
+            diagtr:       { availability: beta }
+            diagbl:       { availability: beta }
+            pixelize:     { availability: experimental }
+            hlslice:      { availability: experimental }
+            vlslice:      { availability: experimental }
+            hblur:        { availability: experimental }
+            distance:     { availability: experimental }
+            squeezeh:     { availability: experimental }
+            # `custom` is `planned` indefinitely as an advisory — for
+            # caller-uploaded luma-matte transitions, use the dedicated
+            # `custom_luma` operation (multi-input with role: base +
+            # transition_mask) per ticket I29 (EPUE5Vs1). FFmpeg's
+            # xfade=custom is an expression-mode parameter, not the
+            # shape callers want; the dedicated operation is the
+            # supported path.
+            custom:       { availability: planned, documentation_url: "https://trello.com/c/EPUE5Vs1" }
+            wipetl:       { availability: planned, eta: "2026-Q3" }
+            wipetr:       { availability: planned, eta: "2026-Q3" }
+            wipebl:       { availability: planned, eta: "2026-Q3" }
+        crossfade_duration:
+          type: float
+          min: 0.1
+          max: 5.0
+          depends_on: { transition: crossfade }
+          description: "Override crossfade duration for this join point"
+
+    audio:
+      # Audio transition catalog is intentionally separate from the
+      # visual xfade catalog used by merge.image / merge.video — audio
+      # uses FFmpeg's `acrossfade` filter, which is fundamentally
+      # different from `xfade` (visual). The two catalogs share no
+      # values and SDK codegen treats them as distinct enum types.
+      # See FORMAT.md §"Audio vs visual transition catalogs (merge)"
+      # for the convention and the rules for adding values to either
+      # catalog. Per ticket I18 (Trello FVuNcRJa) — visual-vs-audio
+      # enum split codification.
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/wav
+        - audio/ogg
+        - audio/flac
+      options:
+        output_type:
+          type: enum
+          values: [audio]
+          required: false
+          description: "Output format for audio merge (concatenation). Currently fixed at 'audio'. Optional — API injects this default post-validation so callers may omit it."
+        transition:
+          type: enum
+          # audio_transition catalog (per ticket I18, FORMAT.md §"Audio
+          # vs visual transition catalogs"). Backed by FFmpeg's
+          # `acrossfade` filter; values share no ground with the visual
+          # xfade catalog on merge.image / merge.video.
+          values: [none, crossfade]
+          default: none
+          description: |
+            Default transition between clips. Audio-only catalog
+            (acrossfade-backed); see FORMAT.md §"Audio vs visual
+            transition catalogs (merge)" for additions policy. Future
+            values (e.g. `fade_curve` variants) will be added with
+            `per_value_availability` per ADR-0001 §1.4.
+        crossfade_duration:
+          type: float
+          min: 0
+          max: 10.0
+          default: 0
+          depends_on: { transition: crossfade }
+          description: "Crossfade duration in seconds"
+        gap_duration:
+          type: float
+          min: 0
+          max: 10.0
+          default: 0
+          description: "Silence duration between clips in seconds"
+        normalize_audio:
+          type: boolean
+          default: true
+          description: "Normalize audio levels across all clips"
+      per_input_options:
+        transition:
+          type: enum
+          # Mirrors merge.audio.options.transition; same audio_transition
+          # catalog. Per ticket I18.
+          values: [none, crossfade]
+          description: |
+            Override transition for the join point preceding this
+            input. Audio-only catalog (acrossfade-backed); see
+            FORMAT.md §"Audio vs visual transition catalogs (merge)".
+        crossfade_duration:
+          type: float
+          min: 0
+          max: 10.0
+          depends_on: { transition: crossfade }
+          description: "Override crossfade duration for this join point"
+        gap_duration:
+          type: float
+          min: 0
+          max: 10.0
+          description: "Override gap duration for this join point"

package/operations/schemas/text_watermark.yaml

@@ -0,0 +1,147 @@
+schema_version: "2.0.0"
+
+operation:
+  type: text_watermark
+  description: |
+    Render a text overlay onto an image using bundled Liberation Sans
+    (SIL OFL). Single-input — text comes from options, not from a file
+    input. Source capped at 25 megapixels (V1 watermark precedent
+    retained). Per ADR-0004 §"V2 JobDefinition" + plan v5 §F1.
+
+    Two rendering modes:
+    - `single`: one label rendered at the anchor + margin position.
+    - `tiled`: text tiled across the source image (Cinavia / Adobe Stock
+      pattern); rotation default -45° and tile_spacing controls density.
+  default: false
+  input_model: single
+
+  mime_groups:
+    image:
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/webp
+      options:
+        text:
+          type: string
+          required: true
+          description: |
+            Watermark text. Must be non-empty. Rendered with bundled
+            Liberation Sans (SIL OFL). A single text overlay is capped
+            at 4 megapixels before rendering fails.
+
+        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.
+
+        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. Tiled canvas is
+            capped at 25 megapixels pre-rotation with 5000 px maximum
+            side length.
+
+        watermark_mode:
+          type: enum
+          values: [single, tiled]
+          default: single
+          description: |
+            Rendering mode:
+            - `single`: one label placed at the anchor + margin offset.
+            - `tiled`: repeated tiles across the entire source image 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.
+            For watermark_mode: tiled, anchor is ignored (tiles fill the
+            source 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 base width (e.g. "5%"). Direction is
+            anchor-relative. Ignored when watermark_mode: tiled.
+
+            **`anchor: center` exception** (watermark_mode: single only).
+            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 label, pick a peripheral anchor
+            (e.g. `top_left`) and use `margin_x` / `margin_y` to
+            position it. Not applicable to watermark_mode: tiled, where
+            anchor + margin are ignored entirely.
+
+        margin_y:
+          type: string
+          pattern: '^\d+(\.\d+)?(px|%)$'
+          default: "0px"
+          description: |
+            Vertical offset from the anchor as pixels or percentage of
+            base height. Ignored when watermark_mode: tiled.
+
+            **`anchor: center` exception** (watermark_mode: single only).
+            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: 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.