# markharrison/audiomark architecture

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

- Interactive diagram: https://gitdiagram.com/markharrison/audiomark
- Repository: https://github.com/markharrison/audiomark

## Overview

##### Project type and purpose
- This is a front-end JavaScript audio library (“AudioMark”) for web games and interactive apps.
- It’s delivered as a single-file module (audio.js), demo page (index.html), tests (test.js), and docs (audiomark.md).

##### File structure
- Top-level files:
– audio.js: the core library implementation
– index.html & test.js: demo/test harness
– audiomark.md: API documentation
– README.md: overview & usage
- No backend or database layers—this lives entirely in the browser.
- Key external interactions: fetch (for audio file URLs), Web Audio API.

##### README for architectural clues
- Core features imply modular sub-systems inside audio.js:
– Loading (URL, File, ArrayBuffer)
– Preloading & processing queue
– Playback (SFX vs Music with separate channels)
– Volume control (master, music, sfx)
– Crossfade/transition manager
– Resource cleanup and context suspension handling

##### Main components & relationships
a. Components:
1. Demo/UI Layer (index.html + test.js)
2. AudioMark Library (audio.js) with internal modules:
– Loader Module
– Preloader/Queue Module
– Decoder Module (AudioContext.decodeAudioData)
– Playback Manager (SourceNode factory)
– Volume Controller (Master/Music/SFX GainNodes)
– Transition Manager (crossfade logic)
– Resource Manager (cleanup/suspension)
3. Web Audio API (AudioContext, AudioBufferSourceNode, GainNode, Destination)
4. External Resources (audio files served via HTTP)
b. Interactions:
– UI calls AudioMark.initialize(), loadAudio(), playMusic(), playSFX(), setVolume()
– Loader fetches URLs → ArrayBuffer
– Decoder hands off ArrayBuffer → AudioBuffer
– Playback Manager spawns AudioBufferSourceNode → GainNode → Destination
– Transition Manager orchestrates overlapping GainNodes for crossfade
– Volume Controller routes all channels through master GainNode
– Resource Manager monitors nodes for stop/unload
c. Architectural patterns & principles:
– Modular separation: Loader vs Decoder vs Playback vs Volume
– Single Responsibility: each module has a clear job
– Publish/Subscribe: state events (loaded, decoded, ended) for UI logging
– Lazy initialization & preloading workflow
d. Key technologies & libraries:
– Native Web Audio API (no external audio framework)
– ES6 module pattern in audio.js
– Fetch API for network loading

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        Demo["Demo/UI Layer"]:::ui
        Test["Test Harness"]:::ui
    end

    subgraph "AudioMark Library"
        Loader["Loader Module"]:::lib
        Preloader["Preloader/Queue Module"]:::lib
        Decoder["Decoder Module"]:::lib
        Playback["Playback Manager"]:::lib
        Volume["Volume Controller"]:::lib
        Transition["Transition Manager"]:::lib
        Resource["Resource Manager"]:::lib
    end

    subgraph "Web Audio API"
        AudioContext["AudioContext"]:::api
        SourceNode["AudioBufferSourceNode"]:::api
        GainNode["GainNode"]:::api
        Destination["Destination"]:::api
    end

    subgraph "Documentation"
        DocAPI["API Documentation"]:::docs
        Guide["Usage Guide"]:::docs
    end

    External["HTTP Audio Server"]:::external

    Demo -->|"initialize()/loadAudio()/playMusic()/playSFX()/setVolume() calls"| Loader
    Test -->|"API calls for logging & tests"| Loader

    Loader -->|"fetch() → ArrayBuffer"| External
    External -->|"ArrayBuffer"| Loader

    Loader -->|"pass ArrayBuffer"| Decoder
    Decoder -->|"decodeAudioData() → AudioBuffer"| AudioContext

    Playback -->|"create SourceNode"| SourceNode
    SourceNode -->|"connect"| GainNode
    Volume -->|"route through master GainNode"| GainNode
    Transition -->|"control overlapping GainNodes for crossfade"| GainNode
    GainNode -->|"connect"| Destination

    Resource -->|"monitor nodes for stop/unload/suspend"| AudioContext

    classDef ui fill:#D5E8F6,stroke:#6C8EBF
    classDef lib fill:#D5E8D4,stroke:#82B366
    classDef api fill:#FFE6CC,stroke:#D6A600
    classDef external fill:#F2F2F2,stroke:#A6A6A6
    classDef docs fill:#FFF2CC,stroke:#D6B656

    click Demo "https://github.com/markharrison/audiomark/blob/main/index.html"
    click Test "https://github.com/markharrison/audiomark/blob/main/test.js"
    click Loader "https://github.com/markharrison/audiomark/blob/main/audio.js"
    click DocAPI "https://github.com/markharrison/audiomark/blob/main/audiomark.md"
    click Guide "https://github.com/markharrison/audiomark/blob/main/README.md"
```
