# createjs/soundjs architecture

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

- Interactive diagram: https://gitdiagram.com/createjs/soundjs
- Repository: https://github.com/createjs/soundjs

## Overview

##### Project type and purpose
- This is an open-source JavaScript audio library (SoundJS) in the CreateJS suite. Its purpose is to provide a unified API for playing and controlling audio across different browsers and environments, with a plugin model to support Web Audio, HTML5 Audio, Flash, and Cordova. It also offers PreloadJS integration for audio preloading.

##### File structure
- Top-level folders:
- src/ – source code split into createjs core, preloadjs (preloading), and soundjs (audio API + plugins).
- lib/ – prebuilt/minified distributions and Cordova/Flash plugins.
- build/ – Grunt build scripts, theming assets, Handlebars templates for docs, and package/config files.
- tests/ – Jasmine specs, test runner, and Grunt tasks for automated tests.
- examples/ & tutorials/ – live HTML demos, assets, and sample code.
- _assets/ – static images, CSS, audio used by examples and docs.
- package.json, bower.json – dependency and build metadata.

##### README for architectural insights
- Core classes: Sound (public API), AbstractSoundInstance, Plugins (WebAudioPlugin, HTMLAudioPlugin, CordovaAudioPlugin, FlashAudioPlugin).
- Integration point: PreloadJS (for preloading audio assets).
- Event system: Uses EventDispatcher and Event classes under createjs/events.
- Build/test tooling: Grunt tasks orchestrate builds, versioning, and tests (Jasmine).

##### Components and interactions
a. Main components
1. Client Application – calls createjs.Sound API.
2. SoundJS Core – Sound and SoundInstance classes, plugin manager.
3. Plugin Interface (AbstractPlugin) – defines load/play API.
4. Plugins – WebAudioPlugin, HTMLAudioPlugin, FlashAudioPlugin, CordovaAudioPlugin.
5. PreloadJS Integration – loader classes (SoundLoader) tying into PreloadJS pipeline.
6. Event System – EventDispatcher, Event classes for load/play events.
7. Utilities – shared helpers (promote, extend, BrowserDetect).
8. Build & Distribution – Grunt tasks, Handlebars templates, SCSS/CSS, packaged output in lib/.
9. Tests & Examples – Jasmine test suite, sample HTML pages, assets from _assets/ and examples/.

b. Relationships and data flow
- Client App → SoundJS Core: API calls (registerSound, play, pause, etc.)
- Core → Plugin Manager: selects appropriate plugin based on environment/capabilities
- Plugin Manager → Plugin: delegates load/play commands
- Plugin → Browser Audio Engine (WebAudio API or HTMLAudio or Flash shim or Cordova native)
- PreloadJS → SoundLoader → Core.registerSound → Plugin Manager
- Core & Plugins → EventDispatcher → Client Application (fileload, complete events)
- src modules → Build pipeline (Grunt) → lib/ (minified + combined)
- Tests → Grunt test runner → Jasmine specs → report results

c. Architectural patterns and design principles
- Plugin architecture (AbstractPlugin interface with multiple concrete implementations)
- Modular code organization (namespaced under createjs, preloadjs, soundjs)
- Event-driven design (EventDispatcher for asynchronous callbacks)
- Build-time templating for docs (Handlebars) and theming (SCSS)
- Automated testing (Jasmine + custom Grunt tasks)

d. Key technologies and frameworks
- JavaScript ES5 modules/namespacing (no bundler required)
- Web Audio API, HTML5 Audio
- SWFObject for Flash fallback
- Cordova/PhoneGap for mobile audio
- Node.js + Grunt for build and test orchestration
- Handlebars for documentation theming
- Jasmine for unit testing

##### Final advice
- Be exhaustive: break the source into namespaces (createjs/events, utils, soundjs/data, etc.) to illustrate modularity.
- Plugin model fully – it is the heart of SoundJS’s architecture.
- Both developer-facing API layer and the underlying browser/native integrations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Layers
    subgraph "Client Application"
        ClientApp["Client App"]:::external
    end

    subgraph "SoundJS Core" 
        Sound["Sound (API)"]:::runtime
        AbstractSoundInstance["AbstractSoundInstance"]:::runtime
    end

    PluginInterface["AbstractPlugin (Interface)"]:::plugin

    subgraph "Plugins"
        WebAudioPlugin["WebAudioPlugin"]:::plugin
        HTMLAudioPlugin["HTMLAudioPlugin"]:::plugin
        FlashAudioPlugin["FlashAudioPlugin"]:::plugin
        CordovaAudioPlugin["CordovaAudioPlugin"]:::plugin
    end

    BrowserEngine["Browser/Native Audio Engine"]:::external

    PreloadIntegration["SoundLoader (PreloadJS)"]:::runtime

    subgraph "Event System"
        EventDispatcher["EventDispatcher"]:::runtime
        Event["Event / ErrorEvent"]:::runtime
    end

    Utilities["Utilities (BrowserDetect, extend, promote, etc.)"]:::runtime
    DataModels["Data Models (AudioSprite, PlayPropsConfig)"]:::runtime
    Version["Version Management"]:::runtime

    subgraph "Build & Distribution"
        Grunt["Grunt Build Scripts"]:::build
        Handlebars["Docs Theming (Handlebars & SCSS)"]:::build
        LibOutputs["Packaged Outputs (lib/*.js)"]:::build
    end

    subgraph "Tests & Examples"
        Tests["Jasmine Tests & Runner"]:::build
        Examples["Examples & Tutorials"]:::docs
    end

    %% Relationships
    ClientApp -->|API call| Sound
    Sound -->|uses| AbstractSoundInstance
    Sound -->|selects plugin| PluginInterface
    PluginInterface -->|implements| WebAudioPlugin
    PluginInterface -->|implements| HTMLAudioPlugin
    PluginInterface -->|implements| FlashAudioPlugin
    PluginInterface -->|implements| CordovaAudioPlugin
    WebAudioPlugin --> BrowserEngine
    HTMLAudioPlugin --> BrowserEngine
    FlashAudioPlugin --> BrowserEngine
    CordovaAudioPlugin --> BrowserEngine

    PreloadIntegration -->|registerSound| Sound
    Sound -->|dispatches| EventDispatcher
    EventDispatcher -- Event / Error events --> Event

    Utilities -->|helpers used by| Sound
    DataModels -->|metadata for| Sound
    Version -->|version info| Sound

    Sound -->|source modules| Grunt
    AbstractSoundInstance --> Grunt
    PluginInterface --> Grunt
    Grunt -->|build outputs to| LibOutputs
    Handlebars -->|templates docs| LibOutputs

    LibOutputs -->|consumed by| Tests
    LibOutputs -->|consumed by| Examples

    %% Click Events
    click Sound "https://github.com/createjs/soundjs/blob/master/src/soundjs/Sound.js"
    click AbstractSoundInstance "https://github.com/createjs/soundjs/blob/master/src/soundjs/AbstractSoundInstance.js"
    click PluginInterface "https://github.com/createjs/soundjs/blob/master/src/soundjs/AbstractPlugin.js"
    click WebAudioPlugin "https://github.com/createjs/soundjs/blob/master/src/soundjs/webaudio/WebAudioPlugin.js"
    click HTMLAudioPlugin "https://github.com/createjs/soundjs/blob/master/src/soundjs/htmlaudio/HTMLAudioPlugin.js"
    click FlashAudioPlugin "https://github.com/createjs/soundjs/blob/master/src/soundjs/flashaudio/FlashAudioPlugin.js"
    click CordovaAudioPlugin "https://github.com/createjs/soundjs/blob/master/src/soundjs/cordovaaudio/CordovaAudioPlugin.js"
    click PreloadIntegration "https://github.com/createjs/soundjs/blob/master/src/preloadjs/loaders/SoundLoader.js"
    click EventDispatcher "https://github.com/createjs/soundjs/blob/master/src/createjs/events/EventDispatcher.js"
    click Event "https://github.com/createjs/soundjs/blob/master/src/createjs/events/Event.js"
    click Utilities "https://github.com/createjs/soundjs/blob/master/src/createjs/utils/BrowserDetect.js"
    click DataModels "https://github.com/createjs/soundjs/blob/master/src/soundjs/data/AudioSprite.js"
    click Version "https://github.com/createjs/soundjs/blob/master/src/soundjs/version.js"
    click Grunt "https://github.com/createjs/soundjs/blob/master/build/Gruntfile.js"
    click LibOutputs "https://github.com/createjs/soundjs/blob/master/lib/soundjs.js"
    click Tests "https://github.com/createjs/soundjs/blob/master/tests/spec/SoundSpec.js"
    click Examples "https://github.com/createjs/soundjs/blob/master/examples/00_Basics.html"

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#004A9F
    classDef plugin fill:#DAF7DC,stroke:#28A745
    classDef build fill:#FFE5B4,stroke:#FF8C00
    classDef docs fill:#E0E0E0,stroke:#666
    classDef external fill:#F0F0F0,stroke:#999
```
