How createjs/soundjs works
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.