# echomusicapp/lossless-extension architecture

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

- Interactive diagram: https://gitdiagram.com/echomusicapp/lossless-extension
- Repository: https://github.com/echomusicapp/lossless-extension

## Overview

Echo Music Lossless Extension is a self-hosted addon that resolves track searches and stream metadata through configurable upstream providers; it redirects users to playable HTTPS audio rather than storing audio. Echo Music users connect to the addon, whose HTTP server serves the home player and addon endpoints, selects a provider, normalizes track IDs and stream responses, and returns results. The documented multi mode races providers, while path-prefixed routes expose individual sources. The graph follows shown imports and calls; unsampled provider details and some dynamic UI behavior are omitted.

Main entry points: [`src/providers/index.ts`](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/index.ts) (Provider selection), [`src/server.ts`](https://github.com/echomusicapp/lossless-extension/blob/main/src/server.ts) (HTTP routes), [`src/home.ts`](https://github.com/echomusicapp/lossless-extension/blob/main/src/home.ts) (Home player), [`src/providers/qobuzdl.ts`](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/qobuzdl.ts) (Qobuz-DL adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Addon entry"]
  node_server["HTTP routes<br/>[server.ts]"]
  node_home["Home player<br/>[home.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
  node_cache["TTL cache<br/>[cache.ts]"]
end

subgraph group_resolution["Resolution and identity"]
  node_normalize["Track and stream normalization<br/>[normalize.ts]"]
end

subgraph group_providers["Provider adapters"]
  node_provider_router["Provider selection<br/>[index.ts]"]
  node_racing["First-response race<br/>[racing.ts]"]
  node_qobuzdl["Qobuz-DL adapter<br/>[qobuzdl.ts]"]
  node_lastbabe["LastBabe adapter<br/>[lastbabe.ts]"]
  node_monochrome["Monochrome adapter<br/>[monochrome.ts]"]
  node_instable["Instable adapter<br/>[instable.ts]"]
  node_remote["Remote addon adapter<br/>[remote-addon.ts]"]
  node_http_provider["Configured HTTP adapter<br/>[http.ts]"]
  node_stub["Stub adapter<br/>[stub.ts]"]
end

subgraph group_upstreams["Upstream services"]
  node_qobuz_service["Qobuz-DL service"]
  node_lastbabe_service["LastBabe service"]
  node_monochrome_service["Monochrome service"]
  node_instable_service["Instable service"]
  node_remote_services["Remote addon services"]
end

node_listener(("Echo Music user"))
node_echo["Echo Music"]

node_listener -->|"uses"| node_echo
node_echo -->|"connects to"| node_server
node_server -->|"serves"| node_home
node_server -->|"loads"| node_config
node_server -->|"uses"| node_cache
node_server -->|"selects providers"| node_provider_router
node_server -->|"normalizes results"| node_normalize
node_home -->|"searches"| node_server
node_provider_router -->|"creates race"| node_racing
node_provider_router -->|"constructs"| node_qobuzdl
node_provider_router -->|"constructs"| node_lastbabe
node_provider_router -->|"constructs"| node_monochrome
node_provider_router -->|"constructs"| node_instable
node_provider_router -->|"constructs"| node_remote
node_provider_router -->|"constructs"| node_http_provider
node_provider_router -->|"constructs"| node_stub
node_qobuzdl -->|"requests"| node_qobuz_service
node_lastbabe -->|"requests"| node_lastbabe_service
node_monochrome -->|"requests"| node_monochrome_service
node_instable -->|"requests"| node_instable_service
node_remote -->|"requests"| node_remote_services

click node_server "https://github.com/echomusicapp/lossless-extension/blob/main/src/server.ts"
click node_home "https://github.com/echomusicapp/lossless-extension/blob/main/src/home.ts"
click node_config "https://github.com/echomusicapp/lossless-extension/blob/main/src/config.ts"
click node_cache "https://github.com/echomusicapp/lossless-extension/blob/main/src/cache.ts"
click node_normalize "https://github.com/echomusicapp/lossless-extension/blob/main/src/normalize.ts"
click node_provider_router "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/index.ts"
click node_racing "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/racing.ts"
click node_qobuzdl "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/qobuzdl.ts"
click node_lastbabe "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/lastbabe.ts"
click node_monochrome "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/monochrome.ts"
click node_instable "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/instable.ts"
click node_remote "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/remote-addon.ts"
click node_http_provider "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/http.ts"
click node_stub "https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/stub.ts"

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_server,node_home,node_config,node_cache,node_listener toneBlue
class node_normalize toneAmber
class node_provider_router,node_racing,node_qobuzdl,node_lastbabe,node_monochrome,node_instable,node_remote,node_http_provider,node_stub toneMint
class node_qobuz_service,node_lastbabe_service,node_monochrome_service,node_instable_service,node_remote_services toneRose
class node_echo toneIndigo
```

## Components

### Addon entry

- [HTTP routes](https://github.com/echomusicapp/lossless-extension/blob/main/src/server.ts): `src/server.ts`
- [Home player](https://github.com/echomusicapp/lossless-extension/blob/main/src/home.ts): `src/home.ts`
- [Runtime configuration](https://github.com/echomusicapp/lossless-extension/blob/main/src/config.ts): `src/config.ts`
- [TTL cache](https://github.com/echomusicapp/lossless-extension/blob/main/src/cache.ts): `src/cache.ts`

### Resolution and identity

- [Track and stream normalization](https://github.com/echomusicapp/lossless-extension/blob/main/src/normalize.ts): `src/normalize.ts`

### Provider adapters

- [Provider selection](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/index.ts): `src/providers/index.ts`
- [First-response race](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/racing.ts): `src/providers/racing.ts`
- [Qobuz-DL adapter](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/qobuzdl.ts): `src/providers/qobuzdl.ts`
- [LastBabe adapter](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/lastbabe.ts): `src/providers/lastbabe.ts`
- [Monochrome adapter](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/monochrome.ts): `src/providers/monochrome.ts`
- [Instable adapter](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/instable.ts): `src/providers/instable.ts`
- [Remote addon adapter](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/remote-addon.ts): `src/providers/remote-addon.ts`
- [Configured HTTP adapter](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/http.ts): `src/providers/http.ts`
- [Stub adapter](https://github.com/echomusicapp/lossless-extension/blob/main/src/providers/stub.ts): `src/providers/stub.ts`

### Upstream services

- **Qobuz-DL service**
- **LastBabe service**
- **Monochrome service**
- **Instable service**
- **Remote addon services**

### Other components

- **Echo Music user**
- **Echo Music**

## Connections

- Echo Music user → Echo Music: uses (evidence: `README.md`)
- Echo Music → HTTP routes: connects to (evidence: `README.md`)
- HTTP routes → Home player: serves (evidence: `src/server.ts`)
- HTTP routes → Runtime configuration: loads (evidence: `src/server.ts`)
- HTTP routes → TTL cache: uses (evidence: `src/server.ts`)
- HTTP routes → Provider selection: selects providers (evidence: `src/server.ts`)
- HTTP routes → Track and stream normalization: normalizes results (evidence: `src/server.ts`)
- Home player → HTTP routes: searches (evidence: `src/home.ts`)
- Provider selection → First-response race: creates race (evidence: `src/providers/index.ts`)
- Provider selection → Qobuz-DL adapter: constructs (evidence: `src/providers/index.ts`)
- Provider selection → LastBabe adapter: constructs (evidence: `src/providers/index.ts`)
- Provider selection → Monochrome adapter: constructs (evidence: `src/providers/index.ts`)
- Provider selection → Instable adapter: constructs (evidence: `src/providers/index.ts`)
- Provider selection → Remote addon adapter: constructs (evidence: `src/providers/index.ts`)
- Provider selection → Configured HTTP adapter: constructs (evidence: `src/providers/index.ts`)
- Provider selection → Stub adapter: constructs (evidence: `src/providers/index.ts`)
- Qobuz-DL adapter → Qobuz-DL service: requests (evidence: `src/providers/qobuzdl.ts`)
- LastBabe adapter → LastBabe service: requests (evidence: `src/providers/lastbabe.ts`)
- Monochrome adapter → Monochrome service: requests (evidence: `src/providers/monochrome.ts`)
- Instable adapter → Instable service: requests (evidence: `src/providers/instable.ts`)
- Remote addon adapter → Remote addon services: requests (evidence: `src/providers/remote-addon.ts`)