@jambonz/schema 0.1.1

package/components/recognizer.schema.json

@@ -0,0 +1,216 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer",
+  "title": "Recognizer",
+  "description": "Configuration for speech-to-text recognition. Specifies the STT vendor, language, and vendor-specific options. Can be set at the session level via the 'config' verb or overridden per-verb (e.g. on 'gather').",
+  "type": "object",
+  "properties": {
+    "vendor": {
+      "type": "string",
+      "description": "The STT vendor to use. Must match a vendor configured in the jambonz platform.",
+      "examples": ["google", "aws", "microsoft", "deepgram", "nuance", "ibm", "nvidia", "soniox", "cobalt", "assemblyai", "speechmatics", "openai", "houndify", "gladia", "elevenlabs", "verbio", "custom"]
+    },
+    "label": {
+      "type": "string",
+      "description": "An optional label identifying a specific credential set for this vendor. Used when multiple credentials are configured for the same vendor."
+    },
+    "language": {
+      "type": "string",
+      "description": "The language code for speech recognition, in BCP-47 format.",
+      "examples": ["en-US", "en-GB", "es-ES", "fr-FR"]
+    },
+    "fallbackVendor": {
+      "type": "string",
+      "description": "A backup STT vendor to use if the primary vendor fails or is unavailable."
+    },
+    "fallbackLabel": {
+      "type": "string",
+      "description": "Credential label for the fallback vendor."
+    },
+    "fallbackLanguage": {
+      "type": "string",
+      "description": "Language code to use with the fallback vendor."
+    },
+    "vad": {
+      "$ref": "vad",
+      "description": "Voice activity detection settings for this recognizer."
+    },
+    "autogeneratePrompt": {
+      "type": "boolean",
+      "description": "If true, automatically generate a prompt for the STT vendor based on context (e.g. TTS voice, language). Supported by vendors that accept prompts for recognition guidance."
+    },
+    "hints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "An array of words or phrases that the recognizer should favor. Use this to improve accuracy for domain-specific terminology, product names, or proper nouns.",
+      "examples": [["jambonz", "drachtio", "SIP", "WebRTC"]]
+    },
+    "hintsBoost": {
+      "type": "number",
+      "description": "A boost factor for hint words. Higher values increase the likelihood of recognizing hinted words. Vendor-specific range."
+    },
+    "altLanguages": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Additional languages the recognizer should listen for simultaneously. Enables multilingual recognition.",
+      "examples": [["es-ES", "fr-FR"]]
+    },
+    "profanityFilter": {
+      "type": "boolean",
+      "description": "If true, the vendor will attempt to filter profanity from transcription results."
+    },
+    "interim": {
+      "type": "boolean",
+      "description": "If true, return interim (partial) transcription results as they become available, before the utterance is complete."
+    },
+    "singleUtterance": {
+      "type": "boolean",
+      "description": "If true, recognition stops after the first complete utterance is detected."
+    },
+    "dualChannel": {
+      "type": "boolean",
+      "description": "If true, send separate audio channels for each call leg (caller and callee) to the recognizer."
+    },
+    "separateRecognitionPerChannel": {
+      "type": "boolean",
+      "description": "If true, perform independent recognition on each audio channel. Requires dualChannel."
+    },
+    "punctuation": {
+      "type": "boolean",
+      "description": "If true, enable automatic punctuation in transcription results."
+    },
+    "enhancedModel": {
+      "type": "boolean",
+      "description": "If true, use an enhanced (premium) recognition model if available from the vendor."
+    },
+    "words": {
+      "type": "boolean",
+      "description": "If true, include word-level timing information in transcription results."
+    },
+    "diarization": {
+      "type": "boolean",
+      "description": "If true, enable speaker diarization to identify different speakers in the audio."
+    },
+    "diarizationMinSpeakers": {
+      "type": "number",
+      "description": "Minimum number of speakers expected. Used to guide the diarization algorithm."
+    },
+    "diarizationMaxSpeakers": {
+      "type": "number",
+      "description": "Maximum number of speakers expected. Used to guide the diarization algorithm."
+    },
+    "interactionType": {
+      "type": "string",
+      "description": "A hint to the recognizer about the type of interaction, which can improve accuracy.",
+      "enum": ["unspecified", "discussion", "presentation", "phone_call", "voicemail", "voice_search", "voice_command", "dictation"]
+    },
+    "naicsCode": {
+      "type": "number",
+      "description": "North American Industry Classification System code. Some vendors use this to improve domain-specific accuracy."
+    },
+    "identifyChannels": {
+      "type": "boolean",
+      "description": "If true, identify and label which channel each transcription segment came from."
+    },
+    "vocabularyName": {
+      "type": "string",
+      "description": "Name of a custom vocabulary resource configured at the vendor for improved recognition of specialized terms."
+    },
+    "vocabularyFilterName": {
+      "type": "string",
+      "description": "Name of a vocabulary filter configured at the vendor for masking or removing specific words."
+    },
+    "filterMethod": {
+      "type": "string",
+      "description": "How filtered vocabulary words should be handled in the transcript.",
+      "enum": ["remove", "mask", "tag"]
+    },
+    "model": {
+      "type": "string",
+      "description": "The specific recognition model to use. Model names are vendor-specific.",
+      "examples": ["latest_long", "phone_call", "nova-2", "chirp"]
+    },
+    "outputFormat": {
+      "type": "string",
+      "description": "The level of detail in recognition results.",
+      "enum": ["simple", "detailed"]
+    },
+    "profanityOption": {
+      "type": "string",
+      "description": "How profanity should be handled in results.",
+      "enum": ["masked", "removed", "raw"]
+    },
+    "requestSnr": {
+      "type": "boolean",
+      "description": "If true, request signal-to-noise ratio information in results."
+    },
+    "initialSpeechTimeoutMs": {
+      "type": "number",
+      "description": "Time in milliseconds to wait for initial speech before timing out.",
+      "examples": [5000]
+    },
+    "azureServiceEndpoint": {
+      "type": "string",
+      "description": "Custom Azure Speech Services endpoint URL. Only applies when vendor is 'microsoft'."
+    },
+    "azureSttEndpointId": {
+      "type": "string",
+      "description": "Azure custom speech endpoint ID for using a custom-trained model. Only applies when vendor is 'microsoft'."
+    },
+    "asrDtmfTerminationDigit": {
+      "type": "string",
+      "description": "A DTMF digit that terminates speech recognition when pressed.",
+      "examples": ["#"]
+    },
+    "asrTimeout": {
+      "type": "number",
+      "description": "Maximum time in seconds to wait for a complete recognition result."
+    },
+    "fastRecognitionTimeout": {
+      "type": "number",
+      "description": "Timeout in seconds for fast recognition mode. Shorter timeout for quick responses."
+    },
+    "minConfidence": {
+      "type": "number",
+      "description": "Minimum confidence score (0-1) required to accept a recognition result. Results below this threshold are discarded.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "deepgramOptions": { "$ref": "recognizer-deepgramOptions" },
+    "googleOptions": { "$ref": "recognizer-googleOptions" },
+    "awsOptions": { "$ref": "recognizer-awsOptions" },
+    "azureOptions": { "$ref": "recognizer-azureOptions" },
+    "nuanceOptions": { "$ref": "recognizer-nuanceOptions" },
+    "ibmOptions": { "$ref": "recognizer-ibmOptions" },
+    "nvidiaOptions": { "$ref": "recognizer-nvidiaOptions" },
+    "sonioxOptions": { "$ref": "recognizer-sonioxOptions" },
+    "cobaltOptions": { "$ref": "recognizer-cobaltOptions" },
+    "assemblyAiOptions": { "$ref": "recognizer-assemblyAiOptions" },
+    "speechmaticsOptions": { "$ref": "recognizer-speechmaticsOptions" },
+    "openaiOptions": { "$ref": "recognizer-openaiOptions" },
+    "houndifyOptions": { "$ref": "recognizer-houndifyOptions" },
+    "gladiaOptions": { "$ref": "recognizer-gladiaOptions" },
+    "elevenlabsOptions": { "$ref": "recognizer-elevenlabsOptions" },
+    "verbioOptions": { "$ref": "recognizer-verbioOptions" },
+    "customOptions": { "$ref": "recognizer-customOptions" }
+  },
+  "required": ["vendor"],
+  "examples": [
+    {
+      "vendor": "deepgram",
+      "language": "en-US",
+      "deepgramOptions": {
+        "model": "nova-2",
+        "smartFormatting": true,
+        "endpointing": 500
+      }
+    },
+    {
+      "vendor": "google",
+      "language": "en-US",
+      "hints": ["jambonz", "drachtio"],
+      "punctuation": true,
+      "enhancedModel": true
+    }
+  ]
+}

package/components/synthesizer.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/synthesizer",
+  "title": "Synthesizer",
+  "description": "Configuration for text-to-speech synthesis. Specifies the TTS vendor, voice, language, and vendor-specific options. Can be set at the session level via the 'config' verb or overridden per-verb (e.g. on 'say').",
+  "type": "object",
+  "properties": {
+    "vendor": {
+      "type": "string",
+      "description": "The TTS vendor to use. Must match a vendor configured in the jambonz platform.",
+      "examples": ["google", "aws", "microsoft", "elevenlabs", "cartesia", "deepgram", "ibm", "nuance", "nvidia", "wellsaid", "whisper", "verbio", "custom"]
+    },
+    "label": {
+      "type": "string",
+      "description": "An optional label identifying a specific credential set for this vendor. Used when multiple credentials are configured for the same vendor on the jambonz platform."
+    },
+    "language": {
+      "type": "string",
+      "description": "The language code for speech synthesis, in BCP-47 format.",
+      "examples": ["en-US", "en-GB", "es-ES", "fr-FR", "de-DE"]
+    },
+    "voice": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object", "additionalProperties": true }
+      ],
+      "description": "The voice to use for synthesis. Format varies by vendor: Google uses voice names like 'en-US-Wavenet-D', AWS Polly uses names like 'Joanna', but ElevenLabs and Cartesia require voice IDs (alphanumeric strings like 'EXAVITQu4vr4xnSDxMaL'), not human-readable names. Some vendors accept an object for more complex voice configuration.",
+      "examples": ["en-US-Wavenet-D", "Joanna", "EXAVITQu4vr4xnSDxMaL"]
+    },
+    "fallbackVendor": {
+      "type": "string",
+      "description": "A backup TTS vendor to use if the primary vendor fails or is unavailable."
+    },
+    "fallbackLabel": {
+      "type": "string",
+      "description": "Credential label for the fallback vendor."
+    },
+    "fallbackLanguage": {
+      "type": "string",
+      "description": "Language code to use with the fallback vendor."
+    },
+    "fallbackVoice": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object", "additionalProperties": true }
+      ],
+      "description": "Voice to use with the fallback vendor."
+    },
+    "engine": {
+      "type": "string",
+      "description": "The synthesis engine tier to use. Availability depends on the vendor.",
+      "enum": ["standard", "neural", "generative", "long-form"]
+    },
+    "gender": {
+      "type": "string",
+      "description": "Preferred voice gender. Used by some vendors (e.g. Google) when a specific voice is not specified.",
+      "enum": ["MALE", "FEMALE", "NEUTRAL"]
+    },
+    "options": {
+      "type": "object",
+      "description": "Vendor-specific options passed through to the TTS provider. The structure depends on the vendor being used.",
+      "additionalProperties": true
+    }
+  },
+  "required": ["vendor"],
+  "examples": [
+    {
+      "vendor": "google",
+      "language": "en-US",
+      "voice": "en-US-Wavenet-D"
+    },
+    {
+      "vendor": "elevenlabs",
+      "voice": "Rachel",
+      "options": {
+        "model_id": "eleven_turbo_v2",
+        "stability": 0.5,
+        "similarity_boost": 0.75
+      }
+    }
+  ]
+}

package/components/target.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/target",
+  "title": "Target",
+  "description": "A call target for the 'dial' verb. Specifies who or what to connect the call to: a phone number (PSTN), a SIP endpoint, a registered user, or a Microsoft Teams user.",
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "The type of target to dial.",
+      "enum": ["phone", "sip", "user", "teams"]
+    },
+    "number": {
+      "type": "string",
+      "description": "The phone number to dial. Required when type is 'phone'. Use E.164 format.",
+      "examples": ["+15085551212"]
+    },
+    "sipUri": {
+      "type": "string",
+      "description": "The SIP URI to dial. Required when type is 'sip'.",
+      "examples": ["sip:alice@example.com"]
+    },
+    "name": {
+      "type": "string",
+      "description": "The registered user name to dial. Required when type is 'user'. Also used as the display name for SIP targets."
+    },
+    "tenant": {
+      "type": "string",
+      "description": "The Microsoft Teams tenant ID. Required when type is 'teams'."
+    },
+    "trunk": {
+      "type": "string",
+      "description": "The SIP trunk to use for the outbound call. When specified, overrides the default carrier routing."
+    },
+    "confirmHook": {
+      "oneOf": [
+        { "type": "string", "format": "uri" },
+        { "$ref": "actionHook" }
+      ],
+      "description": "A webhook to invoke when the target answers, before connecting the call. Use this to screen calls, play a whisper prompt, or require the target to press a key to accept."
+    },
+    "method": {
+      "type": "string",
+      "description": "The HTTP method to use when invoking the confirmHook.",
+      "enum": ["GET", "POST"],
+      "default": "POST"
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include on the outbound INVITE. Keys are header names, values are header values.",
+      "additionalProperties": { "type": "string" }
+    },
+    "from": {
+      "type": "object",
+      "description": "Override the From header on the outbound SIP INVITE.",
+      "properties": {
+        "user": {
+          "type": "string",
+          "description": "The user part of the SIP From URI."
+        },
+        "host": {
+          "type": "string",
+          "description": "The host part of the SIP From URI."
+        }
+      }
+    },
+    "auth": {
+      "$ref": "auth",
+      "description": "SIP authentication credentials for the outbound call, if the far end requires digest auth."
+    },
+    "vmail": {
+      "type": "boolean",
+      "description": "If true, follow the call into voicemail if the target does not answer."
+    },
+    "overrideTo": {
+      "type": "string",
+      "description": "Override the Request-URI on the outbound SIP INVITE. Useful when the Request-URI needs to differ from the To header."
+    },
+    "proxy": {
+      "type": "string",
+      "description": "A SIP proxy to route the outbound call through, specified as a SIP URI.",
+      "examples": ["sip:proxy.example.com"]
+    }
+  },
+  "required": ["type"],
+  "examples": [
+    {
+      "type": "phone",
+      "number": "+15085551212"
+    },
+    {
+      "type": "sip",
+      "sipUri": "sip:alice@example.com"
+    },
+    {
+      "type": "user",
+      "name": "bob"
+    },
+    {
+      "type": "teams",
+      "number": "+15085551212",
+      "tenant": "a]b]c]d]e"
+    }
+  ]
+}

package/components/vad.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/vad",
+  "title": "VAD",
+  "description": "Voice Activity Detection configuration. Controls how jambonz detects the presence or absence of speech on the audio channel. Used to determine speech start/end boundaries for recognition and barge-in.",
+  "type": "object",
+  "properties": {
+    "enable": {
+      "type": "boolean",
+      "description": "Whether to enable voice activity detection."
+    },
+    "voiceMs": {
+      "type": "number",
+      "description": "Duration of voice activity (in milliseconds) required before speech is considered to have started.",
+      "examples": [250]
+    },
+    "silenceMs": {
+      "type": "number",
+      "description": "Duration of silence (in milliseconds) required before speech is considered to have ended.",
+      "examples": [1000]
+    },
+    "strategy": {
+      "type": "string",
+      "description": "The VAD strategy to use."
+    },
+    "mode": {
+      "type": "number",
+      "description": "WebRTC VAD aggressiveness mode (0-3). Higher values are more aggressive at filtering non-speech. Only applies when vendor is 'webrtc'.",
+      "minimum": 0,
+      "maximum": 3
+    },
+    "vendor": {
+      "type": "string",
+      "description": "The VAD engine to use.",
+      "enum": ["webrtc", "silero"]
+    },
+    "threshold": {
+      "type": "number",
+      "description": "Speech detection confidence threshold for Silero VAD. Value between 0 and 1, where higher values require greater confidence. Only applies when vendor is 'silero'.",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "speechPadMs": {
+      "type": "number",
+      "description": "Padding in milliseconds added before and after detected speech segments. Prevents clipping utterance boundaries. Only applies when vendor is 'silero'."
+    }
+  }
+}

package/docs/components/recognizer.md

@@ -0,0 +1,78 @@
+## Vendor documentation links
+
+Refer to vendor documentation for supported models and languages.
+
+**Important**: jambonz requires real-time streaming STT. When choosing a model, ensure it supports real-time/streaming transcription. Models that only support batch transcription cannot be used.
+
+### Deepgram
+- When using Deepgram default to the latest nova model (e.g. nova-3)
+- [Models & Languages Overview](https://developers.deepgram.com/docs/models-languages-overview)
+
+### Google
+
+- [Supported Languages](https://cloud.google.com/speech-to-text/docs/speech-to-text-supported-languages)
+
+### Microsoft Azure
+
+- [Language and Voice Support](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support)
+
+### AWS Transcribe
+
+- [Supported Languages](https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html)
+
+### IBM Watson
+
+- [Models and Languages](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng)
+
+### AssemblyAI
+
+- [Supported Languages](https://www.assemblyai.com/docs/getting-started/supported-languages)
+
+#### Prompting (Universal-3 Pro)
+
+AssemblyAI's Universal-3 Pro streaming model supports a `prompt` parameter that guides transcription behavior around punctuation, disfluencies, formatting, and domain-specific terminology. The default prompt achieves strong turn detection accuracy out of the box — only customize if needed, and start by extending the default rather than replacing it.
+
+- See [Prompting guide](https://www.assemblyai.com/docs/streaming/universal-3-pro/prompting)
+
+jambonz has an autogeneratePrompt recognizer setting which when used with AssemblyAI universal-3 pro streaming will automatically create the prompt for a gather verb based on the text in a nested say property.  See [here](../../examples/assemblyai-autogenerate-prompt/) for details.
+
+A `keyterms` array can boost recognition of specific names, brands, or technical terms. This can be updated mid-stream, making it useful for voice agent scenarios where context changes during the call.
+
+- See [Keyterms guide](https://www.assemblyai.com/docs/streaming/keyterms-prompting)
+
+### OpenAI (Whisper)
+
+- [Speech to Text Guide](https://platform.openai.com/docs/guides/speech-to-text)
+
+### Nvidia Riva
+
+- [ASR Overview](https://docs.nvidia.com/deeplearning/riva/user-guide/docs/asr/asr-overview.html)
+
+### Speechmatics
+
+- [Transcription Languages](https://docs.speechmatics.com/speech-to-text/languages#transcription-languages)
+
+#### Voice Agent (Preview)
+
+Speechmatics offers a Voice Agent API (currently in preview) that provides low-latency conversational AI capabilities. When using the Voice Agent API, set the `host` and `profile` properties in `speechmaticsOptions`:
+
+- `host` - the Speechmatics Voice Agent endpoint URL
+- `profile` - one of `adaptive`, `agile`, `smart`, or `external`
+
+See [Voice Agent API documentation](https://docs.speechmatics.com/private/voice-agent-api#introduction) for details.
+
+### Soniox
+
+- [STT Models](https://soniox.com/docs/stt/models)
+
+### Verbio
+
+- [Supported Languages](https://www.verbio.com/supported-languages)
+
+### Gladia
+
+- [Supported Languages](https://docs.gladia.io/chapters/language/supported-languages)
+
+### Nuance
+
+- [ASR gRPC API](https://docs.mix.nuance.com/asr-grpc/v1/) (Nuance is now part of Microsoft; Azure Speech Service is the successor)

package/docs/components/synthesizer.md

@@ -0,0 +1,27 @@
+## Vendor documentation links
+
+Refer to vendor documentation for supported models, voices, and vendor-specific options.
+
+### Deepgram
+
+- [TTS Models](https://developers.deepgram.com/docs/tts-models)
+
+### Google
+
+- [Supported Voices and Languages](https://cloud.google.com/text-to-speech/docs/voices)
+
+### Microsoft Azure
+
+- [Language and Voice Support](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=tts)
+
+### AWS Polly
+
+- [Available Voices](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html)
+
+### ElevenLabs
+
+- [Models](https://elevenlabs.io/docs/overview/models)
+
+### Cartesia
+
+- [TTS Models](https://docs.cartesia.ai/build-with-cartesia/tts-models)