# harbertraj/beatraxus architecture

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

- Interactive diagram: https://gitdiagram.com/harbertraj/beatraxus
- Repository: https://github.com/harbertraj/beatraxus

## Overview

Beatraxus is an Android music player whose central workflow is discovering local or remote music, selecting a track, and playing it through a custom audio engine with configurable DSP and output. Its documented capabilities also include cloud/NAS and Telegram sources, casting, Auto-EQ and AI analysis, lyrics, video playback and subtitles, and streaming add-ons. The map follows indexed references and explicit README claims; several feature branches are represented at their subsystem paths because their implementation was not sampled.

Main entry points: [`app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt`](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt) (Audio engine), [`app/src/main/java/com/beatraxus/app/ui/screens/MainScreen.kt`](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/MainScreen.kt) (Main screen), [`app/src/main/java/com/beatraxus/app/drive/CloudCacheManager.kt`](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/drive/CloudCacheManager.kt) (Cloud streaming), [`app/src/main/java/com/beatraxus/app/ui/screens/NowPlayingScreen.kt`](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/NowPlayingScreen.kt) (Player screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_main["Main screen<br/>[MainScreen.kt]"]
  node_playerui["Player screens"]
  node_videoui["Video player"]
end

subgraph group_sources["Media sources"]
  node_library["Library scanning<br/>[LibraryScanner.kt]"]
  node_cloud["Cloud streaming"]
  node_telegram["Telegram access<br/>[TdLibManager.kt]"]
  node_nas["NAS connections"]
  node_addons["Streaming add-ons<br/>[AddonManager.kt]"]
end

subgraph group_playback["Playback and audio"]
  node_service["Playback service"]
  node_engine["Audio engine<br/>[AudioEngine.kt]"]
  node_decode["Audio decoding<br/>[DecoderFactory.kt]"]
  node_dsp["DSP pipeline<br/>[DspPipeline.kt]"]
  node_native["Native DSP<br/>[NativeDsp.kt]"]
  node_output["Audio output<br/>[AudioOutput.kt]"]
  node_cast["Casting<br/>[CastManager.kt]"]
end

subgraph group_intelligence["Enrichment and data"]
  node_database[("App database<br/>[AppDatabase.kt]")]
  node_analysis["AI analysis"]
  node_autoeq["Auto-EQ"]
  node_lyrics["Lyrics"]
end

subgraph group_extensions["Connected features"]
  node_subtitles["Subtitle support"]
  node_videoaudio["Video audio bridge"]
end

node_listener(("Listener"))

node_listener -->|"browses"| node_main
node_main -.->|"browses library"| node_library
node_library -.->|"streams and caches"| node_cloud
node_cloud -->|"provides media"| node_engine
node_cloud -->|"requests content"| node_telegram
node_main -.->|"browses add-ons"| node_addons
node_nas -.->|"provides remote files"| node_cloud
node_main -.->|"opens playback"| node_playerui
node_playerui -.->|"controls playback"| node_service
node_service -->|"controls"| node_engine
node_engine -->|"selects decoder"| node_decode
node_engine -->|"renders audio"| node_output
node_engine -.->|"processes audio"| node_dsp
node_dsp -->|"invokes DSP"| node_native
node_service -->|"routes playback"| node_cast
node_engine -.->|"uses stored state"| node_database
node_analysis -.->|"stores analysis"| node_database
node_analysis -->|"calculates EQ"| node_autoeq
node_playerui -.->|"shows lyrics"| node_lyrics
node_main -.->|"opens video"| node_videoui
node_videoui -.->|"manages subtitles"| node_subtitles
node_videoui -.->|"bridges audio"| node_videoaudio

click node_main "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/MainScreen.kt"
click node_playerui "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/NowPlayingScreen.kt"
click node_videoui "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/VideoPlayerScreen.kt"
click node_library "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/LibraryScanner.kt"
click node_cloud "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/drive/CloudCacheManager.kt"
click node_telegram "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/telegram/TdLibManager.kt"
click node_nas "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/SmbConnectionRepository.kt"
click node_addons "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/addons/AddonManager.kt"
click node_service "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/service/AudioPlaybackService.kt"
click node_engine "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt"
click node_decode "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/DecoderFactory.kt"
click node_dsp "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/DspPipeline.kt"
click node_native "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/NativeDsp.kt"
click node_output "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/AudioOutput.kt"
click node_cast "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/cast/CastManager.kt"
click node_database "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/model/AppDatabase.kt"
click node_analysis "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/AiAnalysisEngine.kt"
click node_autoeq "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/AutoEqRepository.kt"
click node_lyrics "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/LyricsRepository.kt"
click node_subtitles "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/subtitles/viewmodel/SubtitleViewModel.kt"
click node_videoaudio "https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/service/VideoAudioBridge.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_main,node_playerui,node_videoui toneBlue
class node_library,node_cloud,node_telegram,node_nas,node_addons toneAmber
class node_service,node_engine,node_decode,node_dsp,node_native,node_output,node_cast toneMint
class node_database,node_analysis,node_autoeq,node_lyrics toneRose
class node_subtitles,node_videoaudio,node_listener toneIndigo
```

## Components

### App experience

- [Main screen](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/MainScreen.kt): `app/src/main/java/com/beatraxus/app/ui/screens/MainScreen.kt`
- [Player screens](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/NowPlayingScreen.kt): `app/src/main/java/com/beatraxus/app/ui/screens/NowPlayingScreen.kt`
- [Video player](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/ui/screens/VideoPlayerScreen.kt): `app/src/main/java/com/beatraxus/app/ui/screens/VideoPlayerScreen.kt`

### Media sources

- [Library scanning](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/LibraryScanner.kt): `app/src/main/java/com/beatraxus/app/repository/LibraryScanner.kt`
- [Cloud streaming](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/drive/CloudCacheManager.kt): `app/src/main/java/com/beatraxus/app/drive/CloudCacheManager.kt`
- [Telegram access](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/telegram/TdLibManager.kt): `app/src/main/java/com/beatraxus/app/telegram/TdLibManager.kt`
- [NAS connections](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/SmbConnectionRepository.kt): `app/src/main/java/com/beatraxus/app/repository/SmbConnectionRepository.kt`
- [Streaming add-ons](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/addons/AddonManager.kt): `app/src/main/java/com/beatraxus/app/addons/AddonManager.kt`

### Playback and audio

- [Playback service](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/service/AudioPlaybackService.kt): `app/src/main/java/com/beatraxus/app/service/AudioPlaybackService.kt`
- [Audio engine](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt): `app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt`
- [Audio decoding](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/DecoderFactory.kt): `app/src/main/java/com/beatraxus/app/engine/DecoderFactory.kt`
- [DSP pipeline](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/DspPipeline.kt): `app/src/main/java/com/beatraxus/app/engine/DspPipeline.kt`
- [Native DSP](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/NativeDsp.kt): `app/src/main/java/com/beatraxus/app/engine/NativeDsp.kt`
- [Audio output](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/AudioOutput.kt): `app/src/main/java/com/beatraxus/app/engine/AudioOutput.kt`
- [Casting](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/cast/CastManager.kt): `app/src/main/java/com/beatraxus/app/cast/CastManager.kt`

### Enrichment and data

- [App database](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/model/AppDatabase.kt): `app/src/main/java/com/beatraxus/app/model/AppDatabase.kt`
- [AI analysis](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/engine/AiAnalysisEngine.kt): `app/src/main/java/com/beatraxus/app/engine/AiAnalysisEngine.kt`
- [Auto-EQ](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/AutoEqRepository.kt): `app/src/main/java/com/beatraxus/app/repository/AutoEqRepository.kt`
- [Lyrics](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/repository/LyricsRepository.kt): `app/src/main/java/com/beatraxus/app/repository/LyricsRepository.kt`

### Connected features

- [Subtitle support](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/subtitles/viewmodel/SubtitleViewModel.kt): `app/src/main/java/com/beatraxus/app/subtitles/viewmodel/SubtitleViewModel.kt`
- [Video audio bridge](https://github.com/harbertraj/beatraxus/blob/main/app/src/main/java/com/beatraxus/app/service/VideoAudioBridge.kt): `app/src/main/java/com/beatraxus/app/service/VideoAudioBridge.kt`

### Other components

- **Listener**

## Connections

- Listener → Main screen: browses
- Main screen → Library scanning: browses library
- Library scanning → Cloud streaming: streams and caches
- Cloud streaming → Audio engine: provides media (evidence: `app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt`)
- Cloud streaming → Telegram access: requests content (evidence: `app/src/main/java/com/beatraxus/app/drive/CloudCacheManager.kt`)
- Main screen → Streaming add-ons: browses add-ons
- NAS connections → Cloud streaming: provides remote files (evidence: `app/src/main/java/com/beatraxus/app/drive/CloudCacheManager.kt`)
- Main screen → Player screens: opens playback
- Player screens → Playback service: controls playback
- Playback service → Audio engine: controls (evidence: `app/src/main/java/com/beatraxus/app/service/AudioPlaybackService.kt`)
- Audio engine → Audio decoding: selects decoder (evidence: `app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt`)
- Audio engine → Audio output: renders audio (evidence: `app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt`)
- Audio engine → DSP pipeline: processes audio
- DSP pipeline → Native DSP: invokes DSP (evidence: `app/src/main/java/com/beatraxus/app/engine/DspPipeline.kt`)
- Playback service → Casting: routes playback (evidence: `app/src/main/java/com/beatraxus/app/service/AudioPlaybackService.kt`)
- Audio engine → App database: uses stored state (evidence: `app/src/main/java/com/beatraxus/app/engine/AudioEngine.kt`)
- AI analysis → App database: stores analysis
- AI analysis → Auto-EQ: calculates EQ (evidence: `app/src/main/java/com/beatraxus/app/engine/AiAnalysisEngine.kt`)
- Player screens → Lyrics: shows lyrics
- Main screen → Video player: opens video
- Video player → Subtitle support: manages subtitles
- Video player → Video audio bridge: bridges audio
