# sundar0989/speech-to-text architecture

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

- Interactive diagram: https://gitdiagram.com/sundar0989/speech-to-text
- Repository: https://github.com/sundar0989/speech-to-text

## Overview

##### Project type and purpose
- This is a small open-source demonstration/toolset implemented as Jupyter notebooks. Its sole purpose is to convert long-duration audio files into text using two cloud-provider speech-to-text APIs (AWS Transcribe and Google LongAudio API), with optional speaker diarization.

##### File structure
- Top level:
- Four notebooks, each implementing one variant of the pipeline:
– AWS_transcribe.ipynb
– AWS_transcribe_with_Speaker_diarization.ipynb
– Google_Longaudio_API_without_speaker_diarization.ipynb
– Google_Longaudio_API_speaker_diarization.ipynb
- README.md describing the overall capability.
- No separate “src” or “scripts” folder—each notebook contains both orchestration logic and SDK calls.

##### README for additional insights
- Confirms that this is an asynchronous, long-audio speech-to-text solution.
- Mentions optional speaker diarization.

a. Main components
1. User / Data Scientist environment (Jupyter Lab / Notebook host)
2. Notebook orchestration code
3. Cloud SDKs (AWS SDK v2/v3 or Google Cloud client libraries)
4. Cloud speech-to-text service endpoints:
- AWS Transcribe
- Google LongAudio API
5. Audio storage (could be local file system or S3/GCS)
6. Transcription result store (local files, in-notebook variables, or cloud storage)
b. Relationships & interactions
- The user uploads or references a long-audio file in the notebook.
- Notebook invokes cloud SDK → submits transcription job asynchronously.
- Cloud service polls or receives events via SDK until transcription completes.
- Result is fetched back into the notebook.
- Optionally, speaker-diarization metadata is retrieved and post-processed.
c. Architectural patterns & design principles
- “Pipeline” pattern: sequential stages (submit job → wait → fetch result → process).
- Asynchronous job orchestration using polling or callbacks.
- Separation of concerns: notebook as driver, cloud as compute.
d. Key technologies & libraries
- Python (within Jupyter)
- Boto3 or AWS SDK for Python
- google-cloud-speech or LongAudio client library
- Optional: pandas or JSON for result parsing

##### Step-by-step approach for the principal software engineer
2. Inside it, show notebooks calling two modules: AWS_Module and Google_Module.
4. Under each cloud service, show “S3/GCS Storage” if used.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Environment and Notebooks
    subgraph "User Notebook Environment"
        direction TB
        A1["AWS_transcribe.ipynb"]:::notebook
        A2["AWS_transcribe_with_Speaker_diarization.ipynb"]:::notebook
        A3["Google_Longaudio_API_without_speaker_diarization.ipynb"]:::notebook
        A4["Google_Longaudio_API_speaker_diarization.ipynb"]:::notebook
        README["README.md"]:::docs
    end

    %% Cloud Services and Storage
    subgraph "Cloud Providers"
        direction TB
        AWSService["AWS Transcribe Service"]:::cloud
        AWSStorage["AWS S3 Storage"]:::storage
        GoogleService["Google LongAudio API"]:::cloud
        GoogleStorage["Google GCS Storage"]:::storage
    end

    %% Processing Modules for Diarization
    P2["Speaker Diarization Parser"]:::process
    P4["Speaker Diarization Parser"]:::process

    %% Data Flows: AWS
    A1 -->|"StartTranscriptionJob"| AWSService
    A2 -->|"StartTranscriptionJob"| AWSService
    AWSService -->|"Transcript JSON"| A1
    AWSService -->|"Transcript JSON"| A2
    AWSService --> AWSStorage
    A2 --> P2
    P2 --> A2

    %% Data Flows: Google
    A3 -->|"LongAudioAsyncRecognize"| GoogleService
    A4 -->|"LongAudioAsyncRecognize"| GoogleService
    GoogleService -->|"Transcript JSON"| A3
    GoogleService -->|"Transcript JSON"| A4
    GoogleService --> GoogleStorage
    A4 --> P4
    P4 --> A4

    %% Documentation Link
    README -.-> A1

    %% Click Events
    click A1 "https://github.com/sundar0989/speech-to-text/blob/master/AWS_transcribe.ipynb"
    click A2 "https://github.com/sundar0989/speech-to-text/blob/master/AWS_transcribe_with_Speaker_diarization.ipynb"
    click A3 "https://github.com/sundar0989/speech-to-text/blob/master/Google_Longaudio_API_without_speaker_diarization.ipynb"
    click A4 "https://github.com/sundar0989/speech-to-text/blob/master/Google_Longaudio_API_speaker_diarization.ipynb"
    click README "https://github.com/sundar0989/speech-to-text/blob/master/README.md"

    %% Styles
    classDef notebook fill:#DDEEFF,stroke:#0066CC,stroke-width:1px;
    classDef cloud fill:#DDFFDD,stroke:#009900,stroke-width:1px;
    classDef storage fill:#FFE5CC,stroke:#CC6600,stroke-width:1px;
    classDef process fill:#F0E6FF,stroke:#660099,stroke-width:1px;
    classDef docs fill:#F5F5F5,stroke:#BBBBBB,stroke-width:1px,stroke-dasharray: 5 5;
```
