{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://jambonz.org/schema/components/recognizer-sonioxOptions",
  "title": "Soniox Recognizer Options",
  "description": "Soniox-specific STT options. Only applies when recognizer vendor is 'soniox'.",
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "Soniox API key."
    },
    "model": {
      "type": "string",
      "description": "Soniox recognition model (e.g. 'stt-rt-v5')."
    },
    "languageHints": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Language hints for the v5 multilingual model, as ISO language codes (e.g. ['en','es']). Improves accuracy and speeds up language detection."
    },
    "enableLanguageIdentification": {
      "type": "boolean",
      "description": "Enable language identification (v5); each recognized token is tagged with its detected language."
    },
    "enableSpeakerDiarization": {
      "type": "boolean",
      "description": "Enable speaker diarization (v5); each recognized token is tagged with a speaker."
    },
    "endpointDetection": {
      "type": "boolean",
      "description": "Enable endpoint detection."
    },
    "endpointSensitivity": {
      "type": "number",
      "minimum": -1,
      "maximum": 1,
      "description": "Endpoint detection sensitivity (v5), -1.0 to 1.0 (default 0.0). Higher values finalize endpoints faster; lower values are more conservative."
    },
    "maxEndpointDelayMs": {
      "type": "integer",
      "minimum": 500,
      "maximum": 3000,
      "description": "Maximum delay in milliseconds before an endpoint is forced (v5), 500-3000 (default 2000)."
    },
    "maxNonFinalTokensDurationMs": {
      "type": "integer",
      "minimum": 0,
      "description": "Maximum duration in milliseconds that tokens may remain non-final before forced finalization (v5)."
    },
    "profanityFilter": {
      "type": "boolean",
      "description": "Filter profanity from results."
    },
    "context": {
      "type": "object",
      "additionalProperties": false,
      "description": "Soniox v5 recognition context to improve accuracy (max ~8000 tokens). See https://soniox.com/docs/stt/concepts/context. When supplied this takes precedence outright over the 'speechContext' and 'hints' shortcuts.",
      "properties": {
        "general": {
          "type": "array",
          "description": "Structured key/value metadata describing the domain, topic, participants, setting, etc.",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "key": { "type": "string" },
              "value": { "type": "string" }
            },
            "required": ["key", "value"]
          }
        },
        "text": {
          "type": "string",
          "description": "Free-form background text (history of prior interactions, reference documents, meeting notes, summaries)."
        },
        "terms": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Domain-specific vocabulary to boost recognition."
        },
        "translation_terms": {
          "type": "array",
          "description": "Source/target term mappings; only used when translation is enabled.",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "source": { "type": "string" },
              "target": { "type": "string" }
            },
            "required": ["source", "target"]
          }
        }
      }
    },
    "speechContext": {
      "type": "string",
      "description": "Shortcut for context.text (free-text background). Ignored when the full 'context' object is supplied. The generic recognizer 'hints' are likewise sent as context.terms unless 'context' is supplied."
    },
    "clientRequestReference": {
      "type": "string",
      "description": "Client request reference for tracking."
    },
    "storage": {
      "type": "object",
      "description": "Soniox storage configuration for persisting transcripts.",
      "properties": {
        "id": { "type": "string", "description": "Storage ID." },
        "title": { "type": "string", "description": "Storage title." },
        "disableStoreAudio": { "type": "boolean", "description": "Disable audio storage." },
        "disableStoreTranscript": { "type": "boolean", "description": "Disable transcript storage." },
        "disableSearch": { "type": "boolean", "description": "Disable search indexing." },
        "metadata": { "type": "object", "description": "Custom metadata.", "additionalProperties": true }
      }
    }
  },
  "additionalProperties": false
}