# hannguyendd/speech-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/hannguyendd/speech-recognition
- Repository: https://github.com/hannguyendd/speech-recognition

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based audio processing pipeline that demonstrates a full round-trip conversion: text → speech (TTS) → format conversion (MP3 → WAV) → speech → text (STT).
- It’s organized as a small monolithic application with a clear modular structure and external dependencies (Google TTS/STT, pydub/ffmpeg, snowflake-id).

##### High-Level Architecture & Main Components
a. Entry Point
- main.py – orchestrates the workflow: takes input text, drives TTS → conversion → STT, and prints results.
b. Configuration/Constants
- core/constant.py – defines AUDIO_FOLDER, MP3_FOLDER, WAV_FOLDER, FILE_EXTENSION.
c. TTS Module
- utilities/text_to_audio.py
– Uses gTTS or pyttsx3 to generate MP3.
– Saves file to AUDIO_FOLDER/MP3_FOLDER with a Snowflake-generated unique filename.
– (Optional) Exposes convert_mp3_to_wav via pydub for format conversion.
d. STT Module
- utilities/audio_to_text.py
– Loads WAV file.
– Uses speechrecognition to call Google Speech Recognition API and returns text.
e. File System
- audio/
– mp3/ (stores generated .mp3 files)
– wav/ (stores converted .wav files)
f. External Services & Libraries
- Google Text-to-Speech (gTTS) or local engine (pyttsx3)
- Google Speech Recognition API
- pydub + ffmpeg (for MP3→WAV)
- snowflake-id (unique IDs)
- soundfile (audio I/O)

##### Relationships & Data Flow
1) User invokes main.py with sample or custom text.
2) main.py calls convert_text_to_speech(text):
– Module → gTTS → generates MP3 → writes to audio/mp3/<id>.mp3
3) main.py then calls convert_mp3_to_wav(mp3_path):
– Module → pydub/ffmpeg → writes to audio/wav/<id>.wav
4) main.py calls convert_audio_to_text(wav_path):
– Module → speechrecognition → Google STT → returns recognized text
5) main.py prints original vs. recognized text.

##### Architectural Patterns & Design Principles
- Pipeline pattern: linear sequence of processing stages (TTS → conversion → STT).
- Separation of concerns:
- main.py (orchestration)
- utilities/ (domain functions)
- core/ (configuration)

##### Essential Elements
- Clear labels on each component (module name, file path)
- Annotations for key configuration values (e.g., folder paths in core/constant.py)

[ main.py ] → [ TTS Module ] → [ MP3 Store ] → [ Converter Module ] → [ WAV Store ] → [ STT Module ] → [ main.py (output) ]

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Layer"
        Main["main.py"]:::app
    end

    subgraph "Business Logic"
        TTS["utilities/text_to_audio.py"]:::app
        STT["utilities/audio_to_text.py"]:::app
    end

    subgraph "Data Storage"
        MP3(("audio/mp3/")):::storage
        WAV(("audio/wav/")):::storage
    end

    subgraph "External Services"
        GoogleTTS(("Google TTS")):::external
        Ffmpeg(("ffmpeg / pydub")):::external
        GoogleSTT(("Google STT")):::external
    end

    subgraph "Configuration"
        Config["core/constant.py"]:::config
    end

    Main -->|"Text"| TTS
    TTS -->|"MP3 file"| MP3
    MP3 -->|"MP3 file"| Ffmpeg
    Ffmpeg -->|"WAV file"| WAV
    WAV -->|"WAV file"| STT
    STT -->|"Recognized Text"| Main

    TTS -->|"TTS API"| GoogleTTS
    STT -->|"STT API"| GoogleSTT

    Main --> Config
    TTS --> Config
    STT --> Config

    click Main "https://github.com/hannguyendd/speech-recognition/blob/main/main.py"
    click Config "https://github.com/hannguyendd/speech-recognition/blob/main/core/constant.py"
    click TTS "https://github.com/hannguyendd/speech-recognition/blob/main/utilities/text_to_audio.py"
    click STT "https://github.com/hannguyendd/speech-recognition/blob/main/utilities/audio_to_text.py"

    classDef app fill:#cce5ff,stroke:#0000cc
    classDef storage fill:#d4edda,stroke:#006400
    classDef external fill:#ffe5b4,stroke:#ff8c00
    classDef config fill:#e2e3e5,stroke:#6c757d
```
