# argmaxinc/whisperkit architecture

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

- Interactive diagram: https://gitdiagram.com/argmaxinc/whisperkit
- Repository: https://github.com/argmaxinc/whisperkit

## Overview

##### Overall Project Structure
- The Core Framework (Sources/WhisperKit)
- The Command Line Interface (Sources/WhisperKitCLI)
- Integration/Example Applications (the Examples/WhisperAX Xcode project and companion Watch App)
- CI/CD & Deployment Automation (GitHub workflows, fastlane scripts)
- Testing & Benchmarks (Tests directory and BENCHMARKS.md)

##### Main Components
a. WhisperKit Core:
- It as a central module that is further subdivided into functional areas:
- Audio Processing: Components like AudioChunker, AudioProcessor, AudioStreamTranscriber, EnergyVAD, and VoiceActivityDetector.
- Text Processing: Modules such as LogitsFilter, SegmentSeeker, TokenSampler, TextDecoder, and TranscribeTask.
- Utility Functions: Concurrency and other helper utilities found in the Utils directory.
- Configuration and Model Management: Files like Configurations.swift and Model selection logic.

b. WhisperKit CLI:
- That it leverages the WhisperKit Core APIs to offer command-line transcription capabilities.
- Command-line inputs (parameters like model-path, audio-path, streaming flag) that direct execution to the CLI.

c. Clients & Example Applications:
- A node representing the example apps (e.g., WhisperAX for iOS and the Watch App). This illustrates how developers integrate the framework into front-end applications.
- That these examples use the core functionality (typically via Swift Package Manager integration) and showcase real-time processing, UI views, and configuration files (like .xcconfig and Info.plist).

d. External Dependencies and Model Management:

e. CI/CD and Quality Assurance:
- CI/CD components (GitHub workflows, fastlane) as supporting systems that automatically run unit tests, pre-release tests, and update processes.
- This illustrates continuous integration and automated build/distribution practices that help maintain code quality and simplify deployments.

##### Architectural Patterns & Design Principles
- That WhisperKit uses modularization and separation of concerns: different directories handle audio logic, text logic, utilities, and configuration.
- Asynchronous programming patterns (for example, use of Swift’s async/await APIs) which are central in handling real-time streaming and processing.
- That dependency injection is likely used to allow testing and flexibility in model selection.

##### Technologies and Tools
- Clearly label components with their respective roles:
- Swift Package Manager for dependency management.
- Xcode for development and integration (as demonstrated by the Examples folder).
- GitHub Workflows and fastlane for building and testing.
- External tools like git-lfs (for model downloads) and Homebrew (for CLI installation) should also be mentioned.

## Diagram (Mermaid)

```mermaid
flowchart TD
    IA["Input Audio"]:::input
    subgraph "WhisperKit Core"
        CoreAudio["Audio Processing"]:::core
        CoreText["Text Processing"]:::core
        CoreUtils["Utility Functions"]:::core
        CoreConfig["Configuration & Model Management"]:::core
    end
    TT["Transcribed Text"]:::output

    CLI["CLI Wrapper"]:::cli
    EX["Example Apps"]:::example

    ExtHF["HuggingFace Model Repo"]:::external
    ExtHB["Homebrew"]:::external

    subgraph "CI/CD & Deployment Automation"
        GH["GitHub Workflows"]:::ci
        FL["fastlane"]:::ci
    end

    TEST["Testing & Benchmarks"]:::test

    IA -->|"Stream"| CoreAudio
    CoreAudio -->|"ExtractFeatures"| CoreText
    CoreText -->|"GenerateText"| TT

    CLI -->|"UsesAPI"| CoreAudio
    EX -->|"IntegratesViaSPM"| CoreAudio

    CoreConfig -->|"DownloadsModels"| ExtHF
    CLI -->|"DistributedViaCLI"| ExtHB

    GH -->|"Triggers"| TEST
    FL -->|"Releases"| CLI

    TEST -->|"Validates"| CoreAudio
    GH -->|"BuildTest"| CoreAudio

    %% Click Events
    click CoreAudio "https://github.com/argmaxinc/whisperkit/tree/main/Sources/WhisperKit/Core/Audio"
    click CoreText "https://github.com/argmaxinc/whisperkit/tree/main/Sources/WhisperKit/Core/Text"
    click CoreUtils "https://github.com/argmaxinc/whisperkit/tree/main/Sources/WhisperKit/Core/Utils"
    click CoreConfig "https://github.com/argmaxinc/whisperkit/blob/main/Sources/WhisperKit/Core/Configurations.swift"
    click CLI "https://github.com/argmaxinc/whisperkit/tree/main/Sources/WhisperKitCLI"
    click EX "https://github.com/argmaxinc/whisperkit/tree/main/Examples/WhisperAX"
    click GH "https://github.com/argmaxinc/whisperkit/tree/main/.github/workflows"
    click FL "https://github.com/argmaxinc/whisperkit/tree/main/fastlane"
    click TEST "https://github.com/argmaxinc/whisperkit/tree/main/Tests"

    %% Styles
    classDef core fill:#f6e58d,stroke:#b71540,stroke-width:2px;
    classDef cli fill:#badc58,stroke:#130f40,stroke-width:2px;
    classDef example fill:#f9ca24,stroke:#130f40,stroke-width:2px;
    classDef external fill:#ff7979,stroke:#130f40,stroke-width:2px;
    classDef ci fill:#7ed6df,stroke:#130f40,stroke-width:2px;
    classDef test fill:#e056fd,stroke:#130f40,stroke-width:2px;
    classDef input fill:#dff9fb,stroke:#130f40,stroke-width:2px;
    classDef output fill:#95a5a6,stroke:#130f40,stroke-width:2px;
```
