@giveitsmaller/contracts 0.2.0 → 0.3.0

package/operations/schemas/compress.yaml

@@ -0,0 +1,297 @@
+schema_version: "2.0.0"
+
+operation:
+  type: compress
+  description: "Reduce file size while maintaining acceptable quality"
+  default: true
+  input_model: single
+
+  mime_groups:
+    image:
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/gif
+        - image/webp
+        - image/svg+xml
+        - image/tiff
+        - image/bmp
+        - image/vnd.microsoft.icon
+        - image/avif
+        - image/heic
+      options:
+        mode:
+          type: enum
+          values: [lossy, lossless, auto]
+          default: lossy
+          description: "Compression algorithm. lossy = smaller file, lossless = no quality loss, auto = best for format"
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          depends_on: { mode: lossy }
+          description: "Compression quality (1 = smallest file, 100 = best quality). Only applies to lossy mode."
+        width:
+          type: integer
+          min: 1
+          max: 16384
+          description: "Maximum output width in pixels"
+        height:
+          type: integer
+          min: 1
+          max: 16384
+          description: "Maximum output height in pixels"
+        fit:
+          type: enum
+          values: [max, crop, scale]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          description: "Resize mode. max = fit within bounds, crop = fill and trim, scale = force exact dimensions. Only applies when width or height is set."
+        metadata:
+          type: enum
+          values: [all, none, copyright, sensitive]
+          default: all
+          description: >-
+            Metadata handling. all = strip everything (smallest file), none = keep all EXIF/IPTC/XMP,
+            copyright = keep only copyright/author fields, sensitive = keep EXIF but strip GPS/location (GDPR-friendly)
+        icc_profile:
+          type: enum
+          values: [preserve, strip, srgb]
+          default: preserve
+          description: "ICC color profile handling. preserve = keep original, strip = remove, srgb = convert to sRGB"
+        auto_orient:
+          type: boolean
+          default: true
+          description: "Auto-rotate based on EXIF orientation"
+        progressive:
+          type: boolean
+          default: true
+          description: "Enable progressive rendering (JPEG only). Renders low-quality preview first, then refines."
+        output_format:
+          type: enum
+          values: [original, auto, smallest, jpeg, png, webp, avif]
+          default: original
+          description: >-
+            Output format. original = keep input format, auto = best for browser support
+            (AVIF > WebP > JPEG based on Accept header hint), smallest = try all supported formats and return the smallest file
+
+    audio:
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/ogg
+        - audio/flac
+        - audio/wav
+        - audio/mp4
+      options:
+        bitrate:
+          type: enum
+          value_type: integer
+          values: [64, 96, 128, 192, 256, 320]
+          default: 128
+          description: "Output bitrate in kbps"
+        channels:
+          type: integer
+          min: 1
+          max: 2
+          description: "Number of audio channels (1 = mono, 2 = stereo)"
+        sample_rate:
+          type: enum
+          value_type: integer
+          values: [22050, 44100, 48000]
+          description: "Audio sample rate in Hz"
+        normalize:
+          type: boolean
+          default: false
+          description: "Apply loudness normalization (EBU R128 / -14 LUFS target)"
+        trim_start:
+          type: float
+          min: 0
+          description: "Trim from beginning in seconds"
+        trim_end:
+          type: float
+          min: 0
+          description: "Trim from end in seconds"
+
+    video:
+      mimes:
+        - video/mp4
+        - video/webm
+        - video/ogg
+      processing_class:
+        # F8 long-form video tier (per ticket I15-CONS, Trello YZpBKzOM).
+        # Public contract uses logical names only — backend selection is
+        # server-decided per plan v5 §F8 round 7.
+        short_form:
+          availability: stable
+          constraints:
+            max_input_duration: "PT5M"
+            max_input_size_bytes: 524288000        # 500 MiB
+            max_output_size_bytes: 524288000
+        long_form:
+          availability: planned
+          required_tier: pro
+          constraints:
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 21474836480      # 20 GiB
+            max_output_size_bytes: 21474836480
+      options:
+        codec:
+          type: enum
+          values: [h264, h265, vp9, av1]
+          default: h264
+          description: "Video codec. h264 = widest compatibility, h265/av1 = better compression but slower"
+        encoding_mode:
+          type: enum
+          values: [crf, target_size]
+          default: crf
+          description: "crf = constant quality (variable file size), target_size = constrained file size (two-pass)"
+        crf:
+          type: integer
+          min: 0
+          max: 51
+          default: 23
+          depends_on: { encoding_mode: crf }
+          description: "Constant Rate Factor (0 = lossless, 51 = worst, 23 = visually good). Only applies to CRF mode."
+        target_size_bytes:
+          type: integer
+          min: 1048576
+          depends_on: { encoding_mode: target_size }
+          description: "Target output file size in bytes (min 1MB). Two-pass encoding to meet this target."
+        preset:
+          type: enum
+          values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
+          default: medium
+          description: "Encoding speed vs compression ratio trade-off"
+        width:
+          type: integer
+          min: 1
+          max: 7680
+          description: "Output width in pixels"
+        height:
+          type: integer
+          min: 1
+          max: 4320
+          description: "Output height in pixels"
+        fit:
+          type: enum
+          values: [max, crop, scale, pad]
+          default: max
+          depends_on: { width: set, height: set, logic: or }
+          description: "Resize mode. max = fit within bounds (preserves ratio), crop/scale/pad = exact dimensions. Only applies when width or height is set."
+        fps:
+          type: float
+          min: 1
+          max: 120
+          description: "Output frame rate"
+        faststart:
+          type: boolean
+          default: true
+          description: "Move MP4 moov atom to start for progressive web playback (MP4 only)"
+        audio_codec:
+          type: enum
+          values: [aac, opus, vorbis, copy]
+          default: aac
+          description: "Audio codec. aac = widest compatibility, opus = best quality/size, copy = passthrough"
+        audio_bitrate:
+          type: enum
+          value_type: integer
+          values: [64, 96, 128, 192, 256, 320]
+          default: 128
+          description: "Audio track bitrate in kbps"
+        trim_start:
+          type: float
+          min: 0
+          description: "Trim from beginning in seconds"
+        trim_end:
+          type: float
+          min: 0
+          description: "Trim from end in seconds"
+
+    document_pdf:
+      mimes:
+        - application/pdf
+      options:
+        profile:
+          type: enum
+          values: [web, print, archive, max]
+          default: web
+          description: "Optimization profile. web = aggressive (downsample images, strip metadata), print = preserve quality, archive = PDF/A compliance, max = smallest file"
+        colorspace:
+          type: enum
+          values: [unchanged, rgb, cmyk, grayscale]
+          default: unchanged
+          description: "Output color space"
+        pages:
+          type: string
+          description: "Page selection (e.g. '1-5,8,10-12'). Omit to keep all pages."
+        flatten_forms:
+          type: boolean
+          default: false
+          description: "Flatten interactive form fields into static content"
+
+    document_office:
+      mimes:
+        - application/vnd.openxmlformats-officedocument.wordprocessingml.document
+        - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
+        - application/vnd.openxmlformats-officedocument.presentationml.presentation
+      options:
+        image_quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          description: "Recompress embedded images at this quality level (1 = smallest, 100 = best)"
+        strip_macros:
+          type: boolean
+          default: true
+          description: "Remove VBA macros and ActiveX controls"
+        strip_hidden_data:
+          type: boolean
+          default: true
+          description: "Remove revisions, comments, personal info, hidden rows/columns, and speaker notes"
+        strip_unused_fonts:
+          type: boolean
+          default: false
+          description: "Remove embedded fonts not referenced in the document. Risk: may affect rendering on systems without the font installed"
+
+    document_odf:
+      mimes:
+        - application/vnd.oasis.opendocument.text
+        - application/vnd.oasis.opendocument.spreadsheet
+        - application/vnd.oasis.opendocument.presentation
+      options:
+        image_quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          description: "Recompress embedded images at this quality level"
+        strip_metadata:
+          type: boolean
+          default: true
+          description: "Remove document metadata (author, revision history, comments)"
+        strip_unused_styles:
+          type: boolean
+          default: false
+          description: "Remove style definitions not referenced in document content"
+
+    document_epub:
+      mimes:
+        - application/epub+zip
+      options:
+        image_quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 80
+          description: "Recompress embedded images at this quality level"
+        font_subsetting:
+          type: boolean
+          default: true
+          description: "Subset embedded fonts to only include glyphs used in the document. Significant size reduction for books with large font files"
+        strip_unused_css:
+          type: boolean
+          default: false
+          description: "Remove CSS rules not referenced by any content. Risk: may affect rendering in some readers"

package/operations/schemas/convert.yaml

@@ -0,0 +1,119 @@
+schema_version: "2.0.0"
+
+operation:
+  type: convert
+  description: "Convert file to a different format"
+  default: false
+  input_model: single
+
+  mime_groups:
+    image:
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/gif
+        - image/webp
+        - image/svg+xml
+        - image/tiff
+        - image/bmp
+        - image/vnd.microsoft.icon
+        - image/avif
+        - image/heic
+      options:
+        output_format:
+          type: enum
+          values: [jpeg, png, webp, avif, gif, tiff]
+          required: true
+          description: "Target format"
+        quality:
+          type: integer
+          min: 1
+          max: 100
+          default: 85
+          depends_on: { output_format: [jpeg, webp, avif] }
+          description: "Output quality for lossy formats"
+        background:
+          type: string
+          depends_on: { output_format: jpeg }
+          description: "Background colour (hex, e.g. '#ffffff') for transparent images converted to JPEG"
+
+    video:
+      mimes:
+        - video/mp4
+        - video/webm
+        - video/ogg
+      processing_class:
+        # F8 long-form video tier (per ticket I15-CONS).
+        short_form:
+          availability: stable
+          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:
+        output_format:
+          type: enum
+          values: [mp4, webm, ogg, gif]
+          required: true
+          description: "Target format"
+        codec:
+          type: enum
+          values: [h264, h265, vp9, av1]
+          description: "Video codec for target format. Defaults to format's standard codec."
+        quality:
+          type: integer
+          min: 0
+          max: 51
+          default: 23
+          description: "CRF value (0 = lossless, 51 = worst)"
+
+    audio:
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/ogg
+        - audio/flac
+        - audio/wav
+        - audio/mp4
+      options:
+        output_format:
+          type: enum
+          values: [mp3, aac, ogg, flac, wav]
+          required: true
+          description: "Target format"
+        bitrate:
+          type: enum
+          value_type: integer
+          values: [64, 96, 128, 192, 256, 320]
+          default: 128
+          depends_on: { output_format: [mp3, aac, ogg] }
+          description: "Output bitrate in kbps (lossy formats only)"
+
+    # Only PDF conversion is supported. Office/ODF/EPUB conversion would require
+    # LibreOffice which is not available in the document Lambda.
+    document_pdf:
+      mimes:
+        - application/pdf
+      options:
+        output_format:
+          type: enum
+          values: [png, jpeg]
+          required: true
+          description: "Target image format (renders PDF pages as images)"
+        pages:
+          type: string
+          default: "1"
+          description: "Page selection (e.g. '1-5,8'). Each page produces a separate output file."
+        dpi:
+          type: integer
+          min: 72
+          max: 600
+          default: 150
+          description: "Render resolution in DPI"

package/operations/schemas/custom_luma.yaml

@@ -0,0 +1,109 @@
+schema_version: "2.0.0"
+
+operation:
+  type: custom_luma
+  availability: planned
+  required_tier: pro
+  description: |
+    Apply a caller-uploaded luma matte (transition-mask) over a base
+    video to produce a custom luma-matte transition effect. Inspired
+    by Cloudinary's deprecated luma-matte custom transitions and
+    intended as a paid-tier (`pro`+) creative feature.
+
+    **NOT** related to FFmpeg's `xfade=custom` filter (which is an
+    expression-mode parameter on the same `xfade` filter). The
+    `merge.transition.custom` value is tagged `planned` with
+    documentation_url pointing at this operation; once `custom_luma`
+    ships, the merge slot is repurposed to a "use the dedicated
+    `custom_luma` operation instead" advisory.
+
+    Multi-input: exactly one input with `role: base` (the source
+    video being transitioned) + exactly one input with
+    `role: transition_mask` (the luma matte — a video whose pixel
+    luminance drives the transition reveal — bright = revealed,
+    dark = held). The mask can be uploaded directly, imported
+    externally, or referenced from a vault connection per
+    `WorkflowSource` (from I10).
+
+    Per ADR-0001 §1.3 (Tension 1 — `planned` operations return
+    `feature_not_available` HTTP 422 until Lambda support ships).
+    Per ADR-0004 §"V2 JobDefinition" + plan v5 §F4 round 6
+    (codex-corrected — `xfade=custom` is an expression, not a
+    transition; this operation is the deliberate alternative).
+  default: false
+  input_model: multi
+  min_inputs: 2
+  max_inputs: 2
+
+  mime_groups:
+    video:
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form video tier (per ticket I15-CONS). custom_luma
+        # is itself `availability: planned` + `required_tier: pro`
+        # at the operation level; the per-class shape lands now to
+        # keep SDK/sidecar shape forward-compatible when the operation
+        # ships.
+        short_form:
+          availability: planned
+          required_tier: pro
+          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:
+        duration:
+          type: float
+          min: 0.1
+          max: 30.0
+          default: 1.0
+          description: |
+            Transition duration in seconds. The mask is time-stretched
+            or trimmed to this duration when applied.
+
+        start_offset:
+          type: float
+          min: 0.0
+          default: 0.0
+          description: |
+            Offset (seconds) from the base clip start at which the
+            transition begins. The transition runs for `duration`
+            seconds starting at `start_offset`.
+
+        mask_contrast:
+          type: float
+          min: 0.0
+          max: 4.0
+          default: 1.0
+          description: |
+            Contrast multiplier applied to the luma matte before
+            compositing. Sharpens (>1) or softens (<1) the
+            transition edge. Default 1.0 = no contrast adjustment.
+
+        mask_blur:
+          type: float
+          min: 0.0
+          max: 10.0
+          default: 0.0
+          description: |
+            Gaussian blur radius (pixels) applied to the luma matte
+            before compositing. Softens the transition edge. Default
+            0.0 = no blur. Larger values produce a more diffused
+            transition.
+
+        mask_invert:
+          type: boolean
+          default: false
+          description: |
+            When true, inverts the luma matte (bright ↔ dark). Lets
+            callers reuse a single mask asset for both reveal and
+            hide directions.