# higuma/web-audio-recorder-js architecture

> Architecture diagram of the GitHub repository higuma/web-audio-recorder-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/higuma/web-audio-recorder-js
- Repository: https://github.com/higuma/web-audio-recorder-js

## Overview

##### Project Type and Purpose
- This is a client-side JavaScript library (an open-source tool) that records audio via the Web Audio API and encodes it into WAV, Ogg, or MP3 formats using Web Workers.

##### Main Components
a. Host Application (Web Page)
- Loads WebAudioRecorder.js on the main browser thread.
- Provides an AudioNode (e.g., microphone input via getUserMedia).
- Receives final Blob (audio file) via event callbacks.

b. WebAudioRecorder Core (Main Script)
- API surface: constructor, setEncoding, setOptions, start/stop/cancel, event handlers.
- Orchestrates recording and worker management.
- Uses Web Audio API (ScriptProcessorNode or AudioWorklet) under the hood to capture PCM buffers.

c. Worker Manager
- Dynamically loads one of three worker scripts (WebAudioRecorderWav.js, WebAudioRecorderOgg.js, WebAudioRecorderMp3.js) based on chosen encoding.
- Passes raw PCM buffers to the worker via postMessage.
- Receives progress updates and final ArrayBuffer/Blob from worker.

d. Encoder Worker (for each format)
- Contains bundled encoder library (e.g., WavAudioEncoder.js, OggVorbisEncoder.js, Mp3LameEncoder.js).
- Performs CPU-intensive encoding off the main thread.
- Uses a memory initializer file (*.mem) for WASM/emulation if needed.
- Posts state messages: “loaded,” “progress,” “complete,” “error.”

e. External Encoder Libraries
- Imported by worker scripts, they implement the actual format encoders.
- Hosted in lib/, also available in lib-minified/.

f. Blob Output
- Worker returns an encoded Blob to the main script.
- Main script triggers onComplete(recorder, blob) so host app can save/play the file.

##### Relationships & Data Flow
- Host App → Core Script: instantiate recorder, pass AudioNode & config.
- Core Script → Web Audio API: subscribe to PCM data.
- Core Script → Worker Manager: load appropriate worker (workerDir + worker script).
- Core Script → Worker Thread: stream PCM chunks via postMessage.
- Worker Thread → Core Script: send back encoding progress or final Blob.
- Core Script → Host App: invoke event handlers (onComplete, onError, onEncodingProgress).

##### Architectural Patterns & Principles
- Worker-Based Concurrency: Offload CPU-heavy encoding to Web Workers.
- Event-Driven: Use event callbacks for lifecycle (loading, progress, complete, error).
- Pluggable Encoders: Strategy pattern—swap in WAV/Ogg/MP3 encoding logic.
- Separation of Concerns: Main script concerns itself only with orchestration; workers handle encoding.

##### Technologies & Libraries
- Web Audio API (AudioNode, ScriptProcessorNode / AudioWorklet)
- Web Workers (postMessage, worker.terminate)
- Encoder libraries (WavAudioEncoder.js, OggVorbisEncoder.js, Mp3LameEncoder.js)
- Blob API for output

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main-thread components
    HostApp["Host App (Browser UI)"]:::main
    subgraph "Main Thread"
        Core["Recorder Core"]:::main
        WorkerMgr["Worker Manager"]:::main
        WebAudioAPI["Web Audio API"]:::main
    end

    %% Worker components
    subgraph "Encoder Workers"
        subgraph "WAV Worker"
            WavWorker["Encoder Worker (WAV)"]:::worker
            WavLib["WavAudioEncoder.js"]:::lib
            WavMem["*.mem (WASM)"]:::lib
        end
        subgraph "OGG Worker"
            OggWorker["Encoder Worker (Ogg)"]:::worker
            OggLib["OggVorbisEncoder.js"]:::lib
            OggMem["*.mem (WASM)"]:::lib
        end
        subgraph "MP3 Worker"
            Mp3Worker["Encoder Worker (MP3)"]:::worker
            Mp3Lib["Mp3LameEncoder.js"]:::lib
            Mp3Mem["*.mem (WASM)"]:::lib
        end
    end

    %% Build outputs
    subgraph "Build Outputs"
        Unminified["Unminified (lib/)"]:::external
        Minified["Minified (lib-minified/)"]:::external
    end

    %% Blob output
    BlobOut["Blob Output"]:::external

    %% Data flows
    HostApp -->|"instantiate Recorder,\npass AudioNode"| Core
    Core -->|"capture PCM buffers"| WebAudioAPI
    WebAudioAPI -->|"PCM data"| Core
    Core -->|"load worker (workerDir)"| WorkerMgr

    WorkerMgr -->|"postMessage PCM"| WavWorker
    WorkerMgr -->|"postMessage PCM"| OggWorker
    WorkerMgr -->|"postMessage PCM"| Mp3Worker

    WavWorker -->|"uses"| WavLib
    WavWorker -->|"uses"| WavMem
    OggWorker -->|"uses"| OggLib
    OggWorker -->|"uses"| OggMem
    Mp3Worker -->|"uses"| Mp3Lib
    Mp3Worker -->|"uses"| Mp3Mem

    WavWorker -->|"progress/blob"| Core
    OggWorker -->|"progress/blob"| Core
    Mp3Worker -->|"progress/blob"| Core

    Core -->|"onComplete/onError events\nwith Blob"| HostApp
    Core -->|"output Blob"| BlobOut

    Unminified -.-> Core
    Unminified -.-> WavWorker
    Unminified -.-> OggWorker
    Unminified -.-> Mp3Worker

    Minified -.-> Core
    Minified -.-> WavWorker
    Minified -.-> OggWorker
    Minified -.-> Mp3Worker

    %% Click events
    click Core "https://github.com/higuma/web-audio-recorder-js/blob/master/lib/WebAudioRecorder.js"
    click WavWorker "https://github.com/higuma/web-audio-recorder-js/blob/master/lib/WebAudioRecorderWav.js"
    click OggWorker "https://github.com/higuma/web-audio-recorder-js/blob/master/lib/WebAudioRecorderOgg.js"
    click Mp3Worker "https://github.com/higuma/web-audio-recorder-js/blob/master/lib/WebAudioRecorderMp3.js"
    click Unminified "https://github.com/higuma/web-audio-recorder-js/tree/master/lib/"
    click Minified "https://github.com/higuma/web-audio-recorder-js/tree/master/lib-minified/"

    %% Styles
    classDef main fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef worker fill:#90EE90,stroke:#333,stroke-width:1px
    classDef lib fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
