# clementine-player/clementine architecture

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

- Interactive diagram: https://gitdiagram.com/clementine-player/clementine
- Repository: https://github.com/clementine-player/clementine

## Overview

Clementine is a cross-platform music player and library organizer. The principal workflow is managing a playlist and playing audio through the GStreamer engine; the sampled engine code shows it coordinating playback pipelines and handling track, buffering, metadata, and error events. Other product branches include device management and music storage, album-cover management, moodbar analysis, and network-remote playback with HTTP media streaming. Several of these are documented by the tree and README-level product description, but their connections to the central workflow are not established by the excerpts, so those links are omitted.

Main entry points: [`src/networkremote/streaming/remoteengine.cpp`](https://github.com/clementine-player/clementine/blob/master/src/networkremote/streaming/remoteengine.cpp) (Remote renderer engine), [`src/networkremote/streaming/pipelineresponder.cpp`](https://github.com/clementine-player/clementine/blob/master/src/networkremote/streaming/pipelineresponder.cpp) (HTTP stream responder), [`src/engines/gstengine.cpp`](https://github.com/clementine-player/clementine/blob/master/src/engines/gstengine.cpp) (GStreamer engine), [`src/engines/gstenginepipeline.cpp`](https://github.com/clementine-player/clementine/blob/master/src/engines/gstenginepipeline.cpp) (Playback pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_playback["Audio playback"]
  node_audio_engine["GStreamer engine<br/>[gstengine.cpp]"]
  node_audio_pipeline["Playback pipeline"]
  node_gstreamer["GStreamer"]
end

subgraph group_library["Library and playlists"]
  node_playlist["Playlist manager"]
end

subgraph group_devices["Devices and storage"]
  node_music_store["Music storage interface<br/>[musicstorage.h]"]
  node_filesystem_store["Filesystem storage"]
  node_device_manager["Device manager<br/>[devicemanager.cpp]"]
end

subgraph group_enrichment["Media enrichment"]
  node_moodbar["Moodbar analysis"]
  node_cover_manager["Album-cover manager"]
  node_cover_services["Cover providers"]
end

subgraph group_remote["Remote playback"]
  node_remote_engine["Remote renderer engine<br/>[remoteengine.cpp]"]
  node_stream_responder["HTTP stream responder"]
  node_renderer(("Network renderer"))
end

node_listener(("Listener"))
node_media_source(("Media source"))
node_http_client(("Renderer HTTP client"))

node_listener -->|"manages playlists"| node_playlist
node_listener -->|"controls playback"| node_audio_engine
node_audio_engine -->|"creates and coordinates"| node_audio_pipeline
node_audio_pipeline -->|"configures playback"| node_gstreamer
node_moodbar -->|"analyzes audio"| node_gstreamer
node_listener -->|"manages devices"| node_device_manager
node_device_manager -->|"uses storage operations"| node_music_store
node_listener -->|"manages covers"| node_cover_manager
node_cover_manager -->|"fetches covers"| node_cover_services
node_renderer -->|"sends playback commands"| node_remote_engine
node_remote_engine -->|"sends renderer commands"| node_renderer
node_media_source -->|"provides media URL"| node_stream_responder
node_stream_responder -->|"streams HTTP audio"| node_http_client
node_remote_engine -->|"publishes stream URL"| node_stream_responder

click node_playlist "https://github.com/clementine-player/clementine/blob/master/src/playlist/playlistmanager.cpp"
click node_music_store "https://github.com/clementine-player/clementine/blob/master/src/core/musicstorage.h"
click node_filesystem_store "https://github.com/clementine-player/clementine/blob/master/src/core/filesystemmusicstorage.cpp"
click node_device_manager "https://github.com/clementine-player/clementine/blob/master/src/devices/devicemanager.cpp"
click node_audio_engine "https://github.com/clementine-player/clementine/blob/master/src/engines/gstengine.cpp"
click node_audio_pipeline "https://github.com/clementine-player/clementine/blob/master/src/engines/gstenginepipeline.cpp"
click node_moodbar "https://github.com/clementine-player/clementine/blob/master/src/moodbar/moodbarpipeline.cpp"
click node_cover_manager "https://github.com/clementine-player/clementine/blob/master/src/ui/albumcovermanager.cpp"
click node_remote_engine "https://github.com/clementine-player/clementine/blob/master/src/networkremote/streaming/remoteengine.cpp"
click node_stream_responder "https://github.com/clementine-player/clementine/blob/master/src/networkremote/streaming/pipelineresponder.cpp"

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_audio_engine,node_audio_pipeline,node_gstreamer,node_http_client toneBlue
class node_playlist toneAmber
class node_music_store,node_filesystem_store,node_device_manager toneMint
class node_moodbar,node_cover_manager,node_cover_services toneRose
class node_remote_engine,node_stream_responder,node_renderer,node_listener,node_media_source toneIndigo
```

## Components

### Audio playback

- [GStreamer engine](https://github.com/clementine-player/clementine/blob/master/src/engines/gstengine.cpp): `src/engines/gstengine.cpp`
- [Playback pipeline](https://github.com/clementine-player/clementine/blob/master/src/engines/gstenginepipeline.cpp): `src/engines/gstenginepipeline.cpp`
- **GStreamer**

### Library and playlists

- [Playlist manager](https://github.com/clementine-player/clementine/blob/master/src/playlist/playlistmanager.cpp): `src/playlist/playlistmanager.cpp`

### Devices and storage

- [Music storage interface](https://github.com/clementine-player/clementine/blob/master/src/core/musicstorage.h): `src/core/musicstorage.h`
- [Filesystem storage](https://github.com/clementine-player/clementine/blob/master/src/core/filesystemmusicstorage.cpp): `src/core/filesystemmusicstorage.cpp`
- [Device manager](https://github.com/clementine-player/clementine/blob/master/src/devices/devicemanager.cpp): `src/devices/devicemanager.cpp`

### Media enrichment

- [Moodbar analysis](https://github.com/clementine-player/clementine/blob/master/src/moodbar/moodbarpipeline.cpp): `src/moodbar/moodbarpipeline.cpp`
- [Album-cover manager](https://github.com/clementine-player/clementine/blob/master/src/ui/albumcovermanager.cpp): `src/ui/albumcovermanager.cpp`
- **Cover providers**

### Remote playback

- [Remote renderer engine](https://github.com/clementine-player/clementine/blob/master/src/networkremote/streaming/remoteengine.cpp): `src/networkremote/streaming/remoteengine.cpp`
- [HTTP stream responder](https://github.com/clementine-player/clementine/blob/master/src/networkremote/streaming/pipelineresponder.cpp): `src/networkremote/streaming/pipelineresponder.cpp`
- **Network renderer**

### Other components

- **Listener**
- **Media source**
- **Renderer HTTP client**

## Connections

- Listener → Playlist manager: manages playlists
- Listener → GStreamer engine: controls playback
- GStreamer engine → Playback pipeline: creates and coordinates
- Playback pipeline → GStreamer: configures playback
- Moodbar analysis → GStreamer: analyzes audio
- Listener → Device manager: manages devices
- Device manager → Music storage interface: uses storage operations
- Listener → Album-cover manager: manages covers
- Album-cover manager → Cover providers: fetches covers
- Network renderer → Remote renderer engine: sends playback commands
- Remote renderer engine → Network renderer: sends renderer commands
- Media source → HTTP stream responder: provides media URL
- HTTP stream responder → Renderer HTTP client: streams HTTP audio
- Remote renderer engine → HTTP stream responder: publishes stream URL