# omwanere/image-to-speech-transcript architecture

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

- Interactive diagram: https://gitdiagram.com/omwanere/image-to-speech-transcript
- Repository: https://github.com/omwanere/image-to-speech-transcript

## Overview

##### Project Type and Purpose
- This is a Python-based embedded application that:
- Captures an image via USB webcam or mobile-phone IP stream
- Performs OCR on the image (pytesseract + Tesseract engine)
- Converts extracted text to speech (espeak)
- Is triggered and controlled by a GPIO-connected physical button

##### File Structure
- Top-level scripts:
- Image_To_Speech_Transcript_Webcam.py (USB webcam variant)
- Image_To_Speech_Transcript.py (mobile-stream variant)
- Support assets:
- images/ (for documentation screenshots)
- No submodules or separate “src” folders—everything runs in a single runtime process.

##### Extract Key Architecture Insights from README
- Dual camera inputs: local USB webcam vs remote IP stream
- Shared workflow:
1. Wait for button press
2. Start live preview
3. On next button press, capture image → OCR → clean text → TTS
- Mobile-stream version adds: image preprocessing (resize, grayscale, filtering) + text cleaning

##### Main Components & Their Interactions
a. Hardware Layer
- Button (GPIO input on Raspberry Pi)
- Camera(s):
- USB Webcam (cv2.VideoCapture(0))
- Mobile-phone IP stream (cv2.VideoCapture(“http://<ip>:<port>/video”))
- Speaker or audio output device (for espeak)
b. Software Modules (all running on the Raspberry Pi)
1. GPIO Controller
- Sets up BUTTON_PIN, listens for presses
2. Preview Module
- Initializes camera stream, displays live feed via OpenCV window
3. Module
- Grabs a single frame, saves it as captured_image.jpg
4. (Mobile only) Preprocessing Module
- Resizes, converts to grayscale, applies filters, adaptive thresholding
5. OCR Module
- Calls pytesseract.image_to_string (with optional config flags)
6. Text Cleaning Module (Mobile only)
- Regex to strip special characters
7. TTS Module
- Invokes espeak with given voice and speed parameters
c. External Dependencies
- Tesseract OCR engine + language data
- IP Webcam mobile app (for mobile-stream variant)

##### Architectural Patterns & Principles
- Single‐threaded sequential workflow triggered by hardware interrupt (button press)
- Clear separation of concerns in code: input acquisition → processing → output
- Reuse of common functions across both scripts (capture_image, text_to_speech)
- Configurable parameters (BUTTON_PIN, IP/port, TTS voice/speed, OCR language)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        Button["Button (GPIO Input)"]:::hardware
        USBWebcam["USB Webcam"]:::hardware
        MobileStream["Mobile IP Stream"]:::hardware
        Speaker["Speaker (Audio Output)"]:::hardware
    end

    %% Software Layer
    subgraph "Software Layer"
        direction TB
        GPIOController["GPIO Controller Module"]:::software
        PreviewWebcam["Preview Module (Webcam)"]:::software
        PreviewMobile["Preview Module (Mobile)"]:::software
        CaptureWebcam["Capture Module (Webcam)"]:::software
        CaptureMobile["Capture Module (Mobile)"]:::software
        Preprocessing["Preprocessing Module"]:::software
        OCRWebcam["OCR Module (Webcam)"]:::software
        OCRMobile["OCR Module (Mobile)"]:::software
        TextCleaning["Text Cleaning Module"]:::software
        TTSWebcam["TTS Module (Webcam)"]:::software
        TTSMobile["TTS Module (Mobile)"]:::software
        ErrorLog["Logging/Error Handler"]:::error
    end

    %% External Services
    subgraph "External Services/Dependencies"
        direction TB
        Tesseract["Tesseract OCR Engine"]:::external
        IPApp["IP Webcam Mobile App"]:::external
        Docs["README.md"]:::external
        Assets["images/ directory"]:::external
    end

    %% Connections
    Button -->|"press"| GPIOController
    GPIOController -->|"start preview"| PreviewWebcam
    GPIOController -->|"start preview"| PreviewMobile

    PreviewWebcam -->|"frame buffer"| USBWebcam
    PreviewMobile -->|"frame buffer"| MobileStream

    PreviewWebcam -->|error| ErrorLog:::error
    PreviewMobile -->|error| ErrorLog:::error

    Button -->|"press capture"| CaptureWebcam
    Button -->|"press capture"| CaptureMobile

    CaptureWebcam -->|"image file"| OCRWebcam
    CaptureWebcam -->|"image file"| TTSWebcam

    CaptureMobile -->|"image file"| Preprocessing
    Preprocessing -->|"processed image"| OCRMobile
    OCRMobile -->|"raw text"| TextCleaning
    TextCleaning -->|"clean text"| TTSMobile

    OCRWebcam -->|"raw text"| TTSWebcam

    OCRWebcam -->|invoke| Tesseract
    OCRMobile -->|invoke| Tesseract

    MobileStream -->|requires app| IPApp

    TTSWebcam -->|"audio stream"| Speaker
    TTSMobile -->|"audio stream"| Speaker

    ErrorLog -->|"logs to"| Docs

    %% Click Events
    click GPIOController "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript.py"
    click PreviewWebcam "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript_Webcam.py"
    click PreviewMobile "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript.py"
    click CaptureWebcam "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript_Webcam.py"
    click CaptureMobile "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript.py"
    click Preprocessing "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript.py"
    click OCRWebcam "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript_Webcam.py"
    click OCRMobile "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript.py"
    click TextCleaning "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript.py"
    click TTSWebcam "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript_Webcam.py"
    click TTSMobile "https://github.com/omwanere/image-to-speech-transcript/blob/main/Image_To_Speech_Transcript.py"
    click Docs "https://github.com/omwanere/image-to-speech-transcript/blob/main/README.md"
    click Assets "https://github.com/omwanere/image-to-speech-transcript/tree/main/images/"

    %% Styles
    classDef hardware fill:#b3e6b3,stroke:#2d662d,color:#2d662d;
    classDef software fill:#cce5ff,stroke:#003366,color:#003366;
    classDef external fill:#ffe0b3,stroke:#cc8400,color:#cc6600;
    classDef error fill:#e0e0e0,stroke:#666666,color:#666666;
```
