Documentation

Rota AI is distributed as a lightweight desktop application with native builds for Windows, macOS, and Linux. No cloud accounts, registration, or subscriptions are required to run the application.

Windows Installation

1. Download: Obtain the latest executable setup (RotaAI-Setup.exe) from the official website or GitHub Releases.
2. Execution: Double-click RotaAI-Setup.exe.
3. SmartScreen Warning: Because the installer is signed with a self-generated developer certificate, Windows SmartScreen may display a warning:
   • Click "More Info".
   • Click "Run anyway".
4. Setup Process: The installer will install Rota AI directly into your local user directory:

   %LOCALAPPDATA%\Programs\RotaAI\
   

   Note: Administrator privileges are not required for this installation path.
5. Autostart: The installer will register Rota AI in your Startup registry key:

   HKCU\Software\Microsoft\Windows\CurrentVersion\Run
   

6. Microphone Permissions: Windows 10/11 requires permission for desktop applications to access your microphone. If transcription fails on launch, verify this in:
   • Settings > Privacy & security > Microphone (Ensure "Let desktop apps access your microphone" is toggled ON).

macOS Installation

1. Download: Download the Apple Silicon or Intel variant (RotaAI-macOS.zip / RotaAI-macOS-x64.zip).
2. Decompress: Double-click the ZIP archive to extract RotaAI.app.
3. Move to Applications: Drag RotaAI.app to your /Applications directory.
4. Gatekeeper Bypass (First Run): Because the app is not currently signed and notarized via an active Apple Developer ID program, double-clicking it normally will show a warning: "RotaAI.app is damaged and can’t be opened." or "macOS cannot verify the developer..."
   • To bypass, Right-click / Control-click on RotaAI.app in the Applications folder and choose Open.
   • In the security dialog that appears, click Open. macOS will cache this exception.
5. System Permissions: Rota AI requires two system permissions to function:
   • Accessibility: Needed to intercept the global hotkey (F9) and inject text into the active app.
   • Microphone: Needed to capture the audio stream. Both prompts will appear on launch. If missed, enable them manually under System Settings > Privacy & Security.

Linux Installation

1. Download: Download the portable AppImage: RotaAI.AppImage.
2. Permit Execution: Open a terminal and grant execution rights:

   chmod +x RotaAI.AppImage
   

3. Execute: Double-click the file or run it via terminal:

   ./RotaAI.AppImage
   

4. Integration: If you want system-wide desktop integration (.desktop shortcut):
   • Move the AppImage to ~/.local/bin/ or /usr/local/bin/.
   • Create a desktop entry at ~/.local/share/applications/rota-ai.desktop pointing to the AppImage path.
5. Wayland Support: For Wayland compositors (GNOME, Sway, Hyprland), ensure wtype or dotool is installed on your host system:

   # Ubuntu/Debian
   sudo apt install wtype
   
   # Fedora
   sudo dnf install wtype
   
   # Arch Linux
   sudo pacman -S wtype
   

Start dictating with Rota AI in less than 2 minutes by following this step-by-step setup guide.

Step 1: Initial Launch

When you open Rota AI for the first time, you will be greeted by the Onboarding Wizard. This wizard configures the application essentials:

1. Choose a Backend: Select your starting transcription processor.
   • Groq is the fastest and highly recommended if you have an active internet connection.
   • Ollama runs entirely local but requires downloading models.
2. Setup your API Key: If using Groq or Gemini, copy-paste your free API Key.
3. Select Microphone: Choose your input audio source. Click Test Mic to speak and see the audio levels peak.
4. Choose Hotkey: By default, the recording key is bound to F9.

Step 2: The Core Workflow

Now that Rota AI is running, it will sit silently in your OS system tray (bottom-right on Windows/Linux, top-bar on macOS).

1. Focus a Text Area: Click inside any application where you want to write text (e.g., Slack, Notepad, VS Code, or an email).
2. Press F9:
   • A modern, glowing visual indicator (recording pill) will appear on screen.
   • The application will immediately begin capturing audio from your microphone.
3. Speak Naturally: Say what you want written. You do not need to pause or pronounce robotically. You can say punctuation explicitly (e.g., "Let's plan for Monday comma and write the code period").
4. Press F9 Again:
   • The recording will stop.
   • Rota AI processes the speech in the background, applies your LLM cleanup settings, and types the output directly at your cursor location.

Tips for Perfect Dictation

• Punctuation Commands: Say "new line" to start a new line, or "new paragraph" to create a double-space separation.
• Volume: Keep a natural speaking volume. You don't need to speak directly into the microphone capsule.
• Canceling: If you make a mistake and want to abort the current recording without typing it, hit the Escape key on your keyboard while recording is active.

Rota AI is optimized to run with low memory and CPU footprints. However, your requirements depend heavily on whether you choose a Cloud Backend or a Local Offline Backend.

Minimum Specifications (Cloud-Only Backend)

If you use Groq or Gemini API keys, all transcription and cleaning calculations are offloaded to high-performance cloud hardware.

Minimum Specifications (Local Offline Backend)

If you configure Rota AI to use Ollama for offline transcription, the heavy neural network models run directly on your hardware.

Rota AI provides modular support for cloud and local AI engines. You can configure and toggle between these backends dynamically inside the Settings > Transcription panel.

Backend Data Routing Flow

1. Groq Cloud (Recommended for Speed)

Groq utilizes LPU (Language Processing Unit) accelerators to deliver sub-second transcription times using OpenAI's Whisper Large v3 model.

• Latency: ~300ms - 600ms (depending on network speed).
• Setup Requirements:
  1. Register for an account at console.groq.com.
  2. Navigate to API Keys and generate a new key (gsk_...).
  3. Paste the key into Rota AI Settings under Groq Backend.
• Limitations: Subject to Groq's API rate limits (tokens-per-minute and requests-per-minute), which are generous on their free tier.

2. Gemini Cloud (Highly Accurate)

Google's Gemini speech recognition API is ideal for technical vocabulary, non-standard spelling, and non-English speakers.

• Latency: ~800ms - 1.5s.
• Setup Requirements:
  1. Visit Google AI Studio.
  2. Click Get API Key and generate a key for a new or existing Google Cloud project.
  3. Paste the key into Rota AI Settings under Gemini Backend.
• Feature Set: Gemini performs excellent multi-language auto-detection out of the box.

3. Ollama (Local & Air-Gapped)

Ollama runs transcription models locally on your system hardware. This is the ultimate option for developers processing proprietary code, sensitive emails, or working in remote environments.

• Latency: ~1.5s - 5.0s (highly dependent on CPU/GPU hardware).
• Prerequisites:
  • Install Ollama from ollama.com.
  • Pull your preferred Whisper model from the command line:

    # Choose one:
    ollama pull whisper-small    # ~480MB, fast, low resource use
    ollama pull whisper-large    # ~3.1GB, highly accurate, slower
    

• Integration: Rota AI automatically detects active local Ollama instances on port 11434 and uses them to process transcription.

Voice snippets allow you to bind long, complex blocks of text to a spoken trigger word. During the post-transcription cleaning pass, Rota AI will look for these trigger words and immediately replace them with the expanded text.

How to Create a Snippet

1. Open Rota AI Settings and navigate to the Snippets tab.
2. Click Add Snippet.
3. Fill in the fields:
   • Trigger Phrase: The word or short phrase you will speak (e.g., "my signature"). Keep triggers distinct and easy for Whisper to hear.
   • Expansion Text: The raw text that should be pasted (supports newlines and formatting).
4. Click Save.

Examples of Useful Snippets

Configuration Rules

• Trigger Prefixes: By default, Rota AI watches for trigger words preceded by a command prefix like "insert" or "paste" (e.g., saying "insert email" instead of just "email"). This prevents accidental expansions during normal dictation. You can customize or disable this prefix in the Settings menu.
• Storage: Snippets are stored locally inside the application's SQLite database (snippets table) and are loaded into memory on startup for zero-latency lookup.

Automatic Speech Recognition (ASR) models like Whisper often struggle with industry-specific terminology, specialized API commands, brand names, or regional nouns (e.g., typing "next JS" instead of "Next.js").

To solve this, Rota AI features a multi-tiered Personal Dictionary system. It guides the Whisper model's token sampling, instructs the post-processing LLM cascade, applies hard local regex replacements, and automatically learns new terms from your dictation history.

Dictionary Override Flow

The following diagram illustrates the horizontal sequence of Rota AI's override pipeline, from raw audio input to final text output injection:

Core Components

1. Configuration & Storage

Your personal dictionary consists of two data sets stored in your local application directory:

• dictionary.json: Explicit word overrides and custom terminology mappings defined by you in the UI.
• personal_dictionary.json: An auto-growing vocabulary cache built dynamically by the Auto-Learning Engine.
• Directory Paths:
  • Windows: %APPDATA%/RotaAI/
  • macOS: ~/Library/Application Support/RotaAI/
  • Linux: ~/.local/share/rota-ai/

2. The Auto-Learning Engine

Every time Rota AI finishes cleaning a transcript, it runs a background worker (learn_from_text()) to scan the polished text and extract notable terms.

• Extraction Rules:
  • Proper Nouns: Capitalized words that do not appear at the start of a sentence (e.g., "Vercel", "TypeScript").
  • Acronyms: Fully capitalized tokens of 2+ characters (e.g., "API", "JSON", "ASR").
  • Technical Identifiers: Words containing underscores, dots, or camelCase/PascalCase syntax (e.g., "main_window.py", "sounddevice", "rx="6"").
• Storage Limits:
  • The local database caps auto-learned entries at 500 terms to keep performance optimal.
  • When the cap is reached, Rota AI prunes the least-frequently-used terms that only have a single occurrence.

Backend Data Routing Pipeline

When you press the global dictation hotkey (F9), Rota AI routes your vocabulary context through three distinct correction layers:

Layer 1: ASR Prompting (Whisper Hinting)

When recording starts, the main controller loads all manual and learned terms and serializes them into a comma-separated list. This list is passed as the prompt parameter to the Whisper API or local CTranslate2 model.

[!NOTE] The ASR prompt guides the decoder's beam search, making the model far more likely to transcribe phonetically similar sounds as your customized terms.

Layer 2: LLM Post-Processing (Context Injection)

The top 50 terms are dynamically appended to the post-processing LLM system prompt under a ## PERSONAL VOCABULARY header. This instructs the cascade (Gemini, Groq, or Ollama) to check spelling and casing against your personal dictionary during grammar cleaning.

Layer 3: Local Regex Normalizer (Hard Replacements)

If the cloud model fails to correct a word, a local normalizer does a case-insensitive regex substitution sweep over the text using your explicit dictionary mappings right before typing the text into the active window.

Managing Terms in the UI

1. Open Rota AI and navigate to Settings > Dictionary.
2. Click Add Word to manually register custom terms.
3. Provide:
   • Spoken Word / Target: How the word sounds or how Whisper usually misbehaves (e.g., "rota ai", "roll tab").
   • Replacement / Preferred Casing: The exact casing and punctuation you want typed (e.g., "Rota AI").
4. Manual entries are given an immediate high weight (+10) in the database so they are never pruned.

This section documents all configuration options available in the Rota AI configuration database. These settings are persisted locally in config.json.

Audio Settings

Configure the parameters for sound capture and silent space stripping.

• Input Device: The active system microphone. Choosing "Default System Device" dynamically tracks OS settings.
• Sample Rate: Locked to 16000 Hz (Whisper models are trained strictly on 16kHz mono audio).
• VAD Sensitivity: The sensitivity threshold for the Silero Voice Activity Detector.
  • Range: 0.1 (very sensitive) to 0.9 (ignores quiet talking). Default is 0.5.
• VAD Padding (ms): The duration of padding silence to keep before and after a speech chunk is detected. Keeps speech boundaries from clipping. Default is 300ms.

Transcription & Models

Configure the speech-to-text engines.

• Backend: Choice between Groq, Gemini, or Ollama.
• Model Size:
  • Cloud: Defaults to whisper-large-v3-turbo.
  • Local (Ollama): Choice between whisper-base, whisper-small, or whisper-large.
• Primary Language: Explicitly set the language ISO code (e.g., en, es, fr, de) to skip the ASR language detection phase, shaving ~200ms off transcription latency.

Injection & Paste Options

Controls how processed text is returned to the operating system.

• Injection Method:
  • Direct Input: Simulates hardware keyboard presses. Safe for all apps but slow for large texts.
  • Clipboard Paste: Copies the text to the clipboard and sends a virtual Ctrl+V (or Cmd+V) hotkey. Virtually instant.
  • Auto: Uses Direct Input for less than 200 characters and Clipboard Paste for larger inputs.
• Injection Delay (ms): Pause interval between key events. If letters appear scrambled or skipped in laggy applications (like remote desktops), increase this to 10ms.

The core workflow of Rota AI is designed to replace keyboard typing with fast, hands-free voice dictation without breaking your active focus.

Operation Modes

You can trigger dictation using two interaction patterns on your configured hotkey (default: F9):

1. Press-and-Hold (Default):
   • Press and hold F9. Keep it held down while speaking.
   • Release the key as soon as you finish talking.
   • Recording stops immediately, and text is processed and pasted.
2. Tap-to-Toggle:
   • Tap F9 once to start recording. The pill overlay appears.
   • Speak your text.
   • Tap F9 again to stop recording.

Recording States and UI Indicators

When recording, Rota AI displays a floating, semi-transparent overlay pill on screen. The pill changes colors to indicate the audio capture state:

• 🟩 Green / Pulse: Actively listening and capturing microphone inputs.
• 🟨 Yellow: Silero VAD has detected silence, indicating you have paused speaking.
• 🟦 Blue: Uploading audio buffer to transcription engine.
• ⚙️ Spinning Wheel: Running the post-transcription LLM cleanup pass.

Punctuation Control

ASR models are highly proficient at auto-punctuating sentences. However, for precise formatting, speak the punctuation commands out loud:

• Say "period", "comma", or "question mark" for standard punctuation.
• Say "new line" or "line break" to insert \n.
• Say "new paragraph" to insert \n\n.
• Say "open quote" and "close quote" for quotation marks.

Rota AI features an advanced Voice Command Engine. By speaking specific key-phrases, you can instruct the post-transcription LLM pass to execute text modifications, formatting tasks, or translations.

Invocation Pattern

To run a command, speak the trigger phrase naturally at the end of your recording, or record a command immediately after a prior dictation.

Standard Command Registry

Custom Editing Commands

Because the backend uses an LLM (Gemini or Llama), you are not limited to fixed commands. You can command Rota AI to perform freeform text updates by starting your command with action verbs:

• "Change the deadline to Friday"
• "Wrap this in a python try except block"
• "Correct my spelling but keep it short"
• "Make this sound like an email subject line"

Rota AI features intelligent Context Awareness. The application constantly tracks which desktop window has active keyboard focus and passes this context metadata (e.g., application class, executable name, window title) to the LLM cleanup layer.

The LLM adapts its formatting instructions to match the target environment.

App-Specific Formatting Rules

1. Software Development (VS Code, Cursor, Terminal, JetBrains)

When a code editor or terminal is in focus, the cleanup pass prioritizes programming formatting:

• Preserves programming casing: camelCase, snake_case, kebab-case.
• Formats code keywords correctly (e.g., typing try except, async await, import statements).
• Prevents auto-capitalization at the start of lines to avoid syntax errors.
• Keeps technical commands like git checkout -b main in raw monospace formatting.

2. Chat and Messaging (Slack, Discord, Teams, Telegram)

When a chat application is in focus:

• Keeps formatting relaxed and conversational.
• Uses appropriate contractions (don't, can't, it's).
• Employs inline markdown for emphasis (*italic*, **bold**).
• Strips formal email greetings and signatures.

3. Professional Writing (Word, Outlook, Notion, Gmail)

When a word processor or email client is in focus:

• Automatically adds formal greetings or closings if dictated.
• Uses formal punctuation, capitalization, and complete sentences.
• Expands common abbreviations.

Privacy & Security Note

Window detection is performed entirely locally on your device. The active window detection code queries standard OS-level accessibility APIs:

• Windows: GetForegroundWindow and UI Automation APIs.
• macOS: NSWorkspace.shared.frontmostApplication and AXUIElement APIs.
• Linux: AT-SPI / xdotool window querying APIs.

Only the name of the application and the title of the window are sent to your configured transcription/LLM backend during the cleaning call.

Rota AI can be configured to run completely offline with zero telemetry and zero network calls, guaranteeing absolute data privacy.

Step-by-Step Offline Setup

1. Install Ollama

Download and run the installer for your platform from ollama.com.

2. Download Whisper Models

Open a terminal (Command Prompt, PowerShell, or bash) and pull the Whisper model sizes you wish to use:

# Pull Whisper Small (480MB weights - fast, balanced accuracy)
ollama pull whisper-small

# Pull Whisper Large (3.1GB weights - highly accurate, requires GPU)
ollama pull whisper-large

3. Download LLM Clean-up Models (Optional)

If you want local AI cleanup, download a lightweight LLM such as Llama 3.2 1B or 3B:

ollama pull llama3.2:3b

4. Configure Rota AI Settings

1. Open Rota AI Settings > Transcription.
2. Set the Backend dropdown to Ollama.
3. Set the Model to matching name, e.g., whisper-small.
4. (Optional) Go to Settings > AI Cleanup, select Ollama as the cleanup processor, and input the model name llama3.2:3b.
5. Save changes.

Offline vs Cloud Performance

This guide details configuration, troubleshooting, and internal details for running Rota AI on Microsoft Windows 10 and 11.

Windows Execution Flow

Prerequisites

• Windows 10 (Build 19041+) or Windows 11.
• Microsoft Visual C++ Redistributable (normally installed automatically).

Internal Hooks & Implementation Details

1. Keyboard Hooks (Hotkey Listener)

On Windows, Rota AI utilizes pynput which hooks into the low-level Windows keyboard driver using standard Win32 hooks:

• API: SetWindowsHookExW with WH_KEYBOARD_LL.
• Because the key listener is global, it can capture key events even when Rota AI is minimized or in the background.

2. Text Injection

Text injection on Windows is handles by two methods depending on text length:

• Direct Input (SendInput): Simulates virtual keystrokes using SendInput. This sends raw virtual keycodes down the Windows message pump.
• Clipboard Paste: For strings larger than 200 characters, Rota AI stores the string in the Windows clipboard (OpenClipboard -> SetClipboardData), sends a virtual keyboard combo of Ctrl+V, and restores the original clipboard content after a brief delay.

Troubleshooting Windows Quirks

1. Hotkey Fails in Administrator Apps

If you focus an application running as Administrator (e.g., Command Prompt, Task Manager, or Visual Studio run as Admin), pressing F9 may not trigger dictation, or the text might not inject.

• Cause: Windows User Account Control (UAC) blocks user-level processes from sending keystrokes or listening to hotkeys inside elevated windows.
• Solution: Right-click the Rota AI shortcut/executable and select Run as administrator.

2. Audio Latency / PortAudio Errors

If you see logs mentioning PortAudio error: Device unavailable or experience crackly recording:

• Go to Windows Settings > Sound > Properties of your microphone.
• Ensure the Format is set to 16-bit, 44100 Hz or 16-bit, 48000 Hz.
• Disable any "Audio Enhancements" or "Spatial Sound" filters which can interfere with raw buffer capture.

This guide covers setup, permissions, and troubleshooting for Rota AI on macOS 13 (Ventura) and macOS 14 (Sonoma).

macOS Execution Flow

Permissions Checklist

Because macOS implements strict sandboxing, Rota AI requires explicit OS permissions to capture keys and insert text.

1. Accessibility API Access

The accessibility API is required for Rota AI to:

• Intercept the global hotkey (F9) in the background.
• Query the active window's identity.
• Inject text at the current text cursor.

To Enable:

1. When Rota AI launches, a system prompt will ask you to open System Settings.
2. Go to System Settings > Privacy & Security > Accessibility.
3. Locate RotaAI in the list and toggle the switch to ON.
4. If it's already ON but not working, click the minus (-) button to remove RotaAI, restart Rota AI, and re-enable it when prompted.

2. Microphone Access

Required to capture raw audio from your selected input device.

To Enable:

1. Go to System Settings > Privacy & Security > Microphone.
2. Find RotaAI and ensure the toggle is active.

Internal Implementation Details

1. Hotkey Interception

On macOS, Rota AI binds key events using the Quartz event system:

• API: CGEventTap is created via Quartz framework (CoreGraphics).
• It captures key down and key up events globally and translates them into UI actions.

2. Text Injection

macOS uses the Accessibility framework and AppleScript paste commands to inject text:

• AXUIElement: Rota AI tries to locate the active focused text element using accessibility reference hooks. If the element exposes writing properties, Rota writes directly to the element's value property.
• AppleScript / NSPasteboard Fallback: If the active application blocks accessibility inputs (like some terminal emulators), Rota copies the text to NSPasteboard, calls an AppleScript to execute a virtual Cmd+V, and restores the clipboard state.

This guide covers system dependencies, hotkey listeners, text injection configuration, and troubleshooting for Rota AI on Linux.

Linux Execution Flow

Wayland vs X11 Display Server Setup

Linux systems use either the X11 or Wayland display server protocol. Because Wayland has strict security barriers that block apps from sniffing keys or injecting text globally, setup varies by environment.

1. X11 Environments (Ubuntu, Mint, Debian, etc.)

Under X11, Rota AI works out of the box:

• Hotkey: Listens using pynput via standard Xlib keyboard capture.
• Injection: Injects text using xdotool to simulate key presses or execute a virtual paste command.

2. Wayland Environments (Fedora, Ubuntu 22.04+, Arch, etc.)

Under Wayland, traditional key sniffing and injection tools are blocked. Rota AI uses the following workarounds:

• Hotkey Hook: Listens using /dev/input/ events via the evdev Python library.
  • Note: Reading /dev/input/ requires your user account to be a member of the input group.

    sudo usermod -aG input $USER
    # Log out and log back in for changes to take effect.
    

• Text Injection: Rota AI utilizes wtype (Wayland type tool) or dotool. Install wtype via your package manager:

  sudo apt install wtype      # Ubuntu/Debian
  sudo dnf install wtype      # Fedora/RHEL
  sudo pacman -S wtype        # Arch Linux
  

Keyboard Injection Fallbacks

If wtype is not supported on your compositor:

1. Open Rota AI Settings > Injection.
2. Change the method to Clipboard Paste Fallback.
3. Rota AI will write to the primary clipboard using xclip or wl-copy and send a virtual keypress combination.

Rota AI is a cross-platform desktop voice-dictation assistant designed for speed, modularity, and privacy. The application is built using a layered architecture that decouples the UI layer from the background audio processing pipeline, platform-specific operating system hooks, and AI transcription interfaces.

High-Level Architectural Layers

1. UI Layer (ui/)

• Written in PyQt6 (Qt 6 bindings for Python).
• Uses customized QSS (Qt Style Sheets) to render a dark-themed interface, featuring smooth transitions, window-blur effects (Windows DPAPI/acrylic), and a floating recording overlay pill.

2. App Logic & Wiring (app/)

• Orchestrates startup health checks, database seeding, logging configurations, and single-instance locks.
• Integrates Mixins to separate concerns (e.g., RecordingStateMixin, HotkeyMixin, TranscriberMixin, and ProcessingPipelineMixin).

3. Platform Abstraction Layer (plat/)

• Bridges OS differences. All code outside this directory is OS-agnostic.
• Employs dynamic imports to load platform-specific modules at runtime based on the target OS.

4. Audio Pipeline (audio/)

• Interlaces audio capturing, voice activity detection, and transcription engines.

5. Data & Storage Layer (data/ / services/)

• Config manager handles configuration reads and writes.
• Local SQLite database caches transcription history and snippet mappings.

Complete Start-to-End Application Lifecycle

To help visualize how all these layers and subsystems interact from initialization to final text injection, here is the full start-to-end execution path:

class RotaApp(QApplication):
    def run(self):
        # Initialize thread lifecycle mixins
        self.init_instance_guard()
        self.init_database()
        self.init_tray_ui()

        # Start global hotkey listener
        self.start_hotkey_listener()

        # Start PyQt6 event loop
        sys.exit(self.exec())

The audio pipeline handles the life cycle of voice data, transforming raw acoustic microphone signals into clean text injected directly into your focus application.

Step-by-Step Execution Flow

Detailed Phase Explanations

1. Microphone Ingest (audio/recorder.py)

• Rota AI utilizes sounddevice (which wraps PortAudio) to establish an input stream.
• Audio is recorded as a single-channel (mono), 32-bit floating-point PCM stream sampled at exactly 16,000 Hz.

2. Real-Time Voice Activity Detection (audio/vad.py)

• Rota AI integrates Silero VAD v6 running locally via onnxruntime.
• As the microphone captures audio, it is split into 30ms chunks (480 samples).
• The VAD model returns a probability score of speech. If the score peaks above the VAD_THRESHOLD (default: 0.5), it is flagged as active speech.
• Padding Buffer: 300ms of audio before and after speech chunks are preserved to avoid clipping the start or end of sentences.

3. Transcription Phase (audio/transcriber.py)

• The compiled WAV buffer is sent to your selected backend.
• Local transcription uses faster-whisper (CTranslate2 framework), wrapping quantized Whisper models in 8-bit integer formats (int8) for GPU or CPU speed.
• Cloud backends stream raw WAV files inside multipart-form payloads.

4. LLM Cleaning Pass (ai/ai_processor.py)

• The raw transcription is processed by an LLM cleaning prompt.
• System Prompting: Instructs the LLM to strip filler words ("um", "uh"), correct speech disfluencies, and format text based on the active window title.
• Context Injection: The prompt is updated dynamically with variables like {window_title} and {app_name} to guide the formatting engine.

To maintain a responsive UI at 60 FPS (preventing the floating recording pill or settings window from freezing), Rota AI segregates UI operations, global keyboard listening, and deep learning transcription workloads into separate execution threads.

Thread Allocations

1. Main GUI Thread

• Responsibility: Manages the PyQt6 event loop, renders all UI components (Tray icon, Settings pages, History dashboard, Overlay recording indicator), and receives execution signals from background workers.
• Constraint: Must never perform blocking network requests, file reads, or AI modeling calculations. Any block > 16ms causes UI stuttering.

2. Global Hotkey Listener Thread (Daemon)

• Responsibility: Listens for system-wide key presses (F9, Esc) globally.
• Mechanism: Spawned on startup as a background Python daemon thread. It runs a blocking keyboard event loop using:
  • Windows: Win32 hook thread.
  • Linux: evdev file reader event loop.
  • macOS: CGEventTap CoreGraphics listener.
• Communication: Emits a custom callback/signal to the Main Thread when the trigger key combination is pressed.

3. Background Model Loader Thread (QThread)

• Responsibility: Preloads local Whisper models (when using Ollama or faster-whisper fallbacks) on startup.
• Mechanism: Implemented using PyQt's QThread. Once the model weights are loaded into VRAM or system memory, it emits a signal to enable local dictation mode.

4. Processing Pipeline Worker Thread (ProcessorThread)

• Responsibility: Handles VAD slicing, connects to APIs, waits for LLM cleaning cycles, and executes local translation.
• Mechanism: A new ProcessorThread (subclass of QThread) is queued when recording stops. It executes synchronously in the background, emitting step signals (transcribing, cleaning, finished) back to the main thread to update the overlay pill animation.

Thread Safety Rules

• No Direct Widget Updates: QWidgets and Qt layouts must only be modified from the Main GUI thread. Calling .setText(), .show(), or .hide() on a widget from inside ProcessorThread will trigger a segmentation fault.
• PyQt Signals/Slots: Thread communication is handled strictly via PyQt Signals. Qt automatically queues these signals across thread boundaries safely.

Rota AI features a robust cross-platform codebase. Platform-specific API calls (like writing to the Windows registry vs. macOS plist, or capturing keys on Linux wayland vs. Windows DLLs) are completely abstract behind a common interface in the plat/ module.

Code outside the plat/ directory is 100% OS-agnostic.

The Abstraction Gateway (plat/__init__.py)

On startup, the system imports sys.platform and exposes factory functions that dynamically import and return the appropriate OS-specific classes.

import sys

IS_LINUX = sys.platform.startswith("linux")
IS_WINDOWS = sys.platform == "win32"
IS_MACOS = sys.platform == "darwin"

def get_hotkey_handler():
    if IS_LINUX:
        from plat.linux_hotkey import HotkeyHandler
        return HotkeyHandler
    elif IS_MACOS:
        from plat.macos_hotkey import HotkeyHandler
        return HotkeyHandler
    else:
        from audio.hotkey import HotkeyHandler
        return HotkeyHandler

Platform Implementation Map

Rota AI is designed under a local-first security architecture. No analytical tracking telemetries exist, and all personal user configurations, voice snippets, dictation history logs, and API credentials are kept strictly on your local machine.

Local SQLite Database

Rota AI stores your structured history logs and snippet shortcuts inside a local SQLite database named rota.db under the OS-appropriate storage directory.

Database Schema Details

1. Table: history

Caches raw transcriptions, AI-cleaned transcriptions, date stamps, and application metadata.

CREATE TABLE history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    raw_text TEXT NOT NULL,
    cleaned_text TEXT NOT NULL,
    app_name TEXT,
    window_title TEXT,
    backend TEXT
);

2. Table: snippets

Stores triggers and text expansion templates.

CREATE TABLE snippets (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    trigger_phrase TEXT NOT NULL UNIQUE,
    expansion_text TEXT NOT NULL
);

Encrypted API Credential Storage

To prevent malware or unauthorized scripts from scraping your cloud API keys (Groq/Gemini), Rota AI encrypts your configuration file and API secrets at rest using platform-native hardware encryption mechanisms.

1. Windows: Data Protection API (DPAPI)

On Windows, keys are encrypted using DPAPI (win32crypt.CryptProtectData).

• Security Model: The key is encrypted using the Windows User Account credentials. Only processes running under your specific Windows login session can decrypt the data. Even if files are stolen off the disk, they cannot be decrypted on another machine.

2. macOS: Keychain Services

On macOS, keys are stored in the secure macOS System Keychain.

• Security Model: Access permissions are controlled by the OS. The first time Rota AI queries the Keychain, a macOS security popup asks you to grant Rota permission to read the Keychain key.

3. Linux: Secret Service API

On Linux, Rota AI connects to the standard D-Bus Secret Service provider (e.g., GNOME Keyring or KWallet) via the Python keyring module.

• Security Model: The database is encrypted using your user login session keyring, unlocked automatically when you sign into your desktop.

Rota AI is an open-source project hosted on GitHub. Follow this guide to clone the source code and prepare your workspace.

Prerequisites

Before cloning, ensure you have the following version control tools installed on your development machine:

• Git: git-scm.com
• Git LFS (Large File Storage): Some model weights and binary files are stored using Git LFS. If not installed, run:
  • macOS: brew install git-lfs
  • Linux: sudo apt install git-lfs / sudo dnf install git-lfs
  • Windows: Included with the official Git installer.

Cloning the Repository

Open a terminal or command prompt and clone the repository along with its submodules:

# Clone the main repository
git clone https://github.com/krthik20050/Rota-AI.git

# Navigate into the project folder
cd Rota-AI

# Initialize Git LFS (pulls down compressed files)
git lfs install
git lfs pull

Folder Layout Reference

The project root has a double-tier layout:

• /desktop: The Python source codebase for the desktop application.
• /website: The Next.js/Tailwind CSS project for the web landing page and documentation engine.
• /tests: Python unit tests and functional test suites.
• /docs: Project developer guides and architectural specifications.

Follow these instructions to set up a Python virtual environment and run the Rota AI desktop application locally from the source files.

Local Environment Setup Flow

Step 1: Python Version Check

Rota AI requires Python 3.12+. Verify your active version:

python --version

Step 2: System Dependency Installation

macOS

Install PortAudio (needed for recording microphone signals) and pkg-config:

brew install portaudio pkg-config

Linux (Debian/Ubuntu)

Install PortAudio headers and compilation dependencies:

sudo apt update
sudo apt install python3-dev build-essential portaudio19-dev libasound2-dev

Windows

No extra installation is required; the raw PortAudio wheels are built-in inside the Python sounddevice Windows binary package.

Step 3: Set Up a Virtual Environment

Create and activate a Python virtual environment inside the desktop/ directory:

# Navigate to desktop source directory
cd Rota-AI/desktop

# Create virtual environment
python -m venv .venv

# Activate - Windows (Command Prompt)
.venv\Scripts\activate.bat

# Activate - Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Activate - macOS / Linux
source .venv/bin/activate

Step 4: Install Dependencies

With the virtual environment active, install the required packages:

# Update pip to latest
python -m pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

Step 5: Running Rota AI

Launch the desktop app using the launcher script or Python:

# Standard Python launch
python app/main.py

Note: On first launch, the app will create the SQLite database rota.db inside your OS app-data directories and compile the default settings.

Rota AI uses PyInstaller to compile the Python source code, Qt files, and Whisper model libraries into a single, executable native application.

Windows Build & Installer Compilation

1. Setup PyInstaller

Activate your virtual environment and run PyInstaller with the spec file:

pip install pyinstaller
pyinstaller RotaAI.spec

This outputs a standalone folder structure at dist/RotaAI/ containing the compiled binary assets.

2. Create the Setup Installer (Inno Setup)

To compile the standalone folder into a single RotaAI-Setup.exe wizard:

1. Install Inno Setup 6.
2. Right-click installer.iss in the root directory and select Compile Script.
3. The setup executable will be written to /dist/.

macOS Application Bundling

To create the macOS .app bundle:

1. Run PyInstaller on macOS:

   pyinstaller RotaAI-macOS.spec
   

2. Compress the output for distribution:

   cd dist
   zip -r RotaAI-macOS.zip RotaAI.app
   

Linux AppImage Compilation

To build a portable Linux AppImage:

1. Execute the build-linux helper script:

   chmod +x scripts/build-linux.sh
   ./scripts/build-linux.sh
   

2. This script retrieves appimagetool, bundles Python and PortAudio libraries, gathers the desktop shortcut configurations, and writes RotaAI-x86_64.AppImage to the output folder.

We welcome contributions to Rota AI! To maintain code quality, security, and stability, please adhere to these guidelines.

Code Quality Standards

• Linter: We use ruff to enforce PEP 8 styles and import sorting. Run ruff check . inside /desktop before committing.
• Typing: Use standard Python type hinting (typing module) for all function arguments and return signatures.
• Error Handling: Never swallow exceptions with naked except: statements. Log errors using our structured logging system:

  from utils.log import get_logger
  logger = get_logger(__name__)
  
  try:
      # Code...
  except Exception as e:
      logger.exception("Descriptive error message", extra={"correlation_id": "xyz"})
  

Testing Protocol

Before submitting a Pull Request, run the unit test suite to verify no regressions occurred:

# From Rota-AI/desktop
pytest tests/

If you add a new service or platform hook, you are required to write matching tests under /desktop/tests/.

Pull Request Lifecycle

1. Fork the repository and create a new feature branch (e.g., feature/improved-linux-hotkey).
2. Implement your changes. Write comprehensive comments detailing what the change does and why it was designed that way.
3. Verify formatting using ruff format ..
4. Ensure all tests pass.
5. Push to your fork and open a Pull Request. The CI actions will test your code across Windows and Linux environments.

Rota AI provides system-wide keyboard hotkeys. You can trigger them from inside any running application.

Default Hotkey Registry

Customizing Hotkeys

To rebind a shortcut:

1. Open the Rota AI UI dashboard.
2. Go to Settings > Hotkeys.
3. Click inside the text box corresponding to the shortcut you want to change.
4. Press the new combination on your keyboard (e.g., Ctrl+Alt+Space or F10).
5. Click Save.

Privacy is not an add-on; it is the core architectural principle of Rota AI. The desktop application is designed to give you complete ownership over your speech data.

Key Privacy Pillars

1. Zero Telemetry & Analytics

• Rota AI has no embedded tracking codes, analytics scripts, crash-reporting aggregators (like Sentry or Bugsnag), or analytics packages.
• The application never reports back on your usage counts, words typed, or average session times.

2. Local SQLite DB Storage

• Your dictation history is stored entirely in a local SQLite file (rota.db).
• History stays on your hard drive. Rota AI provides no cloud synchronizations, which protects you from database leaks or server-side intrusions. You can purge your history database anytime inside the settings page.

3. Encrypted Credentials

• All cloud API tokens (Groq or Gemini keys) are encrypted locally using hardware keys tied to your specific user profile (DPAPI on Windows, macOS Keychain, or Linux Secret Service via D-Bus).
• Unauthorized local apps or scripts cannot access or decrypt your credentials.

4. Absolute Data Routing Control

• You choose where your voice data goes:
  • If you configure Groq or Gemini, audio files are sent over encrypted HTTPS to their APIs. You can view their developer data policies (both guarantee developer payload data is not used for model training).
  • If you configure Ollama, audio files are sent only to the local network port 127.0.0.1. No voice or text data ever leaves your computer.

Here are answers to the most common questions regarding Rota AI.

Is Rota AI really free?

Yes. Rota AI is fully open-source under the permissive MIT License. There are no premium features, no subscription paywalls, and no hidden charges.

Do I need a credit card or cloud account to get started?

No. You do not need any credit card or Rota account. If you choose a cloud backend like Groq or Gemini, you will need to sign up for their developer console platforms to generate a free API key.

Can I dictate in languages other than English?

Yes. Rota AI supports multi-language transcription:

• Under Groq and Gemini, Whisper supports over 99 languages (including Spanish, French, German, Mandarin, Portuguese, Hindi, etc.).
• Under Ollama, make sure you pull a multi-language model version (like whisper-small or whisper-large).

Does Rota AI run inside fullscreen games or software?

It depends on how the software renders:

• In borderless windowed or windowed applications, the floating recording overlay pill displays correctly.
• In exclusive fullscreen mode (like some 3D video games), the OS graphics layer blocks external application overlays from drawing on top. Dictation will still capture audio and inject text, but you won't see the visual recording indicator.

This guide helps you diagnose and resolve common issues encountered while running Rota AI.

Issue 1: Nothing happens when I press F9

Windows Diagnostics

1. Check your system tray. Verify that the Rota AI icon is visible (or check your Task Manager to make sure app/main.py or RotaAI.exe is active).
2. Verify that your microphone is set as the active device and is not hardware-muted.
3. Check permissions under Settings > Privacy & security > Microphone and ensure desktop apps are allowed.
4. Try running Rota AI as Administrator (UAC blocks input events in elevated applications).

macOS Diagnostics

1. Open System Settings > Privacy & Security > Accessibility.
2. Turn RotaAI off and back on.
3. Verify the same settings under Privacy & Security > Microphone.

Issue 2: Text is scrambled or typed out-of-order

If you notice that output text is missing letters, capitalization is random, or sentences are mixed up:

1. Open Settings > Injection.
2. Increase the Injection Delay from 0ms to 10ms or 20ms. (Some slow-rendering applications or remote desktops cannot keep up with rapid simulated hardware keyboard entries).
3. If letters are still missing, toggle the Injection Method strictly to Clipboard Paste.

Issue 3: Local transcription is extremely slow (using Ollama)

If a 5-second voice recording takes more than 10 seconds to transcribe:

• Check GPU Acceleration: Ensure Ollama is running using your dedicated GPU (NVIDIA CUDA or Apple Silicon Unified Memory) rather than falling back to CPU cores.
• Decrease Model Size: If you pulled whisper-large on a low-spec laptop, it will lag. Run ollama pull whisper-small and switch your model setting to whisper-small for a 4x latency improvement.