# vovaaa312/viby architecture

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

- Interactive diagram: https://gitdiagram.com/vovaaa312/viby
- Repository: https://github.com/vovaaa312/viby

## Overview

#### Purpose and Runtime
Viby is a single-module Android offline music player. It downloads YouTube video/playlist audio entirely on-device, stores MP3s in app-scoped external storage, and plays the local library in the background. The APK bundles a Python runtime, yt-dlp, and FFmpeg; playback uses Android Media3/ExoPlayer and the platform equalizer. Build/runtime definition: `app/build.gradle`, `app/src/main/AndroidManifest.xml`.

#### Application and UI Entry Points
`VibyApp` is the application-level bootstrap. `MainActivity` is the primary library/player host, with player and queue presented as fragments. Dedicated activities isolate download intake, equalizer controls, and YouTube authentication/playlist selection.
- `app/src/main/java/com/example/viby/VibyApp.java`
- `app/src/main/java/com/example/viby/ui/MainActivity.java`
- `app/src/main/java/com/example/viby/ui/PlayerFragment.java`
- `app/src/main/java/com/example/viby/ui/DownloadActivity.java`

#### Persistent Library Model
Room-style local persistence represents downloaded tracks, playlist metadata/source links, and resumable/pending download state. This database is the boundary between UI/library management and background work; downloaded media itself lives under `Android/data/com.example.viby/files/Music/<playlist>/`.
- `app/src/main/java/com/example/viby/data/VibyDatabase.java`
- `app/src/main/java/com/example/viby/data/Track.java`
- `app/src/main/java/com/example/viby/data/PlaylistInfo.java`
- `app/src/main/java/com/example/viby/data/PendingDownload.java`

#### Download and Extraction Pipeline
A user supplies or shares a YouTube URL through the download/login/playlist UI. Download jobs coordinate per-track or per-playlist progress and persistent pending state. The background download service invokes the embedded extraction stack, produces tagged MP3s with cover art, and updates the local library. YouTube access/authentication and cookie handling are separate boundaries from local playback.
- `app/src/main/java/com/example/viby/download/DownloadService.java`
- `app/src/main/java/com/example/viby/download/DownloadJob.java`
- `app/src/main/java/com/example/viby/ui/YoutubeLoginActivity.java`
- `app/src/main/java/com/example/viby/util/YtCookies.java`

#### Playback and Audio Effects
`PlaybackService` owns long-lived background audio, media notification/session behavior, queue progression, shuffle/repeat, and the Media3/ExoPlayer lifecycle. UI observes/controls it through `PlayerViewModel`; it should not directly own playback resources. Equalizer effects attach at the Android audio-session boundary and expose preset definitions separately.
- `app/src/main/java/com/example/viby/playback/PlaybackService.java`
- `app/src/main/java/com/example/viby/ui/PlayerViewModel.java`
- `app/src/main/java/com/example/viby/playback/EqFx.java`
- `app/src/main/java/com/example/viby/playback/EqPresets.java`

#### Library, Queue, and Presentation Flow
Library screens render persisted tracks and playlists through adapters; selection/context actions change queue, playlist membership, or files/database records. `QueueFragment` represents the playback queue, while `PlayerFragment` provides transport controls and waveform seeking. Waveform generation/extraction is a local media-processing concern, not a download-service responsibility.
- `app/src/main/java/com/example/viby/ui/QueueFragment.java`
- `app/src/main/java/com/example/viby/ui/TracksAdapter.java`
- `app/src/main/java/com/example/viby/ui/PlaylistsAdapter.java`
- `app/src/main/java/com/example/viby/util/WaveformExtractor.java`

#### Key Boundaries and External Dependencies
The app has no server: YouTube is the external content source, while yt-dlp/FFmpeg are bundled on-device execution dependencies. Android app-scoped external storage is the media boundary, mediated by storage utilities. UI resources provide the Android presentation layer and localization/theme assets.
- `app/src/main/java/com/example/viby/util/StorageHelper.java`
- `app/src/main/res/layout/activity_main.xml`
- `app/src/main/res/layout/fragment_player.xml`

Main entry points: [`app/src/main/java/com/example/viby/ui/MainActivity.java`](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/MainActivity.java) (MainActivity), [`app/src/main/java/com/example/viby/download/DownloadService.java`](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/download/DownloadService.java) (DownloadService), [`app/src/main/java/com/example/viby/playback/PlaybackService.java`](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/playback/PlaybackService.java) (PlaybackService), [`app/src/main/java/com/example/viby/data/VibyDatabase.java`](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/data/VibyDatabase.java) (VibyDatabase)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Android UI"]
  node_bootstrap{{"VibyApp<br/>application bootstrap<br/>[VibyApp.java]"}}
  node_main_activity["MainActivity<br/>library/player host<br/>[MainActivity.java]"]
  node_player_fragment["PlayerFragment<br/>transport UI"]
  node_queue_fragment["QueueFragment<br/>queue UI<br/>[QueueFragment.java]"]
  node_download_activity["DownloadActivity<br/>download intake UI"]
  node_library_adapters["Track &amp; playlist adapters<br/>library presentation<br/>[TracksAdapter.java]"]
end

subgraph group_library["Local Library"]
  node_database[("VibyDatabase<br/>Room library database<br/>[VibyDatabase.java]")]
  node_media_storage[("Music storage<br/>app-scoped MP3 library<br/>[StorageHelper.java]")]
end

subgraph group_download["Download Pipeline"]
  node_download_service["DownloadService<br/>background download service"]
  node_download_job["DownloadJob<br/>job coordinator<br/>[DownloadJob.java]"]
  node_youtube_auth["YouTube auth &amp; cookies<br/>authentication boundary"]
  node_youtube(("YouTube<br/>external content source"))
  node_extractor["yt-dlp + FFmpeg<br/>bundled extraction stack"]
end

subgraph group_playback["Playback"]
  node_playback_service["PlaybackService<br/>background media service"]
  node_player_viewmodel["PlayerViewModel<br/>playback UI state"]
  node_equalizer["EqFx &amp; presets<br/>audio-session effects<br/>[EqFx.java]"]
  node_waveform["WaveformExtractor<br/>local media processing"]
end

node_bootstrap -->|"launches"| node_main_activity
node_main_activity -->|"hosts"| node_player_fragment
node_main_activity -->|"hosts"| node_queue_fragment
node_main_activity -->|"renders library"| node_library_adapters
node_library_adapters -->|"reads and updates"| node_database
node_download_activity -->|"submits URLs"| node_download_service
node_download_activity -->|"requests login"| node_youtube_auth
node_youtube_auth -->|"authenticates with"| node_youtube
node_download_service -->|"runs"| node_download_job
node_download_job -->|"persists pending state"| node_database
node_download_service -->|"invokes"| node_extractor
node_extractor -->|"retrieves media"| node_youtube
node_extractor -->|"writes tagged MP3s"| node_media_storage
node_download_service -->|"imports library records"| node_database
node_player_viewmodel -->|"observes and controls"| node_playback_service
node_player_fragment -->|"binds controls"| node_player_viewmodel
node_queue_fragment -->|"changes queue"| node_player_viewmodel
node_playback_service -->|"plays local files"| node_media_storage
node_playback_service -->|"loads library and queue"| node_database
node_playback_service -->|"provides audio session"| node_equalizer
node_player_fragment -->|"requests seeking waveform"| node_waveform
node_waveform -->|"reads local media"| node_media_storage

click node_bootstrap "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/VibyApp.java"
click node_main_activity "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/MainActivity.java"
click node_player_fragment "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/PlayerFragment.java"
click node_queue_fragment "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/QueueFragment.java"
click node_download_activity "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/DownloadActivity.java"
click node_library_adapters "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/TracksAdapter.java"
click node_database "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/data/VibyDatabase.java"
click node_media_storage "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/util/StorageHelper.java"
click node_download_service "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/download/DownloadService.java"
click node_download_job "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/download/DownloadJob.java"
click node_youtube_auth "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/YoutubeLoginActivity.java"
click node_playback_service "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/playback/PlaybackService.java"
click node_player_viewmodel "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/PlayerViewModel.java"
click node_equalizer "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/playback/EqFx.java"
click node_waveform "https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/util/WaveformExtractor.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_bootstrap,node_main_activity,node_player_fragment,node_queue_fragment,node_download_activity,node_library_adapters toneBlue
class node_database,node_media_storage toneAmber
class node_download_service,node_download_job,node_youtube_auth,node_youtube,node_extractor toneMint
class node_playback_service,node_player_viewmodel,node_equalizer,node_waveform toneRose
```

## Components

### Android UI

Activities, fragments, and presentation resources.

- [VibyApp](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/VibyApp.java): application bootstrap · `app/src/main/java/com/example/viby/VibyApp.java`
- [MainActivity](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/MainActivity.java): library/player host · `app/src/main/java/com/example/viby/ui/MainActivity.java`
- [PlayerFragment](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/PlayerFragment.java): transport UI · `app/src/main/java/com/example/viby/ui/PlayerFragment.java`
- [QueueFragment](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/QueueFragment.java): queue UI · `app/src/main/java/com/example/viby/ui/QueueFragment.java`
- [DownloadActivity](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/DownloadActivity.java): download intake UI · `app/src/main/java/com/example/viby/ui/DownloadActivity.java`
- [Track & playlist adapters](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/TracksAdapter.java): library presentation · `app/src/main/java/com/example/viby/ui/TracksAdapter.java`

### Local Library

Persistent metadata and app-scoped media.

- [VibyDatabase](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/data/VibyDatabase.java): Room library database · Tracks, playlist metadata, and pending downloads. · `app/src/main/java/com/example/viby/data/VibyDatabase.java`
- [Music storage](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/util/StorageHelper.java): app-scoped MP3 library · Downloaded files are organized by playlist. · `app/src/main/java/com/example/viby/util/StorageHelper.java`

### Download Pipeline

On-device YouTube extraction and import.

- [DownloadService](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/download/DownloadService.java): background download service · `app/src/main/java/com/example/viby/download/DownloadService.java`
- [DownloadJob](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/download/DownloadJob.java): job coordinator · Coordinates track or playlist progress and resume state. · `app/src/main/java/com/example/viby/download/DownloadJob.java`
- [YouTube auth & cookies](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/YoutubeLoginActivity.java): authentication boundary · `app/src/main/java/com/example/viby/ui/YoutubeLoginActivity.java`
- **YouTube**: external content source
- **yt-dlp + FFmpeg**: bundled extraction stack · Extracts, transcodes, tags, and embeds cover art on-device.

### Playback

Background playback, queue, and effects.

- [PlaybackService](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/playback/PlaybackService.java): background media service · Owns Media3 playback, notification/session, and queue progression. · `app/src/main/java/com/example/viby/playback/PlaybackService.java`
- [PlayerViewModel](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/ui/PlayerViewModel.java): playback UI state · `app/src/main/java/com/example/viby/ui/PlayerViewModel.java`
- [EqFx & presets](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/playback/EqFx.java): audio-session effects · Applies platform equalizer settings to the playback audio session. · `app/src/main/java/com/example/viby/playback/EqFx.java`
- [WaveformExtractor](https://github.com/vovaaa312/viby/blob/main/app/src/main/java/com/example/viby/util/WaveformExtractor.java): local media processing · `app/src/main/java/com/example/viby/util/WaveformExtractor.java`

## Connections

- VibyApp → MainActivity: launches
- MainActivity → PlayerFragment: hosts
- MainActivity → QueueFragment: hosts
- MainActivity → Track & playlist adapters: renders library
- Track & playlist adapters → VibyDatabase: reads and updates
- DownloadActivity → DownloadService: submits URLs
- DownloadActivity → YouTube auth & cookies: requests login
- YouTube auth & cookies → YouTube: authenticates with
- DownloadService → DownloadJob: runs
- DownloadJob → VibyDatabase: persists pending state
- DownloadService → yt-dlp + FFmpeg: invokes
- yt-dlp + FFmpeg → YouTube: retrieves media
- yt-dlp + FFmpeg → Music storage: writes tagged MP3s
- DownloadService → VibyDatabase: imports library records
- PlayerViewModel → PlaybackService: observes and controls
- PlayerFragment → PlayerViewModel: binds controls
- QueueFragment → PlayerViewModel: changes queue
- PlaybackService → Music storage: plays local files
- PlaybackService → VibyDatabase: loads library and queue
- PlaybackService → EqFx & presets: provides audio session
- PlayerFragment → WaveformExtractor: requests seeking waveform
- WaveformExtractor → Music storage: reads local media