# libre-tube/libretube architecture

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

- Interactive diagram: https://gitdiagram.com/libre-tube/libretube
- Repository: https://github.com/libre-tube/libretube

## Overview

LibreTube is a privacy-focused Android YouTube client. The principal workflow is: a user searches or opens a shared link, the UI requests content through a media repository, displays results, and starts online playback; playback can persist history and positions. Downloads follow a separate enqueue-and-transfer path, while subscriptions, playlists, accounts, synchronization, and privacy-oriented integrations extend the same data layer. Several repository implementations are represented from the tree, but their internal call details were not sampled, so uncertain links are omitted.

Main entry points: [`app/src/main/java/com/github/libretube/services/OnlinePlayerService.kt`](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/OnlinePlayerService.kt) (Online Player), [`app/src/main/java/com/github/libretube/api/MediaServiceRepository.kt`](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/api/MediaServiceRepository.kt) (Media Repository), [`app/src/main/java/com/github/libretube/ui/fragments/SearchResultFragment.kt`](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/fragments/SearchResultFragment.kt) (Search Results), [`app/src/main/java/com/github/libretube/services/DownloadService.kt`](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/DownloadService.kt) (Download Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI and Navigation"]
  node_router["Share Router<br/>[RouterActivity.kt]"]
  node_main_activity["Main Activity<br/>[MainActivity.kt]"]
  node_search_screen["Search Results"]
  node_search_model["Search ViewModel"]
  node_player_gestures["Player Gestures"]
end

subgraph group_content["Content and APIs"]
  node_media_repository["Media Repository"]
  node_newpipe_repository["NewPipe Repository"]
  node_piped_repository["Piped Repository"]
end

subgraph group_playback["Playback and Downloads"]
  node_abstract_player["Player Service"]
  node_online_player["Online Player"]
  node_media3["Media3 Player"]
  node_download_service["Download Service<br/>[DownloadService.kt]"]
  node_playlist_enqueue["Playlist Enqueuer"]
  node_download_provider["Download Providers"]
end

subgraph group_state["State and Sync"]
  node_database[("Local Database<br/>[AppDatabase.kt]")]
  node_local_user_data["Local User Data"]
  node_piped_user_data["Piped User Data"]
  node_sync_user_data["Sync User Data"]
end

node_user(("App User"))
node_youtube["YouTube Service"]
node_piped_service["Piped Service"]
node_sponsorblock["SponsorBlock"]
node_dearrow["DeArrow"]
node_dislike_service["Dislike Service"]
node_sync_server["Sync Server"]

node_user -->|"shares link"| node_router
node_router -->|"routes"| node_main_activity
node_main_activity -->|"opens"| node_search_screen
node_search_screen -->|"collects results"| node_search_model
node_search_model -->|"requests search"| node_media_repository
node_media_repository -->|"delegates"| node_newpipe_repository
node_newpipe_repository -->|"extracts content"| node_youtube
node_media_repository -.->|"selects backend"| node_piped_repository
node_piped_repository -.->|"requests content"| node_piped_service
node_search_screen -->|"shows results"| node_user
node_player_gestures -->|"sends commands"| node_abstract_player
node_abstract_player -->|"starts playback"| node_online_player
node_online_player -->|"loads streams"| node_media_repository
node_online_player -->|"sets source"| node_media3
node_online_player -->|"records history"| node_local_user_data
node_online_player -.->|"loads segments"| node_sponsorblock
node_online_player -.->|"loads metadata"| node_dearrow
node_online_player -.->|"loads ratings"| node_dislike_service
node_playlist_enqueue -->|"gets streams"| node_media_repository
node_playlist_enqueue -->|"starts downloads"| node_download_service
node_download_service -->|"stores metadata"| node_database
node_download_service -->|"downloads media"| node_download_provider
node_local_user_data -->|"reads and writes"| node_database
node_piped_user_data -.->|"syncs account"| node_piped_service
node_sync_user_data -.->|"syncs data"| node_sync_server

click node_router "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/activities/RouterActivity.kt"
click node_main_activity "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/activities/MainActivity.kt"
click node_search_screen "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/fragments/SearchResultFragment.kt"
click node_search_model "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/models/SearchResultViewModel.kt"
click node_player_gestures "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/listeners/PlayerGestureController.kt"
click node_media_repository "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/api/MediaServiceRepository.kt"
click node_newpipe_repository "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/api/NewPipeMediaServiceRepository.kt"
click node_piped_repository "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/api/PipedMediaServiceRepository.kt"
click node_abstract_player "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/AbstractPlayerService.kt"
click node_online_player "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/OnlinePlayerService.kt"
click node_download_service "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/DownloadService.kt"
click node_playlist_enqueue "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/PlaylistDownloadEnqueueService.kt"
click node_download_provider "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/DownloadProvider.kt"
click node_database "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/db/AppDatabase.kt"
click node_local_user_data "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/LocalUserDataRepository.kt"
click node_piped_user_data "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/PipedUserDataRepository.kt"
click node_sync_user_data "https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/LibreTubeSyncServerUserDataRepository.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_router,node_main_activity,node_search_screen,node_search_model,node_player_gestures,node_user toneBlue
class node_media_repository,node_newpipe_repository,node_piped_repository toneAmber
class node_abstract_player,node_online_player,node_media3,node_download_service,node_playlist_enqueue,node_download_provider,node_sync_server toneMint
class node_database,node_local_user_data,node_piped_user_data,node_sync_user_data toneRose
class node_youtube,node_piped_service,node_sponsorblock,node_dearrow,node_dislike_service toneIndigo
```

## Components

### UI and Navigation

- [Share Router](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/activities/RouterActivity.kt): `app/src/main/java/com/github/libretube/ui/activities/RouterActivity.kt`
- [Main Activity](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/activities/MainActivity.kt): `app/src/main/java/com/github/libretube/ui/activities/MainActivity.kt`
- [Search Results](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/fragments/SearchResultFragment.kt): `app/src/main/java/com/github/libretube/ui/fragments/SearchResultFragment.kt`
- [Search ViewModel](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/models/SearchResultViewModel.kt): `app/src/main/java/com/github/libretube/ui/models/SearchResultViewModel.kt`
- [Player Gestures](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/ui/listeners/PlayerGestureController.kt): `app/src/main/java/com/github/libretube/ui/listeners/PlayerGestureController.kt`

### Content and APIs

- [Media Repository](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/api/MediaServiceRepository.kt): `app/src/main/java/com/github/libretube/api/MediaServiceRepository.kt`
- [NewPipe Repository](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/api/NewPipeMediaServiceRepository.kt): `app/src/main/java/com/github/libretube/api/NewPipeMediaServiceRepository.kt`
- [Piped Repository](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/api/PipedMediaServiceRepository.kt): `app/src/main/java/com/github/libretube/api/PipedMediaServiceRepository.kt`

### Playback and Downloads

- [Player Service](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/AbstractPlayerService.kt): `app/src/main/java/com/github/libretube/services/AbstractPlayerService.kt`
- [Online Player](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/OnlinePlayerService.kt): `app/src/main/java/com/github/libretube/services/OnlinePlayerService.kt`
- **Media3 Player**
- [Download Service](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/DownloadService.kt): `app/src/main/java/com/github/libretube/services/DownloadService.kt`
- [Playlist Enqueuer](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/services/PlaylistDownloadEnqueueService.kt): `app/src/main/java/com/github/libretube/services/PlaylistDownloadEnqueueService.kt`
- [Download Providers](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/DownloadProvider.kt): `app/src/main/java/com/github/libretube/repo/DownloadProvider.kt`

### State and Sync

- [Local Database](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/db/AppDatabase.kt): `app/src/main/java/com/github/libretube/db/AppDatabase.kt`
- [Local User Data](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/LocalUserDataRepository.kt): `app/src/main/java/com/github/libretube/repo/LocalUserDataRepository.kt`
- [Piped User Data](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/PipedUserDataRepository.kt): `app/src/main/java/com/github/libretube/repo/PipedUserDataRepository.kt`
- [Sync User Data](https://github.com/libre-tube/libretube/blob/master/app/src/main/java/com/github/libretube/repo/LibreTubeSyncServerUserDataRepository.kt): `app/src/main/java/com/github/libretube/repo/LibreTubeSyncServerUserDataRepository.kt`

### Other components

- **App User**
- **YouTube Service**
- **Piped Service**
- **SponsorBlock**
- **DeArrow**
- **Dislike Service**
- **Sync Server**

## Connections

- App User → Share Router: shares link
- Share Router → Main Activity: routes
- Main Activity → Search Results: opens
- Search Results → Search ViewModel: collects results
- Search ViewModel → Media Repository: requests search
- Media Repository → NewPipe Repository: delegates
- NewPipe Repository → YouTube Service: extracts content
- Media Repository → Piped Repository: selects backend
- Piped Repository → Piped Service: requests content
- Search Results → App User: shows results
- Player Gestures → Player Service: sends commands
- Player Service → Online Player: starts playback
- Online Player → Media Repository: loads streams
- Online Player → Media3 Player: sets source
- Online Player → Local User Data: records history
- Online Player → SponsorBlock: loads segments
- Online Player → DeArrow: loads metadata
- Online Player → Dislike Service: loads ratings
- Playlist Enqueuer → Media Repository: gets streams
- Playlist Enqueuer → Download Service: starts downloads
- Download Service → Local Database: stores metadata
- Download Service → Download Providers: downloads media
- Local User Data → Local Database: reads and writes
- Piped User Data → Piped Service: syncs account
- Sync User Data → Sync Server: syncs data
