# jagthedrummer/ember-stereo architecture

> Architecture diagram of the GitHub repository jagthedrummer/ember-stereo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jagthedrummer/ember-stereo
- Repository: https://github.com/jagthedrummer/ember-stereo

## Overview

ember-stereo is an Ember audio playback library. An app supplies an identifier or URL to a template helper or the stereo service; the service resolves and loads a sound through connection strategies, then exposes playback state and controls for reactive UI. The README also documents audio metadata, error/state helpers, position and volume modifiers, and HLS/Howler/native connection support. Source excerpts show the service’s utility dependencies and the native adapter’s base-class relationship; unsampled helper and adapter wiring is represented only where documented.

Main entry points: [`ember-stereo/src/services/stereo.js`](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/services/stereo.js) (Stereo service), [`ember-stereo/src/-private/utils/strategizer.js`](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/strategizer.js) (Strategy selection), [`ember-stereo/src/helpers/play-sound.js`](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/play-sound.js) (Template helpers), [`ember-stereo/src/helpers/sound-is-playing.js`](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/sound-is-playing.js) (Sound state helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Ember API"]
  node_template["Template helpers<br/>[play-sound.js]"]
  node_service["Stereo service<br/>[stereo.js]"]
end

subgraph group_core["Playback Core"]
  node_identifiers["URL normalization<br/>[stereo-url.js]"]
  node_caches[("Sound and URL caches<br/>[sound-cache.js]")]
  node_strategy["Strategy selection<br/>[strategizer.js]"]
  node_loader["Connection loading"]
  node_errors[("Error tracking<br/>[error-cache.js]")]
  node_proxy["Sound proxy<br/>[sound-proxy.js]"]
  node_sharedaudio["Shared audio access"]
end

subgraph group_connections["Audio Connections"]
  node_base["Sound base<br/>[base.js]"]
  node_native["Native audio<br/>[native-audio.js]"]
  node_hls["HLS connection<br/>[hls.js]"]
  node_howler["Howler connection<br/>[howler.js]"]
end

subgraph group_ui["Reactive UI"]
  node_statehelpers["Sound state helpers"]
  node_metadata["Metadata helpers<br/>[sound-metadata.js]"]
  node_errorshelper["Error details helper"]
  node_controls["Position and volume"]
end

node_app(("Ember app"))

node_app -->|"invokes"| node_template
node_app -->|"calls"| node_service
node_template -->|"controls"| node_service
node_service -->|"normalizes URLs"| node_identifiers
node_service -->|"uses caches"| node_caches
node_service -->|"selects strategies"| node_strategy
node_service -->|"loads connections"| node_loader
node_service -->|"tracks errors"| node_errors
node_service -->|"creates proxies"| node_proxy
node_service -->|"shares audio"| node_sharedaudio
node_strategy -->|"builds URL strategy"| node_identifiers
node_strategy -.->|"tests connections"| node_base
node_native -->|"extends"| node_base
node_service -.->|"tries connection"| node_hls
node_service -.->|"tries connection"| node_howler
node_app -->|"reads state"| node_statehelpers
node_app -->|"reads metadata"| node_metadata
node_app -->|"reads errors"| node_errorshelper
node_app -->|"binds controls"| node_controls
node_statehelpers -.->|"queries sounds"| node_service
node_metadata -.->|"queries sounds"| node_service
node_errorshelper -->|"reads cached errors"| node_service
node_controls -.->|"sets playback position"| node_service

click node_template "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/play-sound.js"
click node_service "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/services/stereo.js"
click node_identifiers "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/stereo-url.js"
click node_caches "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/sound-cache.js"
click node_strategy "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/strategizer.js"
click node_loader "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/connection-loader.js"
click node_errors "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/error-cache.js"
click node_proxy "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/sound-proxy.js"
click node_sharedaudio "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/shared-audio-access.js"
click node_base "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/base.js"
click node_native "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/native-audio.js"
click node_hls "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/hls.js"
click node_howler "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/howler.js"
click node_statehelpers "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/sound-is-playing.js"
click node_metadata "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/sound-metadata.js"
click node_errorshelper "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/sound-error-details.js"
click node_controls "https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/modifiers/sound-position-slider.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_template,node_service toneBlue
class node_identifiers,node_caches,node_strategy,node_loader,node_errors,node_proxy,node_sharedaudio toneAmber
class node_base,node_native,node_hls,node_howler toneMint
class node_statehelpers,node_metadata,node_errorshelper,node_controls toneRose
class node_app toneIndigo
```

## Components

### Ember API

- [Template helpers](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/play-sound.js): `ember-stereo/src/helpers/play-sound.js`
- [Stereo service](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/services/stereo.js): `ember-stereo/src/services/stereo.js`

### Playback Core

- [URL normalization](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/stereo-url.js): `ember-stereo/src/-private/utils/stereo-url.js`
- [Sound and URL caches](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/sound-cache.js): `ember-stereo/src/-private/utils/sound-cache.js`
- [Strategy selection](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/strategizer.js): `ember-stereo/src/-private/utils/strategizer.js`
- [Connection loading](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/connection-loader.js): `ember-stereo/src/-private/utils/connection-loader.js`
- [Error tracking](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/error-cache.js): `ember-stereo/src/-private/utils/error-cache.js`
- [Sound proxy](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/sound-proxy.js): `ember-stereo/src/-private/utils/sound-proxy.js`
- [Shared audio access](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/-private/utils/shared-audio-access.js): `ember-stereo/src/-private/utils/shared-audio-access.js`

### Audio Connections

- [Sound base](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/base.js): `ember-stereo/src/stereo-connections/base.js`
- [Native audio](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/native-audio.js): `ember-stereo/src/stereo-connections/native-audio.js`
- [HLS connection](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/hls.js): `ember-stereo/src/stereo-connections/hls.js`
- [Howler connection](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/stereo-connections/howler.js): `ember-stereo/src/stereo-connections/howler.js`

### Reactive UI

- [Sound state helpers](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/sound-is-playing.js): `ember-stereo/src/helpers/sound-is-playing.js`
- [Metadata helpers](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/sound-metadata.js): `ember-stereo/src/helpers/sound-metadata.js`
- [Error details helper](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/helpers/sound-error-details.js): `ember-stereo/src/helpers/sound-error-details.js`
- [Position and volume](https://github.com/jagthedrummer/ember-stereo/blob/main/ember-stereo/src/modifiers/sound-position-slider.js): `ember-stereo/src/modifiers/sound-position-slider.js`

### Other components

- **Ember app**

## Connections

- Ember app → Template helpers: invokes
- Ember app → Stereo service: calls
- Template helpers → Stereo service: controls
- Stereo service → URL normalization: normalizes URLs (evidence: `ember-stereo/src/services/stereo.js`)
- Stereo service → Sound and URL caches: uses caches (evidence: `ember-stereo/src/services/stereo.js`)
- Stereo service → Strategy selection: selects strategies (evidence: `ember-stereo/src/services/stereo.js`)
- Stereo service → Connection loading: loads connections (evidence: `ember-stereo/src/services/stereo.js`)
- Stereo service → Error tracking: tracks errors (evidence: `ember-stereo/src/services/stereo.js`)
- Stereo service → Sound proxy: creates proxies (evidence: `ember-stereo/src/services/stereo.js`)
- Stereo service → Shared audio access: shares audio (evidence: `ember-stereo/src/services/stereo.js`)
- Strategy selection → URL normalization: builds URL strategy (evidence: `ember-stereo/src/-private/utils/strategizer.js`)
- Strategy selection → Sound base: tests connections
- Native audio → Sound base: extends (evidence: `ember-stereo/src/stereo-connections/native-audio.js`)
- Stereo service → HLS connection: tries connection
- Stereo service → Howler connection: tries connection
- Ember app → Sound state helpers: reads state
- Ember app → Metadata helpers: reads metadata
- Ember app → Error details helper: reads errors (evidence: `ember-stereo/src/helpers/sound-error-details.js`)
- Ember app → Position and volume: binds controls
- Sound state helpers → Stereo service: queries sounds
- Metadata helpers → Stereo service: queries sounds
- Error details helper → Stereo service: reads cached errors (evidence: `ember-stereo/src/helpers/sound-error-details.js`)
- Position and volume → Stereo service: sets playback position
