{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://jambonz.org/schema/components/recognizer-openaiOptions",
  "title": "OpenAI Recognizer Options",
  "description": "OpenAI Whisper/Realtime specific STT options. Only applies when recognizer vendor is 'openai'.",
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "OpenAI API key. Overrides credentials configured in jambonz."
    },
    "model": {
      "type": "string",
      "description": "OpenAI STT model name."
    },
    "prompt": {
      "type": "string",
      "description": "Prompt to guide the recognition model."
    },
    "promptTemplates": {
      "type": "object",
      "description": "Templates for dynamic prompt generation.",
      "properties": {
        "hintsTemplate": { "type": "string", "description": "Template for injecting hints into the prompt." },
        "conversationHistoryTemplate": { "type": "string", "description": "Template for injecting conversation history." }
      }
    },
    "language": {
      "type": "string",
      "description": "Language code for recognition."
    },
    "languages": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "description": "Language hints for 'gpt-live-transcribe', which takes a list rather than a single code (e.g. ['en','fr']). Overrides the recognizer language; do not combine with 'language'."
    },
    "keywords": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Literal term hints (product names, acronyms, medications) for 'gpt-live-transcribe'. Hints, not required output. Defaults to the recognizer's 'hints' when unset."
    },
    "delay": {
      "type": "string",
      "enum": ["minimal", "low", "medium", "high", "xhigh"],
      "description": "Latency/accuracy trade-off for 'gpt-live-transcribe': lower emits partial text sooner, higher gives the model more audio context and can improve accuracy."
    },
    "input_audio_noise_reduction": {
      "type": "string",
      "enum": ["near_field", "far_field"],
      "description": "Input audio noise reduction mode."
    },
    "turn_detection": {
      "type": "object",
      "description": "Turn detection configuration for the OpenAI Realtime API.",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["none", "server_vad", "semantic_vad"],
          "description": "Turn detection strategy."
        },
        "eagerness": {
          "type": "string",
          "enum": ["low", "medium", "high", "auto"],
          "description": "How eagerly the model should respond."
        },
        "threshold": { "type": "number", "description": "VAD activation threshold (0-1)." },
        "prefix_padding_ms": { "type": "number", "description": "Milliseconds of audio to include before detected speech." },
        "silence_duration_ms": { "type": "number", "description": "Milliseconds of silence to detect end of speech." }
      },
      "required": ["type"]
    },
    "vadMode": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3,
      "description": "Local VAD aggressiveness (0-3). Used only with the client-endpointed models ('gpt-live-transcribe', 'gpt-realtime-whisper'), which reject server turn detection and rely on jambonz to end each turn."
    },
    "vadSilenceMs": {
      "type": "integer",
      "minimum": 1,
      "description": "Milliseconds of silence to detect end-of-speech for local VAD. Used only with the client-endpointed models."
    },
    "vadVoiceMs": {
      "type": "integer",
      "minimum": 1,
      "description": "Milliseconds of voice to detect start-of-speech for local VAD. Used only with the client-endpointed models."
    }
  },
  "additionalProperties": false
}