@giveitsmaller/contracts 0.1.2 → 0.2.3

package/operations/schemas/archive.yaml

@@ -0,0 +1,22 @@
+schema_version: "1.0.0"
+
+operation:
+  type: archive
+  description: "Bundle multiple files into a single archive"
+  default: false
+  input_model: multi
+  min_inputs: 2
+  max_inputs: 50
+  accepts_mixed_types: true
+
+  options:
+    format:
+      type: enum
+      values: [zip, tar.gz]
+      default: zip
+      description: "Archive format"
+    folder_structure:
+      type: enum
+      values: [flat, by_job]
+      default: flat
+      description: "flat = all files in root, by_job = subfolder per source job"

package/operations/schemas/compress.yaml

@@ -0,0 +1,280 @@
+schema_version: "1.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/x-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/x-m4a
+      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
+      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,104 @@
+schema_version: "1.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/x-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
+      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/x-m4a
+      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/merge.yaml

@@ -0,0 +1,211 @@
+schema_version: "1.0.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 (collage/grid, animated GIF, video
+  # slideshow/concat, audio concat, PDF concat), not to influence SNS
+  # routing. 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: [image, gif, video]
+          default: image
+          description: "Result format: static image (collage/grid), animated GIF, or slideshow video"
+        # --- Options for output_type: image ---
+        layout:
+          type: enum
+          values: [grid, horizontal, vertical]
+          default: grid
+          depends_on: { output_type: image }
+          description: "How to arrange images in the collage"
+        columns:
+          type: integer
+          min: 1
+          max: 10
+          depends_on: { output_type: image }
+          description: "Number of columns in grid layout. Omit for auto (square-ish grid based on input count)."
+        resize_mode:
+          type: enum
+          values: [fit, fill, none]
+          default: fit
+          depends_on: { output_type: image }
+          description: "How to handle images of different sizes"
+        spacing:
+          type: integer
+          min: 0
+          max: 100
+          default: 0
+          depends_on: { output_type: image }
+          description: "Pixel spacing between images"
+        background:
+          type: string
+          default: "transparent"
+          depends_on: { output_type: image }
+          description: "Background color for spacing/padding (CSS color or 'transparent')"
+        image_format:
+          type: enum
+          values: [jpeg, png, webp]
+          default: png
+          depends_on: { output_type: image }
+          description: "Output image format for the collage"
+        # --- 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
+          values: [none, fade, slide]
+          default: none
+          depends_on: { output_type: video }
+          description: "Transition effect between images"
+        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
+      options:
+        transition:
+          type: enum
+          values: [none, crossfade]
+          default: none
+          description: "Default transition between clips"
+        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"
+      per_input_options:
+        transition:
+          type: enum
+          values: [none, crossfade]
+          description: "Override transition for the join point preceding this input"
+        crossfade_duration:
+          type: float
+          min: 0.1
+          max: 5.0
+          depends_on: { transition: crossfade }
+          description: "Override crossfade duration for this join point"
+
+    audio:
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/wav
+        - audio/ogg
+        - audio/flac
+      options:
+        transition:
+          type: enum
+          values: [none, crossfade]
+          default: none
+          description: "Default transition between clips"
+        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
+          values: [none, crossfade]
+          description: "Override transition for the join point preceding this input"
+        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"
+
+    document:
+      mimes:
+        - application/pdf
+      options:
+        page_range:
+          type: string
+          description: "Default page range per input, e.g. '1-3,5'. Null = all pages."
+      per_input_options:
+        page_range:
+          type: string
+          description: "Override page range for this specific input document"