@giveitsmaller/contracts 0.2.0 → 0.3.0

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/audio_overlay.yaml

@@ -0,0 +1,397 @@
+schema_version: "2.0.0"
+
+operation:
+  type: audio_overlay
+  availability: planned
+  description: |
+    Mix a secondary audio asset (overlay) over a primary audio or
+    video base. Use cases: DJ tags, podcast intros/outros, station
+    IDs, jingles, branded mid-rolls.
+
+    **Industry naming.** This is "audio overlay" or "audio branding"
+    — NOT "audio watermark". Audio watermarking is steganographic
+    (imperceptible identifier embedded in audio for ownership /
+    forensic tracking) and is owned by the separate `audio_watermark`
+    operation (planned per ticket I20).
+
+    Multi-input (Path B with `role: base` + `role: overlay` per
+    `JobInputV2.role`). `min_inputs: 2 = max_inputs: 2` for V2.0;
+    multi-overlay support is advertised as a planned feature
+    (`features.multi_overlay_stack`) but Lambda-side implementation
+    deferred.
+
+    The overlay can be uploaded directly, imported externally, or
+    referenced from a vault connection per `WorkflowSource` (from
+    I10). The base is whatever single-asset source the workflow
+    upstream has — for `mime_groups.audio`, the base is the primary
+    audio track; for `mime_groups.video`, the overlay is mixed into
+    the video's audio track and the visual track passes through
+    untouched.
+
+    Per ADR-0001 §1.3 (Tension 1 — `planned` operations return
+    `feature_not_available` 422 until Lambda support ships). Per
+    ADR-0004 §"V2 JobDefinition" + plan v5 §F1 round 6.
+  default: false
+  input_model: multi
+  min_inputs: 2
+  max_inputs: 2
+
+  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`.
+
+    sync_to_silence:
+      availability: planned
+      description: |
+        Anchor overlay placement to detected silence regions in the
+        base track (e.g. drop a podcast jingle into the natural
+        breath after the host says "back in a sec"). Server-side
+        silence detection runs at workflow-create time; the actual
+        overlay start position is reported on
+        `OperationMetrics.overlay_anchor_ms`. Gates two extra
+        options: `silence_threshold_db` and `min_silence_ms`. Lambda
+        support not yet shipped.
+
+  mime_groups:
+    audio:
+      availability: planned
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/wav
+        - audio/ogg
+        - audio/flac
+      processing_class:
+        # F8 long-form tier (per ticket I15-CONS). Both classes
+        # `planned` because the audio mime_group itself is `planned`
+        # at the group level — schema shape forward-compatible with
+        # Lambda activation.
+        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:
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 21474836480
+            max_output_size_bytes: 21474836480
+      options:
+        start_at:
+          type: float
+          min: 0.0
+          default: 0.0
+          description: |
+            Start position (seconds) on the base track at which the
+            overlay begins playing. Default 0.0 = mix from the
+            beginning. Inert when
+            `features.sync_to_silence.availability` flips to
+            `stable` and `mode: sync_to_silence` is selected
+            (placement is then anchored to detected silence).
+
+        duration:
+          type: float
+          min: 0.0
+          description: |
+            Maximum duration (seconds) of the overlay AS PLAYED — the
+            overlay asset is trimmed to this length if longer. Omit
+            (or set 0) to play the overlay's full natural length.
+            **Disambiguation:** this is overlay-trim duration, NOT
+            output duration. The output duration always matches the
+            base track's duration.
+
+        overlay_gain_db:
+          type: float
+          min: -60.0
+          max: 12.0
+          default: -3.0
+          description: |
+            Gain applied to the overlay in decibels before mixing.
+            Default -3 dB matches typical podcast intro / DJ-tag
+            level. Positive values amplify (clip risk); negative
+            values attenuate. Clamped to range.
+
+        mode:
+          type: enum
+          values: [mix, duck, replace]
+          default: mix
+          description: |
+            How the overlay combines with the base audio:
+            - `mix`: simple sum (overlay + base; both audible).
+            - `duck`: side-chain compress the base under the overlay
+              (base attenuates while overlay plays — broadcast pattern).
+            - `replace`: mute the base for the overlay's duration
+              (overlay only; useful for hard-cut station IDs).
+          per_value_availability:
+            duck: { availability: planned }
+
+        duck_threshold:
+          type: float
+          min: -60.0
+          max: 0.0
+          default: -20.0
+          depends_on: { mode: duck }
+          description: |
+            Side-chain threshold (dB). Base audio is ducked when the
+            overlay exceeds this level. Only applies when `mode: duck`.
+
+        duck_ratio:
+          type: float
+          min: 1.0
+          max: 20.0
+          default: 4.0
+          depends_on: { mode: duck }
+          description: |
+            Side-chain compression ratio. Higher values produce more
+            aggressive ducking. Only applies when `mode: duck`.
+
+        duck_attack_ms:
+          type: integer
+          min: 0
+          max: 5000
+          default: 50
+          depends_on: { mode: duck }
+          description: |
+            Time (milliseconds) for the ducker to reach full
+            attenuation once the overlay crosses `duck_threshold`.
+            Only applies when `mode: duck`.
+
+        duck_release_ms:
+          type: integer
+          min: 0
+          max: 5000
+          default: 300
+          depends_on: { mode: duck }
+          description: |
+            Time (milliseconds) for the ducker to release back to
+            unity gain after the overlay drops below
+            `duck_threshold`. Only applies when `mode: duck`.
+
+        fade_in_ms:
+          type: integer
+          min: 0
+          max: 10000
+          default: 0
+          description: |
+            Linear fade-in applied to the overlay (milliseconds).
+            Default 0 = hard start.
+
+        fade_out_ms:
+          type: integer
+          min: 0
+          max: 10000
+          default: 0
+          description: |
+            Linear fade-out applied to the overlay (milliseconds).
+            Default 0 = hard stop.
+
+        loop:
+          type: boolean
+          default: false
+          description: |
+            When true, the overlay loops continuously across the
+            duration of the base track (or up to the trimmed
+            `duration`). Useful for ambient bed music / background
+            stings.
+
+        loop_interval:
+          type: float
+          min: 0.0
+          max: 600.0
+          default: 0.0
+          depends_on: { loop: true }
+          description: |
+            Silence gap (seconds) inserted between overlay loops.
+            Default 0 = back-to-back. Only applies when `loop: true`.
+
+        silence_threshold_db:
+          type: float
+          min: -80.0
+          max: -10.0
+          default: -50.0
+          availability: planned
+          description: |
+            Silence threshold (dB) for the `sync_to_silence` feature.
+            Base audio below this level for at least `min_silence_ms`
+            qualifies as a silence region into which the overlay can
+            be anchored. Inert until
+            `features.sync_to_silence.availability` flips to stable.
+
+        min_silence_ms:
+          type: integer
+          min: 50
+          max: 30000
+          default: 500
+          availability: planned
+          description: |
+            Minimum silence duration (milliseconds) to qualify as an
+            anchor region for `sync_to_silence`. Inert until that
+            feature flips to stable.
+
+    # Mix overlay into a video's audio track. Visual track passes
+    # through untouched; output container preserved. Lambda support
+    # for the audio-graph manipulation on a video container is not
+    # yet confirmed — tagged planned.
+    video:
+      availability: planned
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form tier (per ticket I15-CONS). Both classes
+        # `planned` because the video mime_group itself is `planned`
+        # at the group level.
+        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:
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 21474836480
+            max_output_size_bytes: 21474836480
+      options:
+        start_at:
+          type: float
+          min: 0.0
+          default: 0.0
+          description: |
+            Start position (seconds) on the base video's audio track
+            at which the overlay begins playing.
+
+        duration:
+          type: float
+          min: 0.0
+          description: |
+            Maximum duration (seconds) of the overlay AS PLAYED. The
+            overlay asset is trimmed to this length if longer. Output
+            video duration always matches the base.
+
+        overlay_gain_db:
+          type: float
+          min: -60.0
+          max: 12.0
+          default: -3.0
+          description: "Gain applied to the overlay in decibels before mixing."
+
+        mode:
+          type: enum
+          values: [mix, duck, replace]
+          default: mix
+          description: |
+            Same modes as the audio mime_group. `replace` mutes the
+            base video's audio for the overlay's duration.
+          per_value_availability:
+            duck: { availability: planned }
+
+        duck_threshold:
+          type: float
+          min: -60.0
+          max: 0.0
+          default: -20.0
+          depends_on: { mode: duck }
+          description: "Side-chain threshold (dB). Only applies when `mode: duck`."
+
+        duck_ratio:
+          type: float
+          min: 1.0
+          max: 20.0
+          default: 4.0
+          depends_on: { mode: duck }
+          description: "Side-chain compression ratio. Only applies when `mode: duck`."
+
+        duck_attack_ms:
+          type: integer
+          min: 0
+          max: 5000
+          default: 50
+          depends_on: { mode: duck }
+          description: "Ducker attack (milliseconds). Only applies when `mode: duck`."
+
+        duck_release_ms:
+          type: integer
+          min: 0
+          max: 5000
+          default: 300
+          depends_on: { mode: duck }
+          description: "Ducker release (milliseconds). Only applies when `mode: duck`."
+
+        fade_in_ms:
+          type: integer
+          min: 0
+          max: 10000
+          default: 0
+          description: "Linear fade-in applied to the overlay (milliseconds)."
+
+        fade_out_ms:
+          type: integer
+          min: 0
+          max: 10000
+          default: 0
+          description: "Linear fade-out applied to the overlay (milliseconds)."
+
+        loop:
+          type: boolean
+          default: false
+          description: |
+            When true, the overlay loops continuously across the
+            duration of the base video.
+
+        loop_interval:
+          type: float
+          min: 0.0
+          max: 600.0
+          default: 0.0
+          depends_on: { loop: true }
+          description: "Silence gap (seconds) between overlay loops."
+
+        no_audio_track_behaviour:
+          type: enum
+          values: [reject, create_silent, replace]
+          default: reject
+          description: |
+            Controls behaviour when the base video has no audio
+            track:
+            - `reject`: workflow-create returns 422 (default — surfaces
+              the problem at the API edge rather than producing a
+              surprising silent-base output).
+            - `create_silent`: synthesise a silent base track at the
+              video's framerate and mix the overlay into that.
+            - `replace`: same as `create_silent` but signals intent
+              ("the overlay IS the audio track"), letting Lambda
+              skip the base-track synthesis when the overlay covers
+              the full video duration.
+
+        silence_threshold_db:
+          type: float
+          min: -80.0
+          max: -10.0
+          default: -50.0
+          availability: planned
+          description: |
+            Silence threshold (dB) for `sync_to_silence`. Inert
+            until that feature flips to stable.
+
+        min_silence_ms:
+          type: integer
+          min: 50
+          max: 30000
+          default: 500
+          availability: planned
+          description: |
+            Minimum silence duration (milliseconds) for
+            `sync_to_silence`. Inert until that feature flips to
+            stable.

package/operations/schemas/audio_watermark.yaml

@@ -0,0 +1,184 @@
+schema_version: "2.0.0"
+
+operation:
+  type: audio_watermark
+  availability: planned
+  required_tier: enterprise
+  description: |
+    Embed a steganographic forensic watermark into an audio asset (or
+    a video's audio track). The watermark is psychoacoustically masked
+    to be inaudible and engineered to survive lossy compression,
+    transcoding, broadcast chains, and analog-hole capture (Cinavia /
+    Resemble PerTh territory).
+
+    **Industry naming.** This is *audio watermarking* (steganographic;
+    used for ownership, forensic tracking, content provenance) — NOT
+    *audio overlay* (audible mixing of secondary audio for branding).
+    Audio overlay is owned by the separate `audio_overlay` operation
+    (per ticket I19).
+
+    Single-input. Watermark embedding takes the base asset and writes
+    out an indistinguishable-to-the-ear copy with the encoded payload.
+
+    **Decode endpoint.** A paired `POST /api/audio-watermark/decode`
+    endpoint extracts the embedded watermark from a previously-marked
+    asset, returning `{watermark_id, payload?, confidence, method,
+    detected_at}`. Decode is **own-watermarks-only** (rate-limited
+    + audited; the decoder will refuse to extract from media the
+    caller did not mark themselves) — pin per spike S11 acceptance.
+
+    Per ADR-0001 §1.3 (Tension 1 — `planned` operations return
+    `feature_not_available` 422 until Lambda support ships).
+    Per plan v5 §F1 round 6 (codex narrowed methods enum from 5 to 3,
+    dropping `spread_spectrum` / `echo_hiding` / `phase_coding` —
+    textbook families, not product choices).
+  default: false
+  input_model: single
+
+  mime_groups:
+    audio:
+      availability: planned
+      mimes:
+        - audio/mpeg
+        - audio/aac
+        - audio/wav
+        - audio/ogg
+        - audio/flac
+      processing_class:
+        # F8 long-form tier (per ticket I15-CONS). audio_watermark is
+        # `availability: planned` + `required_tier: enterprise` at the
+        # operation level; per-class entries inherit the enterprise
+        # tier (long_form widens further to enterprise as the natural
+        # superset of pro).
+        short_form:
+          availability: planned
+          required_tier: enterprise
+          constraints:
+            max_input_duration: "PT5M"
+            max_input_size_bytes: 524288000
+            max_output_size_bytes: 524288000
+        long_form:
+          availability: planned
+          required_tier: enterprise
+          constraints:
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 21474836480
+            max_output_size_bytes: 21474836480
+      options:
+        payload:
+          type: string
+          required: false
+          description: |
+            Optional caller-supplied payload to embed (max 256
+            characters). Use cases: ownership marker, distribution
+            channel ID, license key. When omitted, the server
+            generates a UUID-v7 `watermark_id` and embeds that
+            instead; the generated ID is returned on
+            `OperationResult` so the caller can subsequently call
+            the decode endpoint to verify.
+
+        method:
+          type: enum
+          values: [auto, psychoacoustic, neural]
+          default: auto
+          description: |
+            Watermarking algorithm:
+            - `auto`: server selects the best available method for the
+              input (currently maps to `psychoacoustic`; will widen as
+              `neural` ships).
+            - `psychoacoustic`: classical masking-curve embedding.
+              Resemble's open-source PerTh library provides the path-
+              to-prod reference implementation. Survives MP3/AAC at
+              moderate bitrates and broadcast chains.
+            - `neural`: ML-based embedding (deep generative). Higher
+              survival under aggressive transcoding + analog-hole
+              capture; longer encoding time + non-deterministic.
+          per_value_availability:
+            # `auto` + `psychoacoustic` land first (PerTh path-to-prod);
+            # `neural` lands later via Lambda follow-up.
+            neural: { availability: planned }
+
+        robustness:
+          type: enum
+          values: [light, compression_resistant, broadcast_grade]
+          default: compression_resistant
+          description: |
+            Survival profile:
+            - `light`: minimal payload-strength; smallest perceptual
+              footprint. Survives a single re-encode pass at moderate
+              bitrate.
+            - `compression_resistant` (default): survives multiple
+              MP3/AAC re-encodes at typical streaming bitrates.
+            - `broadcast_grade`: survives broadcast compression
+              chains, EQ, dynamic-range compression, and analog-hole
+              capture (microphone re-recording). Higher embedding
+              time + slightly larger perceptual footprint.
+
+        density:
+          type: enum
+          values: [sparse, normal, dense]
+          default: normal
+          description: |
+            Watermark spatial density along the asset duration:
+            - `sparse`: payload bits inserted at wider intervals;
+              decode confidence drops on short clips.
+            - `normal` (default): balanced.
+            - `dense`: maximum decode confidence on short clips at
+              the cost of slightly higher perceptual risk.
+
+    # Embed the watermark into a video's audio track. Visual track
+    # passes through untouched; output container preserved. Lambda
+    # support for the audio-graph manipulation on a video container
+    # is not yet confirmed — tagged planned (same caveat as
+    # audio_overlay.video).
+    video:
+      availability: planned
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form tier (per ticket I15-CONS).
+        short_form:
+          availability: planned
+          required_tier: enterprise
+          constraints:
+            max_input_duration: "PT5M"
+            max_input_size_bytes: 524288000
+            max_output_size_bytes: 524288000
+        long_form:
+          availability: planned
+          required_tier: enterprise
+          constraints:
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 21474836480
+            max_output_size_bytes: 21474836480
+      options:
+        payload:
+          type: string
+          required: false
+          description: |
+            Optional caller-supplied payload to embed (max 256
+            characters). When omitted, the server generates a UUID-v7
+            `watermark_id` and embeds that instead.
+
+        method:
+          type: enum
+          values: [auto, psychoacoustic, neural]
+          default: auto
+          description: |
+            Watermarking algorithm. Same semantics as the `audio`
+            mime_group; embedded into the video's audio track only.
+          per_value_availability:
+            neural: { availability: planned }
+
+        robustness:
+          type: enum
+          values: [light, compression_resistant, broadcast_grade]
+          default: compression_resistant
+          description: "Survival profile. Same semantics as audio mime_group."
+
+        density:
+          type: enum
+          values: [sparse, normal, dense]
+          default: normal
+          description: "Watermark density along the asset duration."