# nex-devz/solaceaudio architecture

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

- Interactive diagram: https://gitdiagram.com/nex-devz/solaceaudio
- Repository: https://github.com/nex-devz/solaceaudio

## Overview

SolaceAudio is a Lavalink v4 audio-source plugin: a Lavalink request reaches registered provider managers, which resolve searches or direct URLs into tracks and playlists for playback. Mirroring providers use a shared resolution engine with concurrent-search coalescing and candidate scoring; YouTube adds proxying and SponsorBlock, while caching, lyrics, recommendations, and DSP filters provide supporting capabilities. The graph preserves documented provider breadth, but several connections are shown only where the excerpts or README establish them; unsampled implementation details are not inferred.

Main entry points: [`plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`](https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java) (Plugin Registration), [`main/src/main/java/com/solaceaudio/resolver/TrackResolutionEngine.java`](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/TrackResolutionEngine.java) (Resolution Engine), [`main/src/main/java/com/solaceaudio/lyrics/SolaceLyricsManager.java`](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/lyrics/SolaceLyricsManager.java) (Lyrics Aggregator), [`main/src/main/java/com/solaceaudio/sources/spotify/SpotifyAudioSourceManager.java`](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/spotify/SpotifyAudioSourceManager.java) (Spotify Source)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Plugin and API"]
  node_plugin["Plugin Registration"]
  node_recommendations["Recommendations API"]
  node_lyrics_api["Lyrics API"]
  node_sponsor_api["SponsorBlock API"]
end

subgraph group_resolution["Track Resolution"]
  node_resolution_engine["Resolution Engine"]
  node_candidate_scoring["Candidate Scoring"]
  node_mirroring["Mirroring Manager"]
  node_audio_mirror["Mirror Track"]
end

subgraph group_providers["Audio Providers"]
  node_spotify["Spotify Source"]
  node_youtube["YouTube Source"]
  node_deezer["Deezer Source"]
  node_other_sources["Other Providers"]
end

subgraph group_playback["Playback Support"]
  node_youtube_proxy["YouTube Proxy"]
  node_sponsorblock["SponsorBlock"]
  node_filters["Audio Filters"]
  node_cache["Memory Cache"]
  node_playlist["Playlist Model"]
end

subgraph group_metadata["Metadata Services"]
  node_lyrics["Lyrics Aggregator"]
  node_lastfm["Last.fm Source"]
end

node_lavalink(("Lavalink v4"))

node_lavalink -.->|"loads plugin"| node_plugin
node_plugin -.->|"registers source"| node_spotify
node_plugin -.->|"registers source"| node_youtube
node_plugin -.->|"registers source"| node_deezer
node_plugin -.->|"registers sources"| node_other_sources
node_plugin -->|"provides manager"| node_lyrics
node_recommendations -->|"searches tracks"| node_spotify
node_recommendations -->|"gets recommendations"| node_lastfm
node_lyrics_api -->|"requests lyrics"| node_lyrics
node_sponsor_api -->|"requests segments"| node_sponsorblock
node_resolution_engine -->|"resolves track"| node_audio_mirror
node_resolution_engine -->|"scores candidates"| node_candidate_scoring
node_mirroring -.->|"holds resolver"| node_resolution_engine
node_spotify -->|"uses resolver"| node_resolution_engine
node_deezer -.->|"uses resolver"| node_resolution_engine
node_other_sources -.->|"mirrors tracks"| node_resolution_engine
node_lyrics -->|"caches lyrics"| node_cache
node_lyrics -.->|"queries provider"| node_spotify
node_youtube -->|"uses proxy"| node_youtube_proxy
node_youtube -->|"uses manager"| node_sponsorblock
node_playlist -.->|"represents results"| node_other_sources

click node_plugin "https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java"
click node_recommendations "https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/RecommendationController.java"
click node_lyrics_api "https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/LyricsController.java"
click node_sponsor_api "https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/SponsorBlockController.java"
click node_resolution_engine "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/TrackResolutionEngine.java"
click node_candidate_scoring "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/CandidateScorer.java"
click node_mirroring "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/MirroringSourceManager.java"
click node_audio_mirror "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/AudioMirrorTrack.java"
click node_spotify "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/spotify/SpotifyAudioSourceManager.java"
click node_youtube "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/youtube/YouTubeSourceManager.java"
click node_deezer "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/deezer/DeezerAudioSourceManager.java"
click node_other_sources "https://github.com/nex-devz/solaceaudio/tree/main/main/src/main/java/com/solaceaudio/sources"
click node_youtube_proxy "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/youtube/YouTubeProxyHandler.java"
click node_sponsorblock "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/youtube/sponsorblock/SponsorBlockManager.java"
click node_filters "https://github.com/nex-devz/solaceaudio/tree/main/main/src/main/java/com/solaceaudio/filter"
click node_cache "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/core/MemoryCacheManager.java"
click node_playlist "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/model/SolaceAudioPlaylist.java"
click node_lyrics "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/lyrics/SolaceLyricsManager.java"
click node_lastfm "https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/lastfm/LastFmSourceManager.java"

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_plugin,node_recommendations,node_lyrics_api,node_sponsor_api toneBlue
class node_resolution_engine,node_candidate_scoring,node_mirroring,node_audio_mirror toneAmber
class node_spotify,node_youtube,node_deezer,node_other_sources toneMint
class node_youtube_proxy,node_sponsorblock,node_filters,node_cache,node_playlist toneRose
class node_lyrics,node_lastfm,node_lavalink toneIndigo
```

## Components

### Plugin and API

- [Plugin Registration](https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java): `plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`
- [Recommendations API](https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/RecommendationController.java): `plugin/src/main/java/com/solaceaudio/plugin/RecommendationController.java`
- [Lyrics API](https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/LyricsController.java): `plugin/src/main/java/com/solaceaudio/plugin/LyricsController.java`
- [SponsorBlock API](https://github.com/nex-devz/solaceaudio/blob/main/plugin/src/main/java/com/solaceaudio/plugin/SponsorBlockController.java): `plugin/src/main/java/com/solaceaudio/plugin/SponsorBlockController.java`

### Track Resolution

- [Resolution Engine](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/TrackResolutionEngine.java): `main/src/main/java/com/solaceaudio/resolver/TrackResolutionEngine.java`
- [Candidate Scoring](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/CandidateScorer.java): `main/src/main/java/com/solaceaudio/resolver/CandidateScorer.java`
- [Mirroring Manager](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/MirroringSourceManager.java): `main/src/main/java/com/solaceaudio/resolver/MirroringSourceManager.java`
- [Mirror Track](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/resolver/AudioMirrorTrack.java): `main/src/main/java/com/solaceaudio/resolver/AudioMirrorTrack.java`

### Audio Providers

- [Spotify Source](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/spotify/SpotifyAudioSourceManager.java): `main/src/main/java/com/solaceaudio/sources/spotify/SpotifyAudioSourceManager.java`
- [YouTube Source](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/youtube/YouTubeSourceManager.java): `main/src/main/java/com/solaceaudio/sources/youtube/YouTubeSourceManager.java`
- [Deezer Source](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/deezer/DeezerAudioSourceManager.java): `main/src/main/java/com/solaceaudio/sources/deezer/DeezerAudioSourceManager.java`
- [Other Providers](https://github.com/nex-devz/solaceaudio/tree/main/main/src/main/java/com/solaceaudio/sources): `main/src/main/java/com/solaceaudio/sources`

### Playback Support

- [YouTube Proxy](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/youtube/YouTubeProxyHandler.java): `main/src/main/java/com/solaceaudio/sources/youtube/YouTubeProxyHandler.java`
- [SponsorBlock](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/youtube/sponsorblock/SponsorBlockManager.java): `main/src/main/java/com/solaceaudio/sources/youtube/sponsorblock/SponsorBlockManager.java`
- [Audio Filters](https://github.com/nex-devz/solaceaudio/tree/main/main/src/main/java/com/solaceaudio/filter): `main/src/main/java/com/solaceaudio/filter`
- [Memory Cache](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/core/MemoryCacheManager.java): `main/src/main/java/com/solaceaudio/core/MemoryCacheManager.java`
- [Playlist Model](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/model/SolaceAudioPlaylist.java): `main/src/main/java/com/solaceaudio/model/SolaceAudioPlaylist.java`

### Metadata Services

- [Lyrics Aggregator](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/lyrics/SolaceLyricsManager.java): `main/src/main/java/com/solaceaudio/lyrics/SolaceLyricsManager.java`
- [Last.fm Source](https://github.com/nex-devz/solaceaudio/blob/main/main/src/main/java/com/solaceaudio/sources/lastfm/LastFmSourceManager.java): `main/src/main/java/com/solaceaudio/sources/lastfm/LastFmSourceManager.java`

### Other components

- **Lavalink v4**

## Connections

- Lavalink v4 → Plugin Registration: loads plugin (evidence: `README.md`)
- Plugin Registration → Spotify Source: registers source (evidence: `plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`)
- Plugin Registration → YouTube Source: registers source (evidence: `plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`)
- Plugin Registration → Deezer Source: registers source (evidence: `plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`)
- Plugin Registration → Other Providers: registers sources (evidence: `plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`)
- Plugin Registration → Lyrics Aggregator: provides manager (evidence: `plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`)
- Recommendations API → Spotify Source: searches tracks (evidence: `plugin/src/main/java/com/solaceaudio/plugin/RecommendationController.java`)
- Recommendations API → Last.fm Source: gets recommendations (evidence: `plugin/src/main/java/com/solaceaudio/plugin/RecommendationController.java`)
- Lyrics API → Lyrics Aggregator: requests lyrics (evidence: `plugin/src/main/java/com/solaceaudio/plugin/LyricsController.java`)
- SponsorBlock API → SponsorBlock: requests segments (evidence: `plugin/src/main/java/com/solaceaudio/plugin/SponsorBlockController.java`)
- Resolution Engine → Mirror Track: resolves track (evidence: `main/src/main/java/com/solaceaudio/resolver/TrackResolutionEngine.java`)
- Resolution Engine → Candidate Scoring: scores candidates (evidence: `main/src/main/java/com/solaceaudio/resolver/TrackResolutionEngine.java`)
- Mirroring Manager → Resolution Engine: holds resolver (evidence: `main/src/main/java/com/solaceaudio/resolver/MirroringSourceManager.java`)
- Spotify Source → Resolution Engine: uses resolver (evidence: `main/src/main/java/com/solaceaudio/sources/spotify/SpotifyAudioSourceManager.java`)
- Deezer Source → Resolution Engine: uses resolver (evidence: `main/src/main/java/com/solaceaudio/sources/deezer/DeezerAudioSourceManager.java`)
- Other Providers → Resolution Engine: mirrors tracks (evidence: `README.md`)
- Lyrics Aggregator → Memory Cache: caches lyrics (evidence: `main/src/main/java/com/solaceaudio/lyrics/SolaceLyricsManager.java`)
- Lyrics Aggregator → Spotify Source: queries provider (evidence: `plugin/src/main/java/com/solaceaudio/plugin/SolaceAudioPlugin.java`)
- YouTube Source → YouTube Proxy: uses proxy (evidence: `main/src/main/java/com/solaceaudio/sources/youtube/YouTubeSourceManager.java`)
- YouTube Source → SponsorBlock: uses manager (evidence: `main/src/main/java/com/solaceaudio/sources/youtube/YouTubeSourceManager.java`)
- Playlist Model → Other Providers: represents results (evidence: `main/src/main/java/com/solaceaudio/sources/gaana/GaanaAudioSourceManager.java`)