# dataoceanai/dolphin architecture

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

- Interactive diagram: https://gitdiagram.com/dataoceanai/dolphin
- Repository: https://github.com/dataoceanai/dolphin

## Overview

##### Project type and purpose
- Dolphin is a Python-based command-line tool and library providing multilingual, multitask automatic speech recognition (ASR).
- From the README: it performs speech recognition, voice activity detection (VAD), segmentation, and language identification (LID) over 40 Eastern languages and 22 Chinese dialects.

##### File structure
- Top-level files:
- setup.py, requirements.txt – packaging and dependencies
- README.md, LICENSE – documentation
- dolphin/ – the library source
- figures/, languages.md – extra docs/assets
- Inside dolphin/:
- __main__.py – CLI entrypoint
- audio.py – audio loading & waveform conversion
- transcribe.py – the high-level pipeline orchestration
- model.py – model loading & forward pass (encoder-decoder + joint CTC-Attention)
- beam_search.py – decoding logic
- scorefilter.py – post-processing, filtering transcriptions
- constants.py, languages.py, version.py – config, supported languages, metadata
- assets/ – pre-trained BPE model, feature stats, YAML config

##### README for architectural hints
- Dolphin largely follows the Whisper/OWSM design:
- Encoder: E-Branchformer
- Decoder: standard Transformer
- Joint CTC-Attention architecture
- Two-level language tokens (language + region)
- Dependencies: FFmpeg (external binary), PyTorch (implied), standard Python libs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and Components
    CLI["CLI/API Layer"]:::io
    Audio["Audio Loader & Preprocessing"]:::io
    Feature["Feature Extractor"]:::io
    subgraph "ASR Model"
        Encoder["Encoder (E-Branchformer)"]:::core
        Decoder["Decoder (Transformer + joint CTC head)"]:::core
    end
    Beam["Beam Search Decoder"]:::decode
    Score["Score Filter & Post-processing"]:::decode
    Pipeline["Pipeline Orchestration & Output Assembly"]:::io
    Output["Transcript + Metadata"]:::io

    subgraph "Assets Store"
        Stats["feats_stats.npz"]:::asset
        BPE["bpe.model"]:::asset
        Config["config.yaml"]:::asset
    end

    MetaLang["Supported Languages & Metadata"]:::meta
    Version["Versioning"]:::meta

    ExternalFFmpeg[(External FFmpeg)]:::external

    %% Data Flow
    CLI -->|"invoke CLI or API"| Audio
    Audio -->|"waveform"| Feature
    Feature -->|"features"| Encoder
    Encoder -->|"encoder output"| Decoder
    Decoder -->|"logits"| Beam
    Beam -->|"candidates"| Score
    Score -->|"filtered transcripts"| Pipeline
    Pipeline -->|"final output"| Output

    %% Asset Dependencies
    Stats --> Feature
    BPE --> Decoder
    Config --> Decoder
    Config --> Encoder

    %% Metadata & Version inputs
    MetaLang --> Pipeline
    Version --> Pipeline

    %% External Dependencies
    ExternalFFmpeg --> Audio

    %% Click Events
    click CLI "https://github.com/dataoceanai/dolphin/blob/main/dolphin/__main__.py"
    click Audio "https://github.com/dataoceanai/dolphin/blob/main/dolphin/audio.py"
    click Feature "https://github.com/dataoceanai/dolphin/blob/main/dolphin/assets/feats_stats.npz"
    click Encoder "https://github.com/dataoceanai/dolphin/blob/main/dolphin/model.py"
    click Decoder "https://github.com/dataoceanai/dolphin/blob/main/dolphin/model.py"
    click Beam "https://github.com/dataoceanai/dolphin/blob/main/dolphin/beam_search.py"
    click Score "https://github.com/dataoceanai/dolphin/blob/main/dolphin/scorefilter.py"
    click Pipeline "https://github.com/dataoceanai/dolphin/blob/main/dolphin/transcribe.py"
    click BPE "https://github.com/dataoceanai/dolphin/blob/main/dolphin/assets/bpe.model"
    click Config "https://github.com/dataoceanai/dolphin/blob/main/dolphin/assets/config.yaml"
    click MetaLang "https://github.com/dataoceanai/dolphin/blob/main/dolphin/languages.py"
    click Version "https://github.com/dataoceanai/dolphin/blob/main/dolphin/version.py"

    %% Styling
    classDef io fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef decode fill:#FFA500,stroke:#333,stroke-width:1px
    classDef asset fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef meta fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px,nodeShape:roundRect
```
