# sm19052002-lang/echo-music architecture

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

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

## Overview

Echo Music is an Android streaming and local-media player. The main user path is browsing/searching YouTube Music, selecting tracks, and listening through a background media session; the app also supports offline playback, lyrics, recognition, recommendations, Spotify import, and synchronized listening. Nodes represent the principal domain stages and major documented feature branches. Relationship evidence is limited to the README and supplied source excerpts/index; unsampled subsystems are included where the tree and README establish their role, with unverified links omitted or dashed.

Main entry points: [`app/src/main/kotlin/com/music/echo/playback/MusicService.kt`](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt) (Media Session), [`innertube/src/main/kotlin/com/music/innertube/YouTube.kt`](https://github.com/sm19052002-lang/echo-music/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt) (YouTube Music API), [`app/src/main/kotlin/com/music/echo/MainActivity.kt`](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt) (App Navigation), [`app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt) (Audio Recognition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Experience"]
  node_navigation["App Navigation<br/>[MainActivity.kt]"]
  node_player_ui["Player UI<br/>[Player.kt]"]
end

subgraph group_discovery["Discovery &amp; Catalog"]
  node_search["Search &amp; Browse"]
  node_youtube["YouTube Music API<br/>[YouTube.kt]"]
  node_spotify["Spotify Integration"]
  node_spotifyimport["Spotify Import"]
  node_recommendations["Recommendations"]
  node_echo_brain["Echo Brain"]
end

subgraph group_playback["Playback &amp; Library"]
  node_service["Media Session<br/>[MusicService.kt]"]
  node_localmedia["Local Media"]
  node_downloads["Offline Downloads"]
  node_database[("Music Database<br/>[DatabaseDao.kt]")]
end

subgraph group_features["Listening Features"]
  node_lyrics["Synced Lyrics<br/>[Lyrics.kt]"]
  node_lyrics_providers["Lyrics Providers"]
  node_recognition_ui["Echo Find UI"]
  node_recognition["Audio Recognition"]
  node_signature["Signature Engine<br/>[VibraSignature.kt]"]
  node_shazam["ShazamKit<br/>[Shazam.kt]"]
  node_together_ui["Listen Together UI"]
  node_together["Room Synchronization"]
  node_room_client["Room Client"]
end

node_listener(("Listener"))
node_room_service["Listen Together Service"]

node_listener -->|"opens app"| node_navigation
node_navigation -.->|"navigates to"| node_search
node_search -.->|"searches catalog"| node_youtube
node_navigation -.->|"shows playback"| node_player_ui
node_player_ui -.->|"controls"| node_service
node_service -->|"fetches streams"| node_youtube
node_service -.->|"persists queue"| node_database
node_localmedia -.->|"provides tracks"| node_service
node_downloads -->|"downloads media"| node_youtube
node_downloads -.->|"stores download state"| node_database
node_service -.->|"loads lyrics"| node_lyrics_providers
node_lyrics -.->|"displays lyrics"| node_lyrics_providers
node_spotifyimport -.->|"imports playlists"| node_spotify
node_recommendations -.->|"requests suggestions"| node_youtube
node_echo_brain -.->|"extends queue"| node_service
node_listener -.->|"starts recognition"| node_recognition_ui
node_recognition_ui -.->|"requests match"| node_recognition
node_recognition -->|"generates signature"| node_signature
node_recognition -->|"checks match"| node_shazam
node_listener -.->|"joins session"| node_together_ui
node_together_ui -.->|"manages session"| node_together
node_together -->|"handles events"| node_room_client
node_together -->|"synchronizes playback"| node_service
node_room_client -.->|"exchanges room data"| node_room_service

click node_navigation "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt"
click node_search "https://github.com/sm19052002-lang/echo-music/tree/main/app/src/main/kotlin/com/music/echo/ui/screens/search"
click node_youtube "https://github.com/sm19052002-lang/echo-music/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt"
click node_spotify "https://github.com/sm19052002-lang/echo-music/tree/main/app/src/main/kotlin/com/music/echo/spotify"
click node_spotifyimport "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/spotifyimport/SpotifyImportRepository.kt"
click node_recommendations "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ai/AiRecommendationHelper.kt"
click node_echo_brain "https://github.com/sm19052002-lang/echo-music/tree/main/app/src/main/kotlin/com/music/echo/ai"
click node_player_ui "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/player/Player.kt"
click node_service "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt"
click node_localmedia "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/localmedia/LocalSongScanner.kt"
click node_downloads "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt"
click node_database "https://github.com/sm19052002-lang/echo-music/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt"
click node_lyrics "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/component/Lyrics.kt"
click node_lyrics_providers "https://github.com/sm19052002-lang/echo-music/blob/main/lyrics/src/main/kotlin/echo/music/iad1tya/lyrics/LyricsTranslationHelper.kt"
click node_recognition_ui "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/screens/recognition/RecognitionScreen.kt"
click node_recognition "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt"
click node_signature "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/VibraSignature.kt"
click node_shazam "https://github.com/sm19052002-lang/echo-music/blob/main/shazamkit/src/main/kotlin/com/music/shazamkit/Shazam.kt"
click node_together_ui "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/screens/ListenTogetherScreen.kt"
click node_together "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt"
click node_room_client "https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherClient.kt"

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_navigation,node_player_ui toneBlue
class node_search,node_youtube,node_spotify,node_spotifyimport,node_recommendations,node_echo_brain toneAmber
class node_service,node_localmedia,node_downloads,node_database toneMint
class node_lyrics,node_lyrics_providers,node_recognition_ui,node_recognition,node_signature,node_shazam,node_together_ui,node_together,node_room_client toneRose
class node_listener,node_room_service toneIndigo
```

## Components

### App Experience

- [App Navigation](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/MainActivity.kt): `app/src/main/kotlin/com/music/echo/MainActivity.kt`
- [Player UI](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/player/Player.kt): `app/src/main/kotlin/com/music/echo/ui/player/Player.kt`

### Discovery & Catalog

- [Search & Browse](https://github.com/sm19052002-lang/echo-music/tree/main/app/src/main/kotlin/com/music/echo/ui/screens/search): `app/src/main/kotlin/com/music/echo/ui/screens/search`
- [YouTube Music API](https://github.com/sm19052002-lang/echo-music/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt): `innertube/src/main/kotlin/com/music/innertube/YouTube.kt`
- [Spotify Integration](https://github.com/sm19052002-lang/echo-music/tree/main/app/src/main/kotlin/com/music/echo/spotify): `app/src/main/kotlin/com/music/echo/spotify`
- [Spotify Import](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/spotifyimport/SpotifyImportRepository.kt): `app/src/main/kotlin/com/music/echo/spotifyimport/SpotifyImportRepository.kt`
- [Recommendations](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ai/AiRecommendationHelper.kt): `app/src/main/kotlin/com/music/echo/ai/AiRecommendationHelper.kt`
- [Echo Brain](https://github.com/sm19052002-lang/echo-music/tree/main/app/src/main/kotlin/com/music/echo/ai): `app/src/main/kotlin/com/music/echo/ai`

### Playback & Library

- [Media Session](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/playback/MusicService.kt): `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`
- [Local Media](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/localmedia/LocalSongScanner.kt): `app/src/main/kotlin/com/music/echo/localmedia/LocalSongScanner.kt`
- [Offline Downloads](https://github.com/sm19052002-lang/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/sm19052002-lang/echo-music/blob/main/core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt): `core/src/main/kotlin/echo/music/iad1tya/db/DatabaseDao.kt`

### Listening Features

- [Synced Lyrics](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/component/Lyrics.kt): `app/src/main/kotlin/com/music/echo/ui/component/Lyrics.kt`
- [Lyrics Providers](https://github.com/sm19052002-lang/echo-music/blob/main/lyrics/src/main/kotlin/echo/music/iad1tya/lyrics/LyricsTranslationHelper.kt): `lyrics/src/main/kotlin/echo/music/iad1tya/lyrics/LyricsTranslationHelper.kt`
- [Echo Find UI](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/screens/recognition/RecognitionScreen.kt): `app/src/main/kotlin/com/music/echo/ui/screens/recognition/RecognitionScreen.kt`
- [Audio Recognition](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt): `app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`
- [Signature Engine](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/recognition/VibraSignature.kt): `app/src/main/kotlin/com/music/echo/recognition/VibraSignature.kt`
- [ShazamKit](https://github.com/sm19052002-lang/echo-music/blob/main/shazamkit/src/main/kotlin/com/music/shazamkit/Shazam.kt): `shazamkit/src/main/kotlin/com/music/shazamkit/Shazam.kt`
- [Listen Together UI](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/ui/screens/ListenTogetherScreen.kt): `app/src/main/kotlin/com/music/echo/ui/screens/ListenTogetherScreen.kt`
- [Room Synchronization](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt): `app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt`
- [Room Client](https://github.com/sm19052002-lang/echo-music/blob/main/app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherClient.kt): `app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherClient.kt`

### Other components

- **Listener**
- **Listen Together Service**

## Connections

- Listener → App Navigation: opens app (evidence: `app/src/main/kotlin/com/music/echo/MainActivity.kt`)
- App Navigation → Search & Browse: navigates to
- Search & Browse → YouTube Music API: searches catalog
- App Navigation → Player UI: shows playback (evidence: `app/src/main/kotlin/com/music/echo/MainActivity.kt`)
- Player UI → Media Session: controls (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- Media Session → YouTube Music API: fetches streams (evidence: `app/src/main/kotlin/com/music/echo/playback/MusicService.kt`)
- Media Session → Music Database: persists queue
- Local Media → Media Session: provides tracks
- Offline Downloads → YouTube Music API: downloads media (evidence: `app/src/main/kotlin/com/music/echo/playback/ExoDownloadService.kt`)
- Offline Downloads → Music Database: stores download state
- Media Session → Lyrics Providers: loads lyrics
- Synced Lyrics → Lyrics Providers: displays lyrics
- Spotify Import → Spotify Integration: imports playlists
- Recommendations → YouTube Music API: requests suggestions
- Echo Brain → Media Session: extends queue
- Listener → Echo Find UI: starts recognition
- Echo Find UI → Audio Recognition: requests match
- Audio Recognition → Signature Engine: generates signature (evidence: `app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`)
- Audio Recognition → ShazamKit: checks match (evidence: `app/src/main/kotlin/com/music/echo/recognition/MusicRecognitionService.kt`)
- Listener → Listen Together UI: joins session
- Listen Together UI → Room Synchronization: manages session
- Room Synchronization → Room Client: handles events (evidence: `app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt`)
- Room Synchronization → Media Session: synchronizes playback (evidence: `app/src/main/kotlin/com/music/echo/listentogether/ListenTogetherManager.kt`)
- Room Client → Listen Together Service: exchanges room data