config.md

Configuration

The Yova project uses a JSON configuration file to manage various settings for speech recognition, text-to-speech, and OpenAI integration.

Configuration Files

• yova.config.json - Your active configuration file (should not be committed to version control)
• yova.config.default.json - Template configuration file with default values

Configuration Structure

The configuration is organized into several sections.

n8n webhook connector (n8n)

Use this when running the yova-api-n8n connector instead of OpenAI for the LLM turn. Copy the n8n object from yova.config.default.json into your yova.config.json and set your production webhook URL.

{
  "n8n": {
    "webhook_url": "https://your-n8n.example/webhook/your-id",
    "auth_header_name": "Authorization",
    "auth_header_value": "",
    "timeout_seconds": 120,
    "stream": true,
    "session_switch_threshold_seconds": 30,
    "include_hmmm_chunk": true,
    "extra_payload": {}
  }
}

Parameters:

• webhook_url (string, required): Active workflow production webhook URL (POST, JSON body).
• auth_header_name / auth_header_value (string, optional): If the n8n Webhook uses Header Auth, set Name and Value exactly as in n8n Credentials (the value is the full header value, including any Bearer prefix if stored that way). Leave empty to omit custom auth.
• timeout_seconds (number): HTTP client timeout for the webhook request.
• stream (boolean): When true, read the response as newline-delimited JSON (n8n streaming). When false, buffer the full body first.
• session_switch_threshold_seconds (number): Minimum time between session identity changes. If calls are closer than this threshold, the connector keeps using the previous sessionId. Default: 30.
• include_hmmm_chunk (boolean): Emit the same short “hmmm” audio chunk as the OpenAI connector before the model reply (see events.md TTS chunk notes).
• thinking_delay_seconds (number): When waiting for the first server response chunk, emit periodic “thinking” audio (thinking_1.wav..thinking_4.wav) starting after this delay (repeats every thinking_delay_seconds until the first server chunk arrives).
• extra_payload (object): Static JSON fields merged into every POST body (e.g. workflow-specific keys).

Optional overrides: user_agent, chat_input_key, session_id_key (defaults chatInput / sessionId). Environment fallbacks when not set in JSON: N8N_WEBHOOK_URL, N8N_AUTH_HEADER_NAME, N8N_AUTH_HEADER_VALUE.

n8n workflow notes: Match payload keys in the Webhook or use an Edit Fields node; if the workflow uses Respond to Webhook, set the Webhook Respond mode accordingly. Streaming can be buffered by reverse proxies—see the docstring in yova_api_n8n/send_webhook.py for troubleshooting.

OpenAI Configuration (open_ai)

{
  "open_ai": {
    "api_key": "your-openai-api-key-here",
    "budget": {
      "daily_usd_limit": 10.00
    }
  }
}

Parameters:

• api_key (string, required): Your OpenAI API key for accessing speech and transcription services
• budget (object, required): Your OpenAI budget for accessing speech and transcription services
  • daily_usd_limit (number, required): Your daily USD limit for accessing speech and transcription services. When 0.00, the budget is unlimited.

Pro Tips: Use can use Yova to track backend costs too and include them in the budget. See events.md and look for yova.api.usage.occur and yova.core.usage.change events for more details. It's optional.

Text-to-Speech Configuration (text2speech)

{
  "text2speech": {
    "model": "gpt-4o-mini-tts",
    "voice": "marin",
    "speed": 1.25,
    "instructions": "You are a English voice assistant. Read the input text aloud in natural, fluent language with clear pronunciation. Maintain a polite and helpful tone. Do not translate or improvise."
  }
}

Parameters:

• model (string): OpenAI TTS model to use (e.g. "gpt-4o-mini-tts")
• voice (string): Voice to use for speech synthesis
• speed (float): Speech playback speed multiplier
• instructions (string): Instructions for the AI voice personality and language

Speech-to-Text Configuration (speech2text)

{
  "speech2text": {
    "model": "gpt-4o-transcribe",
    "streaming": true,
    "instructions": "The audio is an English voice command for a voice assistant. Transcribe only if the speech is clear and logical. Use correct spelling and punctuation. If the audio is unclear, contains noise, or is not valid, return an empty string ''). Do not attempt to guess or translate.",
    "language": "en",
    "noise_reduction": "far_field",
    "audio_logs_path": "",
    "prerecord_beep": "beep7.wav",
    "preprocessing": {
      "min_speech_length": 0.5,
      "high_pass_cutoff_freq": 70.0,
      "declicking": true,
      "noise_supresion_level": 2,
      "agc_enabled": true,
      "vad_aggressiveness": 2,
      "normalization_enabled": true,
      "normalization_target_rms_dbfs": -20.0,
      "normalization_peak_limit_dbfs": -3.0,
      "edge_fade_enabled": true
    }
  }
}

Parameters:

• model (string): OpenAI transcription model to use (e.g. "gpt-4o-transcribe")
• streaming (boolean): Whether to use streaming transcription API. Streaming API is faster but less accurate.
• instructions (string): Instructions for the transcription model on how to process and format the audio input
• language (string): Language code for speech recognition (e.g., "en", "pl")
• noise_reduction (string): Noise reduction setting for audio processing (see OpenAI API documentation for more details)
• audio_logs_path (string): Path to store audio logs; if set, all recorded commands will be saved to disk (empty string disables logging)
• prerecord_beep (string): Audio file to play before recording (from yova_shared/assets/)

Preprocessing Parameters:

• min_speech_length (float): Minimum length of speech to be transcribed (in seconds)
• high_pass_cutoff_freq (float): Cutoff frequency in Hz for high-pass filter
• declicking (boolean): Enable declicking to reduce audio artifacts
• noise_supresion_level (integer): Noise suppression level (0-3, higher = more aggressive)
• agc_enabled (boolean): Enable Automatic Gain Control
• vad_aggressiveness (integer): Voice Activity Detection aggressiveness (0-3, higher = more aggressive)
• normalization_enabled (boolean): Enable audio normalization
• normalization_target_rms_dbfs (float): Normalisation Target RMS level in dBFS for normalization
• normalization_peak_limit_dbfs (float): Normalisation Peak limit in dBFS to prevent clipping
• edge_fade_enabled (boolean): Enable edge fading to reduce audio artifacts

Voice ID Configuration (voice_id)

{
  "voice_id": {
    "enabled": false,
    "include_embedding": false,
    "threshold": 0.267
  }
}

Parameters:

• enabled (boolean): Whether to enable Voice ID
• include_embedding (boolean): Whether to include the embedding in the voice ID payload
• threshold (float): Similarity threshold for speaker verification (0.0 to 1.0)

More details in Voice ID documentation.

Setup Instructions

1. Copy the template:

   cp yova.config.default.json yova.config.json

2. Edit your configuration:

   • Add your OpenAI API key
   • Customize language settings
   • Adjust audio processing parameters
   • Set audio logging path if desired

3. Keep your config private:

   • Never commit yova.config.json to version control
   • The .gitignore file should exclude this file

Available Audio Assets

The following beep sounds are available in yova_shared/assets/:

• beep1.wav through beep11.wav
• test_sound.wav

Audio Processing Tuning

Noise Reduction

• "far_field": Optimized for distant microphones
• Other options may be available depending on the OpenAI model

Speech Detection

• Adjust preprocessing.min_speech_length based on your speaking style

Audio Preprocessing

The preprocessing section contains advanced audio processing parameters:

• High-Pass Filter: high_pass_cutoff_freq removes frequencies below the cutoff
• Declicking: declicking reduces audio artifacts at segment boundaries
• Noise Suppression: noise_supresion_level (0-3) controls noise reduction aggressiveness
• Automatic Gain Control: agc_enabled automatically adjusts audio levels
• Voice Activity Detection: vad_aggressiveness (0-3) controls speech detection sensitivity
• Normalization: normalization_enabled with target RMS and peak limits for consistent audio levels
• Edge Fading: edge_fade_enabled reduces artifacts at audio segment edges

Troubleshooting

Common Issues

1. API Key Errors: Ensure your OpenAI API key is valid and has sufficient credits
2. Audio Quality: Adjust noise reduction, threshold settings, and capture/playback volume for your environment. See Troubleshooting Guide for more details.
3. Language Mismatch: Ensure the language setting matches your speech and instructions