# echomusicapp/echo-music architecture

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

- Interactive diagram: https://gitdiagram.com/echomusicapp/echo-music
- Repository: https://github.com/echomusicapp/echo-music

## Overview

Echo Music is an Android music-streaming and library app centered on YouTube Music, with playback, offline downloads, lyrics, recommendations, recognition, and listening/social integrations. The graph summarizes the user-facing route from app entry into playback and highlights distinct product branches. The README documents capabilities, while sampled source confirms selected playback, recognition, recommendation, persistence, DSP, and USB-audio behavior; links for unsampled features are limited to README-supported relationships.

Main entry points: [`app/src/main/kotlin/com/music/echo/playback/MusicService.kt`](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt) (Playback service), [`app/src/main/kotlin/com/music/echo/ui/screens`](https://github.com/echomusicapp/echo-music/tree/main/app/src/main/kotlin/com/music/echo/ui/screens) (Browse and player UI), [`app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt) (Echo Find recognition), [`core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt`](https://github.com/echomusicapp/echo-music/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt) (Music database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_main["App and navigation<br/>[MainActivity.kt]"]
  node_screens["Browse and player UI"]
end

subgraph group_playback["Playback and library"]
  node_service["Playback service<br/>[MusicService.kt]"]
  node_download["Offline downloads"]
  node_database[("Music database<br/>[MusicDatabase.kt]")]
  node_dao["Library and history queries<br/>[DatabaseDao.kt]"]
  node_repositories["Song and playlist repositories"]
end

subgraph group_discovery["Discovery and recognition"]
  node_youtube["YouTube Music access<br/>[YouTube.kt]"]
  node_recommendations["Taste recommendations"]
  node_musicflow["Echo Brain queue"]
  node_recognition["Echo Find recognition"]
  node_signature["Audio signatures"]
end

subgraph group_integrations["Integrations"]
  node_lyrics["Lyrics providers and translation"]
  node_spotify["Spotify import and discovery"]
  node_listen["Listen Together"]
  node_discord["Discord presence"]
end

subgraph group_audio["Audio processing"]
  node_dsp["Playback DSP"]
  node_usb["USB audio output<br/>[UsbDacManager.kt]"]
  node_usbengine["USB stream engine"]
end

node_listener(("Listener"))
node_external{{"YouTube Music service"}}
node_recognitionapi{{"Recognition service"}}

node_listener -->|"opens app"| node_main
node_main -->|"navigates"| node_screens
node_screens -.->|"controls playback"| node_service
node_service -->|"resolves streams"| node_youtube
node_youtube -.->|"requests music"| node_external
node_service -.->|"supports offline"| node_download
node_service -->|"persists queue"| node_database
node_database -->|"provides queries"| node_dao
node_recommendations -->|"fetches candidates"| node_youtube
node_recommendations -->|"reads listening data"| node_database
node_musicflow -.->|"injects queue tracks"| node_service
node_listener -->|"starts recognition"| node_recognition
node_recognition -.->|"generates signatures"| node_signature
node_recognition -.->|"identifies audio"| node_recognitionapi
node_recognition -->|"stores history"| node_database
node_screens -.->|"shows synced lyrics"| node_lyrics
node_screens -.->|"imports playlists"| node_spotify
node_main -->|"joins shared rooms"| node_listen
node_service -->|"updates presence"| node_discord
node_service -->|"configures processors"| node_dsp
node_usb -->|"streams audio"| node_usbengine

click node_main "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt"
click node_screens "https://github.com/echomusicapp/echo-music/tree/main/app/src/main/kotlin/com/music/echo/ui/screens"
click node_service "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt"
click node_download "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt"
click node_database "https://github.com/echomusicapp/echo-music/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt"
click node_dao "https://github.com/echomusicapp/echo-music/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt"
click node_youtube "https://github.com/echomusicapp/echo-music/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt"
click node_recommendations "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/generate/RecommendationEngine.kt"
click node_musicflow "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/musicflow/MusicFlowCoordinator.kt"
click node_recognition "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt"
click node_signature "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/ShazamSignatureGenerator.kt"
click node_lyrics "https://github.com/echomusicapp/echo-music/tree/main/lyrics/src/main/kotlin/echo/music/iad1tya/api"
click node_spotify "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/spotifyimport/SpotifyImportRepository.kt"
click node_listen "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt"
click node_discord "https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/discord/DiscordSocialPresenceClient.kt"
click node_dsp "https://github.com/echomusicapp/echo-music/blob/main/audio-dsp/src/main/kotlin/echo/music/dsp/controller/DspControllerImpl.kt"
click node_usb "https://github.com/echomusicapp/echo-music/blob/main/usbaudio/src/main/kotlin/echo/music/usbaudio/UsbDacManager.kt"
click node_usbengine "https://github.com/echomusicapp/echo-music/blob/main/usbaudio/src/main/cpp/usb_stream_engine.cpp"

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_main,node_screens toneBlue
class node_service,node_download,node_database,node_dao,node_repositories toneAmber
class node_youtube,node_recommendations,node_musicflow,node_recognition,node_signature toneMint
class node_lyrics,node_spotify,node_listen,node_discord toneRose
class node_dsp,node_usb,node_usbengine,node_listener,node_external,node_recognitionapi toneIndigo
```

## Components

### App experience

- [App and navigation](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt): `app/src/main/kotlin/com/music/echo/MainActivity.kt`
- [Browse and player UI](https://github.com/echomusicapp/echo-music/tree/main/app/src/main/kotlin/com/music/echo/ui/screens): `app/src/main/kotlin/com/music/echo/ui/screens`

### Playback and library

- [Playback service](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt): `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`
- [Offline downloads](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt): `app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt`
- [Music database](https://github.com/echomusicapp/echo-music/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt): `core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt`
- [Library and history queries](https://github.com/echomusicapp/echo-music/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt): `core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt`
- **Song and playlist repositories**

### Discovery and recognition

- [YouTube Music access](https://github.com/echomusicapp/echo-music/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt): `innertube/src/main/kotlin/com/music/innertube/YouTube.kt`
- [Taste recommendations](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/generate/RecommendationEngine.kt): `app/src/main/kotlin/com/music/echo/generate/RecommendationEngine.kt`
- [Echo Brain queue](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/musicflow/MusicFlowCoordinator.kt): `app/src/main/kotlin/com/music/echo/musicflow/MusicFlowCoordinator.kt`
- [Echo Find recognition](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt): `app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`
- [Audio signatures](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/ShazamSignatureGenerator.kt): `app/src/main/kotlin/com/music/echo/recognition/ShazamSignatureGenerator.kt`

### Integrations

- [Lyrics providers and translation](https://github.com/echomusicapp/echo-music/tree/main/lyrics/src/main/kotlin/echo/music/iad1tya/api): `lyrics/src/main/kotlin/echo/music/iad1tya/api`
- [Spotify import and discovery](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/spotifyimport/SpotifyImportRepository.kt): `app/src/main/kotlin/com/music/echo/spotifyimport/SpotifyImportRepository.kt`
- [Listen Together](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt): `app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt`
- [Discord presence](https://github.com/echomusicapp/echo-music/blob/main/app/src/main/kotlin/com/music/echo/discord/DiscordSocialPresenceClient.kt): `app/src/main/kotlin/com/music/echo/discord/DiscordSocialPresenceClient.kt`

### Audio processing

- [Playback DSP](https://github.com/echomusicapp/echo-music/blob/main/audio-dsp/src/main/kotlin/echo/music/dsp/controller/DspControllerImpl.kt): `audio-dsp/src/main/kotlin/echo/music/dsp/controller/DspControllerImpl.kt`
- [USB audio output](https://github.com/echomusicapp/echo-music/blob/main/usbaudio/src/main/kotlin/echo/music/usbaudio/UsbDacManager.kt): `usbaudio/src/main/kotlin/echo/music/usbaudio/UsbDacManager.kt`
- [USB stream engine](https://github.com/echomusicapp/echo-music/blob/main/usbaudio/src/main/cpp/usb_stream_engine.cpp): `usbaudio/src/main/cpp/usb_stream_engine.cpp`

### Other components

- **Listener**
- **YouTube Music service**
- **Recognition service**

## Connections

- Listener → App and navigation: opens app (evidence: `README.md`)
- App and navigation → Browse and player UI: navigates (evidence: `app/src/main/kotlin/com/music/echo/MainActivity.kt`)
- Browse and player UI → Playback service: controls playback (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- Playback service → YouTube Music access: resolves streams (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- YouTube Music access → YouTube Music service: requests music
- Playback service → Offline downloads: supports offline (evidence: `README.md`)
- Playback service → Music database: persists queue (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- Music database → Library and history queries: provides queries (evidence: `core/src/main/kotlin/echo/music/iad1tya/db/MusicDatabase.kt`)
- Taste recommendations → YouTube Music access: fetches candidates (evidence: `app/src/main/kotlin/com/music/echo/generate/RecommendationEngine.kt`)
- Taste recommendations → Music database: reads listening data (evidence: `app/src/main/kotlin/com/music/echo/generate/RecommendationEngine.kt`)
- Echo Brain queue → Playback service: injects queue tracks
- Listener → Echo Find recognition: starts recognition
- Echo Find recognition → Audio signatures: generates signatures
- Echo Find recognition → Recognition service: identifies audio (evidence: `README.md`)
- Echo Find recognition → Music database: stores history
- Browse and player UI → Lyrics providers and translation: shows synced lyrics (evidence: `README.md`)
- Browse and player UI → Spotify import and discovery: imports playlists (evidence: `README.md`)
- App and navigation → Listen Together: joins shared rooms (evidence: `app/src/main/kotlin/com/music/echo/MainActivity.kt`)
- Playback service → Discord presence: updates presence (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- Playback service → Playback DSP: configures processors (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- USB audio output → USB stream engine: streams audio (evidence: `usbaudio/src/main/kotlin/echo/music/usbaudio/UsbDacManager.kt`)