Voice Processing

Relevant source files

The following files were used as context for generating this wiki page:

• core/commands.py
• core/bot.py
• core/helpers.py
• core/integrations.py
• tests/test_commands.py

The Voice Processing system in GeNCorE enables users to interact with the bot using voice messages. It facilitates a Speech-to-Text (STT) workflow that converts audio input into actionable text commands or natural language queries for the AI.

The system serves as a bridge between the Telegram messaging interface and the Groq AI transcription engine. Once a voice message is transcribed, the system determines whether the intent is a specific command—such as image generation—or a general conversation, and routes the request accordingly.

Sources: core/commands.py:228-259, core/bot.py:23-26

Architecture and Data Flow

The voice processing lifecycle begins when the Telegram bot receives a message with the voice content type. The system downloads the audio, processes it through a transcription model, and then executes logic based on the resulting text.

Voice Processing Workflow

The following diagram illustrates the sequence of events from receiving a voice message to executing a command or AI response.

The system ensures that temporary files are cleaned up regardless of whether the transcription succeeds or fails, preventing storage leaks.
Sources: core/commands.py:228-259, tests/test_commands.py:235-256

Implementation Details

Transcription Engine

The system utilizes the Groq client to access the whisper-large-v3 model. This model is responsible for high-accuracy Speech-to-Text conversion.

Component	Specification	Description
Model	whisper-large-v3	High-performance transcription model via Groq API.
File Format	.ogg	The standard format for Telegram voice messages, saved temporarily with a .ogg suffix.
Storage	tempfile.NamedTemporaryFile	Secure, temporary local storage for audio bytes before processing.

Sources: core/commands.py:231-240, core/bot.py:26

Intent Routing

After transcription, the resulting user_text is analyzed for specific keywords. If the text begins with "rysuj" or "/rysuj", the system treats it as an image generation request. Otherwise, it is passed to the standard AI chat history.

user_text = transcription.text
# ...
lowered = user_text.lower().strip()
if lowered.startswith("rysuj ") or lowered.startswith("/rysuj "):
    parts = user_text.split(None, 1)
    prompt = parts[1].strip() if len(parts) > 1 else ''
    m.text = f"/rysuj {prompt}"
    generate_image(m)
else:
    ai_chat(m)

Sources: core/commands.py:244-256

Integration with External Services

Voice processing relies on several integrations to function correctly:

1. Telegram Bot API: Used to retrieve file metadata (get_file) and download the raw voice bytes (download_file).
2. Groq API: Receives the audio file data and returns a JSON object containing the text attribute.
3. Hugging Face (HF): Triggered indirectly if the transcribed text is routed to the generate_image function, using the FLUX.1-schnell model.

Function	File Reference	Logic
handle_voice(m)	core/commands.py	Main entry point for voice messages.
inteligentna_odpowiedz	core/helpers.py	Formats and sends the "Usłyszałem" notification and subsequent replies.
generate_image_hf(prompt)	core/integrations.py	Called if the voice intent is "rysuj".

Sources: core/commands.py:228-259, core/integrations.py:32-55, core/helpers.py:1-18

Error Handling and Cleanup

The system implements a try...except...finally block to ensure robustness:

• Catching Exceptions: Network errors or API failures during transcription are caught, and a "Błąd głosu" message is sent to the user.
• Guaranteed Cleanup: The os.remove(tmp_path) call is placed in a finally block, ensuring the .ogg file is deleted from the server even if an error occurs.

Sources: core/commands.py:257-262, tests/test_commands.py:218-226

Summary

The Voice Processing module provides a seamless hands-free interface for GeNCorE. By combining Telegram's audio delivery with Groq's Whisper transcription and internal command routing, it allows for both conversational AI and specific tool execution (like image generation) via vocal input.