# ricky0123/vad architecture

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

- Interactive diagram: https://gitdiagram.com/ricky0123/vad
- Repository: https://github.com/ricky0123/vad

## Overview

##### Main components
- Client/Browser Environment: This is where the user interacts with the application and the VAD runs.
- Audio Capture Module: Handles obtaining microphone permissions and streaming audio input.
- VAD Processing Engine: Located primarily in the “packages/web” module, this component processes the captured audio, implements speech detection via ONNX Runtime Web, and applies the Silero VAD model (loaded from the provided ONNX files).
- React Integration Layer: Found in “packages/react”, it is an adapter/wrapper to use the core VAD functionality in React applications.
- External Dependencies: This includes ONNX Runtime Web (and formerly ONNX Runtime Node.js, now deprecated) and Silero VAD model files. The project also contains examples using various bundlers (Webpack, Next.js, script tags) which illustrate integration patterns.
- Developer and Documentation Support: The docs directory, changelogs, GitHub workflows, and examples serve as supporting material to help developers understand, build, and deploy the solution.

##### Establish the relationships and interactions
- The browser provides the entry point by granting microphone access.
- Audio from the microphone is sent to the Audio Capture Module.
- Audio data is passed into the VAD Processing Engine via JavaScript (potentially using Audio Worklets and related utilities in “packages/web”).
- The processing engine uses ONNX Runtime Web to run the Silero VAD model (integrated via the onnx files) and detects segments of speech.
- On detection, callbacks (e.g., onSpeechStart and onSpeechEnd) are triggered to inform the client application.
- When using React, the “packages/react” adapter wraps these functionalities to fit into the React component lifecycle.

##### Architectural patterns and design principles
- Modular Monorepo Structure: Code is separated into distinct packages (“packages/web” and “packages/react”), making the project extensible and maintainable.
- Separation of Concerns: The design clearly distinguishes between the core audio processing (handling raw audio and VAD computation) and its integration within UI frameworks (React, vanilla JavaScript examples).
- Client-Side Emphasis: The architecture is optimized for browser environments, with server-side Node support discontinued to focus effort on the browser-based detection.
- Use of Modern Build and Deployment Tools: Presence of Webpack, Next.js, and bundler examples indicates that the code is designed for compatibility with modern frontend development workflows.

##### Technologies, frameworks, and libraries
- ONNX Runtime Web: Essential for running the VAD model in the browser.
- Silero VAD: The pre-trained model that underpins the voice detection capability.
- JavaScript / TypeScript: The core languages used, especially considering “.ts” and “.tsx” files in the packages.
- Webpack, Next.js, and script tag examples: Illustrate how the package can be bundled and integrated into different setups.
- GitHub Actions (workflows) & MkDocs: Provide CI/CD and documentation, indicating supporting infrastructures for development and deployment.

##### Final recommendations
- Be as detailed as possible, breaking down the project into its smallest functional components.
- Overlaying build and deployment pipelines only if they are directly relevant to the runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Components
    BrowserEnv["Client/Browser Environment"]:::browser
    AudioCapture["Audio Capture Module"]:::core

    subgraph "VAD Processing Engine"
        direction TB
        RealTimeVAD["Real-Time VAD"]:::core
        NonRealTimeVAD["Non-Real-Time VAD"]:::core
        VADModels["Silero VAD Models"]:::external
        ONNX["ONNX Runtime Web"]:::external
    end

    ReactIntegration["React Integration Layer"]:::integration

    subgraph "Developer Support"
        direction TB
        Docs["Documentation"]:::support
        Changelogs["Changelogs"]:::support
        Workflows["CI/CD Workflows"]:::support
        Examples["Examples"]:::support
    end

    %% Data Flow
    BrowserEnv -->|"grants mic access"| AudioCapture
    AudioCapture -->|"sends audio"| RealTimeVAD
    AudioCapture -->|"sends audio"| NonRealTimeVAD

    VADModels -->|"model dependency"| RealTimeVAD
    VADModels -->|"model dependency"| NonRealTimeVAD

    ONNX -->|"execution engine"| RealTimeVAD
    ONNX -->|"execution engine"| NonRealTimeVAD

    RealTimeVAD -->|"triggers callbacks"| BrowserEnv
    NonRealTimeVAD -->|"triggers callbacks"| BrowserEnv

    ReactIntegration -->|"wraps VAD functionality"| RealTimeVAD
    ReactIntegration -->|"wraps VAD functionality"| NonRealTimeVAD

    %% Click Events
    click BrowserEnv "https://github.com/ricky0123/vad/blob/master/examples/bundler/src/index.html"
    click AudioCapture "https://github.com/ricky0123/vad/blob/master/packages/web/src/index.ts"
    click RealTimeVAD "https://github.com/ricky0123/vad/blob/master/packages/web/src/real-time-vad.ts"
    click NonRealTimeVAD "https://github.com/ricky0123/vad/blob/master/packages/web/src/non-real-time-vad.ts"
    click VADModels "https://github.com/ricky0123/vad/tree/master/packages/web/src/models/"
    click ReactIntegration "https://github.com/ricky0123/vad/tree/master/packages/react"
    click Docs "https://github.com/ricky0123/vad/tree/master/docs/"
    click Changelogs "https://github.com/ricky0123/vad/tree/master/changelogs/"
    click Workflows "https://github.com/ricky0123/vad/tree/master/.github/workflows/"
    click Examples "https://github.com/ricky0123/vad/tree/master/examples/"

    %% Styles
    classDef browser fill:#a2d2ff,stroke:#000,stroke-width:1px;
    classDef core fill:#bde0fe,stroke:#000,stroke-width:1px;
    classDef integration fill:#caffbf,stroke:#000,stroke-width:1px;
    classDef external fill:#ffc8dd,stroke:#000,stroke-width:1px;
    classDef support fill:#ffebba,stroke:#000,stroke-width:1px;
```
