# jossephcoder/asistente_voz_vosk architecture

> Architecture diagram of the GitHub repository jossephcoder/asistente_voz_vosk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jossephcoder/asistente_voz_vosk
- Repository: https://github.com/jossephcoder/asistente_voz_vosk

## Overview

##### Project Type and Purpose
- This is a standalone, offline Desktop Voice Assistant written in Python.
- It captures microphone audio, uses Vosk speech-to-text models to transcribe speech into text, parses commands, and executes OS actions or custom routines.

##### High-Level Architecture Components
a. User Interface (UI)
- Microphone input (via `audio_py/microfono.py`)
- Console/terminal output for status and feedback
b. Audio Processing Layer
- Audio capture and file buffering (`grabar_voz.py`)
- Optional real-time streaming (`fase_beta/transcribir_voz_realtime.py`)
- Preprocessing (packaging raw audio frames for transcription)
c. Speech Recognition Engine
- Vosk model loader and manager (`modelos.py`)
- Offline model files in `modelos_voz/` (acoustic model, graph, i-vector configs)
- Transcription wrapper (`transcribir_audio.py` or `transcribir_voz.py`)
d. Command Dispatcher
- Dynamic command collector (`recopilador_objetos.py`)
- Command definitions (`comandos/comandos_win.py`)
- Matching transcribed text against registered commands
e. Action Executor
- OS-level calls (open apps, run scripts)
- Subprocess or `os` library invocations
f. Orchestration (Main)
- Entry point `asistente_voz.py` (initializes all modules, enters listen-process loop)
- Batch launcher `asistente_vosk.bat` (activates virtualenv, runs assistant)

##### Data Flow & Interactions
1. Microphone captures audio →
2. Audio Processing buffers and normalizes audio →
3. Speech Recognition Engine transcribes audio →
4. Transcribed text sent to Command Dispatcher →
5. Dispatcher invokes matching function in `comandos_win.py` →
6. Action Executor runs the OS command or custom logic →
7. Assistant outputs status/result to console (and optionally via speech)

##### Architectural Patterns & Principles
- Modular layering (separate audio, recognition, dispatch, execution)
- Plugin-style command registration (via `recopilador_objetos.py`)
- Single point of orchestration (`asistente_voz.py`)
- Offline-first design (all models and logic local)

##### Technologies and Frameworks
- Python 3.10+ with Virtualenv
- Vosk speech-to-text
- Native Windows commands (via subprocess/os library)
- Zip-packed model directory (`modelos_voz/vosk-model-small-es-0.42`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "Orchestration" 
        direction TB
        AsistEntry["asistente_voz.py"]:::entry
        Bat["asistente_vosk.bat"]:::artifact
        Req["requirements.txt"]:::artifact
    end

    subgraph "User Interface" 
        direction TB
        Mic["[/ Microphone Input /]"]:::external
        Console["[/ Console Output /]"]:::external
    end

    subgraph "Audio Processing Layer" 
        direction TB
        Grabar["grabar_voz.py"]:::core
        Beta["transcribir_voz_realtime.py"]:::beta
    end

    subgraph "Speech Recognition Engine"
        direction TB
        ModelLoader["modelos.py"]:::core
        TransVoice["transcribir_voz.py"]:::core
        TransAudio["transcribir_audio.py"]:::core
        ModelStore[(vosk-model-small-es-0.42)]:::storage
    end

    subgraph "Command Dispatcher"
        direction TB
        Collector["recopilador_objetos.py"]:::core
        CmdDef["comandos_win.py"]:::core
    end

    subgraph "Action Executor"
        direction TB
        Executor["comandos_win.py"]:::core
        OSService["((OS/External Service))"]:::externalService
    end

    %% Orchestration connections
    AsistEntry -->|"starts"| Mic
    Bat -->|"launches"| AsistEntry
    Req --> AsistEntry

    %% Main Flow
    Mic -->|"raw audio frames"| Grabar
    Grabar -->|"buffered audio"| TransAudio
    TransAudio -->|"audio for transcription"| TransVoice
    TransVoice -->|"text transcript"| Collector
    Collector -->|"matched command"| CmdDef
    CmdDef -->|"executes"| OSService
    OSService -->|"status/result"| Console

    %% Data arrows to Beta (optional)
    Mic -.->|"raw audio frames"| Beta

    %% Click events
    click Mic "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/audio_py/microfono.py"
    click Grabar "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/audio_py/grabar_voz.py"
    click Beta "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/fase_beta/transcribir_voz_realtime.py"
    click ModelLoader "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/modelos.py"
    click TransVoice "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/transcribir_voz.py"
    click TransAudio "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/audio_py/transcribir_audio.py"
    click ModelStore "https://github.com/jossephcoder/asistente_voz_vosk/tree/main/modelos_voz/"
    click Collector "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/recopilador_objetos.py"
    click CmdDef "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/comandos/comandos_win.py"
    click Executor "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/comandos/comandos_win.py"
    click AsistEntry "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/proyecto/asistente_voz.py"
    click Bat "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/asistente_vosk.bat"
    click Req "https://github.com/jossephcoder/asistente_voz_vosk/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000;
    classDef storage fill:#90EE90,stroke:#000;
    classDef external fill:#FFFFE0,stroke:#000;
    classDef externalService fill:#FFC0CB,stroke:#000;
    classDef entry fill:#add8e6,stroke-width:3px;
    classDef artifact fill:#f0e68c,stroke:#000;
    classDef beta stroke-dasharray: 5 5;
```
